Document Templates

A Template is reusable, governed construction guidance. A MARKDOWN_DOCUMENT deliverable spec is the separate acceptance contract that describes the pages or files a document must produce.

Template Bindings

A document spec may select a Template with an owner-qualified binding:

json

1{
2  "ownerSpaceRef": {
3    "fence": "tenant",
4    "orgId": "org-123",
5    "space": {
6      "tier": "org",
7      "orgId": "org-123"
8    }
9  },
10  "target": {
11    "resourceKind": "template",
12    "resourceId": "template-architecture-decision-record",
13    "selector": {
14      "kind": "release-channel",
15      "channel": "stable"
16    }
17  }
18}

The owner is mandatory. Xema never guesses between organization, biome, or system resources with a similar slug. A release-channel selector is resolved to an exact revision before execution; an exact selector remains immutable as authored.

Creating a Markdown-Document Spec

The spec contains acceptance metadata and an optional Template binding. It does not contain reusable markdown, Handlebars, assets, or renderer code.

bash

1curl -X POST https://deliverable-specs-api.xema.dev/deliverable-specs \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "slug": "architecture-decision-record",
6    "version": "1.0.0",
7    "title": "Architecture decision record",
8    "kind": "MARKDOWN_DOCUMENT",
9    "category": "architecture",
10    "templateBinding": {
11      "ownerSpaceRef": {
12        "fence": "tenant",
13        "orgId": "org-123",
14        "space": { "tier": "org", "orgId": "org-123" }
15      },
16      "target": {
17        "resourceKind": "template",
18        "resourceId": "template-architecture-decision-record",
19        "selector": { "kind": "release-channel", "channel": "stable" }
20      }
21    },
22    "pages": [
23      { "slug": "decision", "title": "Decision" }
24    ]
25  }'

Omit templateBinding when the workflow or session supplies construction guidance separately. The document acceptance contract still applies.

What the Template Owns

A Template revision may contain parameter schemas, inline files, content-addressed assets, nested Template dependencies, and bounded render transforms. Its Template kind is open and biome-qualified, so new renderers do not require extending a platform enum.

Templates can depend on a DesignSystem. Publication resolves the complete dependency graph to exact revisions and rejects cycles or unauthorized cross-owner edges. Produced artifacts record the exact Template and DesignSystem pins used for the render.

What the Deliverable Spec Owns

The spec owns required files and pages, target slots, validation rules, review dimensions, and evaluation policy. Validation checks the harvested document against those requirements; it does not treat the Template as an acceptance contract.

Failure Behaviour

An unreadable binding, missing exact revision, hash mismatch, or unauthorized dependency fails the operation. Xema does not fall back to a similarly named Template or to retired inline spec content.

Next: Schema Validation →