---
title: "5.5 Requirements: rules from outside the code"
url: https://una-lang.org/en/learn/contracts/requirements-rules-from-outside-the-code/
release: v0.4.0
edition: "0.2"
---

# 5.5 Requirements: rules from outside the code

## 5.5.1 What a requirement is

A **requirement** records a rule that comes from outside the code, in the words of its source, with the team that answers for it. The store's billing policy says "a refund never pays back more than the customer paid". In Una that sentence becomes a `requirement` declaration, and a function whose contract implements it says so with a `derived from` clause.

Think of a store's procedures binder, where each rule has a number, so that a note on a till can say "see rule 4.2". A requirement gives a rule that number, and `derived from` is the note.

## 5.5.2 Why tie a contract to its rule

A contract says what the code does: `ensures result <= paid`. It does not say why. When the billing policy changes, someone must find every function that implements the old rule, and when an auditor asks how the store follows a regulation, someone must show the code that does. Comments drift, and a search for words misses the function that phrases the rule differently. A requirement makes the link part of the program: `una` checks it, and `una trace` follows it from the rule to the proof.

## 5.5.3 How to write a requirement

### 5.5.3.1 The declaration

A requirement is a top-level declaration, like a function or a kind: the word `requirement`, an identifier, and four lines, all required, each indented two spaces:

```una include="steps/22-requirements/src/refunds.una#L3-L7" title="steps/22-requirements/src/refunds.una"
requirement REFUND_1
  text "A refund never pays back more than the customer paid"
  source policy "Store billing rules"
  owner billing
  status active
```

| Line | Says |
| --- | --- |
| `requirement REFUND_1` | The identifier: capital letters, digits and `_`, ending with `_` and a number |
| `text "…"` | The rule, in the words of its source, in quotes |
| `source policy "Store billing rules"` | Where the rule comes from, in one of the four forms below |
| `owner billing` | The team that answers for it, in small letters joined by `_` |
| `status active` | `active` for a rule in force, `proposed` for one that waits for a person to accept it |

The number at the end of the identifier lets you add `REFUND_2` next to `REFUND_1` without renaming anything.

### 5.5.3.2 The sources

`source` takes one of four forms. The step declares one of each:

```una include="steps/22-requirements/src/refunds.una#L9-L25" title="steps/22-requirements/src/refunds.una"
requirement REFUND_2
  text "A refund above 500.00 needs a second look"
  source human
  owner support
  status active

requirement TAX_1
  text "A refund returns the tax that was charged with it"
  source regulation "Consumer tax code, part 4"
  owner finance
  status active

requirement REFUND_3
  text "A refund is never negative"
  source generated "billing review"
  owner billing
  status proposed
```

- **`policy "Store billing rules"`.** A document of the business, by name.
- **`human`.** A person stated the rule, with no document behind it.
- **`regulation "Consumer tax code, part 4"`.** A law or a regulation, by name.
- **`generated "billing review"`.** A tool or an agent proposed the rule, during the task named in quotes. Such a requirement must stay `proposed`: only a person can make it `active`, by changing its source to `human`, `policy` or `regulation`.

### 5.5.3.3 `derived from` on a function

A function that implements a rule names it in a `derived from` clause, the last of its clauses, after `requires` and `ensures`. It may name several requirements, separated by commas:

```una include="steps/22-requirements/src/refunds.una#refund..needs_review" title="steps/22-requirements/src/refunds.una"
--- What a refund pays back: what was asked, which is never more than what was paid.
refund(paid: Cents, asked: Cents) -> Cents
  requires asked <= paid
  ensures result <= paid
  derived from REFUND_1, REFUND_3
=
  asked

--- Whether a refund needs a second look by a person.
needs_review(asked: Cents) -> Bool
  ensures result == (asked > 50000)
  derived from REFUND_2
=
  asked > 50000
```

`una run .` prints:

```text include="steps/22-requirements/expected/output.txt"
refund 3980, needs review: true
```

## 5.5.4 Following a rule to its proof

`una trace` takes a requirement's identifier and lists every function derived from it, with its contract and the status of each obligation:

```text include="steps/22-requirements/expected/commands/trace.txt"
$ una trace REFUND_1
requirement REFUND_1 (active)
  text "A refund never pays back more than the customer paid"
  source policy "Store billing rules"
  owner billing
refunds.refund
  requires asked <= paid
  ensures result <= paid
  proven   ob-0b48412701fd refinement    result >= 0
  proven   ob-0ac4aeb885fd postcondition result <= paid
```

