# Api Specification Validator (`sovanza.inc/api-specification-validator`) Actor API Specification Validator checks OpenAPI 3.x specs and detects drift between documented API paths and Apify JS/Python client SDKs. It outputs structured findings, severity labels, path counts, and full JSON reports for CI/CD and API governance. - **URL**: https://apify.com/sovanza.inc/api-specification-validator.md - **Developed by:** [Sovanza](https://apify.com/sovanza.inc) (community) - **Categories:** Developer tools, Automation, Integrations - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $4.00 / 1,000 validation findings This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ### 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](https://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): ```json { "openApiUrl": "https://docs.apify.com/api/openapi.json", "checkTargets": ["javascript"], "failOnDrift": false, "reportClientOnlySurfaces": false } ```` Full validation example: ```json { "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: ```json { "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: ```json { "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 ```bash 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. # Actor input Schema ## `openApiUrl` (type: `string`): HTTPS URL to OpenAPI 3.x JSON or YAML (e.g. https://docs.apify.com/api/openapi.json). ## `openApiHeaders` (type: `object`): Extra headers when downloading the spec (e.g. private registry). Keys are header names. ## `checkTargets` (type: `array`): Which official clients to cross-check. ## `failOnDrift` (type: `boolean`): If true, the Actor exits with failure when any severity:error finding exists. ## `reportClientOnlySurfaces` (type: `boolean`): If true, emit warnings when a known client accessor exists but no matching /v2 path prefix was found in the spec. ## Actor input object example ```json { "openApiUrl": "https://docs.apify.com/api/openapi.json", "checkTargets": [ "javascript" ], "failOnDrift": false, "reportClientOnlySurfaces": true } ``` # Actor output Schema ## `findings` (type: `string`): Summary row and one row per validation issue (errors, warnings, info). ## `fullReport` (type: `string`): Complete validation report with all findings and metadata. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "openApiUrl": "https://docs.apify.com/api/openapi.json", "checkTargets": [ "javascript" ], "failOnDrift": false, "reportClientOnlySurfaces": false }; // Run the Actor and wait for it to finish const run = await client.actor("sovanza.inc/api-specification-validator").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "openApiUrl": "https://docs.apify.com/api/openapi.json", "checkTargets": ["javascript"], "failOnDrift": False, "reportClientOnlySurfaces": False, } # Run the Actor and wait for it to finish run = client.actor("sovanza.inc/api-specification-validator").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "openApiUrl": "https://docs.apify.com/api/openapi.json", "checkTargets": [ "javascript" ], "failOnDrift": false, "reportClientOnlySurfaces": false }' | apify call sovanza.inc/api-specification-validator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sovanza.inc/api-specification-validator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Api Specification Validator", "description": "API Specification Validator checks OpenAPI 3.x specs and detects drift between documented API paths and Apify JS/Python client SDKs. It outputs structured findings, severity labels, path counts, and full JSON reports for CI/CD and API governance.", "version": "0.0", "x-build-id": "lTm0uvzBfbUDzB2WT" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sovanza.inc~api-specification-validator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sovanza.inc-api-specification-validator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/sovanza.inc~api-specification-validator/runs": { "post": { "operationId": "runs-sync-sovanza.inc-api-specification-validator", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/sovanza.inc~api-specification-validator/run-sync": { "post": { "operationId": "run-sync-sovanza.inc-api-specification-validator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "openApiUrl": { "title": "OpenAPI document URL", "type": "string", "description": "HTTPS URL to OpenAPI 3.x JSON or YAML (e.g. https://docs.apify.com/api/openapi.json)." }, "openApiHeaders": { "title": "Optional fetch headers", "type": "object", "description": "Extra headers when downloading the spec (e.g. private registry). Keys are header names." }, "checkTargets": { "title": "Client targets", "uniqueItems": true, "type": "array", "description": "Which official clients to cross-check.", "items": { "type": "string", "enum": [ "javascript", "python" ] }, "default": [ "javascript", "python" ] }, "failOnDrift": { "title": "Fail run on drift", "type": "boolean", "description": "If true, the Actor exits with failure when any severity:error finding exists.", "default": false }, "reportClientOnlySurfaces": { "title": "Report client-only surfaces", "type": "boolean", "description": "If true, emit warnings when a known client accessor exists but no matching /v2 path prefix was found in the spec.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```