FAFA: A Declarative Agent Capability Format

1.1. Problem Statement

Agent-interaction work consistently defines an object model for agent identity, capability, and endpoint, and then defers the serialization to "some JSON" or an unspecified schema. The object model is specified repeatedly; the on-the-wire, in-the-registry, in-the-repository format — the document an agent publishes about itself — is left unspecified.¶

1.2. Solution Overview

.fafa specifies that document: a vendor-neutral, YAML-native declaration of what an agent is, what it can do, and how it is reached. It defines the document those mechanisms carry; it does not define discovery, transport, authorization, or orchestration.¶

.fafa is complementary by design. It composes with existing and future agent-interaction protocols and competes with none of them. A protocol that needs an agent-identity-and-capability document MAY use .fafa as that document without adopting any other part of the FAF family.¶

1.3. Design Goals

1. Declarative, never executable — a .fafa document describes an agent; it never instructs, authorizes, or executes one.¶

2. Vendor-neutral — no dependency on any single agent-interaction protocol.¶

3. Composable — sits at the format layer beneath protocols, not in competition with them.¶

4. Forward-compatible — unknown fields are preserved as extensions; documents remain valid across minor revisions.¶

5. Family-coherent — extends .faf [FAF-FORMAT]; shares YAML 1.2 [RFC9512] as base syntax and MIT-licensed distribution.¶

3.1. Format Overview

A .fafa file MUST be a valid YAML 1.2 document [RFC9512] [YAML]. It is declarative: it carries identity, capability declarations, and endpoint references, and MUST NOT contain executable content, code, or instructions to a model.¶

3.2. Media Type

The agent format is identified by application/vnd.fafa+yaml, registered in the IANA vendor tree on 2026-06-26 [IANA-FAFA]. This document documents that vendor-tree registration. No standards-tree registration is requested. The canonical specification is [AGENT-FORMAT]. The file extension is .fafa.¶

3.3. Document Structure

A .fafa document is a single YAML mapping. Example:¶

version: "1.0"

agent:                       # REQUIRED -- identity
  name: faf-agent
  id: "did:web:faf.one:agent"
  vendor: WolfeJAM
  version: "1.0.0"
  description: "Cites the spec or refuses out of scope"

capabilities:                # REQUIRED -- MAY be empty
  - name: validate
    type: tool
    description: "Validate .faf documents against the spec"
    tags: [validation, faf, spec]

endpoints:                   # REQUIRED -- MUST be non-empty
  - protocol: mcp
    transport: stdio
    location: faf-agent-mcp

provenance:                  # OPTIONAL -- context substrate
  faf: "./project.faf"
  spec: "application/vnd.faf+yaml"

Required top-level fields: version; agent (with at least name and id); capabilities (array, MAY be empty); endpoints (array, MUST be non-empty).¶

Optional top-level fields: attachment, provenance, signature, metadata (free-form vendor extensions).¶

3.4. Agent Section

Declares identity.¶

• Required: name (string, unique within the issuing vendor namespace); id (globally unique identifier — DID, URI, or vendor-scoped UUID).¶

• Optional: vendor; version (semantic version of the agent, NOT of this specification); description; homepage; license (SPDX identifier).¶

3.5. Capabilities Section

Each capability is a structured object.¶

• Required: name (unique within the document); type (tool, resource, prompt, event, or other).¶

• Optional: description, input_schema, output_schema, tags, apophatic (boolean; if true, the capability refuses out-of-scope invocation rather than attempting best effort), cites_spec (the format or specification the capability operates against).¶

The capabilities array MAY be empty. Declaration is not authorization (see Section 5).¶

3.6. Endpoints Section

Each endpoint declares a protocol binding.¶

• Required: protocol (mcp, a2a, grpc, http, or other); transport (stdio, http, websocket, quic); location (reachable address — URI, package name, or transport-specific locator).¶

• Optional: version, auth, region, health.¶

Multiple endpoints MAY declare the same protocol with different transports.¶

3.7. Attachment Section (Optional)

Describes the infrastructure context within which the agent operates, without requiring any particular gateway protocol. Optional fields: gateway, domain, policy, attachment_point.¶

3.8. Provenance Section (Optional)

