The schema builder is a convenience. This page describes what actually crosses the wire.
When an Agent syncs its contract, what it sends is standard JSON Schema, plus a set of x-z3t-* extension keys the platform reads to decide how to render each field.
This reference is what you need when inspecting a compiled schema, or building your own SDK in an unsupported language.
Standard vocabulary
The platform understands this subset of standard JSON Schema keywords:
type, properties, required, items, enum, const, format, minimum / maximum, minLength / maxLength, pattern, minItems / maxItems, multipleOf, title, description.
These keep their spec-defined meaning. Anything affecting display or behaviour beyond the data contract belongs in an x-z3t-* key, not in a standard keyword.
Required by default
Unlike most schema systems, a field is required unless explicitly made optional.
In practice this means the "optional" marker in a builder must remove a key from the object's required array — never add it. An object with three properties and no optional markers lists all three in required.
The format keyword
format is only valid on type: "string", and only for constraints that actually validate the value.
format | Meaning |
|---|---|
email, uri, date, date-time | Standard JSON Schema formats — validated by the platform |
z3t-file-uri | File upload; value must start with z3t://files/ |
z3t-taxonomy-ref | Taxonomy reference; value must start with z3t://taxonomies/ |
z3t-integration-ref | Integration reference; value must start with z3t://integrations/ |
Do not use format for display hints. Values like markdown, html, code, json, image, and percent describe rendering, not validation — they belong in x-z3t-display. (Older SDKs emitted them as format and the backend still accepts that for compatibility, but new schemas must use x-z3t-display.)
Resource URIs
Files, taxonomies, and integrations are referenced by URI in the form z3t://{resourceType}/{id} — for example z3t://files/abc123. A handler resolves these through the context object.
Composite value shapes
Two output field types carry a value together with its rendering. Both the runtime value a handler returns and the schema declaration that advertises it are fully specified — don't guess at either.
PDF reference
A clickable chip that opens a specific page of an uploaded PDF.
Runtime value returned by a handler:
{ "format": "pdf-reference", "file": "z3t://files/abc123", "page": 12, "hint": "Liability clause" }page and hint are optional.
Schema declaration:
{
"type": "object",
"properties": {
"format": { "type": "string", "const": "pdf-reference" },
"file": { "type": "string", "format": "z3t-file-uri" },
"page": { "type": "integer" },
"hint": { "type": "string" }
},
"required": ["format", "file"],
"x-z3t-display": "pdf-reference"
}Typed value
A self-describing value; the frontend picks the renderer from format.
Runtime value:
{ "format": "markdown", "value": "**hi**" }format is one of text, markdown, number, date, boolean, enum.
Schema declaration:
{
"type": "object",
"properties": {
"format": { "type": "string", "enum": ["text", "markdown", "number", "date", "boolean", "enum"] },
"value": { "type": "string" }
},
"required": ["format", "value"],
"x-z3t-display": "typed-value"
}Full wire spec
The complete, language-agnostic specification — every HTTP endpoint, every default, and every behavioural rule needed to build an SDK — lives in BUILDING_AN_SDK.md in the public z3t-ai/sdks repository.