Tools

validate_datachain

Validate a datachain instance against a schema version — always isError:false.

Invalid is a successful answer. This tool always returns with isError: false; semantic failures surface as ok: false in the envelope.

Summary

Parses a DTPR datachain instance, resolves the schema version, and runs both shape and semantic validation. Returns structured errors with fix_hints agents can feed back into a repair loop.

Input

Field	Type	Required	Description
`version`	`string`	yes	Schema version to validate against.
`datachain`	`object`	yes	Datachain instance JSON. See `schema_json.DatachainInstance` on `get_schema`. The optional `authoring_provenance` block (per-element `rationale`, `confidence`, `source_references` quotes) is accepted here — see Authoring provenance.

Output — valid

{
  "ok": true,
  "data": {
    "ok": true,
    "warnings": []
  },
  "meta": { "content_hash": "sha256-…", "version": "dtpr@2026-09-01-beta" }
}

Warnings are non-blocking — the instance is valid.

Output — invalid (soft-failure)

{
  "ok": false,
  "errors": [
    {
      "code": "REQUIRED_CATEGORY_MISSING",
      "message": "Instance is missing at least one element from required category 'purpose'",
      "severity": "error",
      "path": "instance.elements[].category_id",
      "fix_hint": "Add at least one element whose category_id is 'purpose' (category defined at categories[9])."
    }
  ],
  "meta": {
    "content_hash": "sha256-…",
    "version": "dtpr@2026-09-01-beta",
    "warnings": []
  }
}

The MCP tool result is isError: false in both cases. See envelope for the reasoning.

Errors

Code	Meaning	Fix
`invalid_arguments`	Missing `version` / non-object `datachain`.	Fix the call.
`parse_error`	Datachain shape is malformed (Zod parse).	Fix the offending field from `errors[].path`.
`unknown_version`	Version is not registered.	Call `list_schema_versions`.
`element_provenance_unknown_element`	A key in `authoring_provenance.element_provenance` doesn't match any placement `element_id`.	Remove the orphaned entry, or place an element with that id on `elements`.
`variable_rationale_unknown_variable`	A key inside an `element_provenance[<id>].variable_rationale` map references a variable not declared on the placed element's category.	Remove the entry, or declare the variable on the element's category (`element_variables`).
Semantic validator codes	Instance is shape-valid but semantically wrong.	Follow `fix_hint`.

Example — valid

curl -s https://api.dtpr.io/mcp \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{
      "name":"validate_datachain",
      "arguments":{
        "version":"dtpr@2026-09-01-beta",
        "datachain":{
          "id":"acme-resume-screener",
          "schema_version":"dtpr@2026-09-01-beta",
          "created_at":"2026-09-01T00:00:00Z",
          "elements":[
            {"element_id":"employment"},
            {"element_id":"organization","context_type_id":"deployer","variables":[
              {"id":"title","value":[{"locale":"en","value":"Acme Corp"}]},
              {"id":"description","value":[{"locale":"en","value":"Runs the screener."}]}]},
            {"element_id":"people","context_type_id":"subject","variables":[
              {"id":"title","value":[{"locale":"en","value":"Job applicants"}]},
              {"id":"description","value":[{"locale":"en","value":"Anyone who submits a resume."}]}]},
            {"element_id":"recommends","context_type_id":"human_decides"}
          ]
        }
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_datachain",
    "arguments": {
      "version": "dtpr@2026-09-01-beta",
      "datachain": {
        "id": "acme-resume-screener",
        "schema_version": "dtpr@2026-09-01-beta",
        "created_at": "2026-09-01T00:00:00Z",
        "elements": [
          { "element_id": "organization", "context_type_id": "deployer", "variables": [
            { "id": "title", "value": [{ "locale": "en", "value": "Acme Corp" }] },
            { "id": "description", "value": [{ "locale": "en", "value": "Runs the screener." }] }] },
          { "element_id": "people", "context_type_id": "subject", "variables": [
            { "id": "title", "value": [{ "locale": "en", "value": "Job applicants" }] },
            { "id": "description", "value": [{ "locale": "en", "value": "Anyone who submits a resume." }] }] },
          { "element_id": "recommends", "context_type_id": "human_decides" }
        ]
      }
    }
  }
}

The [tools/call] instance above is shape-valid but places no purpose element, so it returns an ok: false envelope with one REQUIRED_CATEGORY_MISSING entry. A payload that fails the shape check first — missing id, missing created_at, empty elements[] — returns parse_error entries instead; semantic rules never run.