Skip to main content

.faf by example#

One task per section: a sentence, then a file or a command. Every file below is in this repository, and every output was captured with faf-cli 8.10.0 or the JSON Schemas in schemas/. The rules themselves are in SPECIFICATION.md.


The smallest valid project.faf#

A valid .faf needs faf_version and project.name. Everything else is optional. This file is conformance/faf/valid/minimal.faf.

Valid, and scored on what it holds: 3 of 33 slots.

A complete project.faf that scores 100%#

A CLI tool (type: cli): the project block, the six W’s, the three delivery slots it needs, and every other slot marked slotignored. This file is examples/cli-project.faf (comments trimmed).

More complete examples, all scoring 100%: examples/ (Chrome extension, documentation, monorepo root, n8n workflow).

Mark a slot that doesn’t apply: slotignored#

A slot the app type doesn’t need is written as slotignored. It leaves the calculation. A slot that is simply left out counts as empty, so write the label.

A slot holds one fact: text or a number. A list, a mapping, true/false, or a placeholder such as TBD or None counts as empty.

Work out a score by hand#

For examples/cli-project.faf: 21 slots are slotignored, so 12 are active. All 12 are populated.

Tiers: ✪ Trophy 100 · ★ Gold 99 · ◆ Silver 95 · ◇ Bronze 85 · ● Green 70 · ● Yellow 55 · ○ Red 1 · ♡ White 0.

What makes a .faf invalid#

A .faf is invalid if it isn’t YAML, or lacks faf_version or project.name. This file is conformance/faf/invalid/malformed.faf: an unquoted colon breaks the YAML.

Quote the value to fix it: goal: "this value has an unquoted: colon …".

Validate against the JSON Schema#

Each format has a JSON Schema (draft 2020-12): faf.schema.json, fafm.schema.json, fafa.schema.json. Any JSON Schema validator works once the YAML is parsed. In Python:

Results on this repository’s files:

The shared conformance suite, and the outcome each file must produce, is in conformance/.

A .fafm memory file#

.fafm holds what an agent remembers: facts with an id, a type and a priority. The full format is in MEMORY-FORMAT.md. This file is conformance/fafm/valid/knowledge.fafm.

memory is required. Without it the file is rejected (see the validation results above).

A .fafa agent card#

.fafa declares an agent: who it is, what it can do, how to reach it. The full format is in AGENT-FORMAT.md. The minimal valid card, from AGENT-FORMAT.md §10:

Required: version; agent with name and id; capabilities (may be empty); endpoints (at least one). It validates against fafa.schema.json.


Media types: .faf application/vnd.faf+yaml · .fafm application/vnd.fafm+yaml · .fafa application/vnd.fafa+yaml, all IANA-registered.