API

Validate API

Validate report schemas before rendering to catch errors and receive actionable warnings.

Endpoint

POST /api/validate

The validate endpoint checks a report schema for structural errors and potential issues without rendering it.

Request

Send the template schema as the request body:

{
  "template": {
    "version": "1.0",
    "type": "report",
    "page": { "size": "A4", "orientation": "portrait" },
    "bands": [
      {
        "type": "header",
        "height": 40,
        "components": [
          {
            "type": "text",
            "position": { "x": 0, "y": 10, "width": 200, "height": 20 },
            "content": "Hello World",
            "fontSize": 14
          }
        ]
      }
    ]
  }
}

Response

The response indicates whether the schema is valid, along with any errors or warnings:

Valid schema

{
  "valid": true,
  "errors": [],
  "warnings": []
}

Schema with errors

{
  "valid": false,
  "errors": [
    {
      "path": "bands[0].height",
      "message": "Property 'height' is required for band type 'header'"
    },
    {
      "path": "bands[1].components[0].position",
      "message": "Property 'position' is required for component type 'text'"
    }
  ],
  "warnings": []
}

Schema with warnings

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "path": "bands[0].components[0].position.width",
      "message": "Component width (600mm) exceeds page width (530mm). Content may be clipped."
    }
  ]
}

Error format

Each error or warning has two fields:

FieldTypeDescription
pathstringJSON path to the problematic field
messagestringHuman-readable description of the issue

Validation rules

The validator checks for:

  • Required fields — version, type, page, bands
  • Type correctness — numbers where numbers are expected, valid enums
  • Band structure — valid band types, required height property
  • Component structure — valid component types, required position
  • Expression syntax — balanced {{ and }} delimiters
  • Page bounds — components within page margins (warnings)
  • Data binding — detail bands have a dataBinding property

Programmatic usage

You can also use the validation function directly in code:

import { validateReport } from '@nextreport/engine'

const result = validateReport(schema)

if (!result.valid) {
  console.error('Validation errors:', result.errors)
} else if (result.warnings.length > 0) {
  console.warn('Validation warnings:', result.warnings)
} else {
  console.log('Schema is valid')
}

Example with curl

curl -X POST http://localhost:3000/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "version": "1.0",
      "type": "report",
      "page": { "size": "A4", "orientation": "portrait" },
      "bands": []
    }
  }'

Next steps