IANA Media Type Registration: application/vnd.a2ml
=========================================================
SPDX-License-Identifier: MPL-2.0

Canonical copy: format-registrations/iana/a2ml-media-type.txt
This file is a synchronised copy for co-location with the A2ML spec.

Submission Date: 2026-04-03 (Revision 2)
Submitted By: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

---

Type name:
  application

Subtype name:
  vnd.a2ml

Required parameters:
  None

Optional parameters:
  charset
    If specified, the value MUST be "utf-8" (case-insensitive).
    A2ML documents are UTF-8 by default for textual content (RFC 3629).
    The charset parameter SHOULD NOT be specified if the document
    contains opaque payload blocks with arbitrary binary content.

Encoding considerations:
  binary

  A2ML documents are primarily UTF-8 text but MAY include opaque
  payload blocks (via the @opaque directive) containing arbitrary
  binary data.  Because opaque blocks may contain any octet sequence,
  the encoding is classified as "binary" per RFC 6838 Section 4.8.

  Implementations MUST preserve byte-for-byte fidelity of opaque blocks
  across parsing and serialisation.

  Line endings are LF (U+000A) by convention; parsers MUST accept
  CR+LF (U+000D U+000A) as well and normalise to LF internally.

Security considerations:
  A2ML is a document markup format comparable to Markdown and AsciiDoc.
  It is not executable by itself and does not contain active content.

  However, A2ML MAY embed opaque payload blocks (using the @opaque
  directive) and code blocks (using fenced code blocks) that can contain
  code, scripts, or other executable content.  Processors MUST treat
  opaque payloads and code blocks as untrusted data and MUST NOT execute
  embedded content by default.

  If an implementation offers execution or evaluation features (e.g.,
  running code blocks in a REPL environment), it MUST:
  (a) Operate in a sandboxed context with restricted privileges;
  (b) Require explicit user consent before execution;
  (c) Clearly indicate which content is being executed;
  (d) Provide mechanisms to disable execution entirely.

  A2ML documents support cryptographic attestation via Ed25519
  signatures for opaque payloads and document structure.
  Implementations that verify signatures MUST validate:
  (a) Signature correctness against the stated public key;
  (b) Timestamp freshness (to prevent replay);
  (c) Public-key trust (via a known-keys list or certificate chain).

  Documents without signatures SHOULD be treated as unverified.

  Privacy considerations:
  - A2ML documents may contain PII in author metadata, abstracts, or
    content blocks
  - Implementations SHOULD provide mechanisms to redact or strip
    metadata when sharing documents
  - Opaque payloads may contain sensitive data and SHOULD be inspected
    before transmission across trust boundaries

  External references:
  - A2ML link syntax ([label](url)) and @ref() directives may
    reference external resources
  - Implementations MUST NOT automatically fetch external resources
    without user consent

  See security section of the A2ML specification for complete details:
  https://github.com/hyperpolymath/standards/blob/main/a2ml/SPEC-v1.0.adoc

Interoperability considerations:
  A2ML is designed for cross-platform interoperability with progressive
  strictness modes:

  - Lax mode: Permissive parsing, warnings only
  - Checked mode: Structural validation required (unique IDs, valid
    cross-references, well-formed directives)
  - Attested mode: Cryptographic attestation required, enforced by
    dependent-type proofs in the Idris2 reference implementation

  Character encoding is UTF-8 (RFC 3629).  Byte Order Marks (U+FEFF)
  at document start are permitted but not required; parsers MUST accept
  and silently consume a leading BOM.

  Opaque payloads are preserved byte-for-byte across parsing and
  serialisation.  Renderers MAY transform opaque content for display
  but MUST retain the original bytes for attestation.

  A2ML is renderer-agnostic and can be converted to HTML5, LaTeX/PDF,
  Markdown (CommonMark), Djot, or plain text.

  Implementations SHOULD support all three strictness modes.

Published specification:
  Primary specification (v1.0.0, Stable):
  https://github.com/hyperpolymath/standards/blob/main/a2ml/SPEC-v1.0.adoc

  Formal verification (Idris2 typed core):
  https://github.com/hyperpolymath/a2ml/tree/main/src/A2ML

Applications which use this media type:
  - A2ML compilers and validators (the "a2ml" command-line tool)
  - Static site generators that consume A2ML documents
  - Document management systems requiring formal structure guarantees
  - Academic publishing workflows for papers and specifications
  - Technical documentation with verifiable cross-references
  - Standards bodies requiring attested document integrity
  - AI agent manifest files (0-AI-MANIFEST.a2ml, AI.a2ml)

  Reference implementation:
  https://github.com/hyperpolymath/standards/tree/main/a2ml

Fragment identifier considerations:
  Fragment identifiers for A2ML documents refer to element IDs.

  Syntax:  #<id>  where <id> matches [A-Za-z][A-Za-z0-9:_-]*

  Examples:
    #intro        -- references a section with id="intro"
    #fig:results  -- references a figure with id="fig:results"

  Resolution:
    Fragment MUST match an element with the specified ID.
    If no match, user agent SHOULD treat it as unresolvable (no error).
    ID uniqueness depends on strictness mode (attested > checked > lax).

Restrictions on usage:
  None

Additional information:

  Deprecated alias names for this type:
    None

  Magic number(s):
    None (text-based format; identified by file extension or content
    detection of A2ML-specific directives)

  File extension(s):
    .a2ml

  Macintosh file type code(s):
    None

  Object Identifier(s) or OID(s):
    None

Person & email address to contact for further information:
  Jonathan D.A. Jewell
  j.d.a.jewell@open.ac.uk
  The Open University
  Milton Keynes, MK7 6AA, United Kingdom

Intended usage:
  COMMON

Author/Change controller:
  Jonathan D.A. Jewell
  The Open University
  j.d.a.jewell@open.ac.uk

Provisional registration: No (Vendor-tree registration.)

---

Note: A2ML is distinct from ASAM A2L (application/A2L), which is a
measurement and calibration data format for automotive ECUs.

---

References:

[1] RFC 6838 - Media Type Specifications and Registration Procedures
    https://www.rfc-editor.org/rfc/rfc6838.html

[2] A2ML Specification (v1.0.0, Stable)
    https://github.com/hyperpolymath/standards/blob/main/a2ml/SPEC-v1.0.adoc

[3] A2ML Idris2 Core Implementation
    https://github.com/hyperpolymath/a2ml/tree/main/src/A2ML

---

Change Log:

2026-01-30: Initial registration template created
2026-03-16: Expanded security, interoperability, fragments, references
2026-04-03: Revision 2 -- encoding "binary", BOM handling, A2L
            disambiguation, tightened RFC 2119 keywords, web form
