This directory contains the complete JSON Schema definitions for the Agent Object Model (AOM)™ protocol. To validate surfaces and outputs, use the CLI from the repo root (aom.py / aom.mjs).
aom-input-schema.json (core surface schema)What it defines: The structure of an AOM surface (screen, modal, panel, widget, drawer).
Validates: *.aom.json files in examples/ (for example examples/v0.1.0/)
Key sections:
automation_policy — (Optional) Agent automation policy for a surface: forbidden | allowed | open. Conceptually:
forbidden — No automation; agents may read only enough AOM/policy to learn this rule, then MUST stop using this surface.allowed — READY / guardrailed mode; agents MUST treat the AOM as the only source of truth for actions and MUST NOT act based on DOM/HTML or other page content outside the AOM.open — Permissive mode; agents MAY go beyond the AOM’s explicit actions, using additional page content to infer reasonable actions (while still obeying global safety rules).purpose — Primary goal and user rolestasks — Explicit tasks the surface supports, including default_action_identities — Domain objects with schema (including validation), and current valuesactions — Operations agents can perform, including priority ranking and methodstate — Session and workflow state, including flow_id trackingnavigation — Breadcrumbs and neighbor surfacessignals — Errors, warnings, notifications, and automated test_casesUse when: Generating or consuming AOM from web/mobile screens.
aom-output-schema.json (agent output schema)What it defines: The structure of an agent’s response to an AOM surface.
Validates: *.output.json files in Examples/ or examples/ (typically under each surface’s outputs/ folder).
Key sections:
mode — "single" (one-shot) or "flow" (multi-step)thought — Agent’s reasoning (for debugging/transparency)action — Requested action with action_id + paramsresult — Final output (populated when meta.done: true)meta — Control flags including done, error, confidence, and optional a2h_intentUse when: Building agents that operate on AOM surfaces.
Secure/signed payloads are out of scope for this spec; any standard for signed envelopes or verification will be defined elsewhere.
AOM defines two machine-readable contracts. Both are required for AOM-compliant agent systems:
| Contract | Schema | File Extension | Purpose |
|---|---|---|---|
| Surface | aom-input-schema.json |
*.aom.json |
Describes what the agent sees (UI state, available actions, entities) |
| Output | aom-output-schema.json |
*.output.json |
Describes what the agent does (thought, action, result, confidence) |
Both schemas use semantic versioning:
0.1.0 (this document)1.0.0)0.2.0)0.1.1)Each AOM surface must declare its version:
{
"aom_version": "0.1.0",
...
}
These mirror the design intent throughout the spec:
forbidden / allowed / open control how agents may use the surface.AOM describes what users can accomplish (tasks, actions, entities), not the HTML structure.
Why: Agents reason about goals, not CSS selectors.
Domain objects (Product, Order, User) are first-class citizens with schemas, runtime validations, and current values.
Why: Agents operate on structured data, not unstructured text.
Actions declare their inputs, outputs, effects, priorities, and preconditions.
Why: Agents can plan, validate, and execute actions safely.
AOM natively supports automated testing via signals.test_cases and runtime escalation gating via meta.confidence.
Why: Agents require strict validation and human-in-the-loop fallback paths for enterprise reliability.
Supports both single-shot (one action → done) and flow (multi-step workflows).
Why: Different tasks have different execution patterns.
AOM is JSON. Works with any agent framework, LLM, or automation tool.
Why: Interoperability across ecosystems.
Both schemas use JSON Schema Draft 2020-12:
$schema: "https://json-schema.org/draft/2020-12/schema"ajv (Node) or jsonschema (Python)Input/core schema (aom-input-schema.json):
aom_version, surface_id, surface_kind, purpose, context, tasks, entities, actions, state, navigation, signalsgenerated_at, generator, a2hOutput schema (aom-output-schema.json):
mode, action (with action_id), meta (with done and confidence)agent_id, step_id, thought, resultBoth schemas allow additionalProperties: true in specific sections:
context — Add app-specific metadatastate — Add custom flags/valuesnavigation — Add extra routing infosignals — Add structured error objectsExample:
{
"context": {
"app_name": "MyApp",
"locale": "en-US",
"custom_tenant_id": "acme-corp",
"custom_feature_flags": ["beta_ui", "dark_mode"]
}
}
Entity schemas support arbitrary field types and custom validation rules:
{
"entities": {
"CustomWidget": {
"schema": {
"widget_id": {"type": "string", "required": true},
"config": {"type": "object", "required": false}
},
"current": {
"widget_id": "w123",
"config": {"color": "blue", "size": "large"}
}
}
}
}
binds_to (agents.json Integration)Actions can optionally reference external API/tool definitions via the binds_to field:
{
"actions": [
{
"id": "submit_checkout",
"label": "Place order",
"category": "mutation",
"description": "Submit checkout and create order.",
"input_entities": ["CheckoutIntent"],
"output_entities": ["OrderConfirmation"],
"effects": [
"entities.OrderConfirmation.current = shop_api.place(...)",
"state.workflow.step_id = 'order_placed'"
],
"binds_to": {
"type": "agent.workflow_step",
"ref": "place_order_confirm_checkout",
"optional": true
}
}
]
}
When to use:
Your runtime has an external tool registry (e.g., agents.json, MCP tools, OpenAPI specs)
You want agents to call real APIs instead of simulating via effects
When binds_to is present:
Runtime tries to resolve binds_to.ref from external registry
If found → use external tool schema (parameters, authentication, etc.)
If not found AND optional: true → fall back to AOM’s inline effects
If not found AND optional: false → fail with clear error
Schema:
type (string) — Namespace/type of external binding (e.g., “agent.workflow_step”, “mcp.tool”, “openapi.operation”)
ref (string) — External identifier (tool name, operation ID, etc.)
optional (boolean, default false) — Whether binding is required
Default behavior: If binds_to is omitted, runtime executes action using AOM’s effects only.
Roadmap: Auto-resolution from common tool registries.
AOM natively supports the industry-standard A2H protocol for safe Human-in-the-Loop (HITL) escalations. This allows the surface to dictate when an agent must pause and ask a human for approval or data.
aom-core-schema)The surface defines which actions require human intervention via the a2h_policy object on an action:
{
"actions": [
{
"id": "delete_database",
"label": "Delete Production DB",
"category": "mutation",
"a2h_policy": {
"requires_authorization": true,
"escalation_channel": "in_app"
}
}
]
}
aom-output-schema)When the agent realizes it needs to escalate (either due to the surface’s a2h_policy or low internal confidence), it outputs an a2h_intent inside the meta block:
{
"mode": "flow",
"action": { "action_id": "none" },
"meta": {
"done": false,
"confidence": 0.4,
"a2h_intent": {
"type": "AUTHORIZE",
"message": "I am about to delete the production database. Do I have your approval to proceed?"
}
}
}
Supported A2H Intents:
INFORM — One-way notification to the user.COLLECT — Request specific structured data from the user.AUTHORIZE — Request explicit approval for a high-risk action.ESCALATE — Hand off the entire workflow to a human support agent.RESULT — Report final task completion.Tools are organized by language under Tools/ so you can use only Python or only Node. See Tools/README.md.
# From repo root (pip install -r Tools/python/validate/requirements.txt first)
python Tools/python/validate/validate.py spec/v0.1.0/aom-input-schema.json examples/v0.1.0/login-single/login.aom.json
python Tools/python/validate/validate_all.py
python Tools/python/validate/validate_all.py v0.1.0/ecom-flow
# From repo root (npm install in Tools/node/validate first)
node Tools/node/validate/validate.js spec/v0.1.0/aom-input-schema.json examples/v0.1.0/login-single/login.aom.json
node Tools/node/validate/validate_all.js
node Tools/node/validate/validate_all.js v0.1.0/ecom-flow
Golden *.output.json files under each example’s outputs/ folder are generated by the create-outputs tools. From repo root:
python Tools/python/create-outputs/create_outputs.py
# or
node Tools/node/create-outputs/create_outputs.js
Initial public release (current)
signals.test_cases for automated golden-file testing overridestasks[].default_action_id to guide primary agent behavioractions[].priority and actions[].method for semantic agent planningentities.*.validation for runtime data quality checksstate.workflow.flow_id for orchestration context trackingmeta.confidence in the output schema for runtime safety gatingerror and workflow schemasFuture versions MAY introduce:
Q: Why separate surface and output schemas?
A: Surfaces describe what’s available (input to agent), outputs describe what the agent decided (output from agent). Different lifecycles, different consumers.
Q: Can I use AOM with non-LLM agents?
A: Yes. AOM is JSON. Any system that can parse JSON and make decisions can consume AOM.
Q: Does AOM require specific UI frameworks?
A: No. AOM is framework-agnostic. Generate it from React, Vue, mobile apps, or even server-rendered HTML.
Q: What about authentication/security?
A: AOM surfaces can include state.session.authenticated and state.session.user_id. Authorization logic lives in your runtime, not the schema.
Q: Can AOM represent native mobile screens?
A: Yes. surface_kind supports screens, modals, panels, drawers, widgets. The abstraction works for web and mobile.
entities.*.schema_org_type)context.locale)Found an issue or have a suggestion?
Schema improvements should maintain backward compatibility when possible.