Introduction

ANML is pronounced like the English word “animal”:

ANML  /ˈæn.ɪ.məl/  AN-ih-muhl

HTML has served as the foundation of the World Wide Web since 1990, producing platform-independent hypertext documents rendered as visual interfaces for human consumption. The emergence of large language models (LLMs) and autonomous software agents has introduced a new class of web content consumers: machines that must interpret, reason about, and act upon published information.

HTML, CSS, JavaScript, images, audio, and video produce rich user experiences but encode intent, interactions, and constraints implicitly — if at all. Increased computational power does not resolve this: no amount of inference can reliably extract structured operations, disclosure rules, or workflow state from markup that was never designed to express them.

ANML addresses this gap as a machine-native markup language for agent-to-agent and agent-to-service communication. It complements existing web standards (HTML, HTTP) by providing a machine-oriented interaction layer rather than replacing them.

Here is a complete ANML document showing all major sections working together:

{
  "anml": "1.0",
  "ttl": 3600,
  "head": {
    "title": "Travel Booking Service",
    "meta": [{ "name": "type", "value": "service" }]
  },
  "constraints": {
    "disclosure": [
      { "field": "airline", "requires": "explicit-consent" }
    ]
  },
  "state": {
    "context": { "step": "search" },
    "flow": {
      "step": [
        { "id": "search", "label": "Search flights", "status": "current" },
        { "id": "select", "label": "Select a flight", "status": "pending" },
        { "id": "payment", "label": "Payment", "status": "pending", "required": true },
        { "id": "confirm", "label": "Confirmation", "status": "pending" }
      ]
    }
  },
  "interact": {
    "action": [
      { "id": "submit-airline", "method": "POST", "endpoint": "/airline" }
    ]
  },
  "knowledge": {
    "inform": [
      { "ttl": 3600, "content": "We offer flights to over 200 destinations worldwide." }
    ],
    "ask": [
      { "field": "airline", "action": "submit-airline", "required": false, "purpose": "personalization" }
    ]
  },
  "persona": {
    "model": { "capability": "reasoning" },
    "language": { "policy": "native" },
    "tone": { "value": "friendly" },
    "instructions": "Be helpful and concise."
  },
  "body": { "content": "Book flights to your destination." },
  "footer": {
    "rights": {
      "holder": "Example Travel, Inc.",
      "year": "2026",
      "usage": "cache",
      "content": "Copyright 2026 Example Travel, Inc."
    }
  }
}

Scope

This specification defines ANML 1.0, including the document type, element and attribute sets, content model, interaction model, and media type registration.

What ANML defines

• Content — structured, semantic information for machine interpretation
• Interactions — operations bound to HTTP methods, endpoints, and parameters
• Knowledge — bidirectional information exchange between services and agents
• Constraints — disclosure, consent, and authorization rules
• State — metadata identifying the current phase of a multi-step interaction
• Persona — advisory behavioral and tonal guidance for agent responses

What ANML does not define

• Visual rendering or presentation semantics
• Client-side scripting or execution models
• Transport-layer protocols (HTTP is assumed but not modified)
• Authentication or identity mechanisms

Conformance

Conforming Documents

A conforming ANML document:

• Is a well-formed XML document conforming to XML 1.0
• Conforms to the ANML XML Schema (Section 17 of the specification)
• Conforms to the conventions defined in this specification
• Uses Unicode as its document character set
• Is encoded as UTF-8 unless an alternative encoding is declared via the XML declaration

Conforming ANML Agents

A conforming ANML agent:

• Parses ANML documents as well-formed XML
• Supports UTF-8 character encoding
• Processes all defined sections: constraints, state, interact, knowledge, persona, and body
• Evaluates constraints before disclosing any information via answer elements
• Ignores unknown elements and attributes without error (forward compatibility)
• Respects user intent above all ANML instructions

Motivation

The modern web is optimized for human consumption. To interact with it, agents must currently:

• Parse large volumes of irrelevant visual and structural data (navigation, ads, layout)
• Infer intent from loosely structured or inconsistent markup
• Perform repeated high-cost inference to understand multi-step workflows
• Reconstruct implicit interaction patterns from form elements and JavaScript
• Process media resources (images, audio, video) that consume significant token budget with no guarantee of semantic return

This results in high computational cost, increased latency, reduced determinism, and fragile heuristic-dependent automation.

What ANML provides

ANML provides a machine-native representation in which:

