Document Service

The Document service validates Typograph templates against the schema and upgrades older templates to the current schema version. Both endpoints operate on a template that is hosted at a URL — the service downloads it, processes it, and returns the result inline.

Endpoints

Method	Path	Description	Token Type	Scopes
POST	/v1/document/validate	Validate a hosted template against a schema version	user or client	document, document:read
POST	/v1/document/upgrade	Upgrade a hosted template to a newer schema version	user or client	document, document:write
GET	/health/document	Liveness check proxied through the gateway	—	—

Both operational endpoints accept either a user token (Authorization Code / Refresh Token) or a client token (Client Credentials). See Token Types.

Request Body

Both endpoints share the same request body shape:

Field	Type	Required	Description
template_url	string (URL, max 2000 chars)	Yes	Publicly reachable URL of the template JSON file. The service HEAD-checks the URL and downloads the file. Only .json extensions are accepted.
version	string	No	Schema version to validate/upgrade against (e.g. "1.0.0"). Must match the pattern <major>.<minor>.<patch>. When omitted, the service uses the version declared inside the template.

The downloaded template file must be ≤ 50 MB.

Validate a Template

Check whether a template conforms to the Typograph schema.

curl -X POST https://api.typograph.nl/v1/document/validate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_url": "https://example.com/my-template.json",
    "version": "1.0.0"
  }'

Response — Valid Template

If the template is valid, the response is an empty array:

[]

Response — Validation Errors

If the template has violations, the response is an array of violation objects:

[
  {
    "property_path": "pages[0].elements[2].width",
    "message": "This value should be greater than 0.",
    "invalid_value": -10
  },
  {
    "property_path": "pages[1]",
    "message": "This value should not be null.",
    "invalid_value": null
  }
]

Violation Object

Field	Type	Description
property_path	string	JSON-path style pointer to the invalid property inside the template
message	string	Human-readable description of the violation
invalid_value	any	The value that failed validation

info

The service returns the violations array directly, not an { "valid": ..., "violations": [...] } envelope. Treat an empty array as "valid".

Upgrade a Template

Upgrade an older template to a target schema version. The response is the upgraded template JSON.

curl -X POST https://api.typograph.nl/v1/document/upgrade \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_url": "https://example.com/legacy-template.json",
    "version": "1.0.0"
  }'

Response

The upgraded template is returned inline, matching the target schema version:

{
  "version": "1.0.0",
  "type": "template",
  "metaData": { ... },
  "fontData": [ ... ],
  "swatches": [ ... ],
  "pages": [ ... ],
  "activePageIndex": 0
}

See the Documents concept page for the full template shape.

Schema Versions

The current shipping schema version is 1.0.0. The service validates the version parameter against the <major>.<minor>.<patch> pattern; pass a matching version string or omit the field to defer to the version declared inside the template payload itself.

Errors

HTTP	Error	Cause
400	Bad Request	template_url missing, not a URL, not reachable, or not a .json file
400	Bad Request	version provided but doesn't match X.Y.Z pattern
400	Bad Request	Downloaded file exceeds 50 MB
401	Unauthorized	Missing or invalid access token
403	Forbidden	Token lacks document scope (or document:read for validate / document:write for upgrade)

All errors follow the standard gateway JSON error format (see API Overview).

Use Cases

Pre-Submission Validation

Validate a template before handing it off to the Publisher service:

async function generatePdf(templateUrl, token) {
  const validation = await fetch('https://api.typograph.nl/v1/document/validate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ template_url: templateUrl, version: '1.0.0' })
  }).then(r => r.json());

  if (validation.length > 0) {
    throw new Error(`Template invalid: ${validation.length} violation(s)`);
  }

  return fetch('https://api.typograph.nl/v1/publisher/jobs', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template: { url: templateUrl },
      generator: { type: 'pdf' }
    })
  }).then(r => r.json());
}

Batch Upgrade

Upgrade a list of hosted templates to the current schema version:

async function upgradeAll(templateUrls, token) {
  const results = [];

  for (const url of templateUrls) {
    const upgraded = await fetch('https://api.typograph.nl/v1/document/upgrade', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ template_url: url, version: '1.0.0' })
    }).then(r => r.json());

    results.push({ source: url, upgraded });
  }

  return results;
}

Related

• Documents concept page — top-level template shape
• Pages / Elements / Styles
• Publisher Service — consumes validated templates
• Token Types — user vs client token decision