# Avouch

> Avouch is an ontology format whose every claim cites its source. An Avouch file describes a system that is built somewhere else: its object types, the links between them, the actions people take, what each action requires and changes, the states objects move through, and who may act. Every claim is tied to a verbatim quote from a source document, so a reviewer or a checker can trace it. Status: experimental draft, not a standard.

This page is for AI agents that write or edit Avouch files. It states the working rules. It does not list fields: the schema does that, and the schema can change.

## Source of truth

- Schema (shape and field reference): https://avouch.dev/v1/schema.json (identifier: `https://w3id.org/avouch/v1/schema.json`)
  Fetch it before you write. Every field has a description that says what it means and which rule enforces it. Do not rely on memory or on older examples for key names.
- The vocabulary namespace is `https://w3id.org/avouch/v1/vocab#`.
- A file declares the format version it follows. Use the version the schema's `$id` names.
- Viewer: https://avouchstudio.com (Avouch Studio). Open a file with `https://avouchstudio.com/app/?src=<url of the file>`.

## Rules for writing

1. **Write only what a source says.** The sources are the documents your user names (design docs, specs, policies). Do not add objects, actions, states or permissions that no source states, even when they seem obvious.
2. **Cite every claim verbatim.** Name the source section, and copy the quote exactly as it appears in that section, character for character. Do not paraphrase, translate, fix typos or join sentences. If no sentence supports a claim, the claim does not belong in the file.
3. **Write unknowns down; never guess.** When a source is silent on something the format asks for, use the format's explicit unknown form and say what is missing. When two sources disagree, record a known gap that states the conflict and proposes how the sources should be fixed; do not choose a winner.
4. **Be complete per action.** For each action, declare what it creates, what it edits, which events it emits, what it reads to decide whether it may run (stored facts, the action's inputs, or the caller), and its effect on every link of the objects it touches, including links it leaves unchanged.
5. **Bind every state transition.** Each transition names the action that performs it. If no action performs it, state the reason.
6. **Take permissions from the source.** If the source does not say who may run an action, mark the permission as unknown. If the source says no permission key applies, record that with its quote; do not leave it unknown.
7. **Treat waivers as debt.** A waiver records a known gap in the sources. A waiver matches one finding exactly; a waiver that matches nothing is an error. Remove it when the gap is closed.
8. **Preconditions read facts, not computed values.** Classify each property as a recorded fact, a computed value, a configuration value or unknown. A precondition may depend only on recorded facts.
9. **Declare cross-context writes.** If an action changes objects that belong to another context, state how the write crosses the boundary, or mark the mechanism unknown.
10. **Add no keys of your own.** The schema rejects unknown keys. If the format cannot express something, tell your user instead of inventing a field.

## Workflow

1. Read the source documents in full.
2. Fetch the schema and read the descriptions of the parts you will write.
3. Write the smallest correct file first: a few object types and one action, all cited.
4. Validate the file against the schema (any JSON Schema 2020-12 validator; YAML files parse to the same JSON).
5. Open the file in Avouch Studio and review the object graph, the state machines and the action × object matrix with your user. Check that every quote is in its source.
6. Extend in small steps and validate after each one.

## When you are unsure

Ask your user, or write the unknown down with its reason. A visible unknown is correct; a guessed fact is a defect.