Cites the context substrate the agent operates from — the FAF-family integration point. A .fafa agent SHOULD declare which .faf it reads. Optional fields: faf (reference to a .faf document), fafm (reference to a .fafm document), spec (media type of the substrate), version.¶

3.9. Parser Requirements

• Consumers MUST use YAML safe-load (no custom type construction).¶

• Consumers MUST treat unknown top-level fields, and unknown subfields within agent, capabilities, and endpoints, as forward-compatible extensions.¶

• Consumers SHOULD use UTF-8 encoding and SHOULD keep documents within common registry storage budgets (RECOMMENDED: < 64 KB).¶

3.10. File Conventions

• Standard filename: agent.fafa (alongside project.faf at the project layer), or served via the /.well-known/faf discovery anchor defined in [FAF-FORMAT].¶

• File extension: .fafa. Encoding: UTF-8.¶

• Multiple .fafa documents per scope are permitted, distinguished by agent.id.¶

3.11. Versioning

The top-level version field declares the version of this specification to which the document conforms. Versioning is semantic: 1.x revisions are backward-compatible; a new major version is reserved for breaking changes made only with strong cause. Consumers MUST accept documents whose version shares their supported major version, and MUST apply forward-compatible extension handling for unknown fields. This separates the agent's version (agent.version) from the format's version (top-level version), so an agent may revise independently of the specification.¶

5.1. Active or Executable Content

None. A .fafa document is YAML data with no scripts, code, or active markup. Implementations MUST treat .fafa content as data, never as instructions or commands. Declaration is not authorization: an implementation MUST NOT invoke or auto-execute a capability solely because it is declared.¶

5.2. YAML-Specific Vulnerabilities

.fafa is built on YAML 1.2; the YAML security considerations of [RFC9512] apply. Parsers MUST disable custom type construction (e.g., !!python/object, !ruby/object), MUST enforce alias-expansion limits to mitigate entity-expansion ("billion laughs") attacks, and MUST enforce nesting-depth limits to prevent stack overflow.¶

5.3. Untrusted Input and Prompt Injection

.fafa documents originate from agents and third parties and MUST be treated as untrusted input. Consumers MUST NOT elevate .fafa content to "system" or "developer" tiers within prompt hierarchies; it occupies the user-data tier. Capability declarations are a documented vector for over-trust and prompt injection.¶

5.4. Identity, Endpoints, and Least Privilege

Identity claims, capability declarations, and endpoints are self-asserted. Consumers MUST treat endpoints as untrusted until verified (against signature where present), MUST scope capability consumption to the declaring agent's verified identity, and MUST apply least privilege when acting on declared capabilities.¶

5.5. Prohibited Content

.fafa documents MUST NOT contain secrets, API keys, or credentials; MUST NOT contain user-personal data (use .fafm for memory of that kind); and MUST NOT contain executable code.¶

6.1. Media Type (Documentation Only)

The agent format is already registered in the IANA "Media Types" registry, vendor tree:¶

• application/vnd.fafa+yaml — registered 2026-06-26 [IANA-FAFA]. File extension .fafa. Published specification: [AGENT-FORMAT].¶

This document documents that registration. No new media-type registration is requested.¶

6.2. Relationship to the Existing Vendor-Tree Registration

The vendor-tree registration remains valid. This document does not request promotion to the standards tree.¶

7.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC9512]

Polli, R., Wilde, E., and E. Aro, "YAML Media Type", RFC 9512, DOI 10.17487/RFC9512, February 2024, <https://www.rfc-editor.org/rfc/rfc9512>.

[YAML]

Ben-Kiki, O., Evans, C., and I. döt Net, "YAML Ain't Markup Language Version 1.2", October 2009, <https://yaml.org/spec/1.2/>.

7.2. Informative References

[AGENT-FORMAT]

Wolfe, J., ".fafa — FAF Agent Format Specification, Version 1.0", May 2026, <https://github.com/Wolfe-Jam/faf/blob/main/AGENT-FORMAT.md>.

[FAF-FORMAT]

Wolfe, J., "FAF: The Foundational AI-Context Layer", 2026, <https://datatracker.ietf.org/doc/draft-wolfe-faf-format/>.

[IANA-FAFA]

IANA, "Media Type: application/vnd.fafa+yaml", June 2026, <https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml>.