Apify Dataset JSON Schema Validator

Validate inline JSON records or Apify dataset items against a caller-provided JSON Schema. This JSON Schema validator writes one typed result per record, preserves the original record, and reports bounded, structured errors with instance paths and schema paths. It also stores aggregate valid and invalid counts for recurring data-quality gates.

Use it between extraction and downstream automation when malformed records should be visible before they reach a database, CRM, spreadsheet, model, or webhook.

What this Actor does

The Actor compiles your schema once and evaluates every selected record against it. It supports JSON Schema Draft 7 and Draft 2020-12, including common formats such as email, URI, date, and date-time.

For every record it exports:

• a valid boolean;
• the zero-based source index;
• the complete original record;
• the total validation error count;
• a bounded error list;
• JSON Pointer instancePath and schemaPath values;
• the failed keyword, message, parameters, and offending value;
• an ISO validation timestamp.

The SUMMARY key in the default key-value store contains processed, valid, and invalid counts.

Who is it for

Data engineers can put a deterministic contract check between scraping and loading.

Actor developers can test whether dataset output still conforms after a selector or API change.

Automation operators can inspect summary counts before triggering a downstream Task.

QA teams can export exact failure paths instead of manually comparing large JSON objects.

CRM and catalog teams can quarantine invalid records before importing them.

Why use an Actor for schema validation

A local validator is useful for one file. An Actor is useful when validation belongs in an Apify workflow: it can read an existing dataset, run on a schedule, expose API and MCP interfaces, and leave machine-readable output that another Actor, webhook, or integration can consume.

The implementation is deliberately lightweight:

• no browser is started;
• no proxy is used;
• no third-party validation API receives your records;
• the run is bounded by maxItems;
• error output is bounded by maxErrorsPerRecord.

Input sources

Choose exactly one source.

Inline records

Set records to an array of JSON objects. This is best for webhook payloads, API responses, small files, examples, and CI checks.

Apify dataset

Set datasetId to an Apify dataset ID or name readable by the run token. This is best for checking the output of a scraper or an earlier workflow step. Private datasets require a token with access. An unknown or inaccessible dataset fails the run.

Do not provide records and datasetId together.

Input parameters

Field	Type	Required	Default	Description
schema	object	yes	—	Draft 7 or Draft 2020-12 JSON Schema compiled once for all records.
records	array	conditional	—	Inline JSON objects. Use exactly one source.
datasetId	string	conditional	—	Readable Apify dataset ID or name. Use exactly one source.
maxItems	integer	no	10	Maximum records processed, from 1 to 10,000.
maxErrorsPerRecord	integer	no	20	Errors retained per record, from 1 to 100.

The schema is not generated or modified. Invalid and unsupported schemas fail closed before records are charged or written.

Getting started

1. Open the Actor input page.
2. Keep the prefilled product-like schema or paste your own schema.
3. Keep the inline example records, or remove them and enter a dataset ID.
4. Set a bounded maxItems for the first run.
5. Run the Actor.
6. Open Validation results to inspect one row per record.
7. Open Validation summary to read aggregate counts.
8. Use valid, errorCount, and SUMMARY.invalidCount in downstream decisions.

Inline input example

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": ["id", "email"],
    "properties": {
      "id": { "type": "integer" },
      "email": { "type": "string", "format": "email" }
    },
    "additionalProperties": false
  },
  "records": [
    { "id": 1, "email": "support@apify.com" },
    { "id": "2", "email": "not-an-email" },
    { "id": 3 }
  ],
  "maxItems": 100,
  "maxErrorsPerRecord": 20
}

This produces one valid row and two invalid rows.

Validate an Apify dataset

Remove records and pass the dataset identifier:

{
  "schema": {
    "type": "object",
    "required": ["url", "title"],
    "properties": {
      "url": { "type": "string", "format": "uri" },
      "title": { "type": "string", "minLength": 1 }
    }
  },
  "datasetId": "YOUR_DATASET_ID",
  "maxItems": 5000,
  "maxErrorsPerRecord": 25
}