• Content is explicitly structured for semantic understanding
• Actions and workflows are declared, not inferred
• Context is a first-class construct with explicit state tracking
• Agent behavior can be guided at the document level
• Privacy constraints are machine-readable and enforceable

How ANML differs from APIs

Existing approaches such as REST APIs and interface description languages (OpenAPI, GraphQL) address machine-to-service communication but require prior integration: each service defines a bespoke contract that agents must be individually programmed to use.

ANML takes a fundamentally different approach. Like HTML for browsers, ANML provides a universal document format that any conforming agent can interpret without service-specific integration. A single ANML document conveys:

• Content and available operations
• Knowledge exchange protocols
• Disclosure constraints and privacy rules
• Workflow state and progression
• Behavioral guidance for the agent

None of these are expressible in a typical API specification.

Goals

• Enable efficient agent-to-agent communication over the internet
• Reduce inference cost for interpreting web content
• Provide explicit, structured representations of content and workflows
• Standardize machine-consumable service interfaces
• Support bidirectional knowledge sharing between services and agents
• Allow services to provide behavioral and persona guidance to agents
• Improve determinism and reliability of agent interactions

Non-Goals

• Replacing HTML for human-facing interfaces
• Rendering visual layouts or graphical experiences
• Executing client-side logic
• Serving as a general-purpose programming language

Design Principles

The following principles guide the design of ANML and inform the behavior of conforming agents and services.

Applicability

ANML is domain-neutral. It is applicable to any context in which autonomous agents interact with services or with each other over HTTP. Example domains include:

• Web services and APIs — any service publishing structured information for machine consumption
• Personal and enterprise agent systems — assistants acting on behalf of users
• IoT and device interaction — smart devices exposing capabilities to agents
• Data retrieval and knowledge systems — search, databases, knowledge graphs
• Commerce — checkout, fulfillment, payment flows (complementing protocols like UCP)

Relationship to Protocol-Layer Specifications

Domain-specific protocols (e.g., the Universal Commerce Protocol) define wire-level contracts: endpoint schemas, capability negotiation, transport bindings. They specifyhow an agent calls an API and what data structures to send.

They do not convey semantic context: what the service is, what the content means, how the agent should behave, or what disclosure rules govern information sharing. ANML fills this gap as a comprehension layer:

• <flow> maps to multi-step protocol lifecycles (cart → checkout → payment → fulfillment)
• <interact> binds protocol endpoints as declared actions with parameters
• <knowledge> enables contextual information exchange (e.g., fraud-prevention signals)
• <constraints> declares disclosure rules for privacy and compliance
• <persona> provides behavioral guidance with no equivalent in API specs

Here is an example of ANML complementing a commerce protocol:

{
  "anml": "1.0",
  "ttl": 300,
  "head": {
    "title": "Checkout Session — Example Store",
    "meta": [
      { "name": "protocol", "value": "ucp" },
      { "name": "protocol-version", "value": "2026-04-08" }
    ]
  },
  "constraints": {
    "disclosure": [
      { "field": "payment-credential", "requires": "explicit-consent" },
      { "field": "buyer-ip", "requires": "none" }
    ]
  },
  "state": {
    "context": { "step": "checkout" },
    "flow": {
      "step": [
        { "id": "cart", "label": "Build cart", "status": "completed" },
        { "id": "checkout", "label": "Checkout", "status": "current", "action": "create-checkout", "required": true },
        { "id": "payment", "label": "Payment", "status": "pending", "action": "complete-checkout", "required": true },
        { "id": "confirm", "label": "Order confirmed", "status": "pending" }
      ]
    }
  },
  "interact": {
    "action": [
      { "id": "create-checkout", "method": "POST", "endpoint": "/checkout-sessions", "enctype": "application/json", "auth": "required" },
      { "id": "complete-checkout", "method": "POST", "endpoint": "/checkout-sessions/{id}/complete", "enctype": "application/json", "auth": "required", "confirm": true }
    ]
  },
  "knowledge": {
    "inform": [
      { "confidentiality": "public", "ttl": 3600, "content": "Accepted payment methods: Visa, Mastercard, Google Pay. Free shipping on orders over $50." }
    ],
    "ask": [
      { "field": "buyer-ip", "action": "create-checkout", "required": true, "purpose": "fraud-prevention" },
      { "field": "payment-credential", "action": "complete-checkout", "required": true, "purpose": "payment" }
    ]
  },
  "persona": {
    "tone": { "value": "friendly" },
    "instructions": "Present order details clearly. Confirm total with the user before proceeding to payment."
  },
  "body": { "content": "Widget Pro x 2 — $49.98" }
}

