| Internet-Draft | ANML 1.0 | May 2026 |
| Jeskey | Expires 21 November 2026 | [Page] |
ANML (Agentic Notation Markup Language) is a machine-first markup language for agent-to-agent and agent-to-service communication over the internet. HTML provides visual interfaces for human consumption; ANML describes content, intent, and interaction patterns optimized for machine interpretation with minimal computational overhead.¶
ANML defines an abstract data model that MAY be serialized as XML (application/anml+xml) or JSON (application/anml+json). Both serializations are normative and semantically equivalent. The XML serialization is recommended for human authoring and review; the JSON serialization is recommended for programmatic generation and agent-pipeline consumption.¶
An ANML document defines:¶
ANML standardizes these elements to enable deterministic, efficient agent interactions with reduced reliance on inference over unstructured data.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 2 November 2026.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
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. ANML complements existing web standards such as HTML and HTTP by providing a machine-oriented interaction layer, rather than replacing them. ANML is an application of XML 1.0 [XML].¶
The 'application/anml+xml' Internet Media Type is defined by this specification (see Section 6.1 (Section 6.1)).¶
This specification defines ANML 1.0, including the document type, element and attribute sets, content model, interaction model, and media type registration.¶
This specification does not define:¶
All domain names used in examples throughout this document are reserved example domains as defined in [RFC2606]: example.com, example.net, and example.org. These names do not refer to any real organization, product, or service. Where examples require multiple distinct domains, example.com is used for the canonical site domain, example.net for an authorized serving party, and example.org for a second authorized serving party or brand reference.¶
This specification governs the syntax of ANML documents and the behavior of conforming ANML agents.¶
A conforming ANML document:¶
A conforming ANML agent:¶
The modern web is optimized for human consumption. To interact with it, agents must currently:¶
This results in high computational cost, increased latency, reduced determinism, and fragile heuristic-dependent automation.¶
ANML provides a machine-native representation in which:¶
Existing approaches such as REST APIs and interface description languages (e.g., 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 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, available operations, knowledge exchange, disclosure constraints, workflow state, and behavioral guidance — none of which are expressible in a typical API specification.¶
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 but are not limited to:¶
ANML does not presume a commercial, consumer, or enterprise context. Any service that publishes structured information for machine consumption MAY use ANML.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The following principles guide the design of ANML and SHOULD inform the behavior of conforming agents and services.¶
Machine-First. ANML targets machine consumption, not human presentation.¶
Explicit Over Implicit. Interactions SHOULD be explicitly defined. Agents SHOULD NOT need to infer intent from ambiguous markup.¶
Minimize Inference Cost. Documents SHOULD be structured for direct interpretation, minimizing the need for inference.¶
Separation of Concerns. Each section of an ANML document has a distinct responsibility.¶
Privacy by Design. Agents control disclosure. Services MAY request information but MUST NOT require it.¶
Deterministic Behavior. Agents SHOULD produce consistent results given identical inputs.¶
Progressive Enhancement. ANML MAY be adopted incrementally alongside existing web infrastructure.¶
Domain Neutrality. ANML is domain-agnostic. It is not limited to commercial or e-commerce contexts and applies equally to any agent-to-agent or agent-to-service interaction.¶
Extensibility. Conforming agents MUST safely ignore unknown elements and attributes.¶
Trust Awareness. Agents SHOULD evaluate service trustworthiness before disclosing information or executing actions.¶
Human Intent First. User intent overrides all ANML instructions. An agent MUST NOT act contrary to the expressed wishes of its user.¶
ANML is an application of XML 1.0 [XML] and XML Namespaces [XMLNS]. This specification assumes familiarity with XML.¶
An ANML document is a well-formed XML document consisting of a hierarchy of elements as defined in Section 8.¶
The ANML namespace URI is:¶
urn:ietf:params:xml:ns:anml:1.0¶
A conforming ANML document MUST declare this namespace on the root element:¶
<anml xmlns="urn:ietf:params:xml:ns:anml:1.0"> ... </anml>¶
ANML inherits its lexical syntax from XML 1.0. The following subsections define additional constraints.¶
All element and attribute names defined by this specification are lowercase. Conforming documents MUST use lowercase names for all elements defined herein.¶
Attribute values MUST be enclosed in double quotes (U+0022). All attribute values are treated as strings. ANML does not define implicit type coercion.¶
Whitespace within element content is significant and MUST be preserved by conforming agents. ANML does not define whitespace collapsing rules.¶
Numeric character references and the predefined XML entity references are supported as defined in [XML]. ANML does not define additional named entity references.¶
CDATA sections MUST NOT appear in conforming ANML documents.¶
XML comments MAY appear in ANML documents. Conforming agents MAY ignore comments; comments MUST NOT carry semantic meaning. Processing instructions other than the XML declaration MUST NOT appear in conforming ANML documents.¶
Conforming agents MUST ignore any element or attribute not defined by this specification or a recognized extension namespace, without raising an error.¶
ANML uses XML Namespaces [XMLNS] to distinguish its elements from those of other vocabularies. The namespace URI 'urn:ietf:params:xml:ns:anml:1.0' is an identifier and need not resolve to a retrievable resource.¶
The ANML namespace URI 'urn:ietf:params:xml:ns:anml:1.0' is version-specific — the '1.0' is part of the URI. This means a future ANML 2.0 specification using a different namespace URI would be treated as an entirely distinct namespace by conforming XML processors. Documents from the two versions would not be interoperable at the namespace level.¶
The working group has noted the alternative approach used by HTML5 and other standards: a version-independent namespace URI (e.g., 'urn:ietf:params:xml:ns:anml') with the version carried only in the version attribute of the root element. This approach avoids namespace fragmentation across versions and is RECOMMENDED for consideration before the namespace URI is formally registered with IANA.¶
NOTE TO RFC EDITOR AND WORKING GROUP: the choice between a version-specific and version-independent namespace URI MUST be resolved before standards-track publication. The current version-specific URI is used throughout this draft pending that decision. If a version-independent URI is adopted, all namespace URI references in this document will be updated accordingly.¶
The namespace URI includes a version component ('1.0'). Future major versions will use a new namespace URI. The namespace URI is the authoritative version indicator.¶
ANML documents MAY include elements and attributes from other XML namespaces. Extensions MUST be namespace-qualified and MUST NOT use the ANML namespace URI.¶
ANML documents SHOULD NOT include a Document Type Declaration (DOCTYPE). If present, conforming agents MUST NOT process its internal subset or resolve external entities referenced by it.¶
<?xml version="1.0" encoding="UTF-8"?>
<anml xmlns="urn:ietf:params:xml:ns:anml:1.0" ttl="3600">
<head>
<title>Travel Booking Service</title>
<meta name="type" value="service"/>
</head>
<constraints>
<disclosure field="airline" requires="explicit-consent"/>
</constraints>
<state>
<context><step>search</step></context>
<flow>
<step id="search" label="Search flights" status="current"/>
<step id="select" label="Select a flight" status="pending"/>
<step id="payment" label="Payment"
status="pending" required="true"/>
<step id="confirm" label="Confirmation" status="pending"/>
</flow>
</state>
<interact>
<action id="submit-airline" method="POST" endpoint="/airline"/>
</interact>
<knowledge>
<inform ttl="3600">
We offer flights to over 200 destinations worldwide.
</inform>
<ask field="airline" action="submit-airline"
required="false" purpose="personalization"/>
</knowledge>
<persona>
<model capability="reasoning"/>
<language policy="native"/>
<tone value="friendly"/>
<instructions>Be helpful and concise.</instructions>
</persona>
<body>
Book flights to your destination.
</body>
<footer>
<rights holder="Example Travel, Inc." year="2026" usage="cache">
Copyright 2026 Example Travel, Inc.
</rights>
</footer>
</anml>¶
The following is to be registered with IANA:¶
The default character encoding for ANML documents is UTF-8 [RFC3629]. When transmitted via HTTP, the charset parameter of the Content-Type header takes precedence over the XML declaration, as specified in [XMLMIME].¶
A conforming ANML document SHOULD begin with an XML declaration. The XML declaration is REQUIRED when the document uses an encoding other than UTF-8.¶
UTF-8 encoded documents SHOULD NOT begin with a BOM. Conforming agents MUST accept documents that include one. For UTF-16, the BOM is REQUIRED.¶
ANML documents SHOULD use LF (U+000A). Conforming agents MUST accept LF, CR, or CR+LF and normalize to LF as specified in [XML] Section 2.11.¶
Content negotiation follows standard HTTP mechanisms as defined in [RFC9110]. An agent SHOULD include 'application/anml+xml' in the Accept header. A service MUST set the Content-Type header when responding with an ANML document.¶
The interaction between ANML's ttl attribute and HTTP caching directives is defined in Section 8.1.1, adjacent to the ttl attribute definition on the <anml> root element. It is cross-referenced here because HTTP caching is a transport-layer concern. The normative content is in Section 8.1.1; this section serves as a locator for readers approaching from the transport layer.¶
A service MAY publish a discovery document at '/.well-known/anml' [RFC8615]. The serving domain of the well-known URI response is implicitly authoritative: an agent MUST treat an ANML document retrieved from 'https://example.net/.well-known/anml' as asserting the identity of example.net, regardless of any title, persona, or display-name content in the document. A <trust> element or <site> element claiming a different domain in a well-known URI response MUST be treated as a third-party assertion subject to the trust verification procedure in Section 12 — it does not override the serving domain's implicit authority over its own well-known URI. This rule prevents CDN operators or hosting providers from substituting their own ANML identity for a served site's identity at the discovery endpoint. The following normative rules govern agent behavior when interacting with this URI:¶
A service MAY advertise ANML support via a Link header with rel="alternate" and type="application/anml+xml".¶
A service MAY include a <link rel="alternate" type="application/anml+xml"> element in HTML documents.¶
A domain MAY publish SRV records [RFC2782] at '_anml._tcp' and TXT records with key 'v=anml1' and optional 'path' key.¶
ANML defines an abstract data model that MAY be serialized as either XML (Section 5) or JSON. Both serializations are normative and semantically equivalent. An implementation that correctly processes one serialization MUST produce results identical to processing the other serialization of the same document. The serialization format is a deployment choice, not a semantic choice.¶
The JSON serialization is identified by the media type 'application/anml+json'. Content negotiation follows standard HTTP mechanisms: a client SHOULD include both 'application/anml+xml' and 'application/anml+json' in the Accept header with appropriate q-values to indicate preference. A service MUST set the Content-Type header to the serialization actually returned.¶
The XML serialization (Section 5) is RECOMMENDED for documents intended for human authoring and review. The JSON serialization is RECOMMENDED for programmatic generation and agent-pipeline consumption. Both are REQUIRED to be supported by conforming implementations claiming full conformance. Implementations MAY support only one serialization and MUST document which serializations they support.¶
The following is to be registered with IANA:¶
The following rules govern the translation between the XML and JSON serializations of ANML. These rules are applied mechanically and uniformly across all elements.¶
An ANML JSON document is a single JSON object. The root object corresponds to the <anml> element. XML attributes of <anml> become top-level keys of the root object. The version key is REQUIRED. Example:¶
{
"anml": "1.0",
"lang": "en",
"ttl": 3600,
"head": { ... },
"constraints": { ... },
"state": { ... },
"interact": { ... },
"knowledge": { ... },
"persona": { ... },
"aesthetic": { ... },
"body": { ... },
"footer": { ... },
"status": { ... }
}
¶
XML attributes become JSON string, number, or boolean properties of the enclosing object. Attribute names that contain hyphens (e.g., supported-versions) are preserved as-is in JSON keys. Boolean attributes with values "true" or "false" become JSON boolean values true or false. Numeric attributes (ttl, min, max) become JSON numbers. All other attributes become JSON strings.¶
XML element text content (#PCDATA) becomes a JSON string value associated with the key "content" within the element's object representation. When an element has ONLY text content and no attributes or child elements, its value MAY be represented in compact form as a JSON string rather than an object with a "content" key. Example:¶
XML: <inform ttl="3600">We offer 200 destinations.</inform>
JSON (full):
{
"ttl": 3600,
"content": "We offer 200 destinations."
}
JSON (shorthand, only when no other attributes or children):
"We offer 200 destinations."
¶
XML child elements become nested JSON objects keyed by the element name. Elements that may appear multiple times as siblings (repeatable elements) MUST always be represented as a JSON array, even when only one instance is present. This rule is absolute: a repeatable element is never a bare object — it is always a single-element array or a multi-element array. Elements that may appear at most once (non-repeatable elements) are represented as a bare JSON object, never as an array.¶
Repeatable elements (MUST use array form): inform, ask, answer, refuse, action, param, option, step, meta, logo, color, font, section, item, field, attribution.¶
Non-repeatable elements (MUST use object form): 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.¶
Example:¶
XML:
<knowledge>
<inform ttl="3600">Fact one.</inform>
<inform ttl="7200">Fact two.</inform>
<ask field="name" action="submit" required="false"/>
</knowledge>
JSON:
{
"knowledge": {
"inform": [
{ "ttl": 3600, "content": "Fact one." },
{ "ttl": 7200, "content": "Fact two." }
],
"ask": {
"field": "name",
"action": "submit",
"required": false
}
}
}
¶
XML elements with no content and no child elements (EMPTY content model) become JSON objects containing only their attribute properties. An empty element with no attributes becomes an empty JSON object {}. Example:¶
XML: <tone value="friendly"/>
JSON: { "tone": { "value": "friendly" } }
XML: <disclosure field="email" requires="explicit-consent"/>
JSON: { "disclosure": { "field": "email",
"requires": "explicit-consent" } }
¶
Conforming ANML agents processing JSON documents MUST ignore any key not defined by this specification or a recognized extension, without raising an error. This mirrors the requirement for XML unknown elements and attributes in Section 5.2.7.¶
The following is the JSON serialization of the example ANML document in Section 5.4:¶
{
"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."
}
}
}
¶
A service supporting JSON serialization SHOULD include 'application/anml+json' in the Accept-Patch or Alternates header of its well-known URI response. Agents SHOULD include both media types in the Accept header of discovery requests:¶
Accept: application/anml+xml;q=0.9, application/anml+json;q=1.0¶
A service MAY serve different serializations from different endpoints or from the same endpoint based on content negotiation. The data model MUST be identical regardless of serialization. A service MUST NOT include information in one serialization that is absent from the other.¶
JSON documents are subject to the general security considerations in Section 11. The following additional considerations apply specifically to JSON serialization:¶
This section is normative. The following assertions MUST hold for any conforming implementation processing the XML and JSON serializations of the same logical ANML document:¶
The following are explicitly NOT required to be identical across serializations: user interface rendering, caching implementation details, logging format, and internal representation. These are implementation-defined and cannot be specified by this document.¶
Any ANML document expressible in XML serialization MUST be expressible in JSON serialization with equivalent semantics, and vice versa. Where ambiguity exists between the XML and JSON mapping rules, the XML serialization is authoritative. Implementers encountering ambiguity SHOULD file an issue with the ANML Foundation at spec@anmlfoundation.org.¶
An ANML document is a tree of elements rooted at <anml>, organized into sections with distinct responsibilities.¶
The <anml> element is the root element. Attributes: xmlns (REQUIRED), version (OPTIONAL, default "1.0"), role (OPTIONAL, "service"|"agent-response" — declares the document type, enabling schema-based validation of role-specific constraints. Conforming implementations MUST generate the role attribute on all documents they produce. When the role attribute is absent, agents MUST infer document role from HTTP context: a document received in response to an HTTP GET at a well-known URI or HTTP Link header discovery endpoint is a service document; a document submitted as the body of an HTTP POST to an action endpoint is an agent-response document. When present, the role attribute value MUST match the inferred HTTP context role — if they conflict the document MUST be rejected. Validators MUST apply role-appropriate content model rules when this attribute is present. There is no default value — absence triggers context inference, not a default assumption), supported-versions (OPTIONAL, comma-separated list of supported version strings), ttl (OPTIONAL, non-negative integer, seconds until the document SHOULD be considered stale, counted from the value of the HTTP Date response header at time of retrieval; if no Date header is present, ttl is counted from time of receipt; if ttl conflicts with HTTP Cache-Control, the interaction is governed by Section 6.5 (HTTP Caching Interaction); see also Section 8.1.1 for the caching subsection adjacent to this attribute definition), lang (OPTIONAL, BCP 47).¶
Content model (single-site document): head?, constraints?, state?, interact?, knowledge?, persona?, aesthetic?, body?, footer?, status?¶
Content model (multi-site document): site+¶
A conforming <anml> document MUST use one of these two content models exclusively. An <anml> element MUST NOT mix top-level identity sections (persona, aesthetic, knowledge, etc.) with <site> elements. When a document asserts identity for more than one serving party, it MUST use the multi-site content model with <site> wrappers for all parties including the serving domain itself.¶
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 elements and attributes it does not recognize, and SHOULD inform the user that the document uses a version newer than the agent supports. If the supported-versions attribute is present and does not include any version the agent implements, the agent MAY refuse to process the document and MUST NOT execute any actions defined within it. The agent SHOULD surface a meaningful error to the user in this case. This behavior mirrors established web precedent: agents degrade gracefully rather than failing completely when encountering newer versions.¶
The RECOMMENDED authoring order for single-site documents places framing sections (constraints, state, interact, knowledge, persona) before <body> to optimize for streaming consumption.¶
The ANML ttl attribute interacts with HTTP caching headers as follows, in order of precedence:¶
The <site> element is a wrapper used in multi-site documents to group identity sections belonging to a single serving party or trusted third party. It replaces individual top-level identity sections when a document asserts identity for more than one domain.¶
Attributes:¶
Content model: head?, constraints?, state?, interact?, knowledge?, persona?, aesthetic?, body?, footer?, status?, site-ref*¶
When the domain attribute differs from the serving domain, the agent MUST perform trust verification by looking up the _anml DNS TXT record for the site domain and proceeding per Section 12.4. No additional trust-manifest attribute is required — the domain attribute alone triggers the verification procedure.¶
A <site> element MUST contain at least one child element. An empty <site> element is malformed. Each <site> element in a document MUST have a unique domain attribute value. Duplicate domain values within the same <anml> element are not permitted.¶
The <head> element contains document metadata. Content model: title?, meta*.¶
The <title> element provides the document title. Content model: (#PCDATA).¶
The <meta> element provides name/value metadata pairs. Attributes: name (identifier string), value (string). Content model: EMPTY.¶
The <constraints> element defines rules governing disclosure. Agents MUST evaluate constraints before submitting any <answer>. Content model: disclosure*.¶
The <disclosure> element defines a single disclosure rule. Attributes: field (REQUIRED, references an <ask> field), requires (REQUIRED: explicit-consent|implicit-consent|authentication|none). Content model: EMPTY.¶
The <state> element carries contextual information about multi-step interactions. Content model: context?, flow?.¶
The <context> element identifies the current position within a flow. Content model: step. The child <step> element contains (#PCDATA) whose text MUST match a step id defined in <flow>. This <step> child carries no attributes and serves solely as a reference to a flow step.¶
The <flow> element declares the workflow structure. Content model: step*.¶
The <step> element defines a single workflow stage. Attributes: id (REQUIRED), label, status (completed|current|pending|skipped), required (boolean, "true"|"false", default "false"), next (step id of the subsequent step), condition (a service-defined opaque string evaluated by the service to determine step availability; agents MUST treat this as informational and MUST NOT attempt to evaluate condition expressions independently), action (references an <action> id available at this step). Content model: EMPTY.¶
The <interact> element defines executable operations. Content model: action*.¶
The <action> element defines a single operation. Attributes: id (REQUIRED), method (REQUIRED, HTTP method), endpoint (REQUIRED, URI), enctype (media type for request body, default "application/x-www-form-urlencoded"), auth (none|required|optional, default "none"), idempotent (boolean, "true"|"false"), confirm (boolean, "true"|"false", if "true" the agent SHOULD confirm with the user before executing), description (human-readable text). Content model: param*, response?.¶
The <param> element declares an action parameter. Attributes: name, type (string|number|boolean|date|datetime|uri|enum), required (boolean, "true"|"false", default "false"), default, description, pattern, min, max. Content model: option*.¶
The <option> element defines a permitted value for enum parameters. Attributes: value (REQUIRED, string), label (human-readable display text). Content model: EMPTY.¶
The <response> element describes the expected response. Attributes: type (default application/anml+xml), description. Content model: EMPTY.¶
The <knowledge> element defines bidirectional information exchange. Content model: (inform | ask)* for service documents; (answer | refuse | ask | inform)* for agent responses.¶
The <inform> element communicates information from service to agent. Attributes: ttl (non-negative integer, seconds from HTTP Date header of the response in which this element was received; see Section 8.1 for ttl semantics), scope (element id this inform applies to), priority (low|normal|high, default "normal"), confidentiality (public|restricted|private, default "public"), usage (none|display|cache|store|train — see Section 15.4 for the normative usage hierarchy). Content model: (#PCDATA).¶
The <ask> element requests information from the other party. Attributes: field (REQUIRED), action (REQUIRED, references an <action> id), required (boolean, "true"|"false", default "false"), purpose (human-readable reason for the request), type (expected value type: string|number|boolean|date|datetime|uri — see Section 8.14 for the unified ANML type system definition). Content model: EMPTY.¶
The field attribute is a free-form string identifying the information being requested. For interoperability, field values representing personal information SHOULD use the property names defined in vCard version 4.0 [RFC6350] where applicable — for example: "fn" (formatted name), "email", "tel", "adr", "bday", "gender", "lang". Use of these standard property names allows agents to recognize equivalent requests across services that use the same vocabulary. Service-specific field names are permitted and are opaque to agents that do not recognize them; agents MUST NOT refuse to process an <ask> solely because the field name is unrecognized — they MUST instead evaluate it against applicable constraints and user consent as with any other field. When an agent encounters an <ask> with an unrecognized field name, it MUST apply the most restrictive applicable constraint as a default. Specifically: if no <disclosure> constraint is specified for the unrecognized field, the agent MUST treat it as requiring requires="explicit-consent" regardless of any other constraint configuration. This ensures unrecognized fields are never disclosed silently. An IANA registry of standard ANML field names is planned for a future revision.¶
The <answer> element provides requested information. Attributes: field (REQUIRED), value (REQUIRED), consent (explicit|implicit|delegated), consent-granted (OPTIONAL, ISO 8601 datetime in UTC — the time at which the user granted consent for this disclosure; allows services to evaluate whether consent is current relative to their valid-for requirement). Content model: EMPTY.¶
Services that specify valid-for on a <disclosure> element SHOULD evaluate the consent-granted timestamp in the corresponding <answer> to determine whether the agent's consent is still valid. If consent-granted is absent or older than valid-for seconds, the service SHOULD treat the disclosure as requiring fresh consent and SHOULD return a response requesting re-consent rather than processing the stale answer.¶
The <refuse> element explicitly declines an <ask>. Attributes: field (REQUIRED), reason (REQUIRED: constraint-violation|user-denied|policy-violation|unsupported-field|trust-insufficient), constraint (references a <disclosure> field, if applicable), message (human-readable explanation). Content model: EMPTY.¶
The <persona> element provides advisory guidance on agent communication style. Content model: model?, language?, tone?, voice?, instructions?, vocabulary?.¶
Precedence: agents SHOULD apply persona guidance to their responses. However, user safety policies, user-configured preferences, and platform-level guardrails take absolute precedence over all persona guidance. The SHOULD in this section applies only to persona guidance that does not conflict with any higher-priority constraint. When persona guidance conflicts with a safety policy or user preference, the MUST NOT in Section 13.3 governs — the SHOULD creates no obligation to apply conflicting guidance. Agents MUST be able to explain to a user, on request, which persona guidance was applied and which was overridden.¶
The <model> element provides an advisory model preference for agent inference. Agents MAY use this guidance to select an appropriate model but are not required to honor it. Attributes: name (model identifier, e.g., "claude-4", "gpt-5"), provider (e.g., "anthropic", "openai"), capability (e.g., "vision", "code", "reasoning"). All attributes are OPTIONAL. When name is not available, agents SHOULD select a model that satisfies the specified capability. Content model: EMPTY.¶
The <language> element specifies the response language policy. Attributes: value (BCP 47 tag, used when policy="fixed"), policy (native|match|fixed). Content model: EMPTY.¶
Policy values: "native" — the agent SHOULD respond in the user's preferred language as known to the agent; "match" — the agent SHOULD respond in the language of the document; "fixed" — the agent MUST respond in the language specified by the value attribute. Tone and voice values are advisory opaque strings; interoperability of persona guidance across services is not guaranteed and agents SHOULD treat unrecognized tone and voice values as informational only.¶
Privacy note: policy="native" causes the agent to infer or disclose the user's preferred language to influence its response. The user's language preference is personal information. Agents SHOULD treat the application of policy="native" as equivalent to an implicit disclosure of a language preference field and SHOULD apply any applicable <constraints> governing language-related disclosures. Services MUST NOT use policy="native" as a mechanism to fingerprint users by language.¶
The <tone> element specifies the emotional register. Attributes: value (e.g., "friendly", "formal", "neutral"). Content model: EMPTY.¶
The <voice> element specifies character and perspective. Attributes: perspective (first|third), name (character name, string). Content model: EMPTY.¶
The <instructions> element provides free-text behavioral guidance. Advisory only. Content model: (#PCDATA).¶
The <vocabulary> element specifies preferred and avoided terms. Content model: prefer*, avoid*.¶
The <prefer> element declares a preferred term or phrase. Content model: (#PCDATA).¶
The <avoid> element declares a term or phrase that SHOULD NOT be used. Content model: (#PCDATA).¶
The <aesthetic> element provides advisory visual identity guidance. Content model: display-name?, logo*, colors?, typography?.¶
The <display-name> element specifies the preferred service name. Content model: (#PCDATA).¶
The <logo> element references a logo image. Attributes: src (URI), alt (text description), type (media type, e.g., "image/svg+xml"), variant (e.g., "icon", "wordmark", "full"). Content model: EMPTY.¶
The <colors> element defines the service color palette. Content model: color*.¶
The <color> element defines a single color value. Attributes: role (e.g., primary, secondary, accent), value (CSS color string). Content model: EMPTY.¶
The <typography> element defines font preferences. Content model: font*.¶
The <font> element defines a single font preference. Attributes: role (e.g., heading, body), family, fallback. Content model: EMPTY.¶
The <body> element contains the primary semantic content. Attributes: usage (none|display|cache|store|train, default content usage rights). Content model: (#PCDATA | section | data | img | audio | video | link | nav)*.¶
The <section> element groups related content. Attributes: id, label, usage (none|display|cache|store|train). Sections MAY be nested. Content model: (#PCDATA | section | data | img | audio | video | link | nav)*.¶
The <img> element references an image resource. Attributes: src (REQUIRED, URI), inference (none|optional|required), type (media type), width, height, usage (none|display|cache|store|train). Content model: description?. A <description> child SHOULD be provided.¶
The inference attribute indicates whether the agent is expected to perform inference on the media resource: "none" means the resource need not be retrieved or analyzed, "optional" means the agent MAY perform inference if beneficial, and "required" means the resource contains information essential to the document that cannot be conveyed through the <description> alone.¶
The <audio> element references an audio resource. Attributes: src (REQUIRED, URI), inference (none|optional|required), type (media type), duration (seconds), lang (BCP 47), usage (none|display|cache|store|train). Content model: transcript?, description?. The inference attribute has the same semantics as defined for <img>.¶
The <video> element references a video resource. Attributes: src (REQUIRED, URI), inference (none|optional|required), type (media type), duration (seconds), width, height, lang (BCP 47), usage (none|display|cache|store|train). Content model: transcript?, description?. The inference attribute has the same semantics as defined for <img>.¶
The <description> element provides a textual description of a media resource (<img>, <audio>, or <video>). When present, agents MAY use the description instead of performing inference on the media resource. Content model: (#PCDATA).¶
The <transcript> element provides a textual transcript of an <audio> or <video> resource. When present, agents MAY use the transcript instead of performing inference on the media resource. Content model: (#PCDATA).¶
The <link> element references a related resource. Attributes: href (REQUIRED, URI), rel (relationship type, e.g., "alternate", "related", "canonical"), type (media type of the referenced resource), label (human-readable description). Content model: EMPTY.¶
The <data> element contains structured data as a collection of items. Attributes: id, label, usage (none|display|cache|store|train). Content model: item*.¶
The <item> element represents a single record within a <data> collection. Attributes: id (string). Content model: field*.¶
The <field> element represents a named value within an <item>. Attributes: name (string), type (string|number|boolean|date|datetime|uri). Content model: (#PCDATA).¶
The <nav> element provides pagination and continuation controls. Attributes: next (URI for the next page), prev (URI for the previous page), cursor (opaque continuation token), total (total item count, if known). Content model: EMPTY.¶
The following type vocabulary is used by the type attribute of both the <ask> and <field> elements. This section is the single normative definition; both elements reference it. Implementations MUST apply these definitions consistently across both contexts.¶
The type attribute is advisory when present on <ask> — it communicates the service's expected value format to the agent. It is descriptive when present on <field> — it communicates the data type of a value in a result set. In both cases, agents SHOULD validate or format values according to the type definition before transmission.¶
The <footer> element contains copyright, licensing, and attribution declarations. Content model: rights*, attribution*, (#PCDATA)*.¶
The <rights> element declares copyright and usage terms. Attributes: holder, year, license, usage (none|display|cache|store|train, default "none"), scope. Usage values form a hierarchy: none < display < cache < store < train. Multiple <rights> elements MAY target specific element IDs via the scope attribute. Content model: (#PCDATA).¶
The <attribution> element provides credit to content sources. Attributes: required (boolean, "true"|"false", default "false"), scope (element id this attribution applies to). Content model: (#PCDATA).¶
The <status> element communicates the outcome of a preceding operation. Content model: EMPTY. Attributes: code (REQUIRED, machine-readable status code), result (REQUIRED: success|error|partial), message (human-readable description), retry-after (seconds before the agent SHOULD retry).¶
ANML operates over HTTP. It does not replace or modify HTTP methods, headers, authentication, session management, or cookie handling.¶
ANML interactions use HTTP [RFC9110]. The <action> element's method attribute specifies the HTTP method. ANML does not define or constrain HTTP method semantics.¶
A typical ANML interaction proceeds as follows:¶
All executable operations MUST be defined in the <interact> section. The agent resolves the response target by: (1) reading the action attribute of the <ask>, (2) locating the matching <action> element, and (3) using its method and endpoint to submit the response.¶
ANML defines a bidirectional knowledge exchange model. Services include <inform> and <ask> elements in documents; agents include <answer>, <refuse>, <ask>, and <inform> elements in responses.¶
Agents MUST evaluate constraints before submitting any <answer>. Constraints may govern consent requirements, authentication, field-level disclosure restrictions, and rate limitations.¶
ANML separates transport and identity (HTTP) from semantics and interaction (ANML).¶
The ANML internationalization model builds on XML [XML], Unicode [UNICODE], and RFC 2070 [RFC2070].¶
The document character set is Unicode [UNICODE], synchronized with ISO/IEC 10646. Numeric character references resolve via Unicode code points regardless of encoding. ANML does not support non-Unicode character repertoires.¶
The default encoding is UTF-8 [RFC3629]. Non-Unicode encodings MUST NOT be used. Encoding detection precedence: (1) HTTP Content-Type charset, (2) XML declaration encoding attribute, (3) BOM detection, (4) UTF-8 default.¶
The 'lang' attribute specifies natural language using BCP 47 [BCP47] tags. Language declarations inherit from parent to child elements. ANML does not define a 'dir' attribute; bidirectional text is handled by the Unicode Bidirectional Algorithm [UAX9].¶
This section defines the format, content model, and normative behavior for agent-originated ANML documents — documents submitted by an agent to a service in response to an <ask> or as part of a multi-step interaction.¶
An agent response is a conforming ANML document submitted as the body of an HTTP request to the endpoint specified by the <action> element referenced in the originating <ask>. The Content-Type of the request MUST be either 'application/anml+xml' or 'application/anml+json', matching the serialization used. The agent SHOULD use the same serialization as the document it is responding to unless the service has indicated a preference via the Accept header of a prior response.¶
The root element of an agent response document is <anml> with the same namespace and version as defined in this specification. An agent response document MAY contain any combination of the following elements in its knowledge section:¶
An agent response MUST contain at least one <answer> or <refuse> element corresponding to each <ask> element marked required="true" in the originating document. An agent MAY include <answer> or <refuse> elements for optional <ask> elements at its discretion. An agent MUST NOT include <answer> elements for fields not requested by an <ask> in the current interaction context.¶
An agent response MUST NOT include <interact>, <persona>, <aesthetic>, <constraints>, or <state> sections. These sections are reserved for service documents. A service receiving an agent response that includes these sections MUST ignore them.¶
The minimum valid agent response is an ANML document containing a single <refuse> element for each required <ask> in the originating document. This indicates the agent has processed the document but is unable or unwilling to provide the requested information. Example:¶
<?xml version="1.0" encoding="UTF-8"?>
<anml xmlns="urn:ietf:params:xml:ns:anml:1.0">
<knowledge>
<refuse field="airline"
reason="user-denied"
message="User declined to share airline preference."/>
</knowledge>
</anml>¶
A service receiving an agent response MUST return an HTTP response with an appropriate status code. When the service returns an ANML document as the response body, it MUST set Content-Type to the appropriate ANML media type. The service response SHOULD include a <status> element indicating the outcome of the submitted action.¶
The following HTTP status codes have defined semantics in the ANML interaction model:¶
For 4xx responses, services SHOULD return a response body conforming to RFC 9457 [RFC9457] (Problem Details for HTTP APIs), using Content-Type 'application/problem+json' or 'application/problem+xml'. RFC 9457 supersedes RFC 7807 and is backward compatible with it. Problem Details provide machine-parseable error information including field-level validation errors, constraint violations, and retry guidance that agents can act on without human intervention. The ANML <status> element is used for 2xx responses only; 4xx and 5xx responses SHOULD use RFC 9457 Problem Details as the error envelope.¶
The following normative error handling requirements apply to conforming agents and services:¶
The <nav> element within <body> provides next, prev, and cursor references for multi-page result sets. The following normative behavior applies:¶
Example agent response with multiple answers and a counter-ask:¶
<?xml version="1.0" encoding="UTF-8"?>
<anml xmlns="urn:ietf:params:xml:ns:anml:1.0">
<knowledge>
<answer field="destination" value="LAX" consent="explicit"/>
<refuse field="airline"
reason="user-denied"
message="User prefers not to share airline preference."/>
<ask field="available-dates"
action="submit-booking"
purpose="Required to show available flights"/>
<inform>User prefers morning departures before 10:00 AM.</inform>
</knowledge>
</anml>¶
Example service response with pagination and status:¶
<?xml version="1.0" encoding="UTF-8"?>
<anml xmlns="urn:ietf:params:xml:ns:anml:1.0">
<status code="200" result="success"
message="Found 47 flights matching your criteria."/>
<body>
<data id="flights" label="Available flights">
<item id="f1">
<field name="airline" type="string">Example Air</field>
<field name="departure"
type="datetime">2026-05-01T08:00Z</field>
<field name="price" type="number">349</field>
</item>
<item id="f2">
<field name="airline" type="string">Globe Wings</field>
<field name="departure"
type="datetime">2026-05-01T10:30Z</field>
<field name="price" type="number">412</field>
</item>
</data>
<nav next="/flights?page=2" total="47" cursor="eyJwYWdlIjoyfQ"/>
</body>
<state>
<context><step>select</step></context>
</state>
</anml>¶
ANML documents may be served by parties other than the site whose identity they assert. A large retailer may serve brand content under a commercial authorization. A small independent retailer may carry products without any formal authorization relationship. A CDN may serve cached documents on behalf of an origin. In all of these cases, TLS certificate verification establishes only that the agent is talking to the serving domain — it says nothing about whether that domain is authorized to assert the identity of another site.¶
This section defines the ANML Trust Delegation mechanism. It is modeled on the DKIM pattern: a small DNS TXT record at the site's domain serves as the single bootstrap entry point, advertising where authorization data can be found. The authorization data itself lives in a static manifest, a live query endpoint, or both — but never in DNS directly. This keeps DNS records small and stable regardless of how many partners a site authorizes, while giving sites the flexibility to choose the authorization mechanism that fits their scale and operational requirements.¶
ANML defines three trust tiers for third-party serving parties. The site's own canonical domain operates as an implicit Tier 3 — full trust, no verification required.¶
The DNS bootstrap record is the single entry point for trust discovery. It is a DNS TXT record published by the site being represented at a fixed subdomain convention. Its only purpose is to advertise where authorization data can be found. It contains no authorization data itself — keeping the record small and stable regardless of how many partners a site authorizes.¶
The record format follows the tag-list convention established by DKIM [RFC6376] (Section 3.2) and SPF [RFC7208] (Section 4.6): a sequence of key=value pairs separated by semicolons, with defined parsing semantics. Agents MUST parse _anml TXT records using the tag-list rules defined in this section, which are consistent with those RFCs.¶
Rationale for reusing this format: the tag-list convention from RFC 6376 and RFC 7208 is already implemented by every major DNS management platform, monitoring tool, and DNS analysis service. Reusing the format means operators can inspect, validate, and debug _anml records using existing tooling without new software. This is a deliberate operational engineering choice, not a dependency on email authentication semantics.¶
The record is published at:¶
_anml.{site-domain} IN TXT "v=anml1; [manifest=URI;] [query=URI]"
¶
Example:¶
_anml.example.com IN TXT "v=anml1; manifest=https://example.com/.well-known/anml-trust; query=https://trust.example.com/anml/authorize"¶
The following ABNF [RFC5234] defines the _anml TXT record syntax. This grammar is consistent with the DKIM tag-list grammar defined in RFC 6376 Section 3.2 and the SPF record grammar in RFC 7208 Section 4.6.¶
anml-record = tag-list
tag-list = tag *( ";" tag ) [ ";" ]
tag = tag-name "=" tag-value
tag-name = ALPHA *ALNUMPUNC
tag-value = *( %x21-3A / %x3C-7E )
; printable ASCII except ";" (%x3B)
; "=" (%x3D) is permitted in tag-value
; (e.g., within URI query strings)
ALNUMPUNC = ALPHA / DIGIT / "_" / "-" / "."
version-tag = %s"v" "=" %s"anml1"
manifest-tag = %s"manifest" "=" URI
query-tag = %s"query" "=" URI
URI = <URI as defined in RFC 3986, Section 3>
¶
Parsing rules (normative):¶
If no _anml TXT record exists for the asserted site domain, the agent MUST treat all third-party serving parties as Tier 0 for that site. The absence of a DNS record means the site has not published trust delegation — not that the site is absent or does not support ANML.¶
A site domain MAY publish multiple _anml TXT records. Agents MUST process all records with a recognized version tag. If multiple records advertise both manifest and query URIs, agents SHOULD prefer the query endpoint.¶
Sites SHOULD enable DNSSEC for their _anml records. Agents SHOULD verify DNSSEC signatures where available. A DNSSEC validation failure MUST be treated as a verification error — the agent MUST fall back to Tier 0 and MUST NOT treat the failure as equivalent to a missing record.¶
The static Trust Manifest is a JSON document served at the URI advertised in the _anml DNS record. It is appropriate for sites with a small, stable set of authorized partners requiring no additional infrastructure beyond a web server. Served with Content-Type 'application/anml-trust+json' over HTTPS from the site's canonical domain.¶
{
"site": "example.com",
"version": "1.0",
"issued": "2026-05-01T00:00:00Z",
"expires": "2026-08-01T00:00:00Z",
"authorized-domains": [
{
"domain": "*.cdn.example.com",
"tier": 1,
"scope": ["aesthetic", "body"],
"note": "CDN — display only"
},
{
"domain": "example.net",
"tier": 2,
"scope": ["aesthetic", "persona", "knowledge"],
"note": "Authorized retailer"
},
{
"domain": "example.org",
"tier": 2,
"scope": ["aesthetic", "persona", "knowledge", "interact"],
"note": "Preferred retailer — full delegation"
}
]
}
¶
Fields:¶
Each authorization record:¶
The live Trust Query endpoint allows a site to answer per-domain authorization queries in real time without publishing a manifest listing every authorized partner. Appropriate for sites with large or frequently changing partner sets, or sites requiring real-time revocation. The endpoint URI is authoritative because it is published in the site's own _anml DNS record. When DNSSEC is verified for the _anml record, agents MAY use the query endpoint without additional TLS domain verification. When DNSSEC is unavailable, agents SHOULD prefer the manifest, which requires TLS certificate verification against the site domain.¶
Scope of this mechanism: the trust delegation defined in this section applies exclusively to ANML document serving parties. It does not apply to Trust Manifest or Trust Query endpoint responses, which are processed as raw JSON data. Agents MUST NOT apply ANML document parsing, trust tier evaluation, or <trust> element processing to responses received from Trust Manifest or Trust Query endpoints — these responses are authorization data, not ANML documents.¶
Query:¶
GET {query-uri}?domain={serving-domain}&scope={comma-separated-sections}
Accept: application/json
¶
Example:¶
GET https://trust.example.com/anml/authorize?domain=example.net&scope=persona,aesthetic,knowledge¶
Response when authorized (HTTP 200):¶
{
"authorized": true,
"tier": 2,
"scope": ["persona", "aesthetic", "knowledge"],
"expires": "2026-08-01T00:00:00Z"
}
¶
Response when not authorized: the endpoint MUST return HTTP 404 (Not Found) with an empty body or minimal diagnostic JSON. The endpoint MUST NOT return HTTP 200 with an "authorized": false body. Returning 404 for unauthorized domains prevents enumeration of a site's authorized partner list: an agent or third party probing the endpoint cannot distinguish "not authorized" from "we have no record of this domain," which limits competitive intelligence leakage. Agents MUST treat a 404 response as a definitive negative authorization and MUST cache it as such for the duration of the applicable DNS TTL of the _anml record.¶
Response fields (HTTP 200 only):¶
HTTP status codes:¶
Cache key: agents MUST cache query results keyed on the tuple (serving-domain, site-domain). The cached value is the full authorization record including tier, scope, and expires. When a new request arrives, the agent checks the cache for (serving-domain, site-domain), retrieves the full authorization, and applies the intersection of the cached scope with the requested scope locally — without issuing a new network request. The endpoint is queried at most once per (serving-domain, site-domain) pair per TTL period regardless of the scope requested. The same cache key applies to both manifest lookups and query endpoint responses.¶
An ANML document asserting a third-party site identity MUST include either a <trust> element in its <head> section (single-site documents) or a the <site> element with a domain attribute differing from the serving domain (multi-site documents). Without one of these, the agent MUST treat all third-party site identity assertions as Tier 0.¶
In single-site documents the <trust> element carries only the site domain — the agent discovers the manifest and query endpoints via DNS, keeping the ANML document itself free of authorization infrastructure details:¶
<!-- Single-site --> <head> <title>Example Product 30 oz — Independent Retailer</title> <trust domain="example.com"/> </head> <!-- Multi-site --> <site domain="example.com"> <persona>...</persona> </site>¶
Attributes of <trust>:¶
Agent verification procedure:¶
Any verification failure at any step MUST result in Tier 0 for the asserted site. Agents MUST NOT apply partial trust. The serving domain's own identity is unaffected by a failed verification for a third-party site.¶
A Tier 0 serving party that carries content from third-party sites MAY use <site-ref> to point agents to those sites' canonical ANML documents. This is a pointer, not a delegation — the serving party makes no identity assertions about the referenced site.¶
<head>
<title>Independent Retailer — Outdoor Gear</title>
<site-ref domain="example.com"
canonical="https://example.com/.well-known/anml"
relationship="carries-products"/>
</head>
¶
Attributes:¶
A document fetched via <site-ref> is processed as a Tier 3 document — full trust from the canonical domain. <site-ref> does not elevate the serving party's trust tier. The serving party's own identity sections remain subject to Tier 0 restrictions.¶
A serving party MAY publish an ANML document that presents identity for both itself and authorized third-party sites. This is a legitimate and common use case: a retailer's product page carries the retailer's own identity (interactions, service persona) alongside the product manufacturer's identity (product voice, aesthetic, knowledge). The <site> wrapper element (Section 8.2) provides the structural mechanism for this.¶
A document with identity assertions for more than one domain MUST use the multi-site content model: all identity sections are wrapped in <site> elements, one per domain. This replaces the single-site content model where identity sections appear directly under <anml>. The structural separation of identity by domain prevents the layered identity attack described below.¶
The layered identity attack: a malicious serving party blurs the boundary between its own assertions and those of a more trusted site, causing the agent to attribute the serving party's content to the trusted site, or to apply the trusted site's permission tier to the serving party's own sections. The <site> wrapper prevents this by making domain attribution structural rather than attributional — there is no attribute to forge, only a wrapper element whose domain is verified independently.¶
Normative rules for multi-site documents:¶
Example of a conforming multi-site document (example.net serving a Example Brand product page; example.net holds Tier 2 authorization from example.com for persona, aesthetic, and knowledge):¶
<anml xmlns="urn:ietf:params:xml:ns:anml:1.0">
<!-- example.net's own identity — serving domain, Tier 3, no verification -->
<site domain="example.net">
<head>
<title>Example Product 30 oz — Example Retailer</title>
<site-ref site="example.com"
canonical="https://example.com/.well-known/anml"
relationship="carries-products"/>
</head>
<persona>
<tone value="helpful"/>
<instructions>Assist the user with purchase and delivery
questions for this order.</instructions>
</persona>
<interact>
<action id="add-to-cart" method="POST"
endpoint="/cart/add" confirm="true"/>
</interact>
</site>
<!-- Example Brand's authorized identity — Tier 2, scope verified by agent -->
<!-- Agent automatically looks up _anml.example.com for verification -->
<site domain="example.com">
<persona>
<tone value="rugged"/>
<instructions>Speak to Example Brand's product quality, materials,
and warranty. Do not discuss pricing or delivery.</instructions>
</persona>
<aesthetic>
<display-name>Example Brand</display-name>
</aesthetic>
<knowledge>
<inform>The Rambler 30 oz is made from 18/8 stainless steel
and is dishwasher safe.</inform>
</knowledge>
</site>
</anml>
¶
An agent processing this document MUST apply Example Brand's persona and knowledge only in the context of product information, apply example.net's persona for purchase and logistics, and attribute the add-to-cart action exclusively to example.net. The agent MUST NOT represent the add-to-cart action as an example.com-defined interaction because "interact" is not in Example Brand's authorized scope for example.net.¶
Note: the <trust> element used in single-site trust verification (Section 12.3) is replaced in multi-site documents by the domain and trust-manifest attributes on the <site> element. Both mechanisms initiate the same agent verification procedure defined in Section 12.4.¶
The Trust Delegation mechanism is bounded by the security of the brand's canonical domain. A compromised brand domain can issue fraudulent Trust Manifests. Brands SHOULD:¶
Agents MUST NOT:¶
ANML defines document structure and interaction semantics. It does not enforce security, privacy, or access control at the protocol level. Agent developers and service operators are responsible for implementing safety, privacy, and policy controls appropriate to their deployment context. This section provides a structured threat model and MUST-level guidance for conforming implementations.¶
ANML documents are processed by autonomous agents that may act without direct human oversight at each step. The attack surface includes the document itself, the service publishing it, the agent processing it, and the transport layer.¶
The following threat actors and scenarios are in scope for this specification:¶
The following are explicitly out of scope: compromise of the agent runtime environment, attacks on the user's device or operating system, and attacks that exploit vulnerabilities in the underlying XML parser beyond those addressed in this section.¶
The <ask> element requests information from the agent on behalf of a service. This presents a significant data exfiltration risk if agents respond without rigorous evaluation of consent and constraints.¶
Conforming agents MUST:¶
Services MUST NOT rely on ANML constraints alone as an access control mechanism. Server-side authorization MUST be implemented independently of ANML document constraints.¶
Agents SHOULD maintain a disclosure log sufficient to reconstruct, for any completed interaction, which fields were disclosed, to which service domain, under which consent basis, and at what time. Agents SHOULD make this log available to the user on request. The format and retention period of the log are implementation-defined.¶
The <persona> and <instructions> elements present a significant prompt injection risk. A malicious service may craft persona guidance or free-text instructions designed to override the agent's safety policies, manipulate its behavior toward the user, cause it to misrepresent the service, extract information it would not otherwise disclose, or act against the user's expressed interests.¶
Conforming agents MUST:¶
Agents SHOULD apply heuristic or model-based analysis to <instructions> content before processing to identify potential injection patterns. The detection method is implementation-defined; the response to a detected injection attempt is normative. When an agent determines that <instructions> or <persona> content constitutes a prompt injection attempt, the agent MUST: (1) discard the offending element entirely and MUST NOT apply any part of its content to agent behavior — a partial or sanitized application is not permitted; (2) record the detection in its operational log; and (3) produce a user-visible notification that instructions from the service were rejected, without including the rejected content in the notification. The Human Intent First design principle (Section 4) takes absolute precedence over any <persona> or <instructions> content.¶
Services are RECOMMENDED to limit <instructions> content to communication style guidance and to avoid imperative behavioral directives that could be misused by intermediaries.¶
The <interact> section declares operations that agents may execute against arbitrary HTTP endpoints. This presents risks including unauthorized transactions, SSRF (Server-Side Request Forgery) via agent-mediated requests, and unintended side effects on third-party systems.¶
Conforming agents MUST:¶
Services SHOULD use the idempotent attribute to indicate safe retry behavior and the confirm attribute for all consequential actions.¶
Conforming agents and ANML document validators MUST NOT process DOCTYPE declarations, internal DTD subsets, or external entity references in ANML documents. Conforming ANML documents SHOULD NOT include a DOCTYPE declaration. If a DOCTYPE declaration is present, the agent MUST ignore it and MUST NOT resolve any entities defined within it. Parsers configured to resolve external entities MUST NOT be used to parse ANML documents.¶
ANML does not define agent authentication mechanisms. A service cannot cryptographically verify the identity of the agent submitting an answer, nor can an agent cryptographically verify that an ANML document originates from the claimed service without additional mechanisms.¶
Services that require verified agent identity SHOULD use existing HTTP authentication mechanisms (OAuth 2.0, API keys, mutual TLS) in conjunction with ANML interactions.¶
Agents SHOULD verify the TLS certificate of the service before processing an ANML document retrieved over HTTPS. Agents SHOULD treat ANML documents retrieved over unencrypted HTTP as untrusted and MUST NOT submit <answer> responses to services communicating over unencrypted HTTP.¶
Agents SHOULD apply heuristics to detect service impersonation, including verification that the well-known URI origin matches the domain of links and action endpoints in the document.¶
A malicious ANML document may attempt to exhaust agent resources through excessive nesting depth, very large element counts, unbounded <body> content, or circular references in <flow> elements.¶
Conforming agents MUST impose implementation-defined limits on:¶
Agents MUST detect and terminate processing of circular <flow> references.¶
The <constraints> section declares disclosure rules that conforming agents must evaluate. However, a non-conforming or malicious agent may ignore these constraints entirely. Services MUST NOT rely on ANML constraint declarations as the sole mechanism for protecting sensitive information. Server-side access control, authentication, and authorization MUST be implemented independently.¶
The absence of a <constraints> section does not imply authorization to disclose any particular information. Agents MUST apply default-deny disclosure policies in the absence of explicit user consent.¶
An agent or network adversary may attempt to replay previously captured ANML responses or manipulate <state> content to advance or regress a multi-step workflow without authorization.¶
Services MUST NOT trust agent-provided state values without independent server-side validation. Services SHOULD use cryptographic nonces or session tokens to bind state to a specific interaction sequence. Services MAY apply HTTP Message Signatures [RFC9421] to ANML responses to detect tampering.¶
Conforming agents SHOULD impose resource limits on ANML document processing as described in Section 11.7. Services SHOULD apply rate limiting to ANML document endpoints, particularly well-known URIs which are publicly discoverable and may be targeted by automated crawlers. Services SHOULD return HTTP 429 (Too Many Requests) with appropriate Retry-After headers when rate limits are exceeded.¶
Agents SHOULD apply origin-based security policies when retrieving resources referenced within ANML documents, consistent with the same-origin policy principles established for web browsers. Action endpoints that differ in origin from the ANML document SHOULD require additional user confirmation. Agents SHOULD NOT automatically follow links or retrieve resources from origins not established in the initial ANML document without user awareness.¶
Services MUST serve ANML documents over HTTPS with valid TLS certificates. Agents MUST verify TLS certificates when retrieving ANML documents. Agents MUST NOT submit <answer> elements containing personal information to services communicating over unencrypted HTTP. Agents SHOULD refuse to process <interact> action endpoints that specify HTTP (non-TLS) URIs unless the user has explicitly acknowledged the risk.¶
ANML introduces a structured mechanism for information exchange between services and agents acting on behalf of users. This section addresses the privacy implications of that mechanism, with particular attention to the cross-session, cross-platform context portability enabled by the knowledge exchange framework.¶
The foundational privacy principle of ANML is that the user controls what the agent discloses. The <ask> / <answer> framework is designed as a consent mechanism, not a data extraction mechanism. The following conformance requirements govern agent disclosure behavior:¶
NOTE: requirements for specific user interface elements, consent dialog designs, or logging user interface features are outside the scope of this specification and are left to implementation. The conformance requirements above are expressed in terms of agent behavior, not interface design.¶
ANML's <inform> and <ask> / <answer> framework enables agents to carry context established in one session or with one service into subsequent sessions with other services. This capability is intentionally designed to benefit users — allowing preferences, history, and relationship context to persist across platforms without centralized data storage.¶
However, this same capability presents privacy risks if implemented without appropriate user controls:¶
Conforming agents MUST:¶
Services SHOULD request only the information necessary for the stated purpose of the interaction. The purpose attribute of the <ask> element is REQUIRED to be present and accurate. Agents SHOULD evaluate the stated purpose and decline to disclose information where the stated purpose is implausible, vague, or inconsistent with the nature of the service.¶
The usage attribute of <inform> and <rights> elements specifies what agents may do with content. Conforming agents MUST respect usage declarations. In particular:¶
Usage declarations are service assertions and are not cryptographically enforced. Agents are responsible for honoring them. Services should not rely on usage declarations as the sole mechanism for protecting content.¶
ANML implementations may be subject to data protection regulations including the EU General Data Protection Regulation (GDPR), the California Consumer Privacy Act (CCPA), the Health Insurance Portability and Accountability Act (HIPAA), and equivalent regulations in other jurisdictions. This specification does not constitute legal advice. Implementers are responsible for assessing and ensuring compliance with applicable regulations in their jurisdiction and use case.¶
The consent framework provided by <constraints> and <disclosure> elements is designed to be compatible with GDPR explicit consent requirements for sensitive data categories. However, ANML consent mechanisms are not a substitute for proper legal consent mechanisms required by applicable law. Services operating in regulated contexts (healthcare, finance, government) MUST implement additional consent and data protection mechanisms beyond those specified in this document.¶
This document requests registration of three media types with IANA per [RFC6838]:¶
Registration for application/anml-trust+json:¶
This document requests registration of the following Well-Known URIs per [RFC8615]:¶
This document requests creation of a new IANA registry titled "ANML Standard Field Names". The registry tracks standardized values for the field attribute of the <ask> and <answer> elements.¶
Registration policy: Expert Review.¶
Initial values: For personal information fields, implementations SHOULD use the property names defined in vCard version 4.0 [RFC6350] where applicable. The following vCard property names are pre-registered as ANML standard field names with their RFC 6350 semantics: fn, email, tel, adr, bday, gender, lang, tz, nickname, org, title, url. Service-specific field names are permitted and are opaque to agents that do not recognize them.¶
NOTE: A complete initial registry with full field definitions and type mappings is planned for draft-jeskey-anml-02.¶
This document requests registration of the following XML namespace in the IETF XML Registry per RFC 3688:¶
This document requests creation of a new IANA registry titled "ANML Usage Values". The registry tracks permitted values for the usage attribute defined in this specification.¶
Registration policy: Standards Action.¶
Initial values:¶
The usage values form a normative hierarchy. This hierarchy is defined here and is authoritative. All other references to usage values in this specification are subject to this definition.¶
none < display < cache < store < train¶
Implication rules (normative): A usage value at a given level implicitly permits all uses at lower levels in the hierarchy. Specifically:¶
An agent that stores content marked usage="cache" has violated the usage constraint. An agent that uses content marked usage="store" for model training has violated the usage constraint. These are normative requirements: agents MUST honor usage declarations. However, usage declarations are service-side assertions and are not cryptographically enforced. Services MUST NOT rely on usage declarations as an access control mechanism. This hierarchy is advisory in the sense that it cannot be technically enforced — it is normative in the sense that conforming agents MUST comply with it.¶
This document requests creation of a new IANA registry titled "ANML Disclosure Requires Values". The registry tracks permitted values for the requires attribute of the <disclosure> element.¶
Registration policy: Standards Action.¶
Initial values:¶
The normative XML Schema (XSD) and an informative DTD for ANML 1.0 are provided in the companion document ANML.md in the same repository as this Internet-Draft.¶
A formal ABNF grammar [RFC5234] defining the structure of ANML documents, attribute value sets, and content negotiation headers WILL be provided in draft-jeskey-anml-02. This is a committed deliverable for the next revision, not a tentative aspiration. The XML Schema provided in the companion document serves as the normative structural definition for this revision. For the JSON serialization, a JSON Schema is available at anmlfoundation.org/spec/anml-schema.json and is informative pending -02.¶
NOTE TO RFC EDITOR: The namespace URI 'urn:ietf:params:xml:ns:anml:1.0' uses the 'urn:ietf:params' prefix, which requires IETF approval via the IANA XML Namespace Registry per RFC 3688. The IANA registration request for this namespace is included in Section 15.3 of this document. This namespace URI MUST NOT be considered assigned until IANA confirms the registration. If the working group determines that a different namespace URI form is preferred prior to registration, the namespace URI throughout this document will be updated accordingly in a subsequent revision.¶
This document requests creation of a new IANA registry titled "ANML Site Relationship Values". The registry tracks standardized values for the relationship attribute of the <site-ref> element.¶
Registration policy: Expert Review.¶
Initial values:¶
Implementations MUST accept and preserve unrecognized relationship values. Agents SHOULD treat unrecognized values as equivalent to no relationship declaration — they do not affect trust tier determination.¶
The design of ANML was informed by the structural patterns established in RFC 1866 [RFC1866], RFC 2070, RFC 3236 [RFC3236], and RFC 7992 [RFC7992].¶
The authors thank the members of the ANML Foundation working groups and the IETF community for their review, feedback, and contributions to this specification. The trust delegation mechanism benefited from extensive community discussion of the tradeoffs between static manifests, live query endpoints, and DNS-based discovery approaches. The dual serialization architecture was informed by feedback from both content practitioners and agent platform engineers who require different serialization characteristics in different deployment contexts.¶