Home / Docs / Una for agents / Schemas
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:
{
"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.
una.contract/1gains the keyconstraints, afterheader: one entry per constrained type parameter,{"param": "T", "constraint": "Ord", "inferred": false}, in parameter order, and[]when there are none.