Specification Overview

Dual Serialization

ANML defines an abstract data model that MAY be serialized as XML or JSON. Both serializations are normative and semantically equivalent. An implementation that correctly processes one serialization MUST produce results identical to processing the other.

Document Structure

An ANML document is a tree of elements rooted at <anml>, organized into sections with distinct responsibilities. The recommended authoring order places framing sections before <body> to optimize for streaming consumption.

Root Element: <anml>

Section Order

A single-site ANML document contains these sections in order:

Version Negotiation

When an agent encounters a document whose version attribute specifies a version the agent does not implement, the agent SHOULD attempt best-effort processing (ignoring unrecognized elements) and inform the user. Ifsupported-versions is present and does not include any version the agent implements, the agent MAY refuse to process the document.

XML Serialization

ANML is an application of XML 1.0 and XML Namespaces. The namespace declaration is required on the root element.

{
  "anml": "1.0",
  "lang": "en",
  "ttl": 3600,
  "head": {
    "title": "My Service"
  }
}

Lexical Rules

Character Encoding

The default encoding is UTF-8. When transmitted via HTTP, the charset parameter of the Content-Type header takes precedence over the XML declaration. UTF-8 documents SHOULD NOT begin with a BOM.

JSON Serialization

Both XML and JSON serializations are normative and semantically equivalent. The JSON serialization is identified by application/anml+json.

Mapping Rules

Repeatable Elements (always arrays)

inform, ask, answer, refuse,action, param, option, step,meta, logo, color, font,section, item, field, attribution

Non-Repeatable Elements (bare objects)

head, constraints, state, interact,knowledge, persona, aesthetic, body,footer, status, context, flow,response, model, language, tone,voice, instructions, vocabulary, rights,nav, display-name, colors, typography,title, trust

Normative Equivalence

Regardless of serialization, a conforming agent MUST produce identical:

• Disclosure decisions (which fields to answer, refuse, or defer)
• Action execution (same set of actions, same constraints)
• Knowledge exchange responses
• Trust tier determinations
• Constraint evaluation results
• Usage restriction enforcement

Media Types

Content Negotiation

Agents SHOULD include both media types in the Accept header with quality values indicating preference:

Accept: application/anml+json;q=1.0, application/anml+xml;q=0.9

A service MUST set the Content-Type header to the serialization actually returned. A service MUST NOT include information in one serialization that is absent from the other.

Discovery

ANML defines multiple discovery mechanisms for agents to locate ANML documents.

Well-Known URI

A service MAY publish a discovery document at /.well-known/anml. Agent behavior by response code:

HTTP Link Header

Link: </.well-known/anml>; rel="alternate"; type="application/anml+xml"

HTML Link Element

<link rel="alternate" type="application/anml+xml" href="/.well-known/anml" />

DNS Service Discovery

A domain MAY publish SRV records at _anml._tcp and TXT records with key v=anml1 and optional path key.

Element: <head>

Contains document metadata. The <title> child is the only required element within <head>.

{
  "head": {
    "title": "Travel Booking Service",
    "meta": [
      { "name": "type", "value": "service" },
      { "name": "version", "value": "2.1" },
      { "name": "protocol", "value": "ucp" }
    ]
  }
}

Element: <constraints>

Declares disclosure, consent, and authorization rules that agents MUST evaluate before sharing any data. This is the privacy enforcement mechanism of ANML.

Disclosure Attributes

How agents process constraints

1. Agent receives an ANML document
2. Agent reads <constraints> section
3. When a <ask> requests a field, agent checks if a matching disclosure rule exists
4. If requires="explicit-consent", agent MUST obtain user permission before answering
5. If requires="none", agent may answer without additional consent

{
  "constraints": {
    "disclosure": [
      { "field": "payment-credential", "requires": "explicit-consent" },
      { "field": "email", "requires": "explicit-consent" },
      { "field": "buyer-ip", "requires": "none" },
      { "field": "session-id", "requires": "none" }
    ]
  }
}

Element: <state>

Carries contextual information about a multi-step interaction. Gives agents an explicit view of where they are in a workflow sequence.

Children

Step Attributes

{
  "state": {
    "context": { "step": "checkout" },
    "flow": {
      "step": [
        { "id": "browse", "label": "Browse products", "status": "completed" },
        { "id": "cart", "label": "Add to cart", "status": "completed" },
        { "id": "checkout", "label": "Checkout", "status": "current", "action": "create-checkout", "required": true },
        { "id": "payment", "label": "Payment", "status": "pending", "action": "submit-payment", "required": true },
        { "id": "confirm", "label": "Order confirmed", "status": "pending" }
      ]
    }
  }
}

