OpenAPI Publish Readiness and Example Conformance Gate

Audit the OpenAPI 3.x or Swagger 2.0 documents that you publish, before a partner reads them. The Actor downloads each document, resolves its references, validates every declared example against its own schema, and reports each defect with a JSON pointer, a rule ID, a severity and a suggested fix.

The Actor answers one question for the API platform team and for the developer relations engineer: can a mock tool, an SDK generator or a partner test suite use this specification without manual repair?

The Actor reads documents only. It sends no credential, it calls no protected endpoint, and it uses no browser and no proxy. The one write-free probe that it sends outside the documents is an unauthenticated HEAD against each declared server URL, and you can turn that probe off.

What the Actor checks

Rule ID	What it finds
OAS-PARSE-FAILED	The document could not be downloaded, or it is neither JSON nor YAML.
OAS-VERSION-UNKNOWN	The document declares no OpenAPI 3.x version and no Swagger 2.0 version.
OAS-NO-OPERATIONS	The document declares no path with an HTTP method.
OAS-OPERATIONS-TRUNCATED	The document holds more operations than maxOperationsPerSpec.
OAS-REF-UNRESOLVED	A $ref names nothing in the document. A generator stops here.
OAS-REF-EXTERNAL	A $ref points outside the document, so the document is not self-contained.
OAS-REF-CIRCULAR	Named schemas take part in a reference cycle.
OAS-OPERATION-ID-MISSING	An operation declares no operationId, so a client method has no name.
OAS-OPERATION-ID-DUPLICATE	Two operations share one operationId.
OAS-RESPONSES-MISSING	An operation declares no response at all.
OAS-RESPONSE-NO-SCHEMA	A response that carries a body declares no schema. A mock server cannot invent one.
OAS-EXAMPLE-INVALID	A declared example violates the schema next to it.
OAS-EXAMPLE-MISSING	A success response declares a schema and no example.
OAS-PAGINATION-MISSING	A GET that answers with a collection declares no pagination parameter.
OAS-SECURITY-SCHEMES-MISSING	The document declares no security scheme.
OAS-OPERATION-NO-SECURITY	An operation has no security requirement, and there is no global one.
OAS-SERVERS-MISSING	The document declares no server URL.
OAS-SERVER-NOT-ABSOLUTE	A declared server URL is not an absolute http or https URL.
OAS-SERVER-UNREACHABLE	A declared server URL did not answer the unauthenticated HEAD.

An example is checked against the keywords that an OpenAPI schema uses for a body: $ref, type, nullable, enum, const, required, properties, additionalProperties, items, minItems, maxItems, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, allOf, anyOf, oneOf and not. A keyword that the check does not know stays silent, so the Actor never invents a defect.

Profiles

A profile does not change what the Actor looks for. It changes the severity of each rule, and so it changes the gate result.

Profile	The question it asks
mock-readiness	Can a mock server answer every operation with a body? A response without a schema and an example that violates its schema are errors.
sdk-generation	Can a code generator name every operation and every type? An absent or duplicate operationId, an external reference and a reference cycle are errors.
partner-publication	Both questions, and also: can a partner find the service and does the partner know how to authenticate? This is the default.

The gate result of one document is FAIL when the document holds at least one defect that the profile calls an error, and PASS otherwise. A FAIL is a business verdict: the run reports it in the dataset and in the status message, and the run itself succeeds.

Input

Field	Type	Default	Meaning
specUrls	array of 1 to 50 URLs	the two public demo documents	The OpenAPI 3.x or Swagger 2.0 documents to audit. JSON and YAML are both read.
profile	mock-readiness, sdk-generation or partner-publication	partner-publication	Which question the gate asks.
checkServerReachability	boolean	true	Send one unauthenticated HEAD to each declared server URL.
maxOperationsPerSpec	integer 1 to 5000	1000	How many operations of one document are validated.
maxDefectsPerSpec	integer 1 to 5000	500	How many defect rows one document writes.
timeoutSecs	integer 2 to 120	30	Per-request timeout.
maxRedirects	integer 0 to 20	5	Redirect hops for each request. Every hop is checked again.
maxResponseBytes	integer 1000 to 20000000	20000000	Per-document body cap.

Every field has a schema default, so a run with the empty input {} audits the two public demo documents and succeeds.

Safety limits

• Only http and https URLs. No credentials in a URL.
• localhost, and any hostname that resolves to a private or reserved address, is refused. Every redirect hop is resolved and checked again.
• At most 50 documents, at most 20 MB for each document, at most 10 declared server URLs probed for each document, and at most 5 requests in flight at one time.
• YAML aliases are refused, so an alias bomb cannot expand.
• The reference walk, the schema walk and the example check are all depth-capped and node-capped. The check of one example may visit 5000 schema nodes, so a nest of anyOf, oneOf or not members cannot multiply the work without an end.
• A pattern is matched under a time limit, and all matches of one document share a five-second allowance. A value longer than 4000 characters is not matched. A match that reaches a limit reports nothing, because a pattern that the Actor cannot evaluate is not proof of a bad example.

Output

The dataset holds one gate summary row, one row for each document, and one row for each defect. The recordType field separates them.

Summary row (recordType: "summary"): profile, specsRequested, specsAudited, specsUnreadable, specsFailingGate, specsMockReady, specsSdkReady, operationsTotal, operationsValidated, examplesTotal, examplesThatViolateSchema, defectsTotal, errorDefects, warningDefects, gateResult, reasonCode, error, auditedAt.

Document row (recordType: "spec"): specUrl, specVersion, parseOk, operationsTotal, unresolvedRefs, circularRefs, duplicateOperationIds, missingOperationIds, examplesTotal, examplesThatViolateSchema, responsesWithoutSchema, listOperationsWithoutPaginationParameters, securitySchemesDeclared, operationsWithoutSecurity, servers[] (each with url, headStatus, reachable), mockReady, sdkReady, gateResult. The row also carries externalRefs, operationsValidated, operationsTruncated, serversDeclared, serversReachable, defectsTotal, errorDefects, warningDefects, defectsDropped, reasonCode, httpStatus, bytesRead, responseTimeMs and error.

Defect row (recordType: "defect"): specUrl, jsonPointer, ruleId, severity, message, suggestedFix.

mockReady is true when the document parses, holds no unresolved reference, leaves no body response without a schema, holds no example that violates its schema, declares an absolute server URL, and (when the probe is on) has at least one server that answers.

sdkReady is true when the document parses, holds at least one operation, and holds no unresolved reference, no external reference, no reference cycle, no duplicate operationId and no absent operationId.

Pricing: pay per event

Event	Unit	Counted as
run_start	one for each run	Charged once, before any document work. It pays for the container start.
spec_audited	one for each OpenAPI document downloaded, resolved and validated	Charged once for each document that parsed. A document that could not be downloaded or could not be parsed was never resolved and never validated, so it is not charged.
operation_batch_validated	one for each batch of 50 operations above the first 50	For each audited document: ceil((validated operations - 50) / 50), and 0 when the document holds 50 operations or fewer.

Every charge stays inside the run's maximum total charge. When the limit stops a charge, the Actor writes a warning to the log, and every row still reaches the dataset.

Repeat use

Run the gate in the release pipeline at each specification version, and again before each partner onboarding. The Actor keeps no state between runs: each run validates one version of each document against fixed rules.

Local development

uv sync
uv run pytest
uv run ruff check .