Api Specification Validator

API Specification Validator – OpenAPI Schema & Client Consistency Checker

Validate OpenAPI 3.x specifications and detect drift between documented API paths and official Apify client SDK surfaces (JavaScript and Python). Built for API teams, platform engineers, and CI/CD pipelines that need structured validation reports—not manual spec-vs-code comparisons.

What is API Specification Validator and How Does It Work?

API Specification Validator is an Apify Actor that downloads an OpenAPI document from a URL, confirms it is OpenAPI 3.x, extracts path entries, and cross-checks curated Apify API v2 resource bindings against root accessors on apify-client (JS) and apify-client (Python).

It is designed for:

• API maintainers keeping docs aligned with SDKs
• Platform teams validating Apify API exports
• CI/CD jobs that fail builds when failOnDrift is enabled
• Governance workflows that need auditable finding rows

What it validates:

• OpenAPI structure (3.x required)
• Path inventory and Apify /v2/... prefix coverage (when present)
• Spec ↔ JavaScript client accessor mapping
• Spec ↔ Python client factory mapping
• Optional warnings for client-only surfaces not documented in the spec

What it does not do: full OpenAPI linting, request/response contract testing, or arbitrary third-party SDK analysis beyond the curated bindings list.

Why Use This Tool?

Problem	How this Actor helps
OpenAPI spec is outdated	Fetches live URL each run and reports path count + version
SDK exposes undocumented resources	Optional reportClientOnlySurfaces warnings
Spec documents paths missing in clients	Error findings for spec_vs_javascript / spec_vs_python
No audit trail	Dataset rows per finding + full JSON in KV store

➡️ Automated drift detection between spec and official Apify clients—ideal when your spec is the Apify API or another API that uses /v2/ path prefixes.

What It Validates

OpenAPI structure

• Document must be a parseable object with openapi: 3.x
• Supports JSON and YAML (by content-type or URL extension)

Apify path ↔ client mapping

Curated bindings compare spec path prefixes such as /v2/datasets with:

• JavaScript: ApifyClient.datasets, actors, runs, etc.
• Python: datasets, actors, runs, etc.

Bindings cover acts, builds, datasets, key-value stores, request queues, runs, tasks, schedules, users, webhooks, store, logs, and related resources (see RESOURCE_BINDINGS in src/main.js).

Drift detection

Severity	Typical cause
error	Spec documents a /v2/... prefix but the selected client lacks the expected accessor
warning	Client exposes an accessor but the spec has no matching path prefix (when enabled)
info	Summary, scope notes, or non-Apify specs (no /v2/ paths)

How to Use on Apify

Using the Actor

1. Go to API Specification Validator on the Apify platform.
2. Set openApiUrl to your OpenAPI 3.x JSON or YAML URL (e.g. Apify API export from docs.apify.com/api/v2).
3. Optionally set openApiHeaders for private specs.
4. Choose checkTargets: javascript, python, or both.
5. Run the Actor and review findings in the Dataset tab.
6. Download the full report from the key-value store or use Output schema links.

Apify Console (health check & monetization)

After deploying build 0.2+:

1. Health check: prefilled input uses https://docs.apify.com/api/openapi.json, checkTargets: ["javascript"], and failOnDrift: false — should finish in under 5 minutes.
2. Monetization (Console only): in Publication → Monetization, switch to Pay per event without passing platform usage to users.

Input Configuration

Health-check / Try actor (fast):

{
  "openApiUrl": "https://docs.apify.com/api/openapi.json",
  "checkTargets": ["javascript"],
  "failOnDrift": false,
  "reportClientOnlySurfaces": false
}

Full validation example:

{
  "openApiUrl": "https://docs.apify.com/api/openapi.json",
  "openApiHeaders": {},
  "checkTargets": ["javascript", "python"],
  "failOnDrift": false,
  "reportClientOnlySurfaces": true
}

Field	Description
openApiUrl	HTTPS URL to OpenAPI 3.x JSON or YAML. Defaults to https://docs.apify.com/api/openapi.json when omitted.
openApiHeaders	Optional headers when downloading the spec (e.g. auth for private registries).
checkTargets	Which clients to cross-check: javascript, python, or both (default: both).
failOnDrift	If true, the run fails when any severity: "error" finding exists.
reportClientOnlySurfaces	If true, warn when a known client accessor exists but the spec has no matching /v2/ prefix (default: true; only meaningful when the spec contains /v2 paths).

Output

The Actor exposes two outputs (see Output schema in Console):

Output	Description
Dataset findings	Summary row + one row per issue (?view=overview)
Full JSON report	API_SPEC_VALIDATION_REPORT.json in the default key-value store

Dataset row types

type	Description
summary	Parsed OpenAPI version and path count
finding	One validation issue or drift signal

Dataset fields (findings)

Field	Description
severity	info, warning, or error
category	e.g. openapi, spec_vs_javascript, spec_vs_python, client_without_spec_prefix
message	Human-readable detail
resourceId	Binding id (e.g. datasets)
pathPrefixes	Related /v2/... prefixes
specPresent	Whether the spec documents those paths
javascriptOk / pythonOk	Client accessor check result
openapiVersion / pathCount	On summary rows
checkedTargets	Clients checked in this run

