JSON Schema Extensions

Z3T.ai schemas are standard JSON Schema plus a small set of extension keys.

Every platform-specific annotation uses the x-z3t- prefix. Because they're outside the JSON Schema vocabulary, generic tooling ignores them — but the Z3T.ai frontend reads them to decide how to render each field.

The core rule

Keep validation and presentation separate.

• format constrains a value — it's for validation. See the Schema Specification.
• x-z3t-* describes presentation and behaviour — it never changes what values are valid.

Extension keys

Key	Applies to	Purpose
x-z3t-hint	any field	Short helper text shown below the field
x-z3t-order	any field	Explicit sort position within the form
x-z3t-group	any field	Visual grouping label for adjacent fields
x-z3t-display	scalar / object	Rendering widget hint — see values below
x-z3t-code-language	string with x-z3t-display: 'code'	Syntax-highlight language
x-z3t-min / x-z3t-max	date, datetime	Min/max bounds (as ISO strings)
x-z3t-color-map	enum	Map of enum value → badge color, e.g. { ACTIVE: 'green' }
x-z3t-accept	z3t-file-uri	Accepted MIME types for the upload widget
x-z3t-max-size-mb	z3t-file-uri	Max upload size hint (MB)
x-z3t-taxonomy-slug	z3t-taxonomy-ref	Pre-select a specific taxonomy
x-z3t-integration-provider	z3t-integration-ref	Filter the integration dropdown to one provider
x-z3t-table-sortable / x-z3t-table-searchable	array with x-z3t-display: 'table'	Table interaction flags

x-z3t-display values

The widget used for a single field's value.

Value	Field type	Effect
'textarea'	string	Multi-line text input (form)
'markdown'	string	Markdown editor (form) / rendered Markdown (output)
'html'	string	Rendered sanitized HTML (output)
'code'	string	Code editor / highlighted block — use with x-z3t-code-language
'json'	string	Pretty-printed JSON block (output)
'image'	string	Inline image (output); value is a URL or z3t://files/{id}
'hidden'	string	Field is hidden in the form
'range'	number / integer	Slider input (form)
'percent'	number	Percentage bar (output); value must be 0–1
'toggle'	boolean	Toggle switch instead of a checkbox (form)
'radio'	enum	Radio buttons instead of a dropdown (form)
'table'	array	Sortable / searchable table (output)
'file-list'	array	List of download links for file-URI items (output)
'file-output'	string	Agent-produced file — download button (output)
'pdf-reference'	object	Clickable chip that opens a PDF preview
'typed-value'	object	Self-describing { format, value } rendered by inner format

Example

A field with both a rendering hint and metadata:

{
  "type": "string",
  "title": "Summary",
  "x-z3t-display": "markdown",
  "x-z3t-hint": "Written for a non-technical reader",
  "x-z3t-order": 1,
  "x-z3t-group": "Results"
}

An enum rendered as colored badges in the output:

{
  "type": "string",
  "enum": ["pass", "warn", "fail"],
  "x-z3t-color-map": { "pass": "green", "warn": "amber", "fail": "red" }
}

You rarely write these by hand — the schema builder emits them for you. This page is the reference for what it produces and what the platform accepts.

---

Continue learning

SDK Reference

For creators