The Actor reads dataset items in bounded pages and preserves their source order. When maxItems stops the read before source exhaustion, SUMMARY.sourceTruncated is true.

Validation result fields

Field	Meaning
recordIndex	Zero-based position in the selected source.
sourceType	inline or dataset.
sourceDatasetId	Dataset ID/name, or null for inline records.
valid	Whether the complete record conforms.
errorCount	Full number of errors found for the record.
errorsTruncated	Whether only the first configured errors were retained.
errors	Structured AJV errors with paths, keywords, messages, parameters, and values.
record	Original validated JSON object.
validatedAt	ISO 8601 validation timestamp.

Fields are nullable in the Actor's display schema so integrations remain resilient, but current successful result rows populate every field except sourceDatasetId for inline input.

Output example

{
  "recordIndex": 1,
  "sourceType": "inline",
  "sourceDatasetId": null,
  "valid": false,
  "errorCount": 2,
  "errorsTruncated": false,
  "errors": [
    {
      "instancePath": "/id",
      "schemaPath": "#/properties/id/type",
      "keyword": "type",
      "message": "must be integer",
      "params": { "type": "integer" },
      "value": "2"
    },
    {
      "instancePath": "/email",
      "schemaPath": "#/properties/email/format",
      "keyword": "format",
      "message": "must match format email",
      "params": { "format": "email" },
      "value": "not-an-email"
    }
  ],
  "record": { "id": "2", "email": "not-an-email" },
  "validatedAt": "2026-01-15T12:00:00.000Z"
}

Summary output

The SUMMARY record contains:

{
  "sourceType": "inline",
  "sourceDatasetId": null,
  "totalProcessed": 3,
  "validCount": 1,
  "invalidCount": 2,
  "maxItems": 100,
  "sourceTruncated": false,
  "maxErrorsPerRecord": 20,
  "completedAt": "2026-01-15T12:00:00.000Z"
}

A downstream automation can continue only when invalidCount equals zero.

How much does it cost to validate JSON records?

The Actor uses pay-per-event pricing:

• a one-time Run started event costs $0.0003 per run;
• each processed record uses one Record validated event;
• on the BRONZE tier, a record currently costs $0.000728.

At the BRONZE rate, 10 records cost about $0.00758, 100 cost about $0.0731, and 1,000 cost about $0.7283, including one start event. Valid and invalid records have the same processing value and the same item charge. Schema compilation failures and records never reached because input is invalid are not item-charged. Always check the live pricing tab for the tier applicable to your account.

Recurring data-quality workflow

A practical scheduled gate can be built as follows:

1. Run an extraction Actor into an Apify dataset.
2. Pass that dataset ID and the expected schema to this Actor.
3. Read SUMMARY.invalidCount through the API.
4. Continue to enrichment or import only when it is zero.
5. Otherwise export invalid rows and route their errors array to repair or investigation.
6. Keep prior run summaries to spot changes in failure rate.

This Actor reports current conformance. It does not compare runs or send alerts by itself.

Error paths and repair hints

instancePath points into the record, for example /contact/email. schemaPath points into the rule, for example #/properties/contact/properties/email/format. keyword identifies the violated constraint, such as required, type, format, or enum. params retains machine-readable context such as the missing property or expected type. value shows the value resolved at instancePath when available.

For object-level errors such as required and additionalProperties, the offending value may be the containing object. Use params.missingProperty or params.additionalProperty for the exact key.

API with cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~apify-dataset-json-schema-validator/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema":{"type":"object","required":["id"],"properties":{"id":{"type":"integer"}}},
    "records":[{"id":1},{"id":"wrong"}],
    "maxItems":100
  }'

Keep tokens in environment variables or secret storage, not committed source code.

API with JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/apify-dataset-json-schema-validator').call({
  schema: {
    type: 'object',
    required: ['id'],
    properties: { id: { type: 'integer' } },
  },
  records: [{ id: 1 }, { id: 'wrong' }],
  maxItems: 100,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

