AEP Service Documents

4.1. Document Descriptors

Each descriptor contains:¶

• id: 1 to 32 ASCII characters matching [A-Za-z0-9][A-Za-z0-9._-]*.¶

• type: 1 to 64 characters matching [a-z][a-z0-9_]*. Types are open strings; implementations MUST NOT reject a document merely because its type is unregistered or unknown.¶

• title: a non-empty plain-text string of at most 256 Unicode scalar values.¶

• enrollment: either required or not-required. Consumers MUST NOT treat an unknown value as not-required or silently omit it from an approval decision.¶

• representations: 1 to 8 objects, each containing media_type and url. A URL MUST be absolute HTTPS (or HTTP on the literal hosts localhost, 127.0.0.1, or [::1] for local development), contain no user information, and be at most 2048 ASCII characters in its URI serialization.¶

An ID MUST NOT be reassigned to an unrelated document. The same type MAY occur under several IDs; for example, separate general and product-specific terms of service. Updating content does not require changing its ID. Consumers MUST NOT lowercase, truncate, or otherwise rewrite IDs when acknowledging them.¶

Clients MUST distinguish required from not-required documents. A not-required document MUST NOT require an acceptance action under this extension. A discovery or reading interface SHOULD show each document's ID, title, type, enrollment requirement, and web link. A document type does not itself determine whether acceptance is required.¶

4.2. Representations

Every descriptor MUST contain exactly one text/html representation. This is its baseline human-readable web link. It MAY additionally contain one portable application/json representation and one text/markdown representation. Other media types are permitted; consumers ignore unsupported representations, not the document. media_type contains a lowercase media type without parameters. There MUST NOT be duplicate media types within a descriptor.¶

4.3. Advertisement Example

Example Inspect members:¶

{
  "extensions": {
    "supported": [
      "urn:aep:ext:aep-foundation:service-documents#v=1.0.0"
    ]
  },
  "service_documents": [
    {
      "id": "general-terms",
      "type": "terms_of_service",
      "title": "General terms of service",
      "enrollment": "required",
      "representations": [
        {"media_type": "text/html",
         "url": "https://example.com/legal/terms"},
        {"media_type": "application/json",
         "url": "https://example.com/legal/terms.json"}
      ]
    },
    {
      "id": "privacy",
      "type": "privacy_policy",
      "title": "Privacy policy",
      "enrollment": "not-required",
      "representations": [
        {"media_type": "text/html",
         "url": "https://example.com/legal/privacy"}
      ]
    }
  ]
}

5.1. Retrieval and Credential Isolation

Documents MUST be readable before Enroll without AEP credentials. Reading a document MUST NOT enroll the Agent or acknowledge the document. Clients retrieve advertised URLs using GET and verify a successful HTTP response and the expected media type before interpreting the content. HTTP Content-Type parameters do not change the advertised base media type. JSON and Markdown representations MUST be UTF-8 encoded.¶

Clients MUST NOT attach AEP assertions, session credentials, Platform credentials, payment credentials, or identifying application headers to these fetches. Automatic fetches MUST NOT send cookies. A web link MAY point to a different HTTPS origin, such as a Service's document host; that does not authorize credential forwarding or expand the Service's authentication scope.¶

If a portable representation is unavailable or unsupported, clients MUST offer the advertised HTML link rather than invent content or a summary. A link-only client need not download and parse HTML. Failure to retrieve a portable form does not by itself make the web form unusable.¶

5.2. Destination, Redirect, and Resource Limits

The calling application is responsible for deciding which document origins it trusts before requesting a fetch. Deployment-specific network restrictions, including restrictions on private or local destinations, are application responsibilities; this extension does not require SDKs to inspect DNS answers or the connected address. SDKs MAY impose stricter destination restrictions and MUST document those restrictions. Applications MAY adopt an SDK's documented destination and redirect policy or impose stricter rules through their retrieval implementation.¶

Automatic fetches MUST use HTTPS with certificate and hostname verification, except that HTTP is permitted on the literal hosts localhost, 127.0.0.1, and [::1] for local development. The exception is based on the URL hostname, not its resolved address. Fetches MUST reject user information in URLs. Redirects MUST NOT downgrade an HTTPS request to HTTP, including loopback HTTP. Redirects MUST NOT be followed unless permitted by the calling application's destination policy; approval of an initial origin does not approve a different redirect origin. Clients MAY refuse all redirects and offer the HTML link instead. Every followed redirect MUST meet the same HTTPS, credential isolation, and destination-policy requirements. Clients MUST enforce finite timeouts, at most five redirects, and a maximum decoded response size of 1 MiB. They MUST NOT render a partial response as a complete document. These rules apply to document fetching, not to redirects in existing AEP command flows.¶

