Target Audience:Specification ImplementorsPlatform TeamsStandards Committees

AXAG Specification Overview

Status: Draft 0.1.0
Classification: Normative
Last Updated: 2026-03-14

This document provides the normative specification for the Agent Context Annotation Guidelines (AXAG) standard. It defines the vocabulary, annotation primitives, required and optional fields, conformance levels, and validation rules that govern AXAG implementations.

Specification Scope

The AXAG specification defines:

1. Canonical Vocabulary — The set of reserved annotation attribute names and their semantics
2. Annotation Primitives — The atomic annotation units from which semantic contracts are composed
3. Field Requirements — Which fields are required at each conformance level
4. Semantic Dimensions — The categories of meaning that annotations can express
5. Conformance Levels — The tiers of implementation completeness
6. Validation Rules — The rules for checking annotation correctness
7. Versioning Model — How the specification evolves

Content Classification

This specification uses RFC 2119 keywords:

📋 Normative — MUST

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Content in this specification is classified as:

Classification	Meaning
Normative	Binding requirements. Implementations MUST comply.
Recommended	Best practices. Implementations SHOULD follow.
Informative	Explanatory context. Not binding.
Example	Illustrative code or configuration.
Proposed Pattern	Inferred implementation approach. Not yet canonical.

Conformance Levels

AXAG defines three conformance levels:

Basic Conformance Basic Conformance

Minimum viable annotation. Every annotated element MUST include:

Basic Conformance — Required Fields

Field	Type	Required	Description	Example
axag-intent	string	MUST	The semantic intent of the interaction	product.search
axag-entity	string	MUST	The domain entity being operated on	product
axag-action-type	enum	MUST	The operation classification: read, create, mutate, delete, navigate	read

Intermediate Conformance Intermediate Conformance

Production-ready annotation. In addition to Basic fields, every annotated element SHOULD include:

Intermediate Conformance — Additional Fields

Field	Type	Required	Description	Example
axag-required-parameters	string[]	MUST	JSON array of required parameter names	["query"]
axag-scope	string	MUST	The operational boundary	catalog
axag-risk-level	enum	MUST	Risk classification: none, low, medium, high, critical	none
axag-description	string	MUST	Human-readable operation description	Search the product catalog

Full Conformance Full Conformance

Enterprise-grade annotation. In addition to Intermediate fields, annotations SHOULD include all applicable semantic dimensions:

Full Conformance — Additional Fields

Field	Type	Required	Description	Example
axag-optional-parameters	string[]	MAY	JSON array of optional parameter names	["category","sort"]
axag-preconditions	string[]	MAY	Required state before execution	["cart_validated"]
axag-postconditions	string[]	MAY	Guaranteed state after execution	["order_created"]
axag-confirmation-required	boolean	MAY	Whether explicit confirmation is needed	true
axag-approval-required	boolean	MAY	Whether multi-party approval is needed	false
axag-idempotent	boolean	MAY	Whether the operation is safe to repeat	true
axag-side-effects	string[]	MAY	Observable changes beyond primary result	["email_sent"]
axag-required-roles	string[]	MAY	Roles permitted to invoke this operation	["admin"]
axag-rate-limit	string	MAY	Maximum invocation frequency	100/hour

Annotation Format

📋 Normative — MUST

AXAG annotations MUST be expressed as HTML data attributes prefixed with axag-. The prefix is reserved and MUST NOT be used for non-AXAG purposes.

Attribute Naming Convention

• All attributes use kebab-case: axag-intent, axag-action-type
• Array values are JSON-encoded strings: axag-required-parameters='["a","b"]'
• Boolean values use string "true" or "false"
• Enum values use lowercase strings from the defined vocabulary

Example: Minimal Annotation (Basic Conformance)

<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
>
  Search
</button>

Example: Full Annotation (Full Conformance)

<button
  axag-intent="checkout.begin"
  axag-entity="order"
  axag-action-type="mutate"
  axag-required-parameters='["cart_id","payment_method_id","shipping_address_id"]'
  axag-optional-parameters='["promo_code"]'
  axag-preconditions='["cart_validated","inventory_reserved"]'
  axag-postconditions='["checkout_session_created"]'
  axag-scope="customer"
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-side-effects='["inventory_locked","payment_hold_created"]'
  axag-description="Start checkout for a validated cart and create a checkout session"
>
  Checkout
</button>

Specification Sections

The full specification is organized into the following sections:

Section	Content
Canonical Vocabulary	Reserved attribute names and allowed values
Annotation Primitives	Atomic annotation units
Required Fields	Mandatory fields per conformance level
Optional Fields	Additional semantic dimensions
Entities	Entity naming conventions
Actions	Action type definitions
Parameters	Parameter declaration model
Constraints	Constraint declaration model
Risk Classification	Risk level definitions
Safety Boundaries	Confirmation, approval, rate limits
Confirmation Requirements	When and how confirmation is required
Approval Requirements	Multi-party approval model
Context Inheritance	How child elements inherit parent context
Namespacing	Namespace rules for custom extensions
Versioning	Specification version model
Error Semantics	Error code and message conventions
Conformance Levels	Detailed conformance requirements

Next Steps

• Canonical Vocabulary
• Annotation Primitives
• Semantic Manifest