Skip to main content

Data validation

Add a schema.json to a template to validate incoming request data before it is rendered. Invalid data is rejected with HTTP 422 and never reaches the browser — so you never produce a broken or half-filled PDF.

Add a schema​

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["number", "customer"],
  "properties": {
    "number":   { "type": "string" },
    "customer": {
      "type": "object",
      "required": ["name"],
      "properties": { "name": { "type": "string" } }
    }
  }
}

Validation uses santhosh-tekuri/jsonschema; see its documentation for supported drafts and keywords.

What happens on invalid data​

curl -i -X POST -H 'Content-Type: application/json' \
  -d '{"customer": {}}' \
  http://localhost:9999/templates/invoice/render
# HTTP/1.1 422 Unprocessable Entity

The response body describes the schema violation.

Discover a template's schema​

The schema is published for clients and tooling:

curl http://localhost:9999/templates/invoice/schema.json

It is also referenced from the generated OpenAPI spec so the render endpoint documents its expected body.

Without a schema​

A template without schema.json accepts any JSON object. Validation is opt-in per template.

Compositions​

A composition's own schema.json validates the request data. Note that each child template's schema is not re-validated when reached through a composition — validate at the composition boundary. See Compositions.