REST API (v2)

POST /schemas/:version/validate

Validate a datachain instance against a schema version.

POST /schemas/:version/validate

The HTTP status is 200 for both ok: true and ok: false. Validation success/failure is a semantic answer carried in the body — it is not a transport failure.

Summary

Validate a DTPR datachain instance against a schema version. The response carries structured errors with fix_hints that an agent can feed into a repair loop.

Request

POST https://api.dtpr.io/api/v2/schemas/:version/validate
Content-Type: application/json

{ "schema_version": "ai@2026-04-16-beta", "elements": [ /* DatachainInstance */ ] }

Param	In	Description
`version`	path	Canonical version or alias.
(body)	JSON	A `DatachainInstance`. Shape is published in the schema's `schema_json`.

Response — valid

HTTP/1.1 200 OK
Content-Type: application/json
DTPR-Content-Hash: sha256-…
Cache-Control: no-store

{
  "ok": true,
  "warnings": [
    { "code": "placement_label_empty", "message": "…", "path": "elements[2].label" }
  ]
}

Response — invalid

HTTP/1.1 200 OK
Content-Type: application/json
DTPR-Content-Hash: sha256-…
Cache-Control: no-store

{
  "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'."
    }
  ],
  "warnings": []
}

Response — malformed JSON body

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok": false,
  "errors": [
    {
      "code": "bad_request",
      "message": "Invalid JSON body.",
      "fix_hint": "Send a valid JSON datachain-instance payload."
    }
  ]
}

Response — shape errors (400-adjacent)

When the JSON parses but the datachain shape fails Zod validation, the status stays 200 and the body carries code: parse_error entries:

{
  "ok": false,
  "errors": [
    {
      "code": "parse_error",
      "message": "Required",
      "path": "elements.0.element_id",
      "fix_hint": "Fix the field shape and retry."
    }
  ]
}

Errors

Code	HTTP	Meaning
`bad_request`	400	Invalid JSON body or malformed `:version`.
`not_found`	404	Version is not registered.
`parse_error`	200	Datachain shape failed Zod validation.
Semantic validator codes	200	Shape-valid but semantically wrong (`element_required`, placement / cardinality rules, etc.).

Example

curl -s https://api.dtpr.io/api/v2/schemas/ai@2026-04-16-beta/validate \
  -H 'content-type: application/json' \
  --data '{
    "schema_version": "ai@2026-04-16-beta",
    "elements": [{"element_id":"purpose.example","category_id":"purpose"}]
  }'

POST /api/v2/schemas/ai@2026-04-16-beta/validate HTTP/1.1
Host: api.dtpr.io
Content-Type: application/json

{"schema_version":"ai@2026-04-16-beta","elements":[…]}