Skip to content

Type System

This document defines the type system used throughout Zakardo for capability schemas, Plan IR data bindings, Execution Context data, A2UI component schemas, and policy parameters.

Prerequisites: Glossary, System Architecture


The Zakardo type system must:

  1. Be JSON-native. All data in Zakardo is serialized as JSON. The type system must describe JSON structures natively.
  2. Enable structural compatibility checking. The Validator must be able to verify that the output of step A is compatible with the input of step B without executing anything.
  3. Be human-readable and LLM-readable. The Planner (which may use an LLM) must be able to understand type definitions to generate valid plans.
  4. Support versioning. Types evolve. The system must detect breaking vs. compatible changes.
  5. Be extensible. Zakardo adds domain-specific annotations (effect class, boundary, interaction type) on top of base types.
  6. Have existing tooling. The type system should not be invented from scratch. It should build on a widely adopted standard.

The Zakardo type system is based on JSON Schema Draft 2020-12 with Zakardo-specific extensions.

Rationale:

  • JSON Schema is the most widely adopted standard for describing JSON structures.
  • Extensive tooling exists for validation, code generation, and documentation.
  • LLMs are trained on vast amounts of JSON Schema and can read/write it fluently.
  • It supports structural subtyping natively (a value that satisfies a stricter schema also satisfies a looser one).
  • Draft 2020-12 is the latest stable version with full vocabulary support.

What we use from JSON Schema:

  • All standard types: string, number, integer, boolean, null, array, object
  • Object property definitions with properties, required, additionalProperties
  • Array item definitions with items, minItems, maxItems
  • Composition: allOf, anyOf, oneOf, not
  • Conditional: if, then, else
  • String formats: date-time, email, uri, uuid, etc.
  • Numeric constraints: minimum, maximum, multipleOf
  • String constraints: minLength, maxLength, pattern
  • $ref for type references and reuse
  • $defs for local type definitions

What we do NOT use:

  • $id with URI resolution (Zakardo uses its own namespace and versioning system instead).
  • Annotation keywords like title, description, default, examples are supported but not required. Zakardo adds its own annotation layer.

Zakardo extends JSON Schema with a x-zakardo annotation namespace. All Zakardo-specific metadata lives under this key to maintain compatibility with standard JSON Schema tooling.

Every schema in Zakardo may include an x-zakardo object with the following optional fields:

{
"type": "object",
"x-zakardo": {
"kind": "capability-input | capability-output | interaction-response | view-block-input | view-block-response | context-data | policy-param",
"version": "1.0.0",
"sensitive": false,
"trace_mode": "full | hash | omit",
"description": "Human-readable description for Planner consumption"
},
"properties": { ... }
}
FieldTypeDescription
kindstring enumWhat this schema describes. Used by tooling and the Validator.
versionsemver stringVersion of this schema definition.
sensitivebooleanIf true, values conforming to this schema contain sensitive data (PII, credentials). Trace mode defaults to hash.
trace_modestring enumHow values are recorded in traces: full (store value), hash (store SHA-256 hash), omit (do not record). Default: full.
descriptionstringHuman-readable description. The Planner uses this to understand what the type represents.

The kind field classifies what a schema is used for:

KindUsed ByDescription
capability-inputCapability definitionsSchema for data a capability accepts as input.
capability-outputCapability definitionsSchema for data a capability produces as output.
interaction-responseInteraction SpecsSchema for data captured from user interactions (selections, inputs, confirmations).
a2ui-component-inputA2UI Catalog definitionsSchema for data an A2UI component needs to render.
a2ui-component-responseA2UI Catalog definitionsSchema for data an A2UI component captures from user interaction.
context-dataExecution ContextSchema for structured data stored in the Execution Context.
policy-paramPolicy definitionsSchema for parameters used in policy rules.

Zakardo uses the standard JSON Schema primitives:

