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
1. Design Goals
Section titled “1. Design Goals”The Zakardo type system must:
- Be JSON-native. All data in Zakardo is serialized as JSON. The type system must describe JSON structures natively.
- 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.
- Be human-readable and LLM-readable. The Planner (which may use an LLM) must be able to understand type definitions to generate valid plans.
- Support versioning. Types evolve. The system must detect breaking vs. compatible changes.
- Be extensible. Zakardo adds domain-specific annotations (effect class, boundary, interaction type) on top of base types.
- Have existing tooling. The type system should not be invented from scratch. It should build on a widely adopted standard.
2. Base: JSON Schema (Draft 2020-12)
Section titled “2. Base: JSON Schema (Draft 2020-12)”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 $reffor type references and reuse$defsfor local type definitions
What we do NOT use:
$idwith URI resolution (Zakardo uses its own namespace and versioning system instead).- Annotation keywords like
title,description,default,examplesare supported but not required. Zakardo adds its own annotation layer.
3. Zakardo Type Extensions
Section titled “3. Zakardo Type Extensions”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.
3.1 The x-zakardo Annotation
Section titled “3.1 The x-zakardo Annotation”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": { ... }}| Field | Type | Description |
|---|---|---|
kind | string enum | What this schema describes. Used by tooling and the Validator. |
version | semver string | Version of this schema definition. |
sensitive | boolean | If true, values conforming to this schema contain sensitive data (PII, credentials). Trace mode defaults to hash. |
trace_mode | string enum | How values are recorded in traces: full (store value), hash (store SHA-256 hash), omit (do not record). Default: full. |
description | string | Human-readable description. The Planner uses this to understand what the type represents. |
3.2 Schema Kinds
Section titled “3.2 Schema Kinds”The kind field classifies what a schema is used for:
| Kind | Used By | Description |
|---|---|---|
capability-input | Capability definitions | Schema for data a capability accepts as input. |
capability-output | Capability definitions | Schema for data a capability produces as output. |
interaction-response | Interaction Specs | Schema for data captured from user interactions (selections, inputs, confirmations). |
a2ui-component-input | A2UI Catalog definitions | Schema for data an A2UI component needs to render. |
a2ui-component-response | A2UI Catalog definitions | Schema for data an A2UI component captures from user interaction. |
context-data | Execution Context | Schema for structured data stored in the Execution Context. |
policy-param | Policy definitions | Schema for parameters used in policy rules. |
4. Primitive Types and Common Patterns
Section titled “4. Primitive Types and Common Patterns”4.1 Primitive Types
Section titled “4.1 Primitive Types”Zakardo uses the standard JSON Schema primitives:
| Type | JSON Schema | Example 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" } |
4.2 Zakardo Common Types
Section titled “4.2 Zakardo Common Types”Zakardo defines a standard library of reusable types under the zakardo://types/common/ namespace. These are referenced via $ref in schemas.
4.2.1 Identifiers
Section titled “4.2.1 Identifiers”{ "$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" } } }}4.2.2 Effect and Boundary Enums
Section titled “4.2.2 Effect and Boundary Enums”{ "$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" } } }}4.2.3 Timestamps and Durations
Section titled “4.2.3 Timestamps and Durations”{ "$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" } } }}4.2.4 Pagination and Collections
Section titled “4.2.4 Pagination and Collections”{ "$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." } } }}4.2.5 Error Types
Section titled “4.2.5 Error Types”{ "$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" } } }}5. Structural Compatibility
Section titled “5. Structural Compatibility”The Validator uses structural compatibility to check that data flowing between plan steps is type-safe.
5.1 Compatibility Rules
Section titled “5.1 Compatibility Rules”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.,
integeris compatible withnumber). - S’s constraints must be equal to or stricter than T’s (e.g., if T allows
minimum: 0, S withminimum: 1is compatible; S withminimum: -1is 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.
5.2 Compatibility Check Examples
Section titled “5.2 Compatibility Check Examples”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.
6. Type Versioning
Section titled “6. Type Versioning”6.1 Versioning Model
Section titled “6.1 Versioning Model”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.
6.2 Breaking Change Detection
Section titled “6.2 Breaking Change Detection”The Validator can detect breaking changes by comparing two versions of a schema:
| Change | Breaking for Output Schema? | Breaking for Input Schema? |
|---|---|---|
| Remove required property | Yes | No (input no longer needs it) |
| Add required property | No (output now provides more) | Yes (input now demands more) |
| Add optional property | No | No |
| Change property type | Yes | Yes |
| 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).
6.3 Version Pinning in Plans
Section titled “6.3 Version Pinning in Plans”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.
7. Data Binding Path Expressions
Section titled “7. Data Binding Path Expressions”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.
7.1 Supported Path Syntax
Section titled “7.1 Supported Path Syntax”| Expression | Meaning | Example |
|---|---|---|
$.inputs | The parsed intent inputs | $.inputs.date_range |
$.intent | The raw intent payload | $.intent.raw_text |
$.steps[N].out | The output of step N | $.steps[0].out.user_id |
$.steps[N].interaction_response | The user’s interaction response at step N | $.steps[1].interaction_response.selected_id |
$.system | System metadata | $.system.execution_id |
$.system.user | User context | $.system.user.tenant_id |
.property | Property 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 |
7.2 Path Expression Type Resolution
Section titled “7.2 Path Expression Type Resolution”The Validator resolves path expressions to their types at validation time:
- Parse the path expression.
- Walk the Execution Context schema (constructed from intent input schema + capability output schemas for each step).
- At each step, resolve the type of the referenced property.
- 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: stringResult: 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" }8. A2UI Component Schemas
Section titled “8. A2UI Component Schemas”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.
8.1 Block Schema Structure
Section titled “8.1 Block Schema Structure”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" } }}8.2 Block-to-Capability Compatibility
Section titled “8.2 Block-to-Capability Compatibility”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.
9. A2UI Message Schema
Section titled “9. A2UI Message Schema”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"] } } } }}10. Sensitive Data Handling
Section titled “10. Sensitive Data Handling”10.1 The sensitive Annotation
Section titled “10.1 The sensitive Annotation”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" } } }}10.2 Trace Modes
Section titled “10.2 Trace Modes”| Mode | Behavior | Use Case |
|---|---|---|
full | Store the complete value in the trace | Non-sensitive data. Default. |
hash | Store a SHA-256 hash of the value | PII that needs to be correlatable across traces but not readable. |
omit | Do not record the value | Credentials, API keys, passwords. |
The Execution Engine reads trace_mode from the schema annotations when recording capability outputs in the Trace.
10.3 Sensitive Data in A2UI Messages
Section titled “10.3 Sensitive Data in A2UI Messages”When A2UI Composition produces A2UI messages, it checks sensitive annotations:
- Fields marked
sensitivewithtrace_mode: "omit"are never included in A2UI data updates (they cannot be shown to the user). - Fields marked
sensitivewithtrace_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).
11. Schema Registry
Section titled “11. Schema Registry”All schemas in Zakardo are stored in and resolved from the Schema Registry, which is a logical partition within the Capability Registry.
11.1 Schema Namespacing
Section titled “11.1 Schema Namespacing”Schemas are namespaced to avoid collisions:
zakardo://types/common/EntityId/1.0.0 -- Built-in common typeszakardo://types/common/PaginatedList/1.0.0zakardo://capabilities/send_email/input/1.0.0 -- Capability schemaszakardo://capabilities/send_email/output/1.0.0zakardo://a2ui/DataTable/input/1.0.0 -- A2UI component schemaszakardo://a2ui/DataTable/response/1.0.0zakardo://blocks/SelectList/input/1.0.011.2 Schema References
Section titled “11.2 Schema References”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.
12. Summary of Decisions
Section titled “12. Summary of Decisions”| Decision | Resolution |
|---|---|
| Base type system | JSON Schema Draft 2020-12 |
| Extension mechanism | x-zakardo annotation namespace (compatible with standard tooling) |
| Compatibility model | Structural subtyping (output superset is compatible with input subset) |
| Versioning model | Semver with breaking change detection rules for input vs. output schemas |
| Path expression syntax | JSONPath subset ($.steps[N].out.field, $.inputs.field, $.system.field) |
| Sensitive data | Schema-level sensitive and trace_mode annotations |
| Schema storage | Schema Registry (logical partition of Capability Registry) with URI-based namespacing |
| A2UI message format | A2UI protocol messages with typed component instances and data model bindings |
| Schema inference | Plan Enrichment infers plan-level schemas from capability schemas in the registry. The Planner (LLM) never generates schemas. |
13. Questions Deferred
Section titled “13. Questions Deferred”| Question | Deferred 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 |