Markdown for LLMs

Protocols

The source Markdown for this article. Copy it into your assistant or download it as a text file.

# Protocols

Every way of working with Arxo Law — the MCP server, the client library,
the command line, a page in the browser — exchanges the same documents.
Their shapes are named protocols and published as JSON Schemas. A host that
knows them can build a case, ask a question and read the answer without
knowing how the answer was computed.

There are three of them.

| Protocol | What it carries | Schemas |
|---|---|---|
| **Arxo Fact Protocol** | what a host submits: the case with its facts and their origin, the question, pinned external data | [evaluation-request](/protocols/schemas/evaluation-request/), [query](/protocols/schemas/query/), [external-snapshot](/protocols/schemas/external-snapshot/), [case-export](/protocols/schemas/case-export/), [source-mapping](/protocols/schemas/source-mapping/), [fact-set](/protocols/schemas/fact-set/), [derived-facts](/protocols/schemas/derived-facts/) |
| **Arxo Decision Protocol** | what comes back: the answer document with statuses, the proof, the issues and the hashes; diagnostics by code | [evaluation](/protocols/schemas/evaluation/), [query-result](/protocols/schemas/query-result/), [diagnostic](/protocols/schemas/diagnostic/) |
| **Arxo Change Protocol** | a change of the rules as an object: states before and after, the world it applies to, the mode of entry into force, and the dossier assembled from them | [change-set](/protocols/schemas/change-set/), [change-dossier](/protocols/schemas/change-dossier/) |

The whole catalogue, with the versions each schema accepts, lives at
[the schema catalogue](/protocols/schemas/).

## The entry point: case, question, pinned program

A question to Arxo always has three parts. They are described in full on
the [Arxo Fact Protocol](https://github.com/arxohq/law/blob/master/docs/protocols/01-fact-protocol) page; in short:

- **The case** — the facts, each with an identifier and an origin (arrived
  with the case, taken from a pinned source, derived, decided by an
  authority), and the three dates of the question: the legal date, the
  decision date and the date of knowledge.
- **The question** — one of the closed kinds: is a statement established,
  which values satisfy a condition, the value of a term, a deadline, the
  state of duties and powers.
- **The pinned program** — which package, in which version, with which
  dependencies. The host names it; it never sends a program of its own under
  someone else's answer.

What comes back is not a bare status but a document: the manifest, a result
for each question, the proof graph, the list of issues and the positions of
the parties. How to read it is the subject of the
[Arxo Decision Protocol](https://github.com/arxohq/law/blob/master/docs/protocols/02-decision-protocol) page.

## Two version numbers in every document

| Field | Names | Example | Changes when |
|---|---|---|---|
| `schemaVersion` | the shape of the document | `law.core.evaluation/0.2` | a field, a node or an enumeration value appears |
| `semanticVersion` | the meaning it was computed under | `0.2` | a correction changes the meaning while the shape stays |

## How the protocols evolve

Both numbers are present in every message. A new field arrives only with a
new `schemaVersion`; enumerations grow only with a new version; nothing is
removed or renamed; an unknown field is rejected before any computation.
The full rules are on the [Versions](https://github.com/arxohq/law/blob/master/docs/protocols/04-versions) page.

A host that follows these rules keeps working when a new version appears:
it reads the version it knows and refuses, by name, a document it does not.