TypeJSON SchemaExample Values
String{ "type": "string" }"hello", ""
Integer{ "type": "integer" }42, 0, -7
Number{ "type": "number" }3.14, 42, -0.5
Boolean{ "type": "boolean" }true, false
Null{ "type": "null" }null
Array{ "type": "array", "items": {...} }[1, 2, 3]
Object{ "type": "object", "properties": {...} }{ "name": "Zak" }

Zakardo defines a standard library of reusable types under the zakardo://types/common/ namespace. These are referenced via $ref in schemas.

{
"$defs": {
"EntityId": {
"type": "string",
"format": "uuid",
"x-zakardo": {
"description": "A unique entity identifier (UUID v4)"
}
},
"CapabilityRef": {
"type": "object",
"required": ["name", "version"],
"properties": {
"name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
"version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
},
"x-zakardo": {
"description": "A reference to a specific capability name and version"
}
},
"PlanRef": {
"type": "object",
"required": ["plan_id", "version"],
"properties": {
"plan_id": { "$ref": "#/$defs/EntityId" },
"version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
},
"x-zakardo": {
"description": "A reference to a specific plan ID and version"
}
}
}
}
{
"$defs": {
"EffectClass": {
"type": "string",
"enum": ["READ", "WRITE_INTERNAL", "WRITE_EXTERNAL", "DESTRUCTIVE"],
"x-zakardo": {
"description": "The effect classification of a capability"
}
},
"Boundary": {
"type": "string",
"enum": ["LOCAL", "REMOTE", "USER_ENV"],
"x-zakardo": {
"description": "The execution boundary of a capability"
}
},
"ExecutionMode": {
"type": "string",
"enum": ["SIMULATED", "DRY_RUN", "LIVE"],
"x-zakardo": {
"description": "The execution mode for a plan run"
}
},
"LifecycleState": {
"type": "string",
"enum": ["CANDIDATE", "SHADOW", "PROMOTED", "DEPRECATED", "QUARANTINED"],
"x-zakardo": {
"description": "The lifecycle state of a plan"
}
}
}
}
{
"$defs": {
"Timestamp": {
"type": "string",
"format": "date-time",
"x-zakardo": {
"description": "ISO 8601 timestamp with timezone (e.g., 2026-02-05T14:30:00Z)"
}
},
"DurationMs": {
"type": "integer",
"minimum": 0,
"x-zakardo": {
"description": "Duration in milliseconds"
}
}
}
}
{
"$defs": {
"PaginatedList": {
"type": "object",
"required": ["items", "total", "offset", "limit"],
"properties": {
"items": { "type": "array" },
"total": { "type": "integer", "minimum": 0 },
"offset": { "type": "integer", "minimum": 0 },
"limit": { "type": "integer", "minimum": 1 }
},
"x-zakardo": {
"description": "A paginated list of items. The items array schema should be refined by the consumer."
}
}
}
}
{
"$defs": {
"ZakardoError": {
"type": "object",
"required": ["error_code", "message"],
"properties": {
"error_code": { "type": "string" },
"message": { "type": "string" },
"details": { "type": "object" },
"step_index": { "type": "integer", "minimum": 0 },
"capability_ref": { "$ref": "#/$defs/CapabilityRef" }
},
"x-zakardo": {
"description": "Standardized error structure used across all Zakardo components"
}
}
}
}

The Validator uses structural compatibility to check that data flowing between plan steps is type-safe.

A source schema S is compatible with a target schema T if every valid instance of S is also a valid instance of T. In practice:

Object compatibility:

  • Every required property in T must exist in S (with a compatible type).
  • S may have additional properties not in T (extra data is ignored by the consumer).
  • Property types must be recursively compatible.

Array compatibility:

  • The items schema of S must be compatible with the items schema of T.

Primitive compatibility:

  • Same type, or S is a subtype (e.g., integer is compatible with number).
  • S’s constraints must be equal to or stricter than T’s (e.g., if T allows minimum: 0, S with minimum: 1 is compatible; S with minimum: -1 is not).

