Tools

validate_datachain

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

validate_datachain

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`.

Output — valid

{
  "ok": true,
  "data": {
    "ok": true,
    "warnings": [
      { "code": "placement_label_empty", "message": "…", "path": "elements[2].label" }
    ]
  },
  "meta": { "content_hash": "sha256-…", "version": "ai@2026-04-16-beta" }
}

Warnings are non-blocking — the instance is valid.

Output — invalid (soft-failure)

{
  "ok": false,
  "errors": [
    {
      "code": "element_required",
      "message": "Category 'purpose' requires at least one element.",
      "path": "elements",
      "fix_hint": "Add an element with category_id='purpose'."
    },
    {
      "code": "parse_error",
      "message": "Required",
      "path": "elements.0.element_id",
      "fix_hint": "Fix the field shape and retry."
    }
  ],
  "meta": {
    "content_hash": "sha256-…",
    "version": "ai@2026-04-16-beta",
    "warnings": ["placement_label_empty: …"]
  }
}

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`.
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":"ai@2026-04-16-beta",
        "datachain":{
          "schema_version":"ai@2026-04-16-beta",
          "elements":[
            {"element_id":"purpose.example","category_id":"purpose"}
          ]
        }
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_datachain",
    "arguments": {
      "version": "ai@2026-04-16-beta",
      "datachain": { "schema_version": "ai@2026-04-16-beta", "elements": [] }
    }
  }
}

Example — invalid

The call above with elements: [] returns an ok: false envelope whose errors[] contains one entry per missing required category.