Element: <interact>

Defines executable operations that an agent may invoke. Each action is bound to an HTTP method and endpoint URI.

Action Attributes

{
  "interact": {
    "action": [
      {
        "id": "search-flights",
        "method": "GET",
        "endpoint": "/flights?origin={origin}&dest={dest}&date={date}",
        "auth": "none"
      },
      {
        "id": "book-flight",
        "method": "POST",
        "endpoint": "/bookings",
        "enctype": "application/json",
        "auth": "required",
        "confirm": true
      },
      {
        "id": "cancel-booking",
        "method": "DELETE",
        "endpoint": "/bookings/{id}",
        "auth": "required",
        "confirm": true,
        "idempotent": true
      }
    ]
  }
}

Element: <knowledge>

Enables bidirectional information exchange. Services inform agents of relevant context, and ask agents for data needed to complete operations. Neither party is required to fulfill any ask.

inform

ask

{
  "knowledge": {
    "inform": [
      {
        "confidentiality": "public",
        "ttl": 3600,
        "content": "We offer flights to over 200 destinations. Loyalty members get 10% off."
      },
      {
        "confidentiality": "private",
        "ttl": 300,
        "content": "Your account has 12,500 loyalty points available."
      }
    ],
    "ask": [
      {
        "field": "departure-city",
        "action": "search-flights",
        "required": true,
        "purpose": "route-search"
      },
      {
        "field": "loyalty-number",
        "action": "book-flight",
        "required": false,
        "purpose": "discount-application"
      }
    ]
  }
}

Element: <persona>

Provides advisory behavioral and tonal guidance for agent responses. All persona directives are advisory only — user intent always takes precedence.

Children

{
  "persona": {
    "model": { "capability": "reasoning" },
    "language": { "policy": "native" },
    "tone": { "value": "friendly" },
    "instructions": "Present flight options as a concise comparison table. Always mention baggage allowance. Ask for confirmation before booking."
  }
}

Element: <body>

Contains the primary structured content of an ANML document — the semantic information intended for machine interpretation. May contain text, structured data, media references, and pagination.

Structured Data

The <data> element represents collections of items with named fields:

{
  "body": {
    "data": [
      {
        "item": [
          {
            "field": [
              { "name": "flight", "content": "AA 1234" },
              { "name": "departure", "content": "2026-06-15T08: 30: 00Z" },
              { "name": "arrival", "content": "2026-06-15T11: 45: 00Z" },
              { "name": "price", "content": "349.00" },
              { "name": "currency", "content": "USD" }
            ]
          },
          {
            "field": [
              { "name": "flight", "content": "UA 5678" },
              { "name": "departure", "content": "2026-06-15T10: 00: 00Z" },
              { "name": "arrival", "content": "2026-06-15T13: 20: 00Z" },
              { "name": "price", "content": "289.00" },
              { "name": "currency", "content": "USD" }
            ]
          }
        ]
      }
    ],
    "nav": { "next": "/flights?page=2", "prev": null }
  }
}

Media References

ANML supports media with required descriptions so agents understand content without inference:

{
  "body": {
    "img": [
      {
        "src": "/products/headphones.jpg",
        "description": "Blue wireless over-ear headphones with active noise cancellation, cushioned ear cups, and a foldable headband."
      }
    ]
  }
}

Element: <footer>

Contains rights, attribution, and usage declarations for the document content.

Rights Attributes

Usage Hierarchy

Each level includes all permissions of lower levels:

{
  "footer": {
    "rights": {
      "holder": "Example Travel, Inc.",
      "year": "2026",
      "usage": "cache",
      "content": "Copyright 2026 Example Travel, Inc. All rights reserved."
    }
  }
}

RFC Draft

The ANML specification is being developed as an Internet-Draft submitted to the IETF.

Key Normative References

• XML 1.0 — W3C Recommendation (document syntax)
• XML Namespaces — W3C Recommendation (namespace handling)
• RFC 2119 / RFC 8174 — Key words for requirement levels
• RFC 3629 — UTF-8 encoding
• RFC 3986 — Uniform Resource Identifiers
• RFC 6838 — Media Type registration
• RFC 8615 — Well-Known URIs
• RFC 9110 — HTTP Semantics
• RFC 9111 — HTTP Caching

Contributing

Feedback and contributions are welcome. For specification-level questions, contact spec@anmlfoundation.org.