Skip to main content

Agent Definition Language Specification

Version0.4.0-draft
StatusDraft
Patent StatusPatent Pending (US Provisional Application No. 63/985,186, filed 2026-02-18)

1. Introduction​

1.1 Purpose​

The Agent Definition Language (ADL) provides a standard format for describing AI agents. ADL documents are JSON objects that describe an agent's identity, capabilities, tools, permissions, and runtime requirements. This specification describes the structure of ADL documents, the semantics of their members, and conformance requirements for implementations.

ADL serves a similar role for AI agents that OpenAPI serves for REST APIs, AsyncAPI for event-driven architectures, and WSDL for web services. It enables:

  • Discovery: Agents can find other agents and assess their fit for the task at hand.
  • Interoperability: Agents can interact with tools, resources, and other agents using a common description format.
  • Deployment: Runtime environments can provision and configure agents based on declared requirements.
  • Security: Permission boundaries and security requirements are explicitly declared, and given force at admission and at runtime by the protocol layer (see the Trust and Runtime Protocols).
  • Lifecycle: Agents can be versioned, tracked through operational states, and managed across their entire lifecycle from draft to retirement.
  • Accountability: A runtime governor enforces declared limits — budgets, iteration, sub-agent admission, oversight, and degradation — and can produce verifiable evidence that it did (see the Runtime Protocol).

1.2 Goals​

  • Portable: ADL documents describe agents independent of any specific runtime, platform, or provider.
  • Interoperable: ADL documents can be transformed into other formats (A2A Agent Cards, MCP configurations) and consumed by diverse tooling.
  • Extensible: ADL supports profiles that add domain-specific requirements without changing the core specification.
  • Secure: Permission boundaries, authentication, and security constraints are first-class concepts.
  • Machine-readable: ADL documents are validated against JSON Schema and can be processed programmatically.
  • Human-friendly: Clear naming conventions and structures that are easy to read and author.

1.3 Design Model​

An ADL document describes an AI agent — its identity, capabilities, permissions, security posture, and governance signals. From that description an agent distills a passport: the compact credential it carries and presents so a counterparty — peer agent, gateway, orchestrator, registry, or human operator — can make a trust decision without first resolving the full document.

The passport model establishes two principles:

  1. Self-contained trust signals. The passport MUST carry enough information for a counterparty to decide whether to interact with the agent and whether to act on its requests, without requiring access to external systems.

  2. Separation of declaration from operations. Operational detail that changes independently of the agent's declared behavior — escalation contacts, audit schedules, evaluation reports, deployment logs — belongs in external records (e.g., a governance record in a registry), not in the passport. Profiles MAY define linking members (e.g., governance_record_ref) that reference such records by stable URI.

This separation ensures that:

  • The passport remains compact, so it can travel on every agent-to-agent and agent-to-gateway exchange.
  • Operational changes (personnel rotation, policy updates) do not require re-issuing the passport.
  • Internal operational detail is not exposed to external counterparties.

ADL separates declaration from procedure across a family of documents built around this passport:

  • ADL Core (this document) is the single declarative document — what an agent is and the limits it declares.
  • The protocol layer is an open set of procedural documents, each defining what an actor MUST do with those declarations. Two are defined today: the ADL Trust Protocol (a counterparty verifying a passport and authorizing agent-to-agent calls) and the ADL Runtime Protocol (a runtime governor enforcing declared operational limits during execution).

Core declares; the protocols enforce. A declared limit has force only when a protocol procedure acts on it. The protocol layer admits further documents as new enforcement boundaries emerge.

Component diagram of the ADL document family. A DECLARE region at the top holds the ADL Core (identity, capabilities, limits, lifecycle), which derives the Agent Passport, a declared and signed artifact. A dashed declare-versus-enforce boundary separates it from the ENFORCE region (the protocol layer) below, holding the Trust Protocol (admission-time verification and authorization), the Runtime Protocol (a continuous governor performing enforcement and evidence), and a dashed open-layer slot for future protocols such as discovery, reputation, and settlement. The passport is consumed by the Trust Protocol at admission and by the Runtime Protocol at runtime, and is available to the open-layer slot in future. The Runtime Protocol produces an Enforcement Evidence hash-chained record.

Figure 1 (informative): The ADL document family. The Core declares the agent passport; the protocol layer enforces it — Trust at admission, Runtime continuously — and is open to future protocols. This figure is illustrative; the normative requirements are stated in the text of this section and the protocol documents.

1.4 Relationship to Other Specifications​

ADL builds upon, interoperates with, and draws on:

  • JSON [RFC8259] — ADL documents are valid JSON.
  • JSON Schema [JSON-SCHEMA] — ADL documents are validated against JSON Schema; tool parameters use JSON Schema for types.
  • A2A Protocol [A2A] — ADL documents can generate A2A Agent Cards.
  • Model Context Protocol [MCP] — ADL documents can generate MCP server configurations; tools, resources, and prompts align with MCP primitives.
  • OpenAPI [OPENAPI] — ADL can reference OpenAPI specifications for HTTP-based tools.
  • W3C Decentralized Identifiers [W3C.DID] and Verifiable Credentials [W3C.VC] — ADL supports DIDs for cryptographic identity and VCs for attestations.
  • AI agent protocols [AI-PROTOCOLS] — ADL's declarative model complements the framework, use cases, and requirements for AI agent protocols developed in the IETF.
  • Agentic-AI governance frameworks [IMDA-AGENTIC], [CLTC-AGENTIC] — ADL's governance signals, accountability model, and runtime enforcement draw on emerging agentic-AI governance and risk-management guidance.

2. Requirements Language​

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.

3. Terminology​

The terms "AI agent", "AI system", "autonomy", and "automation" are used in this document consistent with their definitions in [ISO-22989]. Where this specification narrows an ISO/IEC 22989 term, the narrower definition below takes precedence.

TermDefinition
ADL documentA JSON object that conforms to this specification.
agentAn AI agent [ISO-22989] further scoped as an AI system [ISO-22989] that operates within boundaries declared by an ADL document. An agent senses and responds to its environment and takes actions to achieve its goals, subject to the permissions and constraints expressed in its ADL document.
sub-agentA subordinate agent: a persona an agent spawns that runs under the parent agent's own identity, sharing its passport, permissions, and accountability rather than holding its own. It is sub-ordinate in the literal sense — part of the parent, not a separate party — typically a distinct context with a focused prompt and a tool subset. Declared in permissions.sub_agents (§9.7). Engaging a separately-identified agent is delegation to a peer, not a sub-agent relationship.
delegationAn agent engaging a separate, independently-identified agent — one with its own ADL document and agent passport — to act with or for it. The engaged agent is a peer, not a subordinate: it is discovered (§6.4) and admitted across a trust boundary via the Trust Protocol, and bounded by the calling agent's permissions.delegation envelope (§9.7).
AI systemAn engineered system that generates outputs such as content, forecasts, recommendations, or decisions for a given set of human-defined objectives [ISO-22989].
modelThe AI model (e.g., large language model) that powers an agent's reasoning. In [ISO-22989] terms, a model is the learned computational artifact within an AI system.
toolA function or capability that an agent can invoke to perform an action or retrieve information (equivalent to "function" in function-calling and "tool" in [MCP]).
resourceA data source that an agent can read from (e.g., vector store, knowledge base, file system).
promptA predefined prompt template that an agent can use.
profileA set of additional requirements and members that extend the core ADL specification for specific domains.
permission domainA category of system access (network, filesystem, etc.) that defines operational boundaries for an agent.
runtimeThe system or environment that executes an agent based on its ADL definition.
autonomyThe characteristic of a system that is capable of modifying its intended domain of use or goal without external intervention, control, or oversight [ISO-22989]. ADL expresses the degree of permitted autonomy through governance profile tiers.
agent passportA compact, verifiable credential derived from an agent's ADL document, carried during agent-to-agent interactions and verified on every exchange (§1.3). Its verification procedures are defined by the Trust Protocol.
counterpartyAn actor — a human, service, or other agent — that interacts with an agent and decides whether to verify, admit, and act on its requests. Counterparty procedures performed at admission are defined by the Trust Protocol.
runtime governorThe actor that holds an admitted agent to its declared operational limits during execution, enforcing them on every step. It is a logical role, not a prescribed component; its procedures are defined by the Runtime Protocol.
enforcement recordA verifiable record produced by a runtime governor attesting that it enforced an agent's declared limits. Its format is specified by the Runtime Protocol (Enforcement Evidence).

4. Document Structure​

4.1 Media Type​

  • ADL documents use the media type application/adl+json.
  • ADL documents MUST be encoded in UTF-8.
  • ADL documents MUST be valid JSON [RFC8259].
  • Member names MUST use snake_case (lowercase with underscores).
  • All timestamps MUST be ISO 8601 strings with timezone (e.g., "2026-02-15T14:30:00Z").
  • All URIs MUST conform to [RFC3986].
  • YAML authoring and JSON canonical form: YAML is an authoring convenience; JSON is the canonical wire format. When an ADL document is authored in YAML, implementations MUST convert it to JSON for processing and validation. The media type application/adl+json applies to the JSON canonical form.

4.2 Top-Level Object​

An ADL document MUST be a single JSON object.

Required members:

  • adl_spec (Section 5.1)
  • name (Section 5.3)
  • description (Section 5.4)
  • version (Section 5.5)
  • data_classification (Section 10.1)

Optional members:

  • $schema, id, provider, cryptographic_identity, lifecycle, model, system_prompt, tools, resources, prompts, permissions, security, runtime, metadata, profiles

An ADL document MUST NOT contain members not defined by this specification, a declared profile, or the extension mechanism.

4.3 Extension Mechanism​

  • Profiles: Add domain-specific requirements and members; declared in profiles. See Section 13.
  • Extensions object: Custom vendor data without a full profile. An extensions member MAY appear at any object level within an ADL document. Within extensions, vendor data is grouped under reverse-domain namespace keys.

Vendor namespace keys MUST use reverse-domain notation with at least two dot-separated segments (e.g., com.acme, io.anthropic, org.example.research). Keys MUST conform to the vendor-key production in Appendix D. Single-segment keys (e.g., acme) and uppercase keys (e.g., COM.ACME) are invalid.

Implementations MUST preserve extensions members when round-tripping ADL documents. Implementations MAY ignore the contents of extensions. Implementations MUST NOT reject documents containing extensions with unknown vendor namespaces.

The member name extensions is reserved at every object level in an ADL document. Implementations MUST NOT define non-extension semantics for the extensions member.

Example:

{
  "adl_spec": "0.3.0",
  "name": "Invoice Processor",
  "version": "2.0.0",
  "description": "Processes and routes invoices.",
  "data_classification": {
    "sensitivity": "confidential",
    "extensions": {
      "com.acme": {
        "data_tier": "gold",
        "retention_override_approved": true
      }
    }
  },
  "model": {
    "name": "acme-large-2024",
    "extensions": {
      "com.acme": {
        "model_tier": "premium",
        "cost_per_1k_tokens": 0.03
      }
    }
  },
  "extensions": {
    "com.acme": {
      "internal_id": "inv-proc-007",
      "cost_center": "engineering"
    }
  }
}

4.4 Pattern Matching​

