{ "openapi": "3.1.0", "info": { "title": "UA1 Validator API", "version": "0.3.0", "description": "PDF/UA-1 and PDF/UA-2 validation API powered by veraPDF. Findings are grouped per rule with occurrence counts, plain-language explanations, remediation steps and WCAG mapping." }, "servers": [ { "url": "https://api.ua1.dev" } ], "paths": { "/api/health": { "get": { "summary": "Health check", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/validate": { "post": { "summary": "Validate a PDF against PDF/UA-1 or PDF/UA-2", "description": "Accepts a multipart file upload or a public PDF URL. Results group every failed rule with its true occurrence count; sample locations are capped per rule.", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "When set to `compact`, returns an LLM-friendly compact result schema.", "schema": { "type": "string", "enum": [ "compact" ] } }, { "name": "profile", "in": "query", "required": false, "description": "Validation profile. Defaults to `ua1`.", "schema": { "type": "string", "enum": [ "ua1", "ua2" ], "default": "ua1" } }, { "name": "url", "in": "query", "required": false, "description": "Public URL of a PDF to fetch and validate instead of uploading a file. Private network addresses are refused.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Input PDF file" } } } } } }, "responses": { "200": { "description": "Validation result (full or compact based on query parameter)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidationFullResponse" }, { "$ref": "#/components/schemas/ValidationCompactResponse" } ] }, "examples": { "full": { "summary": "Full response", "value": { "ok": true, "mode": "full", "document_id": "13270e30-cf8b-4b53-af0f-0b1c434fbc08", "filename": "sample.pdf", "bytes": 483921, "profile": "PDF/UA-1", "profile_id": "ua1", "standard": "ISO 14289-1", "verdict": "fail", "summary": { "errors": 17, "warnings": 3, "total_findings": 17, "failed_rules": 7, "samples_truncated": true }, "document": { "pages": 12, "tagged": false, "has_structure_tree": false, "title": null, "title_displayed": false, "language": null, "pdf_version": "1.4", "encrypted": false, "ua_identifier": null }, "rules": [ { "rule_id": "7.1-3", "clause": "7.1", "severity": "error", "occurrences": 6, "title": "Untagged content on the page", "plain": "Content is drawn on the page but is neither tagged as real content nor marked as an artifact.", "impact": "This content does not exist for a screen reader user.", "how_to_fix": [ "Open Accessibility > Reading Order in Acrobat Pro and assign a tag to each untagged region." ], "wcag": [ "1.3.1 Info and Relationships (A)" ], "object": "SESimpleContentItem", "spec_description": "Content shall be marked as Artifact or tagged as real content", "pages": [ 1, 2 ], "samples": [ { "message": "Content shall be marked as Artifact or tagged as real content", "location": "root/document[0]/pages[0]", "page": 1 } ] } ], "warnings": [ { "code": "NO_DOCUMENT_TITLE", "related_rule": "7.1-9", "message": "The document has no title in its metadata.", "hint": "Set a descriptive title in File > Properties > Description." } ], "findings": [ { "rule_id": "7.1-3", "severity": "error", "message": "Content shall be marked as Artifact or tagged as real content", "location": "root/document[0]/pages[0]", "page": 1 } ], "engine": { "name": "veraPDF", "version": "1.28.2", "profile": "PDF/UA-1", "rule_catalog_version": "2026-08-03" }, "processing_ms": 94, "generated_at": "2026-08-03T09:15:00.000Z" } }, "compact": { "summary": "Compact response", "value": { "ok": true, "mode": "compact", "document_id": "13270e30-cf8b-4b53-af0f-0b1c434fbc08", "profile": "PDF/UA-1", "verdict": "fail", "errors": 17, "failed_rules": 7, "rules": [ { "rule_id": "7.1-3", "count": 6, "title": "Untagged content on the page", "fix": "Open Accessibility > Reading Order in Acrobat Pro and assign a tag to each untagged region.", "pages": [ 1, 2 ] } ], "findings": [ { "rule_id": "7.1-3", "message": "Content shall be marked as Artifact or tagged as real content" } ] } } } } } }, "400": { "description": "Missing required file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "FILE_REQUIRED", "message": "Upload a PDF file in form field 'file'." }, "code": "FILE_REQUIRED", "message": "Upload a PDF file in form field 'file'." } } } }, "413": { "description": "Uploaded file is too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "FILE_TOO_LARGE", "message": "File exceeds 25 MB limit." }, "code": "FILE_TOO_LARGE", "message": "File exceeds 25 MB limit." } } } }, "415": { "description": "Unsupported file type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "UNSUPPORTED_TYPE", "message": "Only PDF files are supported." }, "code": "UNSUPPORTED_TYPE", "message": "Only PDF files are supported." } } } }, "500": { "description": "Server or validator configuration error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validatorNotConfigured": { "value": { "ok": false, "error": { "code": "VALIDATOR_NOT_CONFIGURED", "message": "veraPDF CLI not found. Set VERAPDF_BIN or install verapdf in runtime image." }, "code": "VALIDATOR_NOT_CONFIGURED", "message": "veraPDF CLI not found. Set VERAPDF_BIN or install verapdf in runtime image." } }, "validationFailed": { "value": { "ok": false, "error": { "code": "VALIDATION_FAILED", "message": "Validation failed unexpectedly.", "details": "Unexpected exception" }, "code": "VALIDATION_FAILED", "message": "Validation failed unexpectedly.", "details": "Unexpected exception" } }, "internalError": { "value": { "ok": false, "error": { "code": "INTERNAL_ERROR", "message": "Unexpected server error." }, "code": "INTERNAL_ERROR", "message": "Unexpected server error." } } } } } }, "502": { "description": "Validator returned invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badJson": { "value": { "ok": false, "error": { "code": "VALIDATOR_BAD_JSON", "message": "Validator returned malformed JSON output." }, "code": "VALIDATOR_BAD_JSON", "message": "Validator returned malformed JSON output." } }, "emptyOutput": { "value": { "ok": false, "error": { "code": "VALIDATOR_EMPTY_OUTPUT", "message": "Validator returned empty output." }, "code": "VALIDATOR_EMPTY_OUTPUT", "message": "Validator returned empty output." } } } } } }, "504": { "description": "Validation timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "VALIDATOR_TIMEOUT", "message": "Validation exceeded timeout limit." }, "code": "VALIDATOR_TIMEOUT", "message": "Validation exceeded timeout limit." } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "RATE_LIMITED", "message": "Too many validation requests. Try again later." }, "code": "RATE_LIMITED", "message": "Too many validation requests. Try again later." } } } }, "403": { "description": "URL fetch refused (private address or disabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The PDF could not be parsed, is encrypted, or the URL could not be fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "encrypted": { "value": { "ok": false, "error": { "code": "PDF_ENCRYPTED", "message": "The PDF is encrypted and cannot be validated." }, "code": "PDF_ENCRYPTED", "message": "The PDF is encrypted and cannot be validated." } }, "malformed": { "value": { "ok": false, "error": { "code": "PDF_MALFORMED", "message": "The file could not be parsed as a PDF." }, "code": "PDF_MALFORMED", "message": "The file could not be parsed as a PDF." } } } } } }, "503": { "description": "Validator at capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/metrics": { "get": { "summary": "Runtime metrics", "description": "Lightweight in-memory counters for operational visibility.", "responses": { "200": { "description": "Current metrics snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } } } } } }, "/api/rules": { "get": { "summary": "List every rule in a validation profile", "description": "veraPDF rule metadata merged with curated remediation guidance. Backs the public rule reference pages.", "parameters": [ { "name": "profile", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ua1", "ua2" ], "default": "ua1" } } ], "responses": { "200": { "description": "Rule catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleCatalogResponse" } } } } } } }, "/api/rules/{ruleId}": { "get": { "summary": "Explain a single rule", "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "7.3-1" }, { "name": "profile", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ua1", "ua2" ], "default": "ua1" } } ], "responses": { "200": { "description": "Rule detail", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/badge": { "get": { "summary": "SVG status badge for a public PDF", "description": "Validates the linked PDF (cached for 15 minutes) and renders a README/CI badge. Always returns a badge, never an error page.", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "profile", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ua1", "ua2" ], "default": "ua1" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Badge", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "HealthResponse": { "type": "object", "required": [ "ok", "service", "profile", "timestamp" ], "properties": { "ok": { "type": "boolean", "const": true }, "service": { "type": "string" }, "profile": { "type": "string", "const": "PDF/UA-1" }, "timestamp": { "type": "string", "format": "date-time" }, "profiles": { "type": "array", "items": { "type": "string" } } } }, "ValidationSummary": { "type": "object", "required": [ "errors", "warnings", "total_findings", "failed_rules", "samples_truncated" ], "properties": { "errors": { "type": "integer", "minimum": 0, "description": "Total failed checks across all rules." }, "warnings": { "type": "integer", "minimum": 0 }, "total_findings": { "type": "integer", "minimum": 0 }, "failed_rules": { "type": "integer", "minimum": 0, "description": "Distinct rules that failed." }, "samples_truncated": { "type": "boolean", "description": "True when sample locations cover fewer occurrences than `errors`." } } }, "ValidationFinding": { "type": "object", "required": [ "rule_id", "severity", "message", "location" ], "properties": { "rule_id": { "type": "string" }, "severity": { "type": "string", "const": "error" }, "message": { "type": "string" }, "location": { "type": "string" }, "page": { "type": "integer", "minimum": 1 } } }, "CompactFinding": { "type": "object", "required": [ "rule_id", "message" ], "properties": { "rule_id": { "type": "string" }, "message": { "type": "string" } } }, "ValidationFullResponse": { "type": "object", "required": [ "ok", "mode", "document_id", "filename", "bytes", "profile", "profile_id", "standard", "verdict", "summary", "document", "rules", "warnings", "findings", "engine", "processing_ms", "generated_at" ], "properties": { "ok": { "type": "boolean", "const": true }, "mode": { "type": "string", "const": "full" }, "document_id": { "type": "string" }, "filename": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 }, "profile": { "type": "string", "enum": [ "PDF/UA-1", "PDF/UA-2" ] }, "standard": { "type": "string", "enum": [ "ISO 14289-1", "ISO 14289-2" ] }, "verdict": { "type": "string", "enum": [ "pass", "fail" ] }, "summary": { "$ref": "#/components/schemas/ValidationSummary" }, "findings": { "type": "array", "description": "Flat per-sample view kept for backwards compatibility; prefer `rules`.", "items": { "$ref": "#/components/schemas/ValidationFinding" } }, "engine": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "profile": { "type": "string" }, "rule_catalog_version": { "type": "string" } } }, "processing_ms": { "type": "integer", "minimum": 0 }, "generated_at": { "type": "string", "format": "date-time" }, "profile_id": { "type": "string", "enum": [ "ua1", "ua2" ] }, "document": { "$ref": "#/components/schemas/DocumentInfo" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleFinding" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentWarning" } } } }, "ValidationCompactResponse": { "type": "object", "required": [ "ok", "mode", "document_id", "profile", "verdict", "errors", "failed_rules", "rules", "findings" ], "properties": { "ok": { "type": "boolean", "const": true }, "mode": { "type": "string", "const": "compact" }, "document_id": { "type": "string" }, "profile": { "type": "string" }, "verdict": { "type": "string", "enum": [ "pass", "fail" ] }, "errors": { "type": "integer", "minimum": 0 }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/CompactFinding" } }, "failed_rules": { "type": "integer", "minimum": 0 }, "rules": { "type": "array", "items": { "type": "object", "properties": { "rule_id": { "type": "string" }, "count": { "type": "integer" }, "title": { "type": "string" }, "fix": { "type": [ "string", "null" ] }, "pages": { "type": "array", "items": { "type": "integer" } } } } } } }, "ErrorCode": { "type": "string", "enum": [ "FILE_REQUIRED", "UNSUPPORTED_TYPE", "FILE_TOO_LARGE", "AMBIGUOUS_INPUT", "UPLOAD_FAILED", "PDF_ENCRYPTED", "PDF_MALFORMED", "UNSUPPORTED_PROFILE", "RULE_NOT_FOUND", "URL_REQUIRED", "URL_NOT_ALLOWED", "URL_FETCH_FAILED", "URL_FETCH_TIMEOUT", "URL_FETCH_DISABLED", "VALIDATION_TIMEOUT", "VALIDATION_FAILED", "SERVER_BUSY", "PARAMETER_REQUIRED", "INTERNAL_ERROR", "RATE_LIMITED" ] }, "ErrorObject": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" }, "details": { "type": [ "string", "object", "null" ] } } }, "ErrorResponse": { "type": "object", "required": [ "ok", "error", "code", "message" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "$ref": "#/components/schemas/ErrorObject" }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" }, "details": { "type": [ "string", "object", "null" ] } } }, "MetricsResponse": { "type": "object", "required": [ "ok", "service", "uptime_seconds", "metrics", "timestamp" ], "properties": { "ok": { "type": "boolean", "const": true }, "service": { "type": "string" }, "uptime_seconds": { "type": "integer", "minimum": 0 }, "metrics": { "type": "object", "required": [ "validation_requests_total", "validation_pass_total", "validation_fail_total", "rate_limited_total", "error_codes" ], "properties": { "validation_requests_total": { "type": "integer", "minimum": 0 }, "validation_pass_total": { "type": "integer", "minimum": 0 }, "validation_fail_total": { "type": "integer", "minimum": 0 }, "rate_limited_total": { "type": "integer", "minimum": 0 }, "error_codes": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } } }, "timestamp": { "type": "string", "format": "date-time" } } }, "RuleFinding": { "type": "object", "required": [ "rule_id", "clause", "severity", "occurrences", "title", "how_to_fix" ], "properties": { "rule_id": { "type": "string", "example": "7.3-1" }, "clause": { "type": "string", "example": "7.3" }, "severity": { "type": "string", "const": "error" }, "occurrences": { "type": "integer", "minimum": 1, "description": "Total failures of this rule in the document." }, "title": { "type": "string" }, "plain": { "type": "string" }, "impact": { "type": "string" }, "how_to_fix": { "type": "array", "items": { "type": "string" } }, "wcag": { "type": "array", "items": { "type": "string" } }, "object": { "type": [ "string", "null" ] }, "spec_description": { "type": [ "string", "null" ] }, "pages": { "type": "array", "items": { "type": "integer" } }, "samples": { "type": "array", "description": "Example occurrences, capped per rule.", "items": { "type": "object", "properties": { "message": { "type": "string" }, "location": { "type": "string" }, "page": { "type": [ "integer", "null" ] } } } } } }, "DocumentInfo": { "type": "object", "properties": { "pages": { "type": [ "integer", "null" ] }, "tagged": { "type": [ "boolean", "null" ] }, "has_structure_tree": { "type": [ "boolean", "null" ] }, "title": { "type": [ "string", "null" ] }, "title_displayed": { "type": [ "boolean", "null" ] }, "language": { "type": [ "string", "null" ] }, "pdf_version": { "type": [ "string", "null" ] }, "encrypted": { "type": [ "boolean", "null" ] }, "ua_identifier": { "type": [ "integer", "null" ] } } }, "DocumentWarning": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "NO_DOCUMENT_TITLE" }, "related_rule": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "hint": { "type": [ "string", "null" ] } } }, "RuleCatalogResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "profile": { "type": "string" }, "profile_id": { "type": "string" }, "standard": { "type": "string" }, "catalog_version": { "type": "string" }, "count": { "type": "integer" }, "rules": { "type": "array", "items": { "type": "object" } } } } } } }