Union compatibility:

  • If T is a union (oneOf, anyOf), S must be compatible with at least one member.
  • If S is a union, every member of S must be compatible with T.

Compatible:

Source (capability output): { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": ["id", "name", "email"] }
Target (next capability input): { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] }
Result: COMPATIBLE. Source has all required properties of target plus extra (email). Extra properties are ignored.

Incompatible:

Source (capability output): { "type": "object", "properties": { "user_id": { "type": "integer" } }, "required": ["user_id"] }
Target (next capability input): { "type": "object", "properties": { "user_id": { "type": "string" } }, "required": ["user_id"] }
Result: INCOMPATIBLE. Source produces user_id as integer, target expects string.

5.3 Compatibility Checking Is Performed By

Section titled “5.3 Compatibility Checking Is Performed By”
  • The Validator checks schema compatibility between plan steps before execution.
  • A2UI Composition checks that capability output data conforms to A2UI component input schemas.
  • The Capability Registry checks compatibility when upgrading capability versions.

All Zakardo schemas use Semantic Versioning (semver) for the x-zakardo.version field:

  • MAJOR (breaking): Removing a required field, changing a field’s type, tightening constraints on an output or loosening constraints on an input.
  • MINOR (compatible): Adding optional fields, adding new enum values to outputs, loosening constraints on an output.
  • PATCH (metadata only): Updating descriptions, examples, or annotations without changing the schema structure.

The Validator can detect breaking changes by comparing two versions of a schema:

ChangeBreaking for Output Schema?Breaking for Input Schema?
Remove required propertyYesNo (input no longer needs it)
Add required propertyNo (output now provides more)Yes (input now demands more)
Add optional propertyNoNo
Change property typeYesYes
Tighten constraint (e.g., reduce max length)Yes (output may violate consumer expectations)No (input accepts less)
Loosen constraint (e.g., increase max length)No (output still satisfies looser consumer)Yes (input now accepts values consumers may not handle)

The rules are inverted between input and output schemas because compatibility flows in opposite directions:

  • Output schemas are compatible if the new version produces a superset of what the old version produced (consumers can still read it).
  • Input schemas are compatible if the new version accepts a superset of what the old version accepted (producers can still send to it).

Plans reference capabilities by name and version constraint (semver range):

{
"capability": "send_email",
"version": "^1.0.0"
}

The Validator resolves the version constraint against the Capability Registry and checks compatibility. If the resolved version introduces breaking changes to schemas that affect the plan’s data bindings, validation fails.


The Execution Context is a structured JSON document. Plan IR uses path expressions to reference values within the context. These path expressions are a subset of JSONPath.

ExpressionMeaningExample
$.inputsThe parsed intent inputs$.inputs.date_range
$.intentThe raw intent payload$.intent.raw_text
$.steps[N].outThe output of step N$.steps[0].out.user_id
$.steps[N].interaction_responseThe user’s interaction response at step N$.steps[1].interaction_response.selected_id
$.systemSystem metadata$.system.execution_id
$.system.userUser context$.system.user.tenant_id
.propertyProperty access$.steps[0].out.items
[N]Array index access$.steps[0].out.items[0]
[*]All array items (for mapping operations)$.steps[0].out.items[*].id

The Validator resolves path expressions to their types at validation time:

  1. Parse the path expression.
  2. Walk the Execution Context schema (constructed from intent input schema + capability output schemas for each step).
  3. At each step, resolve the type of the referenced property.
  4. Verify the resolved type is compatible with the target input.

Example:

Plan step 2 has input binding: { "user_id": "$.steps[0].out.id" }
Step 0 capability output schema: { "properties": { "id": { "type": "string", "format": "uuid" } } }
Step 2 capability input schema: { "properties": { "user_id": { "type": "string" } } }
Validator resolves: $.steps[0].out.id -> type: string (format: uuid)
Target: user_id expects type: string
Result: COMPATIBLE (string with format uuid is a valid string)

