Schema validation

POST /v1/schemas/validate

Compiles a schema and reports every error in it, without extracting anything. Run it in CI, or while you’re writing a schema, to catch mistakes before they reach production: a schema that fails here fails the same way in POST /v1/extractions.

Auth: API key with scope schemas:validate.

Body

Parameter	Type	Required	Description
`schema`	object	yes	The schema to check.

Responses

Status	Meaning
`200`	The schema compiles. The body holds its `schema_hash` and any `warnings`.
`400 invalid_request`	The schema doesn’t compile. `error.details` lists the compile errors.
`401 unauthorized`	See Authentication.
`503 pipeline_unavailable`	The compiler service is unavailable. Try again shortly.

Example: a valid schema

This schema compiles, but its second relation, 1 == 1, can never fail, so Tickmarks drops it and warns you:

curl -X POST "$TICKMARKS_API/v1/schemas/validate" \
  -H "Authorization: Bearer $TICKMARKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "hydra_schema": "1.0",
      "name": "lease",
      "fields": [
        { "name": "startDate", "type": "date" },
        { "name": "endDate", "type": "date" }
      ],
      "relations": [
        { "id": "order", "expr": "startDate < endDate" },
        { "id": "always", "expr": "1 == 1" }
      ]
    }
  }'

{
  "schema_hash": "sha256:9a0c…",
  "warnings": [
    { "code": "W-REL-TRIVIAL", "message": "relation 'always' is always true", "pointer": "/relations/1" }
  ]
}

schema_hash identifies this exact schema, and every extraction response made with it carries the same hash. Store it alongside your results if you need to know later which version of a schema produced them.

Example: an invalid schema

Here the relation compares a date with a number, which has no meaning:

{
  "schema": {
    "hydra_schema": "1.0",
    "name": "lease",
    "fields": [
      { "name": "startDate", "type": "date" },
      { "name": "rate", "type": "decimal", "scale": 2 }
    ],
    "relations": [{ "id": "bad", "expr": "startDate < rate" }]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "The schema does not compile.",
    "details": [
      {
        "code": "E-TYPE",
        "message": "cannot compare date with decimal",
        "pointer": "/relations/0/expr",
        "span": [0, 16]
      }
    ]
  }
}

Each entry in details tells you what went wrong and where:

Member	Description
`code`	Stable error code. See Compile errors.
`message`	Human-readable; may change, so don’t parse it.
`pointer`	JSON pointer to the part of the schema at fault.
`span`	For expression errors: the `[start, end)` byte offsets of the problem in the expression string.