Read it from the top: the requirement, its status, its text, source and owner; then `refunds.refund`, the function that implements it, by module and name; its `requires` and `ensures`; and the obligations of the function, both proven. A person who answers for the refund policy can read this instead of the code.

`una report .`, the build report of [section 18.4](https://una-lang.org/en/learn/tools/the-build-report/#s18-4), lists every requirement of the package with the functions derived from it, under `requirements`:

```text include="steps/22-requirements/expected/commands/report.txt#L29-L33"
requirements:
  REFUND_1 (active): refunds.refund
  REFUND_2 (active): refunds.needs_review
  REFUND_3 (proposed): refunds.refund
  TAX_1 (active): 
```

`REFUND_3` is marked `(proposed)`, so a reader sees that `refund` follows a rule nobody has accepted yet; a function derived from a proposed requirement still checks. `TAX_1` has nothing after its colon: no function implements it yet, which the report shows at once.

## 5.5.5 How requirements are checked

### 5.5.5.1 A generated rule stays proposed

Make the generated requirement `active`:

```diff include="steps/22-requirements..steps/23-generated-active:src/refunds.una" context="1" title="src/refunds.una"
--- a/src/refunds.una
+++ b/src/refunds.una
@@ -24,3 +24,3 @@
   owner billing
-  status proposed
+  status active
 
```

```text include="steps/23-generated-active/expected/rendered.txt#L1"
[U1007] Error: requirement `REFUND_3` has source `generated`, so its status must be `proposed`
```

U1007 points at the status. A tool may propose a rule, but only a person may put it in force, and the change of source that does so shows when the code is reviewed.

### 5.5.5.2 Every name in `derived from` exists

A `derived from` that names a requirement the package does not declare, such as a typing slip, is U1006:

```diff include="steps/22-requirements..steps/24-unknown-requirement:src/refunds.una" context="1" title="src/refunds.una"
--- a/src/refunds.una
+++ b/src/refunds.una
@@ -40,3 +40,3 @@
   ensures result == (asked > 50000)
-  derived from REFUND_2
+  derived from REFUND_4
 =
```

```text include="steps/24-unknown-requirement/expected/rendered.txt#L1"
[U1006] Error: requirement `REFUND_4` is not declared in this package
```

### 5.5.5.3 One identifier, one requirement

Two requirements with the same identifier in one package are U1002, as two declarations with one name are anywhere ([section 1.2](https://una-lang.org/en/learn/hello/modules/#s1-2)).

## 5.5.6 Where each rule belongs

:::decide
**Which to use:**

| The rule… | Use |
| --- | --- |
| Holds of every value of a type | a refined kind ([section 5.3](https://una-lang.org/en/learn/contracts/refined-kinds-and-predicates/#s5-3)) |
| Is the caller's to keep | `requires` |
| Is what a function promises about its result | `ensures` |
| Comes from a policy, a regulation or a person | a `requirement`, and `derived from` on the functions that implement it |
| Explains what a function is for | a doc comment (`---`) |
:::

A requirement does not replace a contract: it names the reason for one. The contract is what the verifier proves, and the requirement is what a person reads to know why.

## 5.5.7 Check yourself: requirements

Which of these requirement identifiers check: `RETURNS_1`, `GIFT_CARD_12`, `RETURNS`, and `REFUND_REVIEW`?

:::answer Show the answer
`RETURNS_1` and `GIFT_CARD_12` check: capital letters joined by `_`, ending with `_` and a number. `RETURNS` and `REFUND_REVIEW` do not end with a number. For `REFUND_REVIEW`, `una check .` reports:

```text include="steps/25-requirement-name/expected/rendered.txt#L1"
[U1005] Error: requirement identifier `REFUND_REVIEW` must be upper snake case ending with `_` and a number, as in `REFUND_REVIEW_1`
```

The `Help` line of the full diagnostic renames it to `REFUND_REVIEW_1`, here and in every `derived from` that names it.
:::

A tool adds a requirement with `source generated "pricing review"` and `status proposed`. A person reads it, and the store adopts the rule in its pricing policy. What changes in the declaration?

:::answer Show the answer
Two lines. The source becomes `policy "…"`, with the name of the pricing policy, and then the status may become `active`. Changing only the status is U1007, since a generated requirement must stay proposed, as [A generated rule stays proposed](#a-generated-rule-stays-proposed) shows.
:::
