# A2ML Specification

## Overview

A2ML (Attested Markup Language) is a text-based document format that combines human-readable markup with machine-verifiable attestation blocks. This page describes the format as currently implemented in the [pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml) toolchain.

## File Format

- Extension: `.a2ml`
- Media type: `application/vnd.a2ml` (IANA registration pending)
- Encoding: UTF-8
- Line endings: LF (Unix-style) recommended; CRLF accepted

## Basic Syntax

A2ML uses a Markdown-like syntax with additional constructs for attestation and structured metadata.

### Headings

    # Top-level heading
    ## Second-level heading
    ### Third-level heading

### Inline Formatting

    **Bold text** for emphasis
    *Italic text* for secondary emphasis
    [Link text](https://example.com) for hyperlinks
    @ref(section-id) for internal cross-references
    `inline code` for identifiers

### Lists

    - Unordered list item
    - Another item
    * Asterisk syntax also works

    1. Ordered list item
    2. Another item

### Code Blocks

code goes here

### Comments

    ;; Scheme-style comments are stripped during parsing.
    ;; Use these for notes that should not appear in output.

## Directive Blocks

Directives are the core extension that distinguishes A2ML from plain Markdown. They carry structured, machine-readable content within annotated blocks.

### Syntax

    @directive-name:
    Content of the directive.
    Can span multiple lines.
    @end

The parser collects everything between `@directive-name:` and `@end` into a named container (rendered as a ``

with `class="directive-name"` in HTML output).

### Standard Directives

The following directives have conventional meaning across the A2ML ecosystem. Tooling may validate or enforce these.

#### `@abstract`

A short summary of the document's purpose. Typically one to three sentences.

    @abstract:
    A2ML is a typed, attested markup format for AI agent identity.
    @end

#### `@attestation`

A trust claim with structured fields. This is the fundamental unit of the A2ML trust model.

    @attestation:
    agent-id: hypatia-scanner-v3
    attested-by: rhodibot
    trust-level: verified
    timestamp: 2026-03-16T14:30:00Z
    signature: sha256:9f86d08...
    capabilities:
      - static-analysis
      - secret-detection
      - dependency-audit
    scope: repository
    @end

Fields:

| Field | Required | Description | |-------|----------|-------------| | `agent-id` | Yes | Unique identifier for the agent being attested | | `attested-by` | Yes | Identifier of the attesting authority | | `trust-level` | Yes | One of: `self-declared`, `peer-reviewed`, `verified`, `audited` | | `timestamp` | Yes | ISO 8601 timestamp of the attestation | | `signature` | Recommended | Cryptographic signature (algorithm:hash) | | `capabilities` | Yes | List of declared capabilities | | `scope` | No | Scope of the attestation (e.g., `repository`, `organization`, `global`) |

#### `@refs`

References and citations. Used for linking to external specifications, standards, or related documents.

    @refs:
    [1] Attested Markup Language Specification (draft), 2026
    [2] SLSA Supply Chain Framework, https://slsa.dev
    @end

#### `@policy`

Declares a policy constraint that tooling should enforce.

    @policy:
    require: attestation.trust-level >= verified
    enforce: ci-pipeline
    action: block-merge
    @end

#### `@provenance`

Records the origin and lineage of the document.

    @provenance:
    created-by: Jonathan D.A. Jewell
    created: 2026-01-15
    last-modified: 2026-03-16
    source: https://github.com/hyperpolymath/a2ml-spec
    version: 0.3.0
    @end

## Attestation Chains

The real power of A2ML comes from attestation chains — sequences of attestations where each one references or builds upon previous ones.

    ;; Agent declares its own capabilities
    @attestation:
    agent-id: codebot-v2
    attested-by: codebot-v2
    trust-level: self-declared
    capabilities:
      - code-review
      - style-checking
    @end

    ;; Security team verifies the agent
    @attestation:
    agent-id: codebot-v2
    attested-by: security-team
    trust-level: verified
    verifies: codebot-v2/self-declared/2026-03-10
    signature: sha256:a3f2c8...
    @end

    ;; Auditor provides highest-level attestation
    @attestation:
    agent-id: codebot-v2
    attested-by: external-auditor
    trust-level: audited
    verifies: codebot-v2/verified/2026-03-12
    audit-report: https://audits.example.com/codebot-v2
    signature: sha256:7b1e4d...
    @end

Each successive attestation raises the trust level and creates an auditable trail from `self-declared` through `verified` to `audited`.

## Trust Levels

| Level | Meaning | Typical Attester | |-------|---------|------------------| | `self-declared` | Agent claims its own capabilities | The agent itself | | `peer-reviewed` | Another agent or team has reviewed the claims | A peer agent or team lead | | `verified` | A security or operations team has validated behaviour | Security team, CI system | | `audited` | An independent audit has confirmed the claims | External auditor |

## Canonical File Locations

In repositories following the [Rhodium Standard](https://github.com/hyperpolymath/rhodium-standard-repositories), A2ML files live in the `.machine_readable/` directory:

    .machine_readable/
      STATE.a2ml         # Project state and progress
      META.a2ml          # Architecture decisions, governance
      ECOSYSTEM.a2ml     # Position in ecosystem, relationships
      AGENTIC.a2ml       # AI agent interaction patterns
      NEUROSYM.a2ml      # Neurosymbolic integration config
      PLAYBOOK.a2ml      # Operational runbook
      anchors/
        ANCHOR.a2ml      # Canonical authority declaration
      policies/
        MAINTENANCE-AXES.a2ml
        MAINTENANCE-CHECKLIST.a2ml

The top-level `0-AI-MANIFEST.a2ml` serves as the entry point that all AI agents must read first.

## Pandoc Integration

A2ML is a first-class Pandoc format. Convert between A2ML and any Pandoc-supported format:

    # A2ML to HTML
    pandoc -f a2ml-reader.lua input.a2ml -o output.html

    # A2ML to PDF (via LaTeX)
    pandoc -f a2ml-reader.lua input.a2ml -o output.pdf

    # Markdown to A2ML
    pandoc input.md -t a2ml-writer.lua -o output.a2ml

    # A2ML to A2ML (normalise)
    pandoc -f a2ml-reader.lua input.a2ml -t a2ml-writer.lua -o normalised.a2ml