Empty fields are omitted from dataset rows (compactObject) so the table stays clean.

Example summary row:

{
  "type": "summary",
  "severity": "info",
  "category": "openapi",
  "message": "Parsed OpenAPI 3.0.3 with 412 path entries.",
  "openapiVersion": "3.0.3",
  "pathCount": 412,
  "checkedTargets": ["javascript", "python"]
}

Example error finding:

{
  "type": "finding",
  "severity": "error",
  "category": "spec_vs_javascript",
  "message": "Spec documents /v2/datasets but apify-client-js has no `datasets` accessor on ApifyClient.",
  "resourceId": "datasets",
  "pathPrefixes": ["/v2/datasets"],
  "specPresent": true,
  "javascriptOk": false,
  "pythonOk": true,
  "checkedTargets": ["javascript", "python"]
}

Full JSON report (KV store)

Key: API_SPEC_VALIDATION_REPORT.json

Includes openApiUrl, checkedTargets, openapiVersion, pathCount, generatedAt, and the full findings array.

How the Validator Works

1. Fetch OpenAPI document from openApiUrl (with optional headers).
2. Parse JSON or YAML and assert OpenAPI 3.x.
3. Collect normalized path keys from paths.
4. Introspect JavaScript ApifyClient prototype and Python client factories (via scripts/dump_python_client.py).
5. Compare each curated resource binding: spec present ↔ client accessor.
6. Emit findings to the dataset and write the full report to the key-value store.
7. Fail the run if failOnDrift and any error-level finding exists.

Use Cases

• API schema validation — Confirm OpenAPI 3.x structure before publishing docs
• SDK consistency checks — Ensure Apify clients match documented /v2 resources
• CI/CD gates — Set failOnDrift: true in scheduled or PR validation runs
• API governance — Track drift across environments and spec versions
• Early drift detection — Catch mismatches before customers hit undocumented surfaces

Integrations & API

• Run on Apify with API, schedules, and webhooks
• Export dataset as JSON/CSV for dashboards
• Pull API_SPEC_VALIDATION_REPORT.json from the key-value store API
• Chain after doc publish jobs: validate spec when OpenAPI URL updates

FAQ

What is an API specification validator?

A tool that checks whether an OpenAPI schema is structurally valid and consistent with client SDK implementations. This Actor adds Apify-specific /v2 path ↔ client accessor checks.

Does this validate OpenAPI 3.x only?

Yes. The Actor requires openapi version starting with 3..

How does it detect API drift?

It compares path prefixes from the spec against known client accessors. Errors mean the spec documents a resource the client does not expose (for the checked target); warnings can mean the client exposes something not found in the spec.

Can I use this for non-Apify APIs?

Yes. Structural parsing and path counting still run. Apify-specific drift rules apply only when paths include /v2/; otherwise client-only warnings are skipped with an informational message.

What clients are supported?

• JavaScript — apify-client (Node.js), reflection on ApifyClient
• Python — apify-client, factory names via bundled introspection script

Is this a full OpenAPI linter?

No. It focuses on structure (3.x), path inventory, and curated client comparison—not exhaustive schema rule packs or live HTTP contract tests.

What happens if validation fails?

If failOnDrift is true and any error finding exists, the Actor exits with failure. Otherwise the run succeeds and findings remain in the dataset for review.

Does it support private API specs?

Yes. Pass authentication or custom headers via openApiHeaders.

Why are some boolean fields missing on rows?

The Actor uses compactObject to omit null/undefined fields so the Console table does not show empty columns.

SEO Keywords (high-intent)

openapi validator apify
api specification validator
openapi 3 drift detection
apify client consistency check
spec vs sdk validation
api governance automation
openapi ci cd validation
apify api v2 openapi

Why Choose This Actor?

• Purpose-built for Apify API + official clients
• Structured dataset findings plus full JSON report
• Optional fail-on-drift for CI/CD
• Clean output without null column clutter
• Works with public or header-protected spec URLs

Limitations

Item	Detail
Curated bindings	Only listed /v2 resources are compared; extend RESOURCE_BINDINGS for more coverage
Not full OpenAPI lint	No Spectral/Redocly-style rule engine
Python requires runtime	Python check runs python3 + dump_python_client.py in the container
Apify-centric drift rules	Client-only warnings require /v2 paths in the spec
Reflection-based JS check	Inspects ApifyClient prototype, not every nested method

Running Locally

cd api-specification-validator
npm install
apify run

Provide input via Console or storage/key_value_stores/default/INPUT.json when using Apify CLI local storage.

Deploy to Apify

1. Push from api-specification-validator/ (apify push or Git integration).
2. Build the Actor.
3. Run with a valid openApiUrl and review Output links for dataset findings and the full report.

Get Started

Point openApiUrl at your OpenAPI 3.x document, enable the client targets you care about, run once, and review summary + finding rows—then enable failOnDrift in CI when you are ready to gate releases on zero errors.