API with Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/apify-dataset-json-schema-validator').call(run_input={
    'schema': {
        'type': 'object',
        'required': ['id'],
        'properties': {'id': {'type': 'integer'}},
    },
    'records': [{'id': 1}, {'id': 'wrong'}],
    'maxItems': 100,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

Use with MCP

Add this Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/apify-dataset-json-schema-validator"

Claude Desktop, Cursor, and VS Code setup

Use this HTTP MCP configuration in Claude Desktop, Cursor, or VS Code:

{
  "mcpServers": {
    "apify-json-schema-validator": {
      "url": "https://mcp.apify.com?tools=automation-lab/apify-dataset-json-schema-validator"
    }
  }
}

Example prompts:

• “Validate these webhook records against this Draft 2020-12 schema and list every invalid path.”
• “Run the Apify dataset JSON Schema validator on dataset ID X, stopping after 500 items.”
• “Read the validation summary and tell me whether the downstream import should continue.”

Limits and failure behavior

• A run processes at most 10,000 records.
• Each record retains at most 100 errors; errorCount still reports the full count.
• Inline records and dataset items must be JSON objects, not primitive values or arrays.
• Draft 7 and Draft 2020-12 are supported; Draft 4 and custom meta-schemas are not promised.
• Remote $ref fetching is not enabled. Put required definitions in the supplied schema.
• Dataset access follows the permissions of the Actor run token.
• Extremely complex schemas can require more time than simple type and required-field checks.
• The Actor does not mutate, repair, quarantine, or delete source records.
• The Actor does not monitor prior runs or send notifications.

Malformed input, invalid schemas, conflicting sources, and inaccessible datasets fail the run with a specific log message. A naturally empty input succeeds with zero summary counts.

Tips for reliable gates

Start with a small maxItems while developing the schema. Set additionalProperties: false only when unexpected fields should block the pipeline. Use errorCount for metrics and errors for bounded diagnostics. Raise maxErrorsPerRecord only when downstream users need all failures. Pin a schema version in your own configuration so contract changes are reviewed. Keep reusable definitions under $defs or definitions in the same schema document.

Legality and responsible use

Only validate records you are authorized to process. Dataset access does not bypass Apify permissions. The Actor copies original records into its output dataset, so avoid sending unnecessary secrets, credentials, health data, or other sensitive fields. Apply suitable dataset retention and access controls. The Actor does not send records to a third-party validation service.

Troubleshooting

Why did the run reject my input immediately? Check that schema exists and that exactly one of records and datasetId is present.

Why can the Actor not open my dataset? Confirm the ID or name and ensure the run token can read it.

Why is errorCount larger than errors.length? The error list reached maxErrorsPerRecord; inspect errorsTruncated or raise the bound.

Why is a required-field error's instancePath empty? The failed rule applies to the containing object. Read params.missingProperty for the key.

Why did a schema fail to compile? Check the declared draft, keyword shapes, regular expressions, and local $ref definitions.

Related Automation Lab Actors

• Dataset Dedup removes duplicate records before or after validation.
• Schema-Guided Web Data to Excel extracts schema-guided fields and exports them to XLSX.
• Webpage Structured Data Monitor monitors structured data on public pages.

Use this Actor as a standalone validator when you already have JSON records and need explicit, portable JSON Schema conformance evidence.

FAQ

Does it generate a JSON Schema? No. Supply the exact contract you want enforced; schema inference is a different workflow.

Does it charge invalid records? Yes. An invalid record was fully evaluated and produces actionable output.

Can I validate multiple datasets in one run? No. Run one dataset per execution so source identity and summary counts remain unambiguous.

Can I validate nested objects and arrays? Yes. AJV applies your nested schema and reports JSON Pointer paths to failures.

Can another Actor consume the output? Yes. Read the default dataset for row-level results and SUMMARY for aggregate counts.

Can I schedule it? Yes. Use an Apify Schedule or invoke it from an Actor/Task chain with a current dataset ID.