7.3 Path Expression for Interaction Responses

Section titled “7.3 Path Expression for Interaction Responses”

When a capability has an Interaction Spec, the user’s response is stored at $.steps[N].interaction_response. The response schema is defined by the Interaction Spec’s response_schema.

Subsequent steps can bind to interaction response data:

Step 1: search_contacts capability
- Output: { contacts: Contact[] }
- Interaction Spec: SELECT, response_schema: { selected_contact_id: string }
Step 2: send_email capability
- Input binding: { "to": "$.steps[1].interaction_response.selected_contact_id" }

A2UI catalog components use the same type system for their input and response schemas. This ensures that A2UI Composition can validate that capability output data matches what a component expects.

Every A2UI catalog component definition includes:

{
"block_type": "DataGrid",
"input_schema": {
"type": "object",
"required": ["columns", "rows"],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "object",
"required": ["key", "label"],
"properties": {
"key": { "type": "string" },
"label": { "type": "string" },
"sortable": { "type": "boolean" },
"type": {
"type": "string",
"enum": ["string", "number", "date", "boolean", "currency"]
}
}
}
},
"rows": {
"type": "array",
"items": { "type": "object" }
}
},
"x-zakardo": { "kind": "view-block-input" }
},
"response_schema": {
"type": "object",
"properties": {
"selected_row_ids": {
"type": "array",
"items": { "type": "string" }
}
},
"x-zakardo": { "kind": "view-block-response" }
}
}

A2UI Composition checks that a capability’s output (or a subset of it) is compatible with an A2UI component’s input schema before producing A2UI messages. If incompatible, A2UI Composition falls back to a generic renderer or reports an error.


A2UI messages have a defined schema per the A2UI protocol. This is the contract between the runtime (A2UI Composition) and the frontend (A2UI Renderer).

{
"type": "object",
"required": ["descriptor_id", "view_type", "blocks"],
"properties": {
"descriptor_id": {
"type": "string",
"format": "uuid",
"x-zakardo": { "description": "Unique identifier for this view descriptor instance" }
},
"view_type": {
"type": "string",
"enum": ["ephemeral", "anchored", "plan_preview", "gate", "progress", "error"],
"x-zakardo": { "description": "The type of view this descriptor represents" }
},
"title": {
"type": "string",
"x-zakardo": { "description": "Human-readable title for the view" }
},
"description": {
"type": "string",
"x-zakardo": { "description": "Human-readable description or context message" }
},
"blocks": {
"type": "array",
"items": { "$ref": "#/$defs/ViewBlockInstance" },
"x-zakardo": { "description": "Ordered list of A2UI component instances to render" }
},
"layout": {
"$ref": "#/$defs/LayoutHint",
"x-zakardo": { "description": "How to arrange the blocks" }
},
"requires_response": {
"type": "boolean",
"x-zakardo": { "description": "If true, execution is paused and awaiting user response" }
},
"response_schema": {
"x-zakardo": {
"kind": "interaction-response",
"description": "Schema for the aggregate user response. Only present if requires_response is true."
}
},
"timeout_ms": {
"type": "integer",
"minimum": 0,
"x-zakardo": { "description": "Maximum time to wait for user response. 0 means no timeout." }
},
"metadata": {
"type": "object",
"properties": {
"execution_id": { "type": "string", "format": "uuid" },
"step_index": { "type": "integer", "minimum": 0 },
"capability_ref": { "$ref": "#/$defs/CapabilityRef" },
"plan_ref": { "$ref": "#/$defs/PlanRef" },
"source": {
"type": "string",
"enum": ["capability_output", "interaction_point", "gate", "plan_preview", "error"]
}
}
}
},
"$defs": {
"ViewBlockInstance": {
"type": "object",
"required": ["block_type", "data"],
"properties": {
"block_type": { "type": "string" },
"block_id": { "type": "string", "format": "uuid" },
"data": {
"type": "object",
"x-zakardo": { "description": "Data conforming to the block's input_schema" }
},
"response_key": {
"type": "string",
"x-zakardo": {
"description": "Key in the aggregate response where this block's response is placed"
}
}
}
},
"LayoutHint": {
"type": "object",
"properties": {
"direction": {
"type": "string",
"enum": ["vertical", "horizontal", "grid", "tabs"]
},
"max_width": { "type": "string" },
"spacing": { "type": "string", "enum": ["compact", "normal", "spacious"] }
}
}
}
}