Several ADL members use patterns to specify allowed or denied values. ADL defines a minimal pattern syntax based on a subset of glob matching rules. The following constructs are supported:

  1. Literal match. A string with no wildcard characters matches only itself. Matching is case-sensitive unless the underlying system is case-insensitive (e.g., Windows filesystem paths).

  2. Single-segment wildcard (*). The * character matches zero or more characters within a single segment. The segment boundary depends on context:

    • Host patterns (Section 9.2): segments are separated by . (dot). * does not match dots. *.example.com matches api.example.com but does not match deep.sub.example.com.
    • Environment variable patterns (Section 9.4): * matches any characters in the variable name. APP_* matches APP_PORT and APP_HOST.
    • Command patterns (Section 9.5): * matches any characters in the command name.

  3. Multi-segment wildcard (**). The ** sequence matches zero or more path segments including separators. Valid only in filesystem path patterns (Section 9.3). /data/** matches /data/, /data/foo, and /data/foo/bar/baz. ** MUST NOT appear in host patterns, environment variable patterns, or command patterns.

  4. Restrictions. Patterns MUST contain wildcards only in the positions described above. Mid-string wildcards (e.g., foo*bar) are NOT RECOMMENDED; implementations MAY reject them. A bare * as an entire pattern (matching everything) is valid but NOT RECOMMENDED for security-sensitive domains (allowed_hosts, allowed_variables). Implementations SHOULD warn when a bare * wildcard is used in permission patterns.

Implementations MUST apply patterns using the rules defined in this section. Implementations MUST NOT interpret patterns as regular expressions. Formal grammar productions for pattern elements are defined in Appendix D.

5. Core Members​

5.1 ADL Specification​

Specifies the ADL specification version the document conforms to.

  • REQUIRED. Value MUST be a string in semantic versioning format (MAJOR.MINOR.PATCH). The format MUST conform to the semver production in Appendix D.
  • An implementation implements one or more ADL versions. An adl_spec value is supported when its MAJOR component equals the MAJOR of a version the implementation implements and its MINOR component is less than or equal to the highest MINOR the implementation implements for that MAJOR; any other value is unsupported. A different MAJOR version, or a higher MINOR than the implementation implements, is therefore unsupported.
  • Implementations MUST reject documents whose adl_spec version is unsupported (error ADL-2001, Section 16.2).
  • Within a supported MAJOR, implementations SHOULD accept documents with a lower or equal MINOR version (forward compatibility within a MAJOR) and MAY reject a higher MINOR they do not implement.
  • Pre-release suffixes (e.g., "0.2.0-draft") MUST NOT appear in adl_spec values. Only release versions are valid for conformance. Pre-release identifiers MAY appear in the agent's own version member (Section 5.5).

Example: "adl_spec": "0.3.0"

5.2 $schema​

Optional. URI reference to the JSON Schema for validation. RECOMMENDED for JSON documents (enables IDE validation). Canonical schema URI for ADL 0.3: https://adl-spec.org/0.3/schema.json.

5.3 Name​

Human-readable name for the agent. REQUIRED. Value MUST be a non-empty string. For machine identifiers, use id (Section 6.1).

5.4 Description​

Human-readable description of the agent's purpose and capabilities. REQUIRED. Value MUST be a non-empty string. SHOULD be sufficient for users to understand what the agent does without examining tool definitions.

5.5 Version​

Agent's version. REQUIRED. Value MUST be a string in semantic versioning format (MAJOR.MINOR.PATCH); the format MUST conform to the semver production in Appendix D. Agent version changes SHOULD follow SemVer (MAJOR: breaking; MINOR: new capabilities; PATCH: fixes, docs).

5.6 Lifecycle​

Operational lifecycle status of the agent. OPTIONAL. When present, value MUST be an object containing at minimum a status member.

MemberTypeRequiredDescription
statusstringREQUIREDLifecycle state of the agent
effective_datestringOPTIONALISO 8601 timestamp when current status took effect
sunset_datestringOPTIONALISO 8601 timestamp for planned or actual retirement
successorstringOPTIONALURI or URN of the replacement agent

status​

REQUIRED when lifecycle is present. Value MUST be one of:

StatusMeaning
draftUnder development; not ready for production use
activeOperational and available for use
deprecatedSuperseded; discouraged for new use; may be removed
retiredEnd-of-life; no longer operational

When lifecycle is omitted, no lifecycle assertion is made. Implementations MUST NOT assume a default status.

Runtimes SHOULD check lifecycle.status before provisioning agents. Runtimes SHOULD NOT provision agents with status draft in production environments. Runtimes SHOULD warn users when provisioning agents with status deprecated. Runtimes MUST NOT provision or execute agents with status retired.

note

"Provision" and "execute" refer to instantiating an agent for operation. Reading, parsing, validating, analyzing, or migrating from an agent definition is unrestricted regardless of lifecycle status.

effective_date​

When present, value MUST be a valid ISO 8601 string with timezone. Indicates when the current status took effect.

sunset_date​

When present, value MUST be a valid ISO 8601 string with timezone. Indicates when the agent will be or was retired. Implementations SHOULD warn when sunset_date is in the future and within 30 days. When sunset_date is in the past and status is deprecated, runtimes SHOULD treat the agent as retired.

successor​

When present, value MUST be a string; SHOULD be a URI or URN identifying the replacement agent (see Section 6.1 for identifier formats). SHOULD be present when status is deprecated or retired. Implementations SHOULD warn if successor is present when status is active or draft.

Example:

{
  "lifecycle": {
    "status": "deprecated",
    "effective_date": "2026-01-15T00:00:00Z",
    "sunset_date": "2026-08-01T00:00:00Z",
    "successor": "https://acme.example.com/agents/research-assistant"
  }
}

6. Agent Identity​

6.1 Id​

Unique identifier for the agent. OPTIONAL. When present, value MUST be a string and MUST be a valid URI [RFC3986] or URN [RFC8141].

Identifier formats, in order of preference:

  1. HTTPS URI (RECOMMENDED): https://{domain}/agents/{name} — Provides ownership verification via TLS, direct resolution to the agent's ADL document, and natural integration with .well-known discovery (Section 6.4). The domain authority SHOULD serve the ADL document at the identifier URL with media type application/adl+json.

  2. Decentralized Identifier: did:web:{domain}:agents:{name} — Provides cryptographic identity binding via the DID Document. Resolution follows the did:web method specification [W3C.DID]. RECOMMENDED when cryptographic verification of agent identity is required independent of transport.

  3. URN (offline/catalog use): urn:adl:agent:{namespace}:{name}:{version} — Location-independent identifier suitable for air-gapped environments, offline catalogs, and internal registries where network resolution is unavailable. The {type} segment is agent for an agent identifier; the full namespace syntax (urn:adl:{type}:…) is defined in Section 17.3 and Appendix D, and an id using this scheme MUST conform to the adl-urn production (VAL-37). URN identifiers provide naming only; they do not support ownership verification or discovery without an external resolver.

When an agent has both a resolvable identifier (HTTPS URI or DID) and a URN, the resolvable identifier SHOULD be used as the primary id value. The URN MAY be recorded in metadata for catalog interoperability.

note

The namespace identifier is used as a convention in this specification but is not yet a registered URN namespace per [RFC8141]. Formal registration with IANA will be pursued in a future revision. Implementations SHOULD NOT assume that URNs are globally resolvable.

6.2 Provider​

Identifies the organization or entity that provides the agent. OPTIONAL. When present, value MUST be an object:

MemberTypeRequiredDescription
namestringREQUIREDProvider name
urlstringOPTIONALProvider website
contactstringOPTIONALContact email

6.3 Cryptographic Identity​

Cryptographic identification for the agent. OPTIONAL. When present, value MUST be an object:

MemberTypeRequiredDescription
didstringOPTIONALDecentralized Identifier [W3C.DID]
public_keyobjectOPTIONALPublic key for signature verification

At least one of did or public_key SHOULD be present. The public_key object, when present, MUST contain algorithm (string, REQUIRED) and value (string, Base64-encoded, REQUIRED). Implementations SHOULD reject weak algorithms (e.g., RSA below 2048 bits, DSA, ECDSA below P-256). EdDSA (Ed25519, Ed448) is RECOMMENDED.

Example (agent identity with DID and public key):

{
  "id": "https://acme.example.com/agents/invoice-processor",
  "provider": {
    "name": "Acme Corp",
    "url": "https://acme.example.com",
    "contact": "ai-platform@acme.example.com"
  },
  "cryptographic_identity": {
    "did": "did:web:acme.example.com:agents:invoice-processor",
    "public_key": {
      "algorithm": "Ed25519",
      "value": "MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE="
    }
  }
}

6.4 Discovery​

Agent discovery enables clients to locate agents published by a domain without prior knowledge of individual agent identifiers. It is the front-end of delegation: an agent does its work with its own tools, resources, and model, and turns to discovery only when a task exceeds its own reach and it needs to engage another agent. What it finds is then bounded by the agent's declared permissions.delegation envelope (§9.7.2) and admitted via the Trust Protocol — so discovery widens reach without widening authority.

A two-region figure of governed discovery. On the left is the agent's own reach: a task arrives, and in the common case the agent handles it itself with its own tools, resources, and model, completing with no delegation — whether a task exceeds its reach is judged emergently per run. Only on a capability gap (the exception, drawn at the bottom) does the agent reach out, an arrow crossing into the right region. There a deterministic flow runs top to bottom: a registry served at the well-known adl-agents URL (the directory; publishing invites connection); triage by description and keywords, fetching only the few candidates that fit (emergent — which it picks varies); the delegation envelope of match and deny patterns that permits only peers within the declared boundary (§9.7.2); and Trust Protocol admission verifying the peer's passport and attenuation. Only an admitted peer is engaged, as a separate party. The agent does the work itself whenever it can and reaches a discovered peer only when a task exceeds its own reach, within its declared delegation envelope.

Figure (informative): Discovery is the governed front-end of delegation. The agent acts on its own by default and reaches a discovered peer only when a task exceeds its own reach — bounded by the permissions.delegation envelope (§9.7.2) and admitted via the Trust Protocol. Whether it needs help and which peer it selects are emergent per run; the envelope gate and admission are deterministic. This figure is illustrative; this section and §9.7.2 are authoritative.

Domains hosting ADL agents MAY publish a discovery document at the well-known URI [RFC8615]:

https://{domain}/.well-known/adl-agents

The discovery document, when present, MUST be a JSON object served with media type application/json, MUST contain adl_discovery with the value "1.0", and MUST contain an agents array. Each entry in the array MUST be an object containing:

MemberTypeRequiredDescription
idstringREQUIREDThe agent's identifier per Section 6.1.
adl_documentstringREQUIREDURL to the full ADL document.
descriptionstringRECOMMENDEDA concise, capability-focused summary of what the agent does and when to engage it (see below).
namestringOPTIONALHuman-readable agent name.
versionstringOPTIONALAgent version (Section 5.5).
statusstringOPTIONALLifecycle status (Section 5.6). Permitted values mirror §5.6 and MUST be kept in lockstep with it.
keywordsarrayOPTIONALShort strings naming the agent's domains, tasks, or capabilities, to support programmatic matching.

A domain that publishes a discovery document is, in effect, inviting other agents to connect. The description exists so a discovering agent can triage the list — deciding which agents merit retrieving the full document — without fetching every agent's document first. Publishers SHOULD include it; a discovery document whose entries omit it forces every consumer to fetch each full ADL document just to learn what each agent does. When present, description MUST be a summary of the agent's overall purpose and capabilities, written so another agent can assess fit for a task, and MUST NOT exceed 256 characters. It SHOULD be the agent's top-level description (Section 5.4), or a purpose-focused summary derived from it. The description is a triage aid, not a substitute for the full document: the authoritative capability declarations (tools, resources, permissions) remain in the ADL document at adl_document.

Example discovery document:

{
  "adl_discovery": "1.0",
  "agents": [
    {
      "id": "https://acme.example.com/agents/invoice-processor",
      "adl_document": "https://acme.example.com/agents/invoice-processor/adl.json",
      "name": "Invoice Processor",
      "description": "Processes vendor invoices: extracts line items, validates against purchase orders, and flags discrepancies for human review. Handles PDF and structured formats; does not issue payments.",
      "keywords": ["invoicing", "accounts-payable", "document-extraction"],
      "version": "2.0.0",
      "status": "active"
    },
    {
      "id": "https://acme.example.com/agents/research-assistant",
      "adl_document": "https://acme.example.com/agents/research-assistant/adl.json",
      "name": "Research Assistant",
      "description": "Answers research questions by searching internal knowledge bases and the public web, then synthesizing cited summaries. Read-only; does not modify records or take external actions.",
      "keywords": ["research", "search", "summarization"],
      "version": "2.1.0",
      "status": "active"
    }
  ]
}

The discovery document format is defined by the JSON Schema schema-discovery.json, a standalone artifact verified independently of any individual ADL document.

Clients performing discovery MUST fetch the discovery document over HTTPS. Clients SHOULD validate the TLS certificate chain. The discovery document SHOULD be cacheable; servers SHOULD set appropriate Cache-Control headers.

note

Registration of with IANA per [RFC8615] will be pursued alongside the IETF Internet-Draft submission.

7. Model Configuration​

7.1 Model​

AI model configuration. OPTIONAL. When omitted, the runtime determines the model. When present, value MUST be an object:

MemberTypeRequiredDescription
providerstringOPTIONALModel provider identifier
namestringOPTIONALModel identifier
versionstringOPTIONALModel version
context_windownumberOPTIONALMax context window (tokens)
temperaturenumberOPTIONALSampling temperature (0.0–2.0)
max_tokensnumberOPTIONALMax output tokens
capabilitiesarrayOPTIONALRequired model capabilities

capabilities values may include: function_calling, vision, code_execution, streaming.

7.2 System Prompt​

System prompt for the agent. OPTIONAL. Value MUST be a string or an object. When an object, it MUST contain template (string, REQUIRED) and MAY contain variables (object).

Template Variable Syntax​

Variables in templates use the {{variable_name}} syntax and MUST conform to the template-var production in Appendix D. Variable names MUST begin with a letter (A–Z or a–z) and MAY contain letters, digits, and underscores.

Escaping: To include a literal {{ in template text without triggering variable substitution, implementations MUST support the escape sequence \{{. A \{{ in the template string is rendered as {{ and is not treated as a variable reference.

Undefined variables: When a template references a variable name not present in variables, the implementation MUST treat this as an error (error code ADL-2024) and MUST NOT silently substitute an empty string. Implementations SHOULD include the undefined variable name in the error detail.

Example:

{
  "model": {
    "provider": "acme-ai",
    "name": "acme-large-2024",
    "context_window": 200000,
    "temperature": 0.7,
    "max_tokens": 4096,
    "capabilities": ["function_calling", "vision"]
  },
  "system_prompt": {
    "template": "You are a helpful assistant for {{company_name}}. Today is {{current_date}}.",
    "variables": {
      "company_name": "Acme Corp",
      "current_date": "2026-02-18"
    }
  }
}

8. Capabilities​

8.1 Tools​

Array of tool objects (functions the agent can invoke). OPTIONAL. Each tool MUST contain name (string, REQUIRED) and description (string, REQUIRED). Each tool MAY contain: parameters (JSON Schema), returns (JSON Schema), examples, requires_confirmation (bool), idempotent (bool), read_only (bool), annotations, data_classification (Section 10.1). Tool names MUST be unique, MUST match ^[a-z][a-z0-9_]*$, and MUST conform to the tool-name production in Appendix D. The parameters and returns objects, when present, MUST be valid JSON Schema.

The read_only and idempotent members are behavioral hints, each a boolean defaulting to false when absent. read_only: true declares that invoking the tool does not modify any state observable outside the agent (a pure query). idempotent: true declares that invoking the tool more than once with the same arguments has the same observable effect as invoking it once. A runtime MAY use these hints to decide whether a tool is safe to retry (Section 11.3) or to invoke in parallel, but MUST NOT treat them as a security control: state-changing boundaries are governed by permissions (Section 9), not by these hints.

The examples member, when present, MUST be an array of example objects. Each example object MAY contain:

MemberTypeRequiredDescription
namestringOPTIONALHuman-readable name for the example
inputobjectOPTIONALExample input parameters
outputanyOPTIONALExpected output value

The annotations member, when present, MUST be an object containing implementation hints and metadata. Annotations is an open object — implementations MAY add custom keys. Standard annotation members include:

MemberTypeRequiredDescription
openapi_refstringOPTIONALURI to an OpenAPI specification
operation_idstringOPTIONALOpenAPI operation identifier

See Section 15.3 for OpenAPI integration details. Implementations MUST preserve all annotation members when processing, including unrecognized keys.

Example:

{
  "tools": [
    {
      "name": "search_invoices",
      "description": "Search for invoices by vendor name, date range, or amount.",
      "parameters": {
        "type": "object",
        "properties": {
          "vendor": { "type": "string", "description": "Vendor name to search" },
          "date_from": { "type": "string", "format": "date" },
          "date_to": { "type": "string", "format": "date" }
        },
        "required": []
      },
      "returns": {
        "type": "array",
        "items": { "type": "object" }
      },
      "examples": [
        {
          "name": "Search by vendor",
          "input": { "vendor": "Acme Supplies" },
          "output": [{ "id": "INV-001", "amount": 1500.00 }]
        }
      ],
      "idempotent": true,
      "read_only": true,
      "annotations": {
        "openapi_ref": "https://api.acme.example.com/openapi.json",
        "operation_id": "searchInvoices"
      },
      "data_classification": { "sensitivity": "confidential" }
    }
  ]
}

8.2 Resources​

Array of resource objects (data sources the agent can access). OPTIONAL. Each resource MUST contain name (string, REQUIRED) and type (string, REQUIRED). type MUST be one of: vector_store, knowledge_base, file, api, database. Each resource MAY contain: description, uri, mime_types, schema, annotations, data_classification (Section 10.1). Resource names MUST be unique.

The mime_types member, when present, MUST be an array of strings. Each value MUST be a valid MIME type (e.g., "application/json", "text/plain").

The schema member, when present, MUST be a valid JSON Schema describing the structure of the resource's data.

The annotations member, when present, MUST be an object. Same semantics as tool.annotations — an open object for implementation hints that MUST be preserved when processing.

Example:

{
  "resources": [
    {
      "name": "invoice_store",
      "type": "vector_store",
      "description": "Vector store containing indexed invoice documents for semantic search.",
      "uri": "https://store.acme.example.com/invoices",
      "mime_types": ["application/pdf", "application/json"],
      "data_classification": { "sensitivity": "confidential" }
    }
  ]
}

8.3 Prompts​

Array of prompt objects (reusable prompt templates). OPTIONAL. Each prompt MUST contain name (string, REQUIRED) and template (string, REQUIRED). Each prompt MAY contain description, arguments (JSON Schema). Template arguments use {{argument_name}} and MUST conform to the template-var production in Appendix D. Prompt names MUST be unique.

Example:

{
  "prompts": [
    {
      "name": "summarize_invoice",
      "description": "Summarizes an invoice for a reviewer.",
      "template": "Summarize the following invoice for {{reviewer_role}}:\n\n{{invoice_text}}\n\nHighlight amounts over {{threshold}}.",
      "arguments": {
        "type": "object",
        "properties": {
          "reviewer_role": { "type": "string" },
          "invoice_text": { "type": "string" },
          "threshold": { "type": "number" }
        },
        "required": ["reviewer_role", "invoice_text"]
      }
    }
  ]
}

9. Permissions​

The permissions member defines the agent's operational boundaries. OPTIONAL. When present, value MUST be an object containing one or more permission domain members.

9.1 Permissions Model​

DomainDescription
networkNetwork access boundaries
filesystemFilesystem access boundaries
environmentEnvironment variable access
executionProcess execution boundaries
resource_limitsResource consumption limits
sub_agentsSubordinate personas this agent may spawn
delegationSeparate-identity peers this agent may engage

The first five domains govern the agent's access to system resources. The last two govern delegation, and they differ by identity: sub_agents (§9.7) bounds which subordinate personas the agent may spawn under its own identity (a static list), while delegation (§9.7) bounds which separately-identified peers it may engage across a trust boundary (an envelope over agents it discovers at runtime, §6.4). All are members of permissions and follow the same deny-by-default model below.

Permissions operate on a deny-by-default model. Runtimes MUST deny any capability not explicitly granted in the permissions member. Runtimes MUST enforce declared permissions. Runtimes that cannot enforce a specific permission domain MUST warn users before execution and SHOULD refuse to execute the agent unless the user explicitly acknowledges the limitation.

When the permissions member is omitted from an ADL document, no permissions are granted to the agent. Runtimes MUST treat the absence of permissions as equivalent to an empty permissions object — the agent has no granted capabilities.

When a specific permission domain (e.g., network, filesystem) is omitted from the permissions object, all operations in that domain are denied. For example, if permissions is present but does not contain network, the agent MUST have no network access.

Runtimes MUST NOT infer, assume, or provide default permissions when permissions or a permission domain is absent.

Conflict Resolution​

When a value matches both an allowed_* pattern and a denied_* pattern within the same permission domain, the denied_* pattern MUST take precedence. The agent MUST NOT be granted access to any value matched by a denied_* pattern, regardless of whether it also matches an allowed_* pattern. This deny-takes-precedence rule ensures that explicit exclusions cannot be overridden by broad allow patterns.

Example: If allowed_variables is ["APP_*"] and denied_variables is ["APP_SECRET_*"], the variable APP_SECRET_KEY is denied even though it matches APP_*.

9.2 Network​

Optional members: allowed_hosts (array of host patterns), allowed_ports, allowed_protocols, deny_private (bool). Host patterns support exact match and *.example.com.

Host patterns in allowed_hosts MUST conform to the pattern syntax defined in Section 4.4.

9.3 Filesystem​

Optional members: allowed_paths (array of { path, access } where access is read, write, or read_write), denied_paths.

Path patterns in allowed_paths[*].path and denied_paths MUST conform to the pattern syntax defined in Section 4.4. The ** multi-segment wildcard is valid in filesystem path patterns.

9.4 Environment​

Optional members: allowed_variables, denied_variables (patterns with wildcards, e.g., APP_*).

Variable patterns in allowed_variables and denied_variables MUST conform to the pattern syntax defined in Section 4.4.

9.5 Execution​

Optional members: allowed_commands, denied_commands, allow_shell (bool).

Command patterns in allowed_commands and denied_commands MUST conform to the pattern syntax defined in Section 4.4.

9.6 Resource Limits​

Optional members: max_memory_mb, max_cpu_percent, max_duration_sec, max_concurrent, budget.

The budget member, when present, MUST be an object declaring cumulative consumption ceilings. It MAY contain tokens, cost_usd, and wall_clock_sec; each, when present, MUST be an object that MAY contain per_session and per_day caps.

MemberUnitDescription
budget.tokens.per_session / .per_daytokensMaximum model tokens (input + output) consumed in one session / rolling 24-hour window.
budget.cost_usd.per_session / .per_dayUSDMaximum monetary cost incurred in one session / rolling day.
budget.wall_clock_sec.per_session / .per_daysecondsMaximum cumulative wall-clock run time in one session / rolling day.

Whereas max_duration_sec bounds a single execution, budget.wall_clock_sec bounds cumulative wall-clock across a session or day; the two compose. Each cap MUST be a number greater than 0, and within a dimension per_session MUST be less than or equal to per_day when both are present. These are declarations; the procedure a runtime governor applies to enforce them is defined in the Runtime Protocol.

Example (complete permissions object):

{
  "permissions": {
    "network": {
      "allowed_hosts": ["api.acme.example.com", "*.storage.example.com"],
      "allowed_ports": [443],
      "allowed_protocols": ["https"],
      "deny_private": true
    },
    "filesystem": {
      "allowed_paths": [
        { "path": "/data/invoices/**", "access": "read" },
        { "path": "/tmp/processing/**", "access": "read_write" }
      ],
      "denied_paths": ["/tmp/processing/**/secrets"]
    },
    "environment": {
      "allowed_variables": ["APP_*", "INVOICE_*"],
      "denied_variables": ["APP_SECRET_*"]
    },
    "execution": {
      "allowed_commands": ["python3", "jq"],
      "allow_shell": false
    },
    "resource_limits": {
      "max_memory_mb": 512,
      "max_cpu_percent": 25,
      "max_duration_sec": 300,
      "budget": {
        "tokens": { "per_session": 1000000, "per_day": 10000000 },
        "cost_usd": { "per_session": 5.00, "per_day": 50.00 },
        "wall_clock_sec": { "per_session": 1800, "per_day": 14400 }
      }
    }
  }
}