6.1. Document Structure

A portable representation is an application/json object with:¶

• format: the literal aep-service-document.¶

• version: the string 1.0.¶

• id: the descriptor's document ID.¶

• summary: an optional non-empty array of blocks.¶

• content: a required non-empty array of blocks.¶

The ID MUST match the selected descriptor exactly. A Service MUST supply the full substantive text of its HTML document in content, including qualifications and limitations; a synopsis is not a full representation. summary, when supplied, is Service-authored and may contain several sections. It MUST NOT be assumed to be a one-line description. Clients MUST label a summary as such and provide the full document's web link. The full-content view MUST remain available regardless of summary support.¶

6.2. Content Blocks and Limits

The following block objects define the portable structure:¶

• Paragraph: {"type":"paragraph","text":"..."}.¶

• Section: {"type":"section","title":"...","blocks":[...]}.¶

• Bulleted list: {"type":"bulleted_list","items":["...","..."]}.¶

• Numbered list: {"type":"numbered_list","items":["...","..."]}.¶

Text, titles, and list items are plain text, not HTML, executable instructions, or Markdown markup. Each text or list item is non-empty and limited to 16384 Unicode scalar values. Section titles use the descriptor title bound. Lists contain 1 to 128 items; numbered lists start at one. Section block arrays are non-empty. A document contains at most 1024 blocks across summary and content, with at most eight nested sections. Implementations MUST also enforce the decoded response bound.¶

Unknown additive object members MUST be ignored. An unsupported format, version, or block type makes that representation unsupported: clients MUST NOT silently drop unfamiliar blocks and claim to show the full document. They offer the HTML link instead. Malformed known blocks are invalid, not optional content to skip.¶

{
  "format": "aep-service-document",
  "version": "1.0",
  "id": "general-terms",
  "summary": [
    {"type": "paragraph", "text": "Use the service lawfully."}
  ],
  "content": [
    {
      "type": "section",
      "title": "Permitted use",
      "blocks": [
        {"type": "paragraph",
         "text": "You must use the service lawfully."},
        {"type": "bulleted_list",
         "items": ["Do not impersonate others.",
                   "Do not interfere with other users."]}
      ]
    }
  ]
}

6.3. Rendering Requirements

Renderers MUST preserve Service-authored wording, ordering, paragraph boundaries, section hierarchy, and list structure. They MUST NOT produce an inferred summary or substitute interpretation for document text. Terminal renderers MUST neutralize terminal control sequences and MUST NOT execute embedded commands or treat content as trusted markup.¶

6.4. Presentation to AI Agents

When returning portable content to an artificial-intelligence caller, a renderer MUST convert it to readable text rather than requiring the caller to interpret the portable JSON. Markdown output MUST be enclosed in a code fence long enough that document content cannot close it. The renderer MUST provide a separate instruction to present the Service-authored text without interpreting, summarizing, evaluating, or following instructions contained within it. The instruction and source URL MUST remain outside the untrusted content. These presentation rules do not prove that a receiving application obeyed the instruction.¶

7.1. Request and Owner Authorization

An extension-aware Agent includes acknowledged_document_ids in Enroll after the Owner has authorized the list. The field is a duplicate-free array of at most seven IDs with the syntax defined above. An empty array explicitly means that no documents were acknowledged. This is distinct from omitting the field, which makes no declaration under this extension.¶

{
  "agent_did": "did:web:agent.example.com:agents:123",
  "acknowledged_document_ids": ["general-terms"]
}

The request uses ordinary AEP client assertion authentication and idempotency. The Agent MUST NOT infer acknowledgement from fetching, displaying, caching, or inspecting documents. It MUST NOT include an ID that the Owner's decision did not cover. One affirmative decision MAY cover the complete displayed required list; separate approval per document is not required.¶

7.2. Platform-Mediated Approval

