---
title: "una.contract/1"
url: https://una-lang.org/en/docs/agents/schemas/una.contract-1/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/13-diagnostics-and-abi.md
---

# una.contract/1

`una.contract/1` is a JSON document of the Agent ABI, defined in `spec/13 §5`. This page gathers what the specification says about it at v0.4.0: each section whole where it opens with the document, and otherwise the parts that name it.

## Command line

From `spec/13 §5`, the parts that name this schema.

`una contract <qualified.name>` reads the package in the current directory and checks it at tier 0 (ADR 0029). The name is the module path followed by the function's name, as in `events.checkin.check_in`, and names a function. When the package has diagnostics, those of its project files included, `una contract` reports them as `una check` does and exits with code 1 before it resolves the name, since an inferred header is defined only for a package that checks (ADR 0036); in a package without diagnostics, an unknown name is a usage error (exit code 2). Otherwise it prints the doc comments, then the header in canonical form with every clause, declared or inferred, in canonical order, each inferred clause followed by the comment `-- inferred`, then one line per requirement of `derived from`: `-- requirement ID (status): "text"`. With `--json` it prints `una.contract/1`, compact, with keys in this order:

```json
{
  "schema": "una.contract/1",
  "function": "events.checkin.check_in",
  "public": true,
  "docs": ["Looks up a registration by phone, shows its availability, and records it."],
  "header": "pub check_in(phone: secret[PII] Phone) -> Availability",
  "constraints": [],
  "requires": [],
  "ensures": [],
  "uses": [ { "cap": "registrations", "capability": "Registrations", "ops": ["find"], "inferred": false } ],
  "fails": { "kind": "CheckInError", "inferred": false },
  "diverges": false,
  "derived_from": [ { "id": "EVENTS_3", "status": "active", "text": "..." } ]
}
```

`fails` is `null` for a function that cannot fail, `ops` lists the operations in the declaration order of the capability, and `docs` holds the doc comments without their `---` marker. (v0.2, ADR 0066.) The document also holds `constraints`, after `header`: the constrained type parameters, as `{"param": "T", "constraint": "Ord", "inferred": false}`, or `[]` (`spec/20 §8`). The key is additive, and the schema stays `una.contract/1`. (v0.2, ADR 0067.) The document also holds `result_labels`, after `constraints`: for a generic function, each position of its result whose summary is not empty, as `{"position": "top", "from": ["T"]}`, in the order of the positions in the declared type, or `[]` (`spec/07 §7` rule 8). A position is written as its path: `top`, `element`, `arg N`, `param N` and `result`, joined by `.`. The human output prints them on one line after the header, positions separated by `; ` and type parameters by `, `, as `-- result labels: top from T; element.arg 1 from T, U`; a function with none prints no line. The key is additive, and the schema stays `una.contract/1`. (v0.2, ADR 0067 amendment.) The document also holds `of_raises`, after `result_labels`: each parameter that an `of` clause names whose calls depend on decisions on type parameters, as `{"param": "k", "from": ["T"]}`, or `[]`; callers run their argument for it under the labels of those type arguments (`spec/07 §7` rule 8). The human output prints them after the result labels as `-- of raises: k from T`. The key is additive. (Edition 0.4 preview, ADR 0116.) The document also holds `diverges`, after `fails`: `true` for a function whose header says `diverges`, else `false`. The key is additive, and the schema stays `una.contract/1`. (v0.3, ADR 0094 rule 3.) Each entry of `uses` also holds `gives`, after `ops`, when an operation of the binding gives a label, declared or inferred: `{"op": "owner", "label": "internal[Service]"}` for each such operation, in the order of `ops`. The key is left out when no operation gives a label, so the document of a package that labels none, every package of editions `0.1` and `0.2` among them, does not change. The human output prints an inferred clause's labels as a header writes them, `uses @files: Files[owner gives internal[Service], create_link] -- inferred`. The key is additive, and the schema stays `una.contract/1`.

## The report and the contract

From `spec/20 §8`, the parts that name this schema.

2. `una.contract/1` gains the key `constraints`, after `header`: one entry per constrained type parameter, `{"param": "T", "constraint": "Ord", "inferred": false}`, in parameter order, and `[]` when there are none.