Any schema field can be marked as sensitive:

{
"properties": {
"api_key": {
"type": "string",
"x-zakardo": { "sensitive": true, "trace_mode": "omit" }
},
"email": {
"type": "string",
"format": "email",
"x-zakardo": { "sensitive": true, "trace_mode": "hash" }
}
}
}
ModeBehaviorUse Case
fullStore the complete value in the traceNon-sensitive data. Default.
hashStore a SHA-256 hash of the valuePII that needs to be correlatable across traces but not readable.
omitDo not record the valueCredentials, API keys, passwords.

The Execution Engine reads trace_mode from the schema annotations when recording capability outputs in the Trace.

When A2UI Composition produces A2UI messages, it checks sensitive annotations:

  • Fields marked sensitive with trace_mode: "omit" are never included in A2UI data updates (they cannot be shown to the user).
  • Fields marked sensitive with trace_mode: "hash" are included in A2UI data updates only if the view explicitly needs them (the Anchored View or Interaction Spec must declare that it displays sensitive data).

All schemas in Zakardo are stored in and resolved from the Schema Registry, which is a logical partition within the Capability Registry.

Schemas are namespaced to avoid collisions:

zakardo://types/common/EntityId/1.0.0 -- Built-in common types
zakardo://types/common/PaginatedList/1.0.0
zakardo://capabilities/send_email/input/1.0.0 -- Capability schemas
zakardo://capabilities/send_email/output/1.0.0
zakardo://a2ui/DataTable/input/1.0.0 -- A2UI component schemas
zakardo://a2ui/DataTable/response/1.0.0
zakardo://blocks/SelectList/input/1.0.0

Schemas reference other schemas using $ref with the Zakardo namespace:

{
"properties": {
"user": { "$ref": "zakardo://types/common/EntityId/1.0.0" },
"deals": {
"type": "array",
"items": { "$ref": "zakardo://capabilities/query_deals/output/1.0.0#/properties/deal" }
}
}
}

The Validator, A2UI Composition, and Plan Enrichment resolve $ref URIs against the Schema Registry. Plan Enrichment uses the Schema Registry to:

  • Infer plan input/output schemas from the capabilities referenced in a Plan Draft.
  • Validate data flow between steps by checking that a step’s output schema satisfies the next step’s input schema requirements.
  • Convert simplified Plan Draft bindings to full Plan IR bindings by resolving field names against capability schemas.

DecisionResolution
Base type systemJSON Schema Draft 2020-12
Extension mechanismx-zakardo annotation namespace (compatible with standard tooling)
Compatibility modelStructural subtyping (output superset is compatible with input subset)
Versioning modelSemver with breaking change detection rules for input vs. output schemas
Path expression syntaxJSONPath subset ($.steps[N].out.field, $.inputs.field, $.system.field)
Sensitive dataSchema-level sensitive and trace_mode annotations
Schema storageSchema Registry (logical partition of Capability Registry) with URI-based namespacing
A2UI message formatA2UI protocol messages with typed component instances and data model bindings
Schema inferencePlan Enrichment infers plan-level schemas from capability schemas in the registry. The Planner (LLM) never generates schemas.

QuestionDeferred To
What are the complete schemas for all Zakardo Standard A2UI Catalog components?Frontend Architecture Specification
What is the full Plan IR schema?Plan IR Specification
What is the full Capability definition schema?Capability System Specification
What is the full Trace data model schema?Trace System Specification
What are the policy parameter schemas?Policy and Governance Specification