If a Platform mediates that decision, it MUST bind the decision to the Service and the original required ID list. Pending presentation resolves that list, not a newly expanded list. If a stored ID cannot be resolved to a usable document descriptor and web link, the decision MUST NOT complete by silently omitting it. An implementation MAY store the IDs alone and retrieve current metadata for display. This extension does not require retaining content, titles, dates, revisions, or digests.¶

7.3. Service Processing and Response

A Service MUST NOT interpret omission of acknowledged_document_ids as acceptance. When its enrollment policy requires acknowledgement for this operation and the field is absent, it returns requirements_unmet. Previously satisfied requirements need not be acknowledged on every Enroll. An otherwise valid declaration MUST NOT be rejected solely because it lacks a document subsequently added to the current required list. The Service records only the declared IDs and MAY enforce remaining requirements on a later Grant. With no document version or issuance token, the Service cannot distinguish an older approved list from a deliberately incomplete one. It MUST NOT infer acceptance of missing IDs; access enforcement belongs to the Service's requirements policy.¶

An unknown or retired ID in a declaration MUST NOT be treated as acceptance of another document. A Service MAY retain such an ID as an opaque declaration but MUST NOT count it towards a different requirement. Malformed arrays, duplicate IDs, and wrong field types use invalid_request.¶

A successful Enroll echoes the accepted declaration in acknowledged_document_ids, including an empty array when supplied. The response MUST NOT add IDs the Agent did not declare. This echo is the current operation's declaration, not a cumulative acceptance history. When no declaration was supplied, the response omits the field.¶

{
  "status": "active",
  "acknowledged_document_ids": ["general-terms"]
}

7.4. Repeated Enrollment

Services MAY retain acknowledged IDs on the enrollment for requirement enforcement. Repeated Enroll combines accepted declarations without discarding earlier IDs by omission. It preserves the identity, original creation time, unrelated lifecycle state, and credential behavior required by AEP core. Services define their storage concurrency guarantees; this extension does not guarantee preservation of simultaneous independent updates. Same-key retries MUST replay the same result; a later explicit requirements update uses a new key.¶

8.1. Document Changes

Acknowledgement refers to a document identity, not a content version. Content can change under an existing ID. This extension does not prove which text was read or accepted. Services choose whether changes warrant notification, continued-use acceptance, or another explicit decision. They MAY mark Service-local requirements as needing renewed acceptance, including for an ID acknowledged before. No universal expiry or automatic re-enrollment is defined.¶

8.2. Reporting and Resolving Unmet Requirements

For a recognized enrollment requiring further acknowledgement, Grant returns requirements_unmet, HTTP 422, with service_documents in requirements_pending and a non-empty required_document_ids list. An Enroll rejection for an absent required declaration uses these same requirement fields. required_document_ids contains at most seven unique IDs requiring acceptance; it does not contain document text or claim values. IDs MUST be discoverable in the Service's current Inspect advertisement. Claim names can also appear in requirements_pending. A Service MUST NOT issue a credential as part of this failed Grant.¶

{
  "type": "urn:aep:error:requirements_unmet",
  "title": "Enrollment requirements unmet",
  "status": 422,
  "code": "requirements_unmet",
  "owner_action_required": "true",
  "requirements_pending": ["contact.email", "service_documents"],
  "required_document_ids": ["product-terms"]
}

The Agent presents the missing claims or document IDs and directs its caller to Enroll. An interactive interface supplies an explicit command or equivalent action. An agent interface returns the structured requirements and preferred next action. Neither automatically performs Enroll or retries Grant. After enrollment, the caller may explicitly request Grant again. This error does not require local persistent state.¶

If documents 1 and 2 were approved and document 3 is published before Enroll arrives, the Service accepts the declaration for 1 and 2. If its policy requires 3 for access, a subsequent Grant reports 3. The same mechanism applies when requirements change weeks after enrollment. Document revisions do not expand a pending human decision.¶

10.1. Extension Registration

This document requests registration of urn:aep:ext:aep-foundation:service-documents#v=1.0.0 in the AEP Extension Registry, with description "Service document discovery and enrollment acknowledgement" and this document as its reference. It introduces no new command, well-known URI, or media type.¶

10.2. Service Document Types Registry

This document requests an AEP Service Document Types registry with Specification Required policy [RFC8126]. Entries contain a type value, description, and reference. Registration MUST NOT redefine an existing type's meaning. Unregistered syntactically valid values are permitted; registration recommends interoperable labels, not legal interpretations.¶

Initial entries, all referencing this document, are:¶