9.7 Sub-Agents and Delegation​

An agent may bring other agents into its work in two structurally different ways, distinguished by identity. ADL declares them as two separate permission domains:

  • Sub-agents (§9.7.1) are subordinate personas the agent spawns under its own identity — no separate passport. They are statically enumerated and governed as part of the parent.
  • Delegation (§9.7.2) is engaging a separately-identified peer — an agent with its own ADL document and passport — across a trust boundary. Peers are discovered at runtime (§6.4) and admitted via the Trust Protocol.

9.7.1 Sub-Agents (personas)​

The sub_agents member declares the subordinate personas this agent may spawn: distinct contexts, each with a focused prompt and a tool subset, that run under the parent's own identity (§3). A sub-agent has no agent passport and crosses no trust boundary — it is the parent, acting in a narrower role — so its authority is a subset of the parent's by construction. OPTIONAL. When present, MUST be an array of persona objects. Deny-by-default applies (§9.1): a runtime MUST NOT spawn a persona not declared here. Each entry MAY contain:

MemberTypeRequiredDescription
namestringREQUIREDLocal persona/role name (not an agent identifier). MUST be unique within the array.
descriptionstringOPTIONALWhat the persona is for.
prompt_resourcestringOPTIONALIdentifier of a resources entry (§8.2) holding the persona's prompt/instructions — keeps the persona's content in resources (versioned and signed-over) and its declaration here.
toolsarrayOPTIONALSubset of the parent's tools the persona may use. Omitted ⇒ the parent's full tool set. A persona MUST NOT be granted a tool the parent lacks.
max_parallelintegerOPTIONALMaximum instances of this persona running concurrently. Composes with resource_limits.max_concurrent (§9.6).
budget_shareobjectOPTIONALPer-instance sub-cap within the parent's resource_limits.budget (same shape as §9.6 budget), so one persona cannot exhaust the whole envelope.

A persona's authority is always a subset of the parent's; there is no attenuation chain to verify, because there is no separate grant. The parent's declared envelope is the ceiling for the parent and all its personas in aggregate — personas draw down the parent's budget rather than receiving fresh envelopes. The procedure a runtime governor applies to cap personas at spawn time is defined in the Runtime Protocol; a spawn that no entry permits is denied, and the governor resolves runtime.degradation.on_sub_agent_denied (§11.5), defaulting to fail-closed.

9.7.2 Delegation (external peers)​

The delegation member declares the envelope of separately-identified agents this agent may engage as peers. Unlike sub-agents, a delegated peer is a distinct party with its own ADL document and agent passport, and engagement crosses a trust boundary. Because peers are discovered at runtime (§6.4 / the Registry Profile / a trusted directory) rather than enumerated at design time, this domain declares which discovered agents are permitted, not a fixed roster. OPTIONAL. When present, MUST be an object. Deny-by-default applies (§9.1): a delegation to an agent matched by no match pattern is denied. It MAY contain:

