Home / Docs / Language guide / Requirements

requirement and derived from

Release v0.4.0Edition 0.1 and laterU1002U1005U1006U1007

What it does

A requirement records a human or business statement, with its source and its owner, so contracts (the conditions a function states with requires and ensures) can be traced to intent. A function names the requirements it implements with derived from. una trace then lists, for one requirement, every function derived from it, with its contract and the status of each proof.

Learn more: What the verifier proves, and what examples show.

una
module shop

requirement EVENTS_3
  text "An event with no remaining seats is always shown as sold out"
  source policy "Box Office Handbook 2.1"
  owner box_office
  status active

pub kind Availability = SoldOut | Few | Open

pub availability(remaining: Int) -> Availability
  requires remaining >= 0
  ensures remaining == 0 implies result is SoldOut
  derived from EVENTS_3
=
  if remaining == 0 then SoldOut else if remaining < 20 then Few else Open

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
requirement_decl = "requirement" upper_ident NEWLINE INDENT
                     "text" text_lit NEWLINE
                     "source" source NEWLINE
                     "owner" lower_ident NEWLINE
                     "status" ( "proposed" | "active" ) NEWLINE
                   DEDENT ;
source          = "human" | ( "policy" | "regulation" | "generated" ) text_lit ;

The fields:

Field Values
text The statement, as written by its source
source human, policy "<document>", regulation "<document>", generated "<task reference>"
owner Team or person accountable (lower snake case)
status proposed or active

A requirement's identifier is upper snake case ending in _ and a number, as SHOP_1 or EVENTS_3; another form is U1005.

derived from R1, R2 is the last clause of a function header, at most once.

Examples

The function above proves the requirement's intent as a contract: ensures remaining == 0 implies result is SoldOut. The requirement says what people want; the contract says what the code guarantees, and the verifier (the part of una check that proves facts about the code) checks the contract.

A requirement written by an agent is only proposed. A person activates it by changing its source:

una
-- fails with U1007
module shop

requirement GEN_1
  text "Seats are counted"
  source generated "task 42"
  owner agents
  status active

Edge cases

The identifier follows its convention:

una
-- fails with U1005
module shop

requirement Shipping
  text "Orders ship within two days"
  source human
  owner warehouse
  status active

derived from names declared requirements:

una
-- fails with U1006
module shop

pub seats_left(remaining: Int) -> Int
  derived from NOPE_1
=
  remaining

Identifiers are unique per package:

una
-- fails with U1002
module shop

requirement SHOP_1
  text "Prices include sales tax"
  source human
  owner team
  status active

requirement SHOP_1
  text "Prices show sales tax apart"
  source human
  owner team
  status active

Further rules:

Diagnostics

Edition

Requirements are the same in editions 0.1 and 0.2.

Normative source