Schema Requirements

Overview

We use JSON Schema to define the structure of extracted data.

Rules

Root must be an object type
Allowed types: string, number, integer, boolean, object, array
Primitive fields must be nullable: "type": ["string", "null"]
Maximum nesting level: 3
Array items: objects or primitives (string, number, integer, boolean)
Enums: strings only, must include null
Use description fields to provide context
Date values should use "custom:type": "date" on string fields
Validation rules should be modeled as a boolean field with beltic:validation and a sibling field_ref

Unsupported Features

Schema composition (anyOf, oneOf, allOf)
Regular expressions
Conditional validation
Constant values

Examples

Basic Schema

{
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": ["string", "null"],
      "description": "Invoice identifier"
    },
    "amount": {
      "type": ["number", "null"],
      "description": "Invoice amount"
    }
  },
  "required": ["invoice_number", "amount"]
}

With Nested Objects

{
  "type": "object",
  "properties": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": ["string", "null"] },
        "city": { "type": ["string", "null"] }
      },
      "required": ["street", "city"]
    }
  }
}

With Arrays

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": ["string", "null"] },
          "quantity": { "type": ["number", "null"] }
        }
      }
    }
  }
}

With Enums

{
  "type": "object",
  "properties": {
    "status": {
      "enum": ["pending", "approved", "rejected", null],
      "description": "Document status"
    }
  }
}

Validation Fields (Date Reference)

Date validations are configured on a boolean field, not on the date field itself. Use this pattern:

Source date field: type: ["string", "null"] + "custom:type": "date"
Validation field: type: ["boolean", "null"] + beltic:validation
field_ref must point to a sibling date field name in the same scope

{
  "type": "object",
  "properties": {
    "issue_date": {
      "type": ["string", "null"],
      "custom:type": "date",
      "description": "Document issue date"
    },
    "is_recent": {
      "type": ["boolean", "null"],
      "description": "Whether issue_date is recent enough",
      "beltic:validation": {
        "kind": "date_recency",
        "field_ref": "issue_date",
        "max_age_days": 90
      }
    }
  },
  "required": ["issue_date", "is_recent"]
}

Validation Fields in Nested Objects/Arrays

field_ref is scope-relative:

Inside an object, it references a field in that same object
Inside an array item object, it references a field in each item

{
  "type": "object",
  "properties": {
    "documents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "expiry_date": {
            "type": ["string", "null"],
            "custom:type": "date"
          },
          "is_valid": {
            "type": ["boolean", "null"],
            "beltic:validation": {
              "kind": "date_expiry",
              "field_ref": "expiry_date",
              "min_valid_days": 30
            }
          }
        },
        "required": ["expiry_date", "is_valid"]
      }
    }
  },
  "required": ["documents"]
}

Overview

Workflow API

Credentials API

Document API

Identity API (Legacy)

Overview

Rules

Unsupported Features

Examples

Basic Schema

With Nested Objects

With Arrays

With Enums

Validation Fields (Date Reference)

Validation Fields in Nested Objects/Arrays

​Overview

​Rules

​Unsupported Features

​Examples

​Basic Schema

​With Nested Objects

​With Arrays

​With Enums

​Validation Fields (Date Reference)

​Validation Fields in Nested Objects/Arrays

Overview

Rules

Unsupported Features

Examples

Basic Schema

With Nested Objects

With Arrays

With Enums

Validation Fields (Date Reference)

Validation Fields in Nested Objects/Arrays