MemberTypeDescription
matcharrayAgent-identifier patterns this agent MAY delegate to. Patterns follow §4.4.
denyarrayAgent-identifier patterns this agent MUST NOT delegate to. deny overrides match (§9.1).
max_depthintegerMaximum delegation depth rooted at this agent.
attenuationobjectConstraints a delegated peer MUST satisfy; MAY contain scopes_subset (bool) and budget_subset (bool).

attenuation.scopes_subset: true requires a peer's security.scopes to be a subset of this agent's ceiling; budget_subset: true requires its permissions.resource_limits.budget caps to be less than or equal to this agent's. These compose with the delegation-chain verification defined in the Trust Protocol.

These are declarations; the admission procedure a runtime governor applies when this agent attempts to delegate to a peer is defined in the Runtime Protocol. A delegation that no rule permits is denied; the governor resolves runtime.degradation.on_delegation_denied (§11.5), defaulting to fail-closed.

10. Security​

The security member defines security requirements. OPTIONAL. When present, value MUST be an object that MAY contain authentication, encryption, and attestation.

Section 10 spans two ADL layers. The declarative members defined here in ADL Core — data_classification (§10.1), attestation (§10.2), the credential schemes (§10.3.3), and the scope declarations (§10.4.1–§10.4.2) — describe what an agent handles and what it advertises. The procedural members — passport verification (§10.3.1), presentation proof (§10.3.2), and authorization enforcement (§10.4.3) — define what a counterparty MUST do with those declarations and are specified in the companion ADL Trust Protocol, where they are numbered independently as §1 (Authentication) and §2 (Authorization).

Section 10 is ordered to follow the dependency stack of the security model. Data Classification (§10.1) declares what the agent handles. Attestation (§10.2) signs the passport. Authentication (§10.3) defines how parties prove identity at runtime — agent-to-agent via passport verification (§10.3.1) and presentation proof (§10.3.2), and human or external services via OAuth 2.1, OIDC, mTLS, or API keys (§10.3.3). Authorization (§10.4) covers scope-based AuthZ. Encryption (§10.5) covers channel security.

10.1 Data Classification​

The data_classification member declares the sensitivity and categories of data the agent may access, process, or produce. REQUIRED. Value MUST be an object.

Data classification is required by NIST FIPS 199, NIST SP 800-60, ISO 27001:2022 Annex A.5.12, FedRAMP, SOC 2, and CMMC. It is the foundational step of security categorization across all major compliance frameworks.

This member is a reusable composable attribute. In addition to the required top-level declaration, it MAY also appear within individual tools[*] or resources[*] objects to classify specific capabilities. When present on both the top level and a tool or resource, the tool/resource-level classification applies to that capability.

High-Water Mark Rule​

The top-level data_classification.sensitivity MUST be greater than or equal to the highest sensitivity value declared in any tool-level or resource-level data_classification within the same document. This follows the FIPS 199 high-water mark principle: a system's overall security categorization is the highest value among its constituent information types.

The sensitivity ordering from lowest to highest is: public < internal < confidential < restricted.

Sensitivity levels align with NIST FIPS 199 impact categorization and ISO 27001:2022 Annex A.5.12 information classification.

MemberTypeRequiredDescription
sensitivitystringREQUIREDInformation sensitivity level
categoriesarrayOPTIONALBroad information categories handled
retentionobjectOPTIONALData retention requirements
handlingobjectOPTIONALData handling constraints

sensitivity​

REQUIRED when data_classification is present. Value MUST be one of:

ValueDefinition
publicInformation approved for unrestricted disclosure
internalInformation limited to organizational use
confidentialInformation requiring protection; unauthorized disclosure could cause harm
restrictedInformation requiring the highest level of protection; unauthorized disclosure could cause severe harm

categories​

When present, MUST be a non-empty array. Each item MUST be one of:

ValueDefinition
piiPersonally Identifiable Information
phiProtected Health Information (HIPAA)
financialFinancial data (PCI-DSS, GLBA, SOX scope)
credentialsAuthentication credentials, secrets, keys
intellectual_propertyTrade secrets, proprietary algorithms, business-sensitive data
regulatoryData subject to specific regulatory requirements

Profiles MAY define additional category values.

retention​

When present, MUST be an object. MAY contain:

MemberTypeDescription
min_daysnumberMinimum retention period in days
max_daysnumberMaximum retention period in days
policy_uristringURI to the governing retention policy

When both min_days and max_days are present, min_days MUST be less than or equal to max_days.

handling​

When present, MUST be an object. MAY contain:

MemberTypeDescription
encryption_requiredboolWhether data must be encrypted at rest
anonymization_requiredboolWhether data must be anonymized before processing
cross_border_restrictedboolWhether data may not leave jurisdictional boundaries
logging_requiredboolWhether all access must be logged

Profile Extensions​

Profiles MAY add domain-specific sub-objects within data_classification to provide granular classification vocabularies. For example, a healthcare profile may add a healthcare sub-object with PHI type enumerations, and a financial profile may add a financial sub-object with financial data type enumerations. Multiple profile extensions compose naturally within the same data_classification object. See Section 13 for profile composition rules.

Example (top-level and tool-level data classification demonstrating the high-water mark rule):

{
  "data_classification": {
    "sensitivity": "confidential",
    "categories": ["financial", "pii"],
    "retention": { "max_days": 2555, "policy_uri": "https://acme.example.com/data-retention" },
    "handling": {
      "encryption_required": true,
      "logging_required": true
    }
  },
  "tools": [
    {
      "name": "get_invoice_details",
      "description": "Returns detailed invoice data including PII.",
      "data_classification": {
        "sensitivity": "confidential",
        "categories": ["financial", "pii"]
      }
    },
    {
      "name": "get_invoice_summary",
      "description": "Returns anonymized invoice summary.",
      "data_classification": { "sensitivity": "internal" }
    }
  ]
}

The top-level sensitivity of "confidential" satisfies the high-water mark rule: it equals the highest tool-level value ("confidential" for get_invoice_details).

10.2 Attestation​

The security.attestation member declares cryptographic attestation of the passport. OPTIONAL. When present, value MUST be an object that MAY contain type (one of self, third_party, verifiable_credential), issuer, issued_at, expires_at (ISO 8601), and signature (object). Implementations SHOULD warn when expires_at is in the past or within 30 days.

Signature object: When present, MUST contain algorithm, value (Base64url-encoded), signed_content ("canonical" or "digest"). When signed_content is "digest", MUST also include digest_algorithm and digest_value. Supported algorithms include Ed25519 (RECOMMENDED), Ed448, ES256/384/512, RS256, PS256 (RSA ≥ 2048). Verification: remove signature, serialize with JCS [RFC8785], verify digest if applicable, resolve public key from cryptographic_identity, verify signature.

Example:

{
  "security": {
    "attestation": {
      "type": "third_party",
      "issuer": "https://trust.acme.example.com",
      "issued_at": "2026-01-01T00:00:00Z",
      "expires_at": "2027-01-01T00:00:00Z"
    }
  }
}

10.3 Authentication​

ADL defines authentication at two complementary boundaries:

  1. Agent-to-agent. When one ADL agent calls another, both sides authenticate using cryptographically signed passports (§10.3.1) and per-request presentation proofs (§10.3.2). This path establishes identity for autonomous agent meshes where no shared OAuth 2.1 authorization server exists.

  2. Human or external service to agent. When a human user, an OAuth 2.1 client, or an external service calls an ADL agent, the agent authenticates that party using standard credential schemes — OAuth 2.1 [OAUTH2.1], OIDC [OPENID-CONNECT], mTLS [RFC8705], or API keys (§10.3.3).

The two paths compose. A human's OAuth 2.1 access token authenticates their session at the agent boundary; the receiving agent then presents its own passport plus proof to upstream agents it calls on the human's behalf. ADL does not replace OAuth 2.1 — it adds the agent-identity layer that OAuth 2.1's resource-server protocol does not specify, and integrates cleanly with OAuth 2.1 at the human and external-service boundary.

The security.authentication member of an ADL document is declarative: it advertises which credential scheme (§10.3.3) external clients use to reach the agent. The procedures in §10.3.1 (Passport Verification) and §10.3.2 (Presentation Proof) are procedural rather than declarative — they describe what counterparties MUST do when receiving an ADL passport, and apply regardless of whether security.authentication is present.

10.3.1 Passport Verification & 10.3.2 Presentation Proof​

The agent-to-agent authentication procedures — passport verification and presentation proof — are normatively defined in the companion ADL Trust Protocol as §1.1 and §1.2. They specify what a counterparty MUST do when receiving and acting on an ADL passport, and what a presenter MUST do to bind a passport to a specific request. The credential schemes below (§10.3.3) cover the complementary human and external-service boundary.

10.3.3 Credential Schemes​

The security.authentication member declares the credential scheme that human users, OAuth 2.1 clients, or external services use when calling the agent. It is the OAuth-2.1-aligned (and OAuth-2.1-adjacent) surface of ADL — the did:web-and-passport machinery in §10.3.1 and §10.3.2 covers agent-to-agent identity, while §10.3.3 covers the human-and-external-service boundary.

security.authentication is OPTIONAL. When present, value MUST be an object that MAY contain type (one of none, api_key, oauth2, oidc, mtls) and required (bool). Type-specific members MAY be present.

When type is "none", the agent declares that it requires no credential at its request boundary: requests are accepted without authentication at this layer, and required SHOULD be omitted or false. type: "none" MUST NOT be used by agents handling confidential or restricted data (§10.1) without compensating network-layer controls. This setting governs only the human-and-external-service credential layer (§10.3.3); agent-to-agent passport verification (§10.3.1) and presentation proof (§10.3.2) still apply when the caller is another ADL agent, regardless of type.

10.3.3.1 OAuth 2.1 (type: "oauth2")​

When type is "oauth2", the agent acts as an OAuth 2.1 [OAUTH2.1] resource server and SHOULD follow the OAuth 2.0 security best current practice [RFC9700]. The following members SHOULD be declared so clients can integrate without out-of-band configuration:

MemberTypeDescription
token_endpointstring (HTTPS URI)OAuth 2.1 token endpoint URL
authorization_endpointstring (HTTPS URI)OAuth 2.1 authorization endpoint URL (for grant types that require user interaction)
scopesarray of stringsScopes the agent recognizes; clients MUST request only declared scopes
grant_types_supportedarray of stringsSubset of ["authorization_code", "client_credentials", "refresh_token"] (the grant types OAuth 2.1 recommends)
pkce_requiredbooleanWhether the agent requires PKCE [RFC7636] for the authorization-code grant. SHOULD be true; OAuth 2.1 mandates PKCE for public clients and RECOMMENDS it for confidential clients
dpop_requiredbooleanWhether the agent requires DPoP [RFC9449] sender-constrained tokens. SHOULD be true for deployments handling confidential or restricted data classification (§10.1)

Agents SHOULD NOT issue or accept OAuth 2.0 implicit-grant or password-grant tokens; OAuth 2.1 deprecates both.

10.3.3.2 OpenID Connect (type: "oidc")​

When type is "oidc", the agent acts as an OpenID Connect relying party for end-user authentication on top of OAuth 2.1. The following members SHOULD be declared:

MemberTypeDescription
issuerstring (HTTPS URI)OIDC issuer identifier (the iss value in ID tokens)
audiencestringThe agent's audience identifier (the aud value clients MUST request)
scopesarray of stringsOIDC scopes the agent requires (typically includes openid; MAY include profile, email, etc.)
userinfo_endpointstring (HTTPS URI)UserInfo endpoint (when the agent fetches additional claims)

OIDC inherits OAuth 2.1's PKCE and DPoP requirements; the same recommendations from §10.3.3.1 apply.

10.3.3.3 Mutual TLS (type: "mtls")​

When type is "mtls", the agent requires X.509 client certificates per [RFC8705]. The following members SHOULD be declared:

MemberTypeDescription
accepted_issuersarray of stringsDNs (Distinguished Names) or URIs of CAs the agent accepts
required_sanstringRequired Subject Alternative Name pattern (e.g., URI form) when applicable

mTLS is RECOMMENDED for service-to-service deployments where a client-credential OAuth 2.1 flow would require unnecessary token-exchange machinery.

10.3.3.4 API Key (type: "api_key")​

When type is "api_key", the agent accepts a static or rotating shared secret. The following members SHOULD be declared:

MemberTypeDescription
header_namestringHTTP header carrying the key (default: Authorization with Bearer prefix; common alternatives: X-API-Key)
rotation_policy_uristring (HTTPS URI)Reference to the operational rotation policy for the key

API keys SHOULD NOT be used for confidential or restricted data classification (§10.1) without compensating controls (mTLS at the network layer, IP allowlisting, per-request HMAC). OAuth 2.1 with DPoP is the RECOMMENDED alternative.

10.3.3.5 Composition with §10.3.1 / §10.3.2​

When an agent that declares security.authentication (§10.3.3) calls a peer agent, two authentications happen end-to-end:

  1. The calling client (human, OAuth 2.1 client, or external service) presents a §10.3.3 credential to authenticate at the agent's request boundary.
  2. The agent itself presents its own ADL passport (§10.3.1) plus presentation proof (§10.3.2) to the peer agent it calls upstream.

