.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 complete project.faf that scores 100%
- Mark a slot that doesn’t apply: slotignored
- Work out a score by hand
- What makes a .faf invalid
- Validate against the JSON Schema
- A .fafm memory file
- A .fafa agent card
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.