These are independent authentications. A failed §10.3.3 check MUST NOT bypass §10.3.1 verification of any upstream agent the request reaches; conversely, a successful §10.3.1 verification MUST NOT be treated as authentication of a non-agent caller. Implementations MUST record both authentications in the audit trail when both apply.

Example:

{
  "security": {
    "authentication": {
      "type": "oauth2",
      "required": true,
      "token_endpoint": "https://auth.acme.example.com/oauth/token",
      "authorization_endpoint": "https://auth.acme.example.com/oauth/authorize",
      "scopes": ["invoices:read", "invoices:write"],
      "grant_types_supported": ["authorization_code", "client_credentials"],
      "pkce_required": true,
      "dpop_required": true
    }
  }
}

10.4 Authorization Scopes​

Authentication (§10.3) establishes who a counterparty is. Authorization (§10.4) establishes what they may do. ADL adopts scope-based authorization aligned with OAuth 2.1 [OAUTH2.1]: the agent declares scope requirements at the root level and per-tool, and a counterparty's request is authorized only if its presented scope set covers every scope the targeted resource requires.

Scopes apply uniformly across both authentication paths defined in §10.3:

  • Human or external service to agent (§10.3.3): scopes are presented in the OAuth 2.1 access token, OIDC ID token, or equivalent credential.
  • Agent to agent (§10.3.1 + §10.3.2): scopes are presented in the presentation proof's scopes member (Trust Protocol §1.2.2), bound cryptographically to the request.

The two paths use the same scope vocabulary, the same inheritance and override rules, and the same effective-scope computation. They diverge only in how the requesting scope set arrives at the verifier.

10.4.1 Scope Declaration​

ADL adds two scope-declaration members:

MemberLocationTypeRequiredDescription
security.scopesrootarray of stringsOPTIONALDefault required scopes for the agent. Acts as the agent's scope ceiling when the agent itself is making upstream calls (see Trust Protocol §2.4).
tools[*].security.scopesper toolarray of stringsOPTIONALRequired scopes to invoke this specific tool. Overrides the root default for this tool.

Each scope value MUST be a non-empty string matching the OAuth 2.1 scope grammar: visible ASCII characters excluding double-quote and backslash, separated where needed by single space characters per [RFC6749] §3.3. The recommended convention is <resource>:<action> (e.g., invoices:read, documents:write), and ADL validators SHOULD warn on values that do not follow the convention. Scopes prefixed with adl: are reserved for future spec-defined values.

Scope declarations are meaningful when the authentication path supports scope assertion: OAuth 2.1, OIDC, and presentation proofs (§10.3.2). For non-scope-bearing credentials (api_key, mtls), implementations MUST treat scope declarations as advisory unless the credential is augmented out-of-band (e.g., an API key bound to a server-side scope record).

10.4.2 Inheritance and Override​

The inheritance rule is override-on-presence, not augment:

  • If a tool omits tools[*].security.scopes, the root security.scopes applies for that tool.
  • If a tool declares tools[*].security.scopes (including an empty array), that declaration completely replaces the root scope set for that tool.
  • An empty array ("scopes": []) at tool level explicitly means "this tool requires no scopes" and MUST be treated as a deliberate downgrade, not an oversight.

Validators SHOULD warn when a tool's declared scope set introduces values not present in the root security.scopes, since this expands the agent's stated capability surface beyond what the root advertises. Validators MAY support a strict mode that rejects such expansions.

10.4.3 Authorization Enforcement​

The procedures for enforcing these scope declarations — human-to-agent authorization, agent-to-agent authorization (including the passport-ceiling subset check), multi-hop composition, and effective-scope computation — are normatively defined in the companion ADL Trust Protocol as §2.1–§2.6. Scope declaration and inheritance (§10.4.1–§10.4.2) are part of ADL Core; their enforcement is part of ADL Trust.

10.5 Encryption​

The security.encryption member declares channel and at-rest encryption requirements. OPTIONAL. When present, value MUST be an object that MAY contain in_transit (required, min_version) and at_rest (required, algorithm).

Example:

{
  "security": {
    "encryption": {
      "in_transit": { "required": true, "min_version": "TLS1.3" },
      "at_rest": { "required": true, "algorithm": "AES-256-GCM" }
    }
  }
}

11. Runtime Behavior​

The runtime member configures agent runtime behavior. OPTIONAL. When present, value MUST be an object.

11.1 Input Handling​

The input_handling member, when present, MUST be an object. Optional members: max_input_length, content_types, sanitization.

The sanitization member, when present, MUST be an object describing input sanitization rules. It MAY contain:

MemberTypeRequiredDescription
enabledbooleanOPTIONALWhether input sanitization is active
strip_htmlbooleanOPTIONALWhether to strip HTML tags from input
max_input_lengthnumberOPTIONALMaximum input length in characters

The content_types member, when present, MUST be an array of strings. Each value MUST be a valid MIME type specifying an accepted input content type.

11.2 Output Handling​

The output_handling member, when present, MUST be an object. Optional members: max_output_length, format, streaming (bool).

The format member, when present, MUST be a string specifying the default output format. Value MUST be one of: "text", "json", "markdown", "html".

11.3 Tool Invocation​

The tool_invocation member, when present, MUST be an object. Optional members: parallel (bool), max_concurrent, timeout_ms, retry_policy, max_iterations, max_tool_calls_per_session, loop_detection.

The retry_policy member, when present, MUST be an object describing retry behavior for tool invocations. It MAY contain:

MemberTypeRequiredDescription
max_retriesnumberOPTIONALMaximum number of retry attempts
backoff_strategystringOPTIONALOne of: "fixed", "exponential", "linear"
initial_delay_msnumberOPTIONALInitial delay between retries in milliseconds
max_delay_msnumberOPTIONALMaximum delay between retries in milliseconds

The max_iterations, max_tool_calls_per_session, and loop_detection members bound an agent's reasoning loop:

MemberTypeDescription
max_iterationsintegerMaximum reason→act iterations the agent may take in one session.
max_tool_calls_per_sessionintegerMaximum total tool invocations in one session.
loop_detectionobjectDetection of repetitive behavior; see below.

loop_detection, when present, MUST be an object that MAY contain window (integer; number of most-recent steps examined for repetition) and on_detected (a degradation response object per §11.5, applied when a loop is detected and overriding degradation.on_iteration_limit for the loop case).

These are declarations; the procedure a runtime governor applies — counting iterations and tool calls, detecting loops, and the fail-closed default — is defined in the Runtime Protocol. When a limit or loop fires with no specific response declared, the governor resolves runtime.degradation.on_iteration_limit (§11.5), defaulting to fail-closed.

11.4 Error Handling​

The error_handling member, when present, MUST be an object. Optional members: on_tool_error (abort, continue, or retry), max_retries, fallback_behavior.

The fallback_behavior member, when present, MUST be an object describing behavior when errors occur and on_tool_error does not resolve the situation. It MAY contain:

MemberTypeRequiredDescription
actionstringOPTIONALOne of: "return_error", "use_default", "skip"
defaultanyOPTIONALDefault value to return when action is "use_default"
messagestringOPTIONALUser-facing message on fallback

runtime.degradation (§11.5) generalizes fallback_behavior across all limit causes; this member is equivalent to degradation.on_tool_error, and degradation takes precedence when both are present.

Example:

{
  "runtime": {
    "input_handling": {
      "max_input_length": 32768,
      "content_types": ["text/plain", "application/json"],
      "sanitization": { "enabled": true, "strip_html": true }
    },
    "output_handling": {
      "format": "json",
      "max_output_length": 8192,
      "streaming": false
    },
    "tool_invocation": {
      "parallel": true,
      "max_concurrent": 3,
      "timeout_ms": 30000,
      "retry_policy": {
        "max_retries": 2,
        "backoff_strategy": "exponential",
        "initial_delay_ms": 500,
        "max_delay_ms": 5000
      }
    },
    "error_handling": {
      "on_tool_error": "retry",
      "max_retries": 2,
      "fallback_behavior": {
        "action": "return_error",
        "message": "Invoice processing temporarily unavailable."
      }
    }
  }
}

11.5 Degradation​

The degradation member declares how the agent behaves when an operational limit is reached or a fault occurs. OPTIONAL. When present, MUST be an object whose keys are cause identifiers matching ^on_[a-z0-9_]+$ and whose values are response objects. Recognized causes include on_budget_exhausted (§9.6), on_iteration_limit (§11.3), on_sub_agent_denied (a subordinate-persona spawn was denied, §9.7.1), on_delegation_denied (an external-peer delegation was denied, §9.7.2), on_oversight_timeout (Governance Profile), on_tool_error, and on_anomaly. Causes are an open set: this list is not exhaustive, and profiles MAY define additional causes (for example, on_oversight_timeout and on_anomaly are defined by the Governance Profile).

Each response object MUST contain action and MAY contain the rest:

MemberTypeRequiredDescription
actionstringREQUIREDOne of: "halt", "pause", "fallback", "continue".
valueanyOPTIONALValue to return when action is "fallback".
messagestringOPTIONALUser-facing message.
notifybooleanOPTIONALWhether to emit an out-of-band notification when this cause fires.

degradation generalizes the per-tool runtime.error_handling.fallback_behavior (§11.4), which is retained for backward compatibility and is equivalent to degradation.on_tool_error; when both address that cause, degradation takes precedence.

These are declarations. The procedure a runtime governor applies — and the fail-closed default when a cause fires with no declared response — is defined in the Runtime Protocol. Absence of a degradation response does not mean "continue": a conforming governor halts.

12. Metadata​

The metadata member provides additional information. OPTIONAL. When present, value MUST be an object.

12.1 Authors​

Array of author objects. Each MAY contain name, email, url.

12.2 License​

String: SPDX license identifier or URI to license document.

12.3 Documentation​

String: URI to documentation.

12.4 Repository​

String: URI to source repository.

12.5 Tags​

Array of strings. SHOULD be lowercase, alphanumeric and hyphens only. Tags SHOULD conform to the tag production in Appendix D.

12.6 Example​

{
  "metadata": {
    "authors": [
      {
        "name": "Platform Team",
        "email": "platform@example.com",
        "url": "https://example.com/team/platform"
      }
    ],
    "license": "Apache-2.0",
    "documentation": "https://docs.example.com/agents/invoice-processor",
    "repository": "https://github.com/example/invoice-processor",
    "tags": ["finance", "invoice", "production"]
  }
}

13. Profiles​

The profiles member declares which profiles the document conforms to. OPTIONAL. Value MUST be an array of profile identifiers (URIs or registered names). When a profile is declared: the document MUST satisfy all profile requirements, MAY use profile-defined members, and validators SHOULD check profile-specific rules.

ADL defines two categories of profiles:

  • Standard profiles define domain-specific top-level members and validation rules. Standard profiles use the urn:adl:profile:* namespace and SHOULD be registered with the IANA profile registry (Section 13.5) to prevent naming conflicts. Examples: Governance (urn:adl:profile:governance:1.0), Healthcare, Financial.
  • Vendor profiles declare vendor-specific extensions with schema validation, targeting the extensions namespace rather than defining new top-level members. Vendor profiles use URI identifiers controlled by the vendor (e.g., https://acme.com/adl/extensions/v1) and do not require registration — the reverse-domain namespace provides collision prevention through DNS ownership. See Section 13.4.

Both categories use the same allOf composition mechanism (Section 13.1) and MAY appear together in a document's profiles array.

13.1 Profile Schema Composition​

Profiles extend the base ADL schema using the JSON Schema 2020-12 allOf composition mechanism. Each profile publishes a JSON Schema that:

  1. References the base ADL schema via allOf with $ref.
  2. Declares the profile's additional top-level members in its own properties.
  3. Is an open additive mixin: it MUST NOT set unevaluatedProperties or additionalProperties at its root. A profile schema MAY still close its own sub-objects with additionalProperties: false (each providing an extensions escape), because those constraints are scoped to a single member and do not interfere with other profiles.

A profile schema MUST NOT close its own root because unevaluatedProperties is annotation-scoped: a $ref'd schema only "sees" the properties it evaluated itself, so a self-closed profile would reject members contributed by any other profile — breaking composition (§13.2) and even a profile's own dependencies (§13.3). Instead, closure is applied once, at the composition root, over the full set of declared profiles. A validator constructs the effective schema for a document as:

{
  "allOf": [
    { "$ref": "https://adl-spec.org/0.3/schema.json" },
    { "$ref": "https://adl-spec.org/profiles/example-a/1.0/schema.json" },
    { "$ref": "https://adl-spec.org/profiles/example-b/1.0/schema.json" }
  ],
  "unevaluatedProperties": false
}

This accepts exactly the union of base ADL members, every declared profile's members, and extensions members (reserved at every object level, §4.3), and rejects anything else.

The base ADL schema (Appendix A) follows the same principle: it declares properties and patternProperties but omits additionalProperties and unevaluatedProperties, so it is itself an open building block onto which closure is layered. For documents that declare no profiles, validators SHOULD use the strict schema (schema-strict.json), which applies unevaluatedProperties: false over the base alone.

Profile schemas MUST NOT redefine core ADL members with incompatible types. Profiles MAY:

  • Add top-level members.
  • Add members to existing objects (e.g., extending data_classification with domain-specific sub-objects).
  • Define validation rules.
  • Require specific values for optional core members.
  • Use conditional validation (if/then) to enforce tier-based or context-dependent requirements.

13.2 Multi-Profile Composition​

When a document declares multiple profiles, the document MUST satisfy all declared profile requirements. Validators compose profile schemas using allOf as shown in §13.1 — the base schema and each declared profile's schema are included as elements, and unevaluatedProperties: false is applied once at the composition root. JSON Schema allOf uses "strictest wins" semantics: if any profile requires a member, the composed result requires it.

Profiles MUST be designed for independent composition. A profile's validation rules MUST NOT assume the absence of members defined by other profiles, and a profile schema MUST NOT close its own root (§13.1). For standard profiles, the IANA profile registry designated expert review (see Section 13.5) prevents cross-profile field naming conflicts. Vendor profiles avoid conflicts through their reverse-domain namespace isolation.

13.3 Profile Dependencies​

A profile MAY declare dependencies on other profiles. When a profile declares a dependency, documents using that profile MUST also satisfy the dependency profile's requirements. The profiles array MUST include all transitive dependencies.

At the schema level, a dependent profile composes its parent via allOf. Like every profile schema it is an open mixin (§13.1) and MUST NOT close its own root — closure is applied by the validator over the full set of declared profiles:

{
  "allOf": [
    { "$ref": "https://adl-spec.org/0.3/schema.json" },
    { "$ref": "https://adl-spec.org/profiles/governance/1.0/schema.json" }
  ],
  "properties": {
    "hipaa_data_handling": { "type": "object" }
  }
}

A dependent profile MAY tighten constraints from its parent (e.g., make an optional parent field required, narrow an enum). A dependent profile MUST NOT loosen constraints from its parent (e.g., make a required parent field optional). This follows from allOf semantics — the parent's constraints remain in force.

If a dependent profile needs a parent field to not be required, this indicates a design issue. Resolutions include: refactoring the parent into a base profile with looser constraints, changing the relationship from dependency to sibling, or revising the parent profile in a new major version.

13.4 Vendor Profiles​

A vendor profile is a profile published by an organization to declare vendor-specific extensions with schema validation. Vendor profiles use the same allOf composition mechanism as standard profiles (Section 13.1) but target the extensions namespace rather than defining new top-level members. See Section 13 for an overview of the standard/vendor profile taxonomy.

Vendor profiles use URI identifiers controlled by the vendor (e.g., https://acme.com/adl/extensions/v1). The urn:adl:profile:* namespace is reserved for standard profiles. Vendor profiles MUST NOT use this namespace.

A vendor profile MAY add schema constraints to the extensions object at any level, validating that its reverse-domain namespace contains the expected structure. The profile schema references the base ADL schema via allOf and declares properties for extensions within the relevant objects.

A vendor profile MAY declare a dependency on a standard profile and add schema constraints to extensions within that profile's objects. The vendor profile composes its dependency via allOf and adds extensions constraints inside the profile-defined objects. This enables vendors to extend profile-defined objects without redefining them.

Vendor profiles are subject to the following constraints:

  • Vendor profiles MUST NOT redefine core ADL members or standard profile members with incompatible types.
  • Vendor profiles MUST only add schema constraints within their own reverse-domain namespace under extensions.
  • A vendor profile's extensions schema applies only when the vendor profile is declared in the document's profiles array.
  • Documents MAY include extensions data for a vendor without declaring the vendor's profile. In this case, the data is preserved but unvalidated — implementations treat it as opaque.
  • Multiple vendor profiles compose independently. Each vendor's extensions constraints apply only within its own namespace.

Vendor profiles do not require IANA registration. The reverse-domain namespace provides collision prevention through DNS ownership.

Vendors SHOULD:

  • Publish their profile schema at a stable, dereferenceable URI.
  • Version their profile schemas (e.g., /v1/, /v2/).
  • Document the semantics of their extension fields.

13.5 Standard Profile Registration​

Standard profile identifiers SHOULD be registered to prevent naming conflicts. Only standard profiles — those using the urn:adl:profile:* namespace — are subject to registration. Vendor profiles rely on reverse-domain namespace isolation and do not require registration (see Section 13.4).

The registration authority (e.g., IANA profile registry) MUST employ designated expert review to ensure:

  1. New standard profiles do not redefine members from existing profiles with incompatible semantics.
  2. New standard profiles do not introduce field names that conflict with existing profiles.
  3. Dependencies between profiles are explicitly declared and acyclic.

If a member becomes cross-cutting (needed by multiple standard profiles), the registration authority MAY recommend promoting it to the core ADL specification.

13.6 Example​

{
  "adl_spec": "0.3.0",
  "name": "Invoice Processor",
  "version": "2.0.0",
  "description": "Processes invoices with governance and financial compliance.",
  "data_classification": {
    "sensitivity": "confidential",
    "categories": ["financial"]
  },
  "profiles": [
    "urn:adl:profile:governance:1.0",
    "urn:adl:profile:financial:1.0"
  ]
}

14. Processing ADL Documents​

14.1 Parsing​

Implementations MUST parse ADL as JSON [RFC8259], MUST reject invalid JSON, and MUST reject documents where the top-level value is not a JSON object.

14.2 Validation​

Implementations MUST validate ADL documents against the JSON Schema defined in Appendix A. Implementations MUST validate the following semantic rules:

RuleDescription
VAL-01adl_spec MUST match a supported version
VAL-02Tool names MUST be unique
VAL-03Resource names MUST be unique
VAL-04Prompt names MUST be unique
VAL-05Timestamps MUST be valid ISO 8601
VAL-06URIs MUST be valid per RFC 3986
VAL-07JSON Schema in parameters/returns MUST be valid
VAL-08Profile requirements MUST be satisfied
VAL-09lifecycle.status MUST be a valid status value if present
VAL-10lifecycle.effective_date MUST be valid ISO 8601 if present
VAL-11lifecycle.sunset_date MUST be valid ISO 8601 if present
VAL-12lifecycle.successor MUST be a valid URI if present
VAL-13Tool names MUST match ^[a-z][a-z0-9_]*$
VAL-14Resource type MUST be a valid resource type value
VAL-15model.temperature MUST be between 0.0 and 2.0 if present
VAL-16security.authentication.type MUST be a valid authentication type if present
VAL-17security.attestation.type MUST be a valid attestation type if present
VAL-18runtime.error_handling.on_tool_error MUST be a valid error action if present
VAL-19runtime.output_handling.format MUST be a valid format value if present
VAL-20model.capabilities items MUST be valid capability values if present
VAL-21Host patterns MUST conform to Section 4.4 pattern syntax
VAL-22Filesystem path patterns MUST conform to Section 4.4 pattern syntax
VAL-23Environment variable patterns MUST conform to Section 4.4 pattern syntax
VAL-24Attestation signature.signed_content value "digest" MUST have digest_algorithm and digest_value present
VAL-25data_classification.sensitivity MUST be a valid sensitivity level if present
VAL-26data_classification.categories items MUST be valid category values if present
VAL-27data_classification.retention.min_days MUST be less than or equal to max_days when both are present
VAL-28Top-level data_classification.sensitivity MUST be >= the highest sensitivity in any tool or resource data_classification (high-water mark)
VAL-29Every permissions.resource_limits.budget cap MUST be a number greater than 0
VAL-30Within any budget dimension, per_session MUST be <= per_day when both are present
VAL-31Each runtime.degradation response action MUST be one of halt, pause, fallback, continue
VAL-32runtime.tool_invocation.max_iterations and max_tool_calls_per_session, when present, MUST be integers >= 1
VAL-33runtime.tool_invocation.loop_detection.window, when present, MUST be an integer >= 2
VAL-34permissions.delegation.match and deny patterns MUST conform to Section 4.4 pattern syntax
VAL-35permissions.delegation.max_depth, when present, MUST be an integer >= 1
VAL-35aEach permissions.sub_agents[] entry MUST have a name, unique within the array; a persona's tools MUST be a subset of the parent's tools
VAL-36Each runtime.degradation cause key MUST match ^on_[a-z0-9_]+$
VAL-37Any value using the urn:adl: URN scheme MUST conform to the adl-urn production (Appendix D), including a {type} segment of agent or profile

Implementations MAY perform additional validation based on declared profiles.

14.3 Unknown Members​

Implementations MUST preserve unrecognized members when round-tripping. Implementations MUST NOT reject documents containing extensions with unknown vendor namespaces. Implementations MAY warn on unknown non-extension, non-profile members.

15. Interoperability​

15.1 A2A Agent Card Generation​

Implementations SHOULD support generating A2A Agent Cards from ADL (e.g., name, description, version, tools→skills, cryptographic_identity.did→id, security.authentication→authentication).

15.2 MCP Server Configuration​

Implementations SHOULD support generating MCP server configurations (name, description, version, tools, resources, prompts).

15.3 OpenAPI Integration​

Tools that invoke HTTP APIs MAY reference OpenAPI specs. The tool annotations object MAY contain openapi_ref (URI) and operation_id.

16. Errors​

16.1 Error Format​

Implementations SHOULD return errors in a consistent format, e.g.:

{
  "errors": [
    {
      "code": "ADL-1001",
      "title": "Invalid JSON",
      "detail": "Unexpected token at line 42, column 15",
      "source": { "pointer": "/tools/0/name" }
    }
  ]
}

The source object MAY contain: pointer (JSON Pointer to the error location), line (1-indexed), column (1-indexed).

16.2 Error Codes​

CodeCategoryDescription
ADL-1001ParseInvalid JSON syntax
ADL-1002ParseDocument is not a JSON object
ADL-1003SchemaMissing required member
ADL-1004SchemaInvalid member type
ADL-1005SchemaInvalid enum value
ADL-1006SchemaValue does not match pattern
ADL-2001SemanticUnsupported ADL version
ADL-2002SemanticDuplicate tool name
ADL-2003SemanticDuplicate resource name
ADL-2004SemanticDuplicate prompt name
ADL-2005SemanticInvalid timestamp format
ADL-2006SemanticInvalid URI format
ADL-2007SemanticInvalid JSON Schema
ADL-2008SemanticInvalid tool name pattern
ADL-2009SemanticInvalid resource type value
ADL-2010SemanticTemperature out of range
ADL-2011SemanticInvalid authentication type
ADL-2012SemanticInvalid attestation type
ADL-2013SemanticInvalid error handling action
ADL-2014SemanticInvalid output format
ADL-2015SemanticInvalid model capability
ADL-2016SemanticInvalid host pattern syntax
ADL-2017SemanticInvalid filesystem path pattern
ADL-2018SemanticInvalid environment variable pattern
ADL-2019SemanticMissing digest fields for digest-mode signature
ADL-2020SemanticInvalid data classification sensitivity level
ADL-2021SemanticInvalid data classification category
ADL-2022SemanticRetention min_days exceeds max_days
ADL-2023SemanticTop-level sensitivity below tool/resource sensitivity (high-water mark violation)
ADL-2024SemanticUndefined template variable
ADL-2025SemanticInvalid ADL URN: a urn:adl: value does not conform to the adl-urn production (missing or invalid {type} segment) (VAL-37)
ADL-3001ProfileProfile requirements not satisfied
ADL-3002ProfileUnknown profile
ADL-4001SecurityWeak key algorithm
ADL-4002SecurityInvalid signature
ADL-4003SecurityExpired attestation
ADL-5001LifecycleInvalid lifecycle status value
ADL-5002LifecycleSuccessor present on active/draft agent
ADL-5003LifecycleSunset date in the past with non-retired status
ADL-6001RuntimeResource-limit budget cap not greater than zero (VAL-29)
ADL-6002RuntimeBudget per_session exceeds per_day (VAL-30)
ADL-6003RuntimeInvalid degradation response action (VAL-31)
ADL-6004RuntimeInvalid tool-invocation iteration limit (VAL-32)
ADL-6005RuntimeInvalid loop-detection window (VAL-33)
ADL-6006RuntimeInvalid sub-agent pattern syntax (VAL-34)
ADL-6007RuntimeInvalid sub-agent max_depth (VAL-35)
ADL-6008RuntimeInvalid degradation cause key (VAL-36)
ADL-6009RuntimeInvalid sub-agent declaration: missing or duplicate name, or tools not a subset of the parent's (VAL-35a)

16.3 Error Source Examples​

The source.pointer member uses JSON Pointer [RFC6901] to identify the location of the error within the ADL document. The following examples illustrate source values for representative error codes from each category:

// ADL-1003 (Schema): Missing required member "data_classification"
{
  "code": "ADL-1003",
  "title": "Missing required member",
  "detail": "Required member 'data_classification' is missing",
  "source": { "pointer": "" }
}
// ADL-2002 (Semantic): Duplicate tool name at index 2
{
  "code": "ADL-2002",
  "title": "Duplicate tool name",
  "detail": "Tool name 'search_documents' already defined at index 0",
  "source": { "pointer": "/tools/2/name" }
}
// ADL-2016 (Semantic): Invalid host pattern in permissions
{
  "code": "ADL-2016",
  "title": "Invalid host pattern syntax",
  "detail": "Pattern '**' is not a valid host pattern",
  "source": { "pointer": "/permissions/network/allowed_hosts/1" }
}
// ADL-2023 (Semantic): High-water mark violation on a tool
{
  "code": "ADL-2023",
  "title": "High-water mark violation",
  "detail": "Tool 'query_records' has sensitivity 'confidential' which exceeds top-level 'internal'",
  "source": { "pointer": "/tools/1/data_classification/sensitivity" }
}
// ADL-3001 (Profile): Profile requirement not satisfied
{
  "code": "ADL-3001",
  "title": "Profile requirements not satisfied",
  "detail": "Governance profile requires 'compliance' member",
  "source": { "pointer": "/profiles/0" }
}
// ADL-4001 (Security): Weak key algorithm
{
  "code": "ADL-4001",
  "title": "Weak key algorithm",
  "detail": "Algorithm 'RS256' with 1024-bit key does not meet minimum strength requirements",
  "source": { "pointer": "/cryptographic_identity/public_key" }
}
// ADL-5002 (Lifecycle): Successor on active agent
{
  "code": "ADL-5002",
  "title": "Successor present on non-retired agent",
  "detail": "Member 'successor' is only valid when lifecycle.status is 'retired'",
  "source": { "pointer": "/lifecycle/successor" }
}

17. IANA Considerations​

17.1 Media Type​

This document requests IANA to register the application/adl+json media type in the "Media Types" registry in accordance with [RFC6838].

  • Type name: application
  • Subtype name: adl+json
  • Required parameters: None
  • Optional parameters:
    • profile — A comma-separated list of ADL profile identifiers (URIs or registered names from the ADL Profile Registry defined in Section 17.2) that the document conforms to. Each identifier MUST be a URI conforming to [RFC3986]. Consumers that do not recognize a profile identifier MAY ignore the parameter and MUST preserve it when retransmitting the document.
  • Encoding considerations: binary — ADL documents are JSON text sequences encoded in UTF-8 [RFC8259]. No other character encoding is permitted. Consistent with [RFC8259], UTF-8 without a byte-order mark (BOM) is RECOMMENDED.
  • Security considerations: ADL documents declare agent behavior including permission grants, system prompt templates, tool invocation configuration, and cryptographic identity. Processors MUST treat content from untrusted sources with appropriate caution. Template variables in system_prompt and prompt templates use a {{variable_name}} substitution syntax; processors MUST sanitize variable values before substitution to prevent prompt injection attacks that could alter agent behavior. ADL documents include URI references in fields such as $schema, openapi_ref, documentation, and repository; processors MUST NOT automatically dereference these URIs from untrusted documents, as doing so may target internal network resources and enable Server-Side Request Forgery (SSRF). Documents that declare broad permissions (e.g., a bare * wildcard in allowed_hosts) represent elevated risk and SHOULD require explicit human review before deployment. Processors SHOULD impose limits on document size, JSON nesting depth, and array lengths to prevent resource exhaustion from adversarially crafted documents. For a comprehensive treatment of all security considerations applicable to this media type, see Section 18.
  • Interoperability considerations: ADL documents MUST be processed as JSON [RFC8259] regardless of authoring format. YAML is a common authoring convenience, but processors MUST operate on the JSON form; documents intended to be signed using JCS [RFC8785] MUST be serialized as JSON before signing. Profile declarations — whether via the profile optional parameter or the profiles document member — allow multiple profiles to compose within a single document; consumers that partially implement profile requirements SHOULD process the members they recognize and preserve unrecognized members per Section 14.3. Validation against the JSON Schema defined in Appendix A provides a baseline interoperability check. Implementations that generate A2A Agent Cards or MCP server configurations from ADL documents SHOULD follow the mappings defined in Section 15. Producers SHOULD include the $schema member to enable tooling-assisted validation.
  • Published specification: [this document]
  • Applications that use this media type: AI agent platforms, agent registries, development tools, orchestration frameworks, and runtime environments that provision and manage AI agents.
  • Fragment identifier considerations: Fragment identifiers for resources of this type SHOULD be interpreted as JSON Pointer expressions [RFC6901] identifying a location within the ADL document object.
  • Additional information:
    • Deprecated alias names for this type: N/A
    • Magic number(s): N/A
    • File extension(s): .adl.json, .adl
    • Macintosh file type code(s): N/A
    • Object Identifiers: N/A
  • Person and email address to contact for further information: See the Author's Address section of this document.
  • Intended usage: COMMON
  • Restrictions on usage: None
  • Author: See the Author's Address section of this document.
  • Change controller: IETF

17.2 Profile Registry​

IANA is requested to create and maintain a new registry titled "ADL Profile Registry" within a new "Agent Definition Language (ADL)" registry group.

Registration Policy: Specification Required [RFC8126]. The designated expert reviews registration requests to verify that the profile is documented in a publicly available, stable specification and that all required registration template fields are complete.

Registration Template: Parties wishing to register a profile MUST provide all of the following fields:

FieldDescription
Identifier (URI)A URI that uniquely identifies the profile, conforming to [RFC3986]. The URI SHOULD be dereferenceable and return a human-readable description of the profile.
NameA short human-readable name for the profile (e.g., "ADL Governance Profile").
VersionThe profile version string in MAJOR.MINOR form (optionally MAJOR.MINOR.PATCH), matching the {version} segment of the profile URN (Section 17.3).
Specification ReferenceA stable, publicly accessible URI or document reference for the profile specification. The specification MUST define all profile-required members, validation rules, and any additional semantics added by the profile.
ADL Version CompatibilityThe ADL specification version(s) with which the profile is designed to operate (e.g., "0.2.x").
ContactName and email address of the person or group responsible for the profile registration.
StatusOne of: active (currently maintained) or deprecated (superseded or abandoned).

Initial Registry Contents:

Identifier (URI)NameVersion
urn:adl:profile:governance:1.0ADL Governance Profile1.0.0
urn:adl:profile:portfolio:1.0ADL Portfolio Profile1.0.0
urn:adl:profile:healthcare:1.0ADL Healthcare Profile1.0.0
urn:adl:profile:financial:1.0ADL Financial Profile1.0.0

All initial entries reference Appendix C of this document, target ADL compatibility 0.2.x, are active, and list the Author's Address as contact.

Designated Expert Criteria: The designated expert SHOULD evaluate requests against the following criteria:

  1. Publicly available specification: The profile specification MUST be accessible at a stable, public URI. Specifications behind paywalls or access controls are not acceptable for registration.
  2. Non-conflict with core ADL: The profile MUST NOT redefine or contradict normative requirements of the core ADL specification. Profiles MAY add new members, constrain optional members to a subset of permitted values, or require that optional core members be present.
  3. Complete registration template: All required template fields MUST be present and non-empty. Incomplete registrations MUST be returned to the submitter.
  4. Stable identifier: The profile URI SHOULD be dereferenceable and SHOULD remain stable over time. Ephemeral or frequently changing URIs are not acceptable.
  5. Legitimate purpose: The profile SHOULD address a genuine domain or deployment need not already covered by an existing active registered profile.

17.3 URN Namespace​

IANA is requested to register the adl URN namespace identifier in the "Formal URN Namespaces" registry in accordance with [RFC8141].

  • Namespace Identifier: adl
  • Version: 1
  • Date: [date of publication]
  • Registrant: See the Author's Address section of this document.
  • Purpose: The urn:adl: namespace provides persistent, location-independent identifiers for ADL agents, profiles, and related artifacts. These identifiers are intended for use in offline catalogs, air-gapped environments, and internal registries where network resolution is unavailable. For connected environments, HTTPS URIs (Section 6.1) are the RECOMMENDED identifier format.
  • Syntax: URNs in this namespace take one of two type-discriminated forms. Agent URNs are urn:adl:agent:{namespace}:{name}:{version}, where {namespace} is a lowercase alphanumeric organization identifier and {name} is a lowercase alphanumeric resource name (which may contain hyphens). Profile URNs are urn:adl:profile:{name}:{version}, where {name} is the registry-assigned profile name; profile URNs carry no organization namespace. {version} is a semantic version (MAJOR.MINOR.PATCH) for agent URNs and a MAJOR.MINOR (optionally MAJOR.MINOR.PATCH) version for profile URNs. The formal syntax is defined by the adl-urn production in Appendix D. A urn:adl: value that does not conform to adl-urn — for example, an agent URN omitting the {namespace} segment, or any URN whose type segment is neither agent nor profile — MUST be rejected (VAL-37, error ADL-2025).
  • Assignment: Sub-namespace assignment under urn:adl:profile: is governed by the ADL Profile Registry (Section 17.2). Sub-namespace assignment under urn:adl:agent: is at the discretion of the namespace holder; no central registry is required for agent URNs.
  • Security and Privacy: URN identifiers in this namespace are opaque strings and carry no inherent security properties. Implementations MUST NOT infer ownership, trust, or authorization from a urn:adl: identifier alone. Verification of agent identity MUST rely on the mechanisms described in Section 6.3 (Cryptographic Identity) and Section 10.2 (Attestation). See Section 18 for comprehensive security considerations.

17.4 Well-Known URI​

IANA is requested to register the adl-agents well-known URI suffix in the "Well-Known URIs" registry in accordance with [RFC8615].

  • URI suffix: adl-agents
  • Change controller: IETF
  • Specification document: Section 6.4 of [this document]
  • Status: permanent
  • Related information: The well-known URI https://{domain}/.well-known/adl-agents returns a JSON document listing all ADL agents published by the domain authority. The document format is defined in Section 6.4. The resource MUST be served over HTTPS.

18. Security Considerations​

18.1 Document Integrity​

ADL documents define agent behavior, permission grants, and security requirements. The trust model for an ADL document depends on its provenance and the integrity mechanisms applied to it. Unsigned ADL documents from untrusted or unverified sources MUST be treated as potentially malicious.

When a document includes a cryptographic signature in security.attestation.signature, implementations MUST verify the signature before acting on the document's permission or security declarations. Signature verification requires serializing the document (with the signature object removed) using JCS [RFC8785] to produce a canonical byte sequence, then verifying the resulting digest using the algorithm and public key declared in cryptographic_identity. Implementations MUST reject documents that claim to be signed but whose signature does not verify. Implementations SHOULD warn when processing signed documents whose attestation has expired (expires_at is in the past). An ADL document whose permissions or capabilities have been modified after signing will produce a different canonical byte sequence and fail signature verification; this is the intended behavior and provides protection against privilege escalation via document tampering.

18.2 Sensitive Data in ADL Documents​

ADL documents SHOULD NOT contain secrets, credentials, or other sensitive data in plaintext. Fields such as system_prompt, provider.contact, metadata.authors, and tool parameter examples may inadvertently expose confidential information if documents are logged, cached, or transmitted without adequate access controls.

API keys, passwords, private keys, bearer tokens, and other authentication material MUST NOT appear as literal string values in ADL documents. Where agent configuration requires secret values at runtime, implementations SHOULD use environment variable references or external secret manager URIs rather than embedding values directly. Implementations SHOULD warn when string values match patterns commonly associated with credentials (e.g., values matching the format of known API key prefixes). Organizations SHOULD subject ADL documents to the same secret-scanning controls applied to source code repositories before storage or distribution.

18.3 Template Injection​

The system_prompt member (Section 7.2) and prompts[*].template members (Section 8.3) support a template substitution syntax using {{variable_name}} placeholders. If variable values are derived from untrusted user input and substituted without sanitization, an attacker may be able to alter agent behavior by injecting malicious instructions into the rendered prompt — including instructions that override the intended agent behavior or cause the agent to exfiltrate information.

Implementations MUST sanitize template variable values before substitution. At minimum, implementations SHOULD escape or reject values that contain the template delimiter sequence {{ or }}, and SHOULD apply length limits to variable values. Applications that allow end users to supply template variable values SHOULD treat such values as untrusted and apply content validation appropriate to the deployment context. Runtimes operating on agents with data_classification.sensitivity of confidential or restricted SHOULD log rendered prompts (after variable substitution) to enable post-incident review, subject to applicable privacy constraints.

18.4 Information Disclosure​

ADL documents may reveal infrastructure details that are useful to attackers. The name, description, and tool description fields may disclose the existence of internal services or system architecture. The permissions.network.allowed_hosts list may reveal internal hostname patterns, private IP ranges, or internal service naming conventions. The permissions.filesystem.allowed_paths list may reveal sensitive directory structures. The provider.url, metadata.documentation, and metadata.repository fields may reference internal systems not intended for public visibility.

ADL documents intended for public distribution SHOULD be reviewed to remove or generalize infrastructure-specific information. Host patterns SHOULD use registered domain names rather than IP addresses or internal hostnames. Path patterns SHOULD avoid exposing sensitive directory names. Documents with data_classification.sensitivity of confidential or restricted SHOULD only be distributed to parties with appropriate access authorization and SHOULD NOT be published to public registries without thorough review.

18.5 Resource Exhaustion​

Implementations that parse and validate ADL documents are susceptible to resource exhaustion from adversarially crafted inputs. Specific attack vectors include: deeply nested JSON Schema in parameters and returns members (including circular $ref chains or exponentially expanding allOf/anyOf combinators); documents with very large numbers of tools, resources, or prompts; and documents with excessively long string values in system_prompt, description fields, or pattern arrays.

Implementations SHOULD enforce and document limits on: total document size (recommended maximum: 1 MB); JSON nesting depth (recommended maximum: 32 levels); number of entries in tools, resources, and prompts arrays (recommended maximum: 1000 each); string length for system_prompt and description fields (recommended maximum: 1 MB per field); and number of entries in any permission pattern array (recommended maximum: 500 patterns per domain). Implementations SHOULD terminate processing with an appropriate error code when any of these limits is exceeded rather than continuing to consume resources.

18.6 Pattern Matching Abuse​

The permission pattern syntax (Section 4.4) governs access grants across network, filesystem, environment variable, and execution domains. Overly permissive patterns undermine the deny-by-default permission model; patterns that are expensive to evaluate can enable denial-of-service.

A bare * as the sole value of an entry in allowed_hosts grants access to all hostnames and effectively disables network permission enforcement. Implementations MUST warn when a bare * wildcard is used in any security-sensitive permission pattern, including allowed_hosts and allowed_variables. Implementations SHOULD require explicit user acknowledgment — or refuse to deploy — agents that use bare * patterns in these domains. Pattern evaluation SHOULD be bounded in time and space: implementations that use backtracking pattern matchers SHOULD reject or normalize patterns that would require exponential backtracking (e.g., consecutive wildcards such as ***). The ** multi-segment wildcard MUST NOT appear in host, environment, or command patterns, and implementations MUST reject documents in which it does.

18.7 URI Reference Attacks (SSRF)​

Multiple ADL fields accept URI values: $schema, id, provider.url, metadata.documentation, metadata.repository, resource.uri, tool.annotations.openapi_ref, lifecycle.successor, security.attestation.issuer, and others defined by profiles. If an implementation automatically dereferences these URIs when processing a document from an untrusted source, an attacker may cause the implementation to issue requests to arbitrary endpoints, including internal services not reachable from the public internet — a class of vulnerability known as Server-Side Request Forgery (SSRF).

Implementations MUST NOT automatically dereference URI values from ADL documents received from untrusted sources without explicit operator or user consent. Implementations that fetch external schema documents (e.g., via $schema) for validation purposes SHOULD use an allowlist of trusted schema hosts and MUST NOT follow redirects that leave the trusted set. When fetching openapi_ref documents for tool description or validation, implementations SHOULD verify that the target URI matches a pre-approved allowlist. Implementations SHOULD validate that URI values in ADL documents conform to [RFC3986] and SHOULD reject URIs with schemes other than https, http, or urn unless the deployment context explicitly allows them.

18.8 Canonicalization Attacks​

ADL supports document integrity verification via cryptographic signatures using JCS canonicalization [RFC8785]. The security of this mechanism depends on all conforming implementations producing identical canonical byte sequences for the same logical document. Subtle differences in JCS implementations — such as incorrect handling of Unicode escape sequences, floating-point number serialization, or object member ordering — could cause a legitimate signature to fail verification, or, more critically, allow an attacker to construct a document where different implementations produce different canonical forms, potentially enabling a signature verification bypass.

Implementations MUST use a conformant JCS [RFC8785] implementation for both signing and verification. Implementations SHOULD validate their JCS implementation against the test vectors provided in RFC 8785 before use in a production environment. Implementations MUST NOT verify signatures against non-canonical serializations such as pretty-printed JSON or YAML. Implementations that process ADL documents containing IEEE 754 floating-point values in signed content SHOULD be aware that platform-specific floating-point representation differences may affect canonicalization and SHOULD avoid floating-point values in fields that will be signed when possible.

18.9 Privacy Considerations​

ADL documents may contain personal information subject to applicable privacy regulations. The provider.contact field (Section 6.2) contains a contact email address. The metadata.authors array (Section 12.1) may contain author names, email addresses, and URLs. The system_prompt member may contain information about intended user roles, user populations, or organizational context. When ADL documents are published to public registries or shared broadly, this information becomes publicly accessible.

Publishers SHOULD review ADL documents for personally identifiable information (PII) before public distribution and SHOULD use organizational or role-based contact addresses rather than personal email addresses. Implementations that log ADL document contents for debugging or auditing SHOULD redact or omit provider.contact, metadata.authors, and system_prompt fields from logs unless there is a documented operational requirement to retain them. Users SHOULD be informed when their ADL documents are transmitted to third-party services for validation, indexing, or registry queries.

18.10 Privilege Escalation​

An ADL document that has been modified — whether by a malicious actor during transmission or by a compromised storage or distribution system — could grant an agent permissions or capabilities beyond those that were reviewed and approved for deployment. This risk is the primary motivator for the integrity mechanisms described in Section 10.2.

Implementations SHOULD verify document integrity (Section 10.2) before enforcing the permissions declared in a document, particularly when documents are retrieved from network locations, shared storage systems, or public registries. Runtimes that cannot verify document integrity SHOULD apply compensating controls — such as mandatory human review — before deploying agents that declare elevated permissions or sensitive data access. When a document's data_classification.sensitivity is confidential or restricted, runtimes SHOULD require a verified signature or a verified supply chain (e.g., document retrieved from a trusted registry over an authenticated and integrity-protected channel) before provisioning. Organizations SHOULD maintain an inventory of approved ADL documents along with their expected signatures or cryptographic digests, and SHOULD treat any discrepancy between the recorded and observed document as a potential security incident.

18.11 Cross-Origin and Supply Chain Concerns​

ADL documents may be fetched from remote sources: registries, source control systems, artifact stores, or agent marketplaces. A document tampered with in transit or at the origin could cause a runtime to provision a malicious agent without the operator's knowledge.

ADL documents SHOULD be fetched over authenticated, integrity-protected channels (HTTPS with full certificate validation). Implementations SHOULD verify document signatures (Section 10.2) when documents are retrieved from remote or third-party sources. Implementations SHOULD validate that the signing identity declared in cryptographic_identity matches an expected, trusted identity for the document's declared provider.

Supply chain integrity requires attention at every reference boundary: the ADL document itself, referenced OpenAPI specifications (openapi_ref), and external JSON Schemas ($schema). Implementations that automatically resolve external references during provisioning SHOULD pin or verify all such references. When accepting ADL documents from third-party sources, implementations SHOULD apply an allowlist of trusted providers (based on provider.name or id URI authority), verify attestation signatures from trusted issuers, and treat documents from unverified sources with the same caution applied to untrusted executable code.

18.12 Permission Model and Defense in Depth​

The deny-by-default permission model (Section 9.1) is a foundational security property of ADL: an agent can only access resources and capabilities that its ADL document explicitly permits. However, the effectiveness of this model depends entirely on the runtime correctly enforcing declared permissions. No permission model is a substitute for defense in depth.

Runtimes MUST enforce declared permissions and MUST NOT allow agents to exceed those permissions under any circumstances, including error conditions or fallback behaviors. Runtimes that cannot enforce a specific permission domain (e.g., because the underlying platform lacks the required isolation primitives) MUST warn users before execution and SHOULD refuse to execute the agent unless the user explicitly acknowledges the limitation.

Beyond permission enforcement, runtimes SHOULD monitor agent behavior during execution: logging tool invocations, recording network destinations contacted, and alerting on anomalous activity such as repeated attempts to access resources outside declared permissions. The ADL document represents intended access boundaries at definition time; runtime monitoring ensures actual behavior remains within those boundaries in production.

Runtimes SHOULD validate tool inputs and outputs against the declared JSON Schema (Section 8.1) before passing them to or from the agent. Malformed responses from external tool implementations could inject unexpected data into agent reasoning; runtime-level schema validation provides a defense against malfunctioning or malicious tool backends. Tools annotated with requires_confirmation: true MUST receive explicit user confirmation before invocation; runtimes MUST NOT invoke such tools autonomously regardless of other configuration.

Lifecycle status MUST be enforced as a security boundary. Runtimes MUST NOT provision or execute agents with lifecycle.status of retired. Retired agents may have revoked credentials, unpatched vulnerabilities, or stale permission configurations. Agents with lifecycle.status of deprecated SHOULD trigger warnings to operators, who SHOULD migrate to the agent identified by lifecycle.successor before the sunset_date is reached.

19. References​

19.1 Normative References​

19.2 Informative References​

Appendix A. JSON Schema​

The normative JSON Schema for ADL is available at https://adl-spec.org/0.3/schema.json (JSON Schema Draft 2020-12). A minimal required-fields schema is provided in schema.json in this directory.

Appendix B. Examples​

See the examples/ directory:

Appendix C. Profiles​

ADL profiles are maintained in the profiles/ directory. Each profile is versioned independently and declares compatibility with ADL versions.

Available Profiles​

ProfileIdentifierStatus
Governanceurn:adl:profile:governance:1.0Draft
Portfoliourn:adl:profile:portfolio:1.0Draft
Healthcareurn:adl:profile:healthcare:1.0Draft
Financialurn:adl:profile:financial:1.0Draft

See the profiles/ directory for the full profile index and contribution guidelines.

Appendix D. ABNF Grammar​

This appendix defines formal ABNF grammar productions (RFC 5234 / RFC 7405) for syntactic constructs specified in this document. All productions use ASCII character references consistent with RFC 5234, Appendix B. The core ABNF rules ALPHA (letters), DIGIT (decimal digits), and VCHAR (visible ASCII characters) are defined in RFC 5234 Section 6 (B.1).

; Semantic Versioning format (Sections 5.1, 5.5)
semver          = 1*DIGIT "." 1*DIGIT "." 1*DIGIT

; Tool name (Section 8.1)
; All alpha characters MUST be lowercase; satisfies ^[a-z][a-z0-9_]*$
tool-name       = lc-alpha *( lc-alpha / DIGIT / "_" )
lc-alpha        = %x61-7A          ; a-z (lowercase letters only)

; Vendor extension namespace key (Section 4.3)
; Reverse-domain notation, minimum two segments
vendor-key     = domain-segment 1*("." domain-segment)
domain-segment = lc-alpha *(lc-alpha / DIGIT / "-")

; Template variable (Sections 7.2, 8.3)
; Used in system_prompt templates and prompt templates
template-var    = "{{" var-name "}}"
var-name        = ALPHA *( ALPHA / DIGIT / "_" )
                  ; First character MUST be a letter (upper or lowercase)

; Tag (Section 12.5)
; Lowercase alphanumeric characters and hyphens
tag             = 1*( lc-alpha / DIGIT / "-" )

; Pattern syntax (Section 4.4)
; An ADL pattern consists of literal characters and optional wildcard tokens
pattern         = 1*pattern-element
pattern-element = multi-wildcard / single-wildcard / literal-chars
multi-wildcard  = "**"
                  ; Valid only in filesystem path patterns (Section 9.3)
                  ; MUST NOT appear in host, env-variable, or command patterns
single-wildcard = "*"
                  ; Matches within one segment; does not cross "." in host
                  ; patterns or "/" in filesystem path patterns
literal-chars   = 1*literal-char
literal-char    = %x21-29 / %x2B-7E
                  ; Printable ASCII except "*" (%x2A)
                  ; "/" (%x2F) carries segment-boundary meaning in path patterns
                  ; "." (%x2E) carries segment-boundary meaning in host patterns

; ADL URN namespace (Section 17.3)
; Agent URNs carry an organization namespace; profile URNs do not.
;   urn:adl:agent:{namespace}:{name}:{version}
;   urn:adl:profile:{name}:{version}
adl-urn         = agent-urn / profile-urn
agent-urn       = "urn:adl:agent:" urn-namespace ":" urn-name ":" semver
profile-urn     = "urn:adl:profile:" urn-name ":" profile-version
profile-version = 1*DIGIT "." 1*DIGIT [ "." 1*DIGIT ]
                  ; MAJOR.MINOR, optionally MAJOR.MINOR.PATCH
urn-namespace   = 1*( lc-alpha / DIGIT )
                  ; Lowercase alphanumeric organization identifier (agent URNs only)
urn-name        = ( lc-alpha / DIGIT ) *( lc-alpha / DIGIT / "-" )
                  ; Lowercase alphanumeric resource name, may contain hyphens

Cross-Reference Summary​

ProductionNormative SectionUsage
semver5.1, 5.5adl_spec and version values
tool-name8.1Tool name values
vendor-key4.3Vendor extension namespace keys
template-var7.2, 8.3{{variable}} references in templates
tag12.5metadata.tags array items
pattern4.4, 9.2–9.5Permission domain pattern strings
adl-urn17.3urn:adl: namespace identifiers