URDAD-OCL Language Specification

About this specification

This is the specification of URDAD-OCL, the language in which a URDAD model’s formal specifications are written: its grammar, what each expression means, and the standard library of types and operations it can use, with examples. It is a profile of OCL 2.4: where the two overlap, an expression means here exactly what it means in OCL.

It is the user manual’s chapter on the language, together with the manual’s description of the standard library, published on their own, so that the manual and this specification carry the same text.

Licence

This document is published under the Creative Commons Attribution 4.0 International licence (CC BY 4.0). You may share and adapt it for any purpose, provided you credit URDAD (urdad.org), link to the licence and say whether you changed it.

1. URDAD-OCL, the constraint language

A pre-condition, a post-condition, an invariance, a flow condition and a loop’s continuation condition are all written as a formal specification. The model stores every one in URDAD-OCL, the profile this chapter defines. You may read and write them in URDAD-FEEL instead, a choice you make under Settings (URDAD-FEEL, the other notation).

It is a profile of OCL, not a language of its own. Wherever the two overlap, an expression means here exactly what it means in OCL 2.4. Nothing has been invented, and a few things have been left out; both lists are below.

1.1. The cheat sheet

If you are new to the language, you need not read this chapter before writing your first constraint. Every formal specification section has a ? button in its header, beside the title, that opens the URDAD-OCL cheat sheet: the forms you will reach for most, each as a working example with a one-line note. It covers what a body may name, values, operators, collections, populations and @pre, functions, now() and caller, exact numbers and dates.

Two of its sections are guidance as much as syntax, because they cover the choices a model most often gets quietly wrong:

OffsetDateTime, LocalDateTime or ZonedDateTime: what each kind of point in time lets a body do. An OffsetDateTime is an instant: it compares with now() but has no year() or hour(). A LocalDateTime can be taken apart. A ZonedDateTime is reached through its local reading and its zone, and two zoned readings are compared only within one zone. See Section 1.6, and Section A.2 for which type a field should be.
Specifying an amount of time: when an amount is a Duration and when it is a CalendarPeriod, and what each can be combined with. A fixed amount is written in single quotes, 'PT72H'; one that is a setting rather than part of the rule is held in a field the body names. See Section 1.6.2 and Section A.3.

The button is there on a read-only form too. Someone deciding whether an informal requirement can be formalised is exactly who the sheet is for.

The sheet does not block the rest of the window. It opens at the left, away from the details pane, and stays open while you click into the specification and type. Escape in the editor goes to the editor, for example to close its list of completions. To close the sheet, use its Close button, or press Escape while you are in the sheet.

Every example on the sheet is well-formed URDAD-OCL; the tool’s own tests parse each one. The date, time and duration examples are also type-checked against the standard library’s types. The examples name fields of an imaginary model, though. Copied into yours, a name the model does not have is reported like any other (Names in a constraint that do not resolve). The sheet is a summary, and this chapter is the reference: where a rule needs more than one line, it is here.

1.2. A body is an expression

The whole body is one expression. There is no context header, no inv: or pre: label, and no package declaration:

-- Write this
amount > 0

-- Not this
context Claim inv: self.amount > 0

The context is structural — it is the element the specification is written on — so the tool already knows what the expression is about. A header would let a body disagree with the element carrying it, which is a contradiction nothing could resolve.

1.3. What is in scope

A name in the body must be something the surrounding element makes available. What that is depends on where the specification sits:

Written on You may name

Written on	You may name
An invariance on a data structure	`self` — the structure being constrained — and its fields.
An invariance on a primitive type or enumeration	`value` — the value being constrained. A primitive has no fields, so there is nothing to navigate into.
A pre-condition	`request` — the service’s request structure — and its fields. Also `caller` — see Section 1.15.
A post-condition	`request` and `response`, and their fields. Also `caller`. And the state before the service, through `@pre` — see Section 1.13.
A condition inside a process	The process’s original `request`, and the process variables in scope at that point — see Values a process names. Also `caller`. Inside an exception handler, `exception`: the exception it caught, with the values its raise stated — see Giving an exception its values.
A request constraint	The same as a condition inside a process — `request` keeps its ordinary meaning, never rebound — plus `providerRequest`: the request object being built for this step, before it is sent. See Values a process names's "Populating a nested request". `providerRequest` must always be written out; unlike `self`, it is never the implicit subject.
A response constraint	The same as a condition inside a process, plus `response`: the response this process answers with, the object its contract’s post-conditions describe. See Populating the response. Written out like `providerRequest`, and nameable only here — no other step of a process can read `response`.
An exception value on a Raise exception step	The same as a condition inside a process — `exception` too, inside a handler — plus `raised`: the exception being raised. See Giving an exception its values. Written out like `response`, and nameable only here.
An exception value on a pre-condition	What the pre-condition may name — `request`, `caller` — plus `raised`.

An invariance on a data structure

self — the structure being constrained — and its fields.

An invariance on a primitive type or enumeration

value — the value being constrained. A primitive has no fields, so there is nothing to navigate into.

A pre-condition

request — the service’s request structure — and its fields. Also caller — see Section 1.15.

A post-condition

request and response, and their fields. Also caller. And the state before the service, through @pre — see Section 1.13.

A condition inside a process

The process’s original request, and the process variables in scope at that point — see Values a process names. Also caller. Inside an exception handler, exception: the exception it caught, with the values its raise stated — see Giving an exception its values.

A request constraint

The same as a condition inside a process — request keeps its ordinary meaning, never rebound — plus providerRequest: the request object being built for this step, before it is sent. See Values a process names's "Populating a nested request". providerRequest must always be written out; unlike self, it is never the implicit subject.

A response constraint

The same as a condition inside a process, plus response: the response this process answers with, the object its contract’s post-conditions describe. See Populating the response. Written out like providerRequest, and nameable only here — no other step of a process can read response.

An exception value on a Raise exception step

The same as a condition inside a process — exception too, inside a handler — plus raised: the exception being raised. See Giving an exception its values. Written out like response, and nameable only here.

An exception value on a pre-condition

What the pre-condition may name — request, caller — plus raised.

The subject may be left out. As in OCL generally, an unqualified name is read as a navigation from the subject: premium > 0 means self.premium > 0, and a pre-condition may be written claim <> null rather than request.claim <> null. Both spellings mean the same thing.

One more thing is nameable in every body, whatever the row: an entity, to speak about the things of that kind that exist — see Section 1.12.

A post-condition has two subjects, so a field name both the request and the response carry identifies neither. Write the subject out in that case.

Note

Every body declared OCL is parsed, and one that is not well-formed URDAD-OCL is reported and blocks a phase transition — see Specifications that are not the language they declare.

What the names mean is checked too, for every row of the table above: self.nosuch > 0 is well-formed and is reported, because no field is called nosuch — see Names in a constraint that do not resolve, which lists the scope of every slot, including the ones inside a process, and the constructs the check deliberately leaves alone.

And so are the types: self.startDate = 3 resolves and still cannot hold. The standard library’s operations are typed too, so a chain is checked to its end — claims→select(…)→first().amount = 'x' is reported. See Constraints whose types do not fit together for what fits what, and for what is still accepted unchecked.

1.4. Values

Kind Written

Kind	Written
Boolean	`true`, `false`
Integer	`42`, `-7`
Decimal	`3.14`, `2e3`, `1.5e-3` — see Section 1.5
String	`'in single quotes'`, `'it's escaped'`
Absent	`null`
Erroneous	`invalid`
Enumeration literal	`Status::OPEN`
Collection	`Set{1, 2}`, `Bag{…}`, `Sequence{1..9}`, `OrderedSet{…}`
Tuple	`Tuple{name = 'x', amount = 3}` — see A tuple fits a structure by its fields

Boolean

true, false

Integer

42, -7

Decimal

3.14, 2e3, 1.5e-3 — see Section 1.5

String

'in single quotes', 'it's escaped'

Absent

null

Erroneous

invalid

Enumeration literal

Status::OPEN

Collection

Set{1, 2}, Bag{…}, Sequence{1..9}, OrderedSet{…}

Tuple

Tuple{name = 'x', amount = 3} — see A tuple fits a structure by its fields

null and invalid are different, and the difference matters. null is a value that is absent — an optional field nobody filled in. invalid is a value that is erroneous — dividing by zero, or taking the first element of an empty collection. A function asked for an answer it cannot give is not erroneous: it gives null (see Section 1.14.1).

invalid spreads: anything computed from it is invalid too. A condition that evaluates to invalid is not satisfied. It is not "unknown", and it is not skipped — a constraint nobody can evaluate must never read as one that holds. The one exception is oclIsInvalid(), which asks whether a value is invalid and is itself always true or false.

1.5. Exact and approximate numbers

There are two kinds of number, and which one you are holding matters.

Decimal is exact, to whatever precision the value has. 0.1 + 0.2 is 0.3, and a ledger that sums a million amounts reconciles rather than drifting. Model money with it, through Money or a structure of your own.

Real is binary floating point, so it is approximate. 0.1 + 0.2 is not 0.3, and the error accumulates with volume. It is the right type for a quantity that is approximate in the first place — an interest rate, a yield, a day-count fraction — and the wrong one for anything that has to balance.

Neither fits where the other is expected. A whole number fits either, but a Decimal and a Real brought together by +, *, = or < is reported, and that is the rule this pair exists for: it is how an approximate factor otherwise gets into an exact amount without anyone deciding that it should.

Crossing between them is therefore written down:

principal * rate                        -- reported: Decimal against Real
principal * rate.roundHalfEven(6)       -- Decimal, rounded to 6 places
balance.toReal()                        -- the other way, deliberately

A number written in the body — 1.5, 0.05 — is exact, and adapts to whatever it stands beside. So rate ⇐ 1.5 is fine against a Real, and balance * 1.05 is fine against a Decimal; neither needs a conversion.

1.5.1. Rounding

Multiplying an exact amount by a rate gives a result with more places than anything is reported to, and which way it rounds is a contractual or regulatory decision rather than an engineering detail. So it is stated, by name, with the scale it rounds to:

Operation Rounds

Operation	Rounds
`roundCeiling(scale)`	Toward positive infinity, whatever the sign. This is what a "rounds in our favour" clause means: a fee owed grows and a refund owed shrinks, both moving the same way.
`roundFloor(scale)`	Toward negative infinity — the mirror, for "rounds in the customer’s favour".
`roundHalfEven(scale)`	Banker’s rounding: a tie goes to the even digit. Statistically neutral, and the right default for high-volume calculation.
`roundHalfUp(scale)`	The schoolbook rule: a tie goes away from zero. Some consumer-facing and regulatory contexts mandate it explicitly.

roundCeiling(scale)

Toward positive infinity, whatever the sign. This is what a "rounds in our favour" clause means: a fee owed grows and a refund owed shrinks, both moving the same way.

roundFloor(scale)

Toward negative infinity — the mirror, for "rounds in the customer’s favour".

roundHalfEven(scale)

Banker’s rounding: a tie goes to the even digit. Statistically neutral, and the right default for high-volume calculation.

roundHalfUp(scale)

The schoolbook rule: a tie goes away from zero. Some consumer-facing and regulatory contexts mandate it explicitly.

All four apply to a Real as well, and that is the only way to reach a Decimal from one.

1.5.2. `Decimal` has no `/`

Adding, subtracting and multiplying two exact decimals is exact. Dividing is not: 10 / 3 has no exact decimal value at all. Rather than round by a rule nobody wrote down, the operator was removed — and balance / 12 is reported, naming what to write instead:

balance.divideHalfEven(12, 2)     -- divide, half-even, to 2 places

Wherever the tool evaluates a body — trying an example, checking a request or an answer at run time — Decimal arithmetic and all eight operations are computed exactly, and a division is rounded once, straight to its scale: 23.34.divideHalfUp(7, 2) is 3.33, (1.0).roundHalfUp(2).divideHalfEven(8, 2) is 0.12, a tie going to the even digit.

divideCeiling, divideFloor, divideHalfEven and divideHalfUp are the same four modes as binary operations, each taking the divisor and the scale. Every other number keeps /, which yields a Real — so 1.5 / 2 and count / 12 are unaffected.

1.5.3. Scale belongs to the field, not to the type

Decimal carries no number of decimal places. Precision genuinely varies — two places for most currencies, three for a few, four to six for an FX quote, fractional pricing for some bonds — so a field that must hold a particular scale says so as an ordinary invariance on the field, exactly as it would state any other numeric constraint.

1.6. Dates, times and amounts of time

The standard library separates points in time — Date, Time, DateTime, LocalTime, LocalDateTime — from the two amounts that separate them: Duration, an exact number of hours, minutes and seconds, and CalendarPeriod, days, months and years. The operators follow that split.

Written Is a For example

Written	Is a	For example
a point `+` or `-` a `Duration`	the same kind of point	`receivedAt + notificationWindow` — the notification deadline
a point `-` a point of the same kind	a `Duration`	`respondedAt - receivedAt ⇐ serviceLevel`
a `Date` `-` a `Date`	an `Integer` — whole days	`expiryDate - inceptionDate > 30`
a `Date` `+` or `-` whole days written as text, `'P3D'` or `'P2W'`	a `Date`	`dueOn = today() + 'P3D'`
`Duration` `+` or `-` `Duration`	a `Duration`
`CalendarPeriod` `+` `CalendarPeriod`	a `CalendarPeriod`	`P1M` and `P3D` make `P1M3D`
an amount `*` an `Integer`, either way round	the same amount	`retryInterval * 3`
`Duration` `/` `Duration`	a `Real` — how many of the one the other is	`(respondedAt - receivedAt) / serviceLevel ⇐ 0.8`

a point + or - a Duration

the same kind of point

receivedAt + notificationWindow — the notification deadline

a point - a point of the same kind

a Duration

respondedAt - receivedAt ⇐ serviceLevel

a Date - a Date

an Integer — whole days

expiryDate - inceptionDate > 30

a Date + or - whole days written as text, 'P3D' or 'P2W'

a Date

dueOn = today() + 'P3D'

Duration + or - Duration

a Duration

CalendarPeriod + CalendarPeriod

a CalendarPeriod

P1M and P3D make P1M3D

an amount * an Integer, either way round

the same amount

retryInterval * 3

Duration / Duration

a Real — how many of the one the other is

(respondedAt - receivedAt) / serviceLevel ⇐ 0.8

Nothing else divides. A Duration divided by a number would need a rule for the fraction of a second left over, the same reason an amount is scaled only by an Integer, and a CalendarPeriod has no ratio at all: how many days a month is depends on the month. Both are reported as not being numbers.

A Duration has an order, since PT72H is the same length wherever it is read, so respondedAt - receivedAt ⇐ serviceLevel is how a service level is stated. A CalendarPeriod does not: one month is 28 to 31 days depending on which month, so P1M < P30D has no answer and is reported.

Two things are refused, each with its own finding rather than a complaint that something is not a number:

A CalendarPeriod moving a point. inceptionDate + term looks complete and is not. Whether the result may land on a closed day, and where it goes if it does, depends on a BusinessCalendar and a BusinessDayConvention — see the standard library’s Resolving an amount to a date. + states neither; addPeriod does (Section 1.6.1). The one exception is whole calendar days written as text moving a Date: today() + 'P3D' needs no calendar, and a date has room for days. It must be written out, because only the text can be known to hold days alone. A CalendarPeriod field may hold P1M, so inceptionDate + term is still refused, and so is 'P1M'. An instant is not moved by days either: across a daylight-saving change a day is 23 or 25 hours, and 'PT72H' says which is meant.
A Duration moving a Date. A date is a whole day, with no time of day for hours to move. To say "within 30 days", compare days: settledOn - tradeDate ⇐ 30.

1.6.1. Moving a date by a calendar period

A Date or a LocalDateTime moves by a CalendarPeriod through an operation that states what + leaves out:

expiryDate = inceptionDate.addPeriod(term, calendar, BusinessDayConvention::following)
noticeDate = expiryDate.subtractPeriod(noticePeriod, calendar, BusinessDayConvention::preceding)

The three arguments are the CalendarPeriod, StandardLib’s BusinessCalendar and StandardLib’s BusinessDayConvention, and all three are required. BusinessDayConvention::unadjusted says that no adjustment is made, but the calendar is still named, so a reader knows which one was considered and set aside. A wrong number of arguments, or an argument of the wrong type, is reported. A type of your own called BusinessCalendar is not StandardLib’s and does not fit.

The day of the month is kept where the month has it and otherwise becomes the month’s last day: 31 January plus P1M is 28 February, or 29 in a leap year.

A DateTime and a Time have no addPeriod. Moving an instant by a month needs the time zone it is read in, which it does not carry, and a time of day has no date to move. Move the local date or date-time the rule is about.

Important

The tool knows only the name of a business calendar, not which days it closes. So only a shift under unadjusted can be worked out. Under any other convention the result is undecided, both when you try an example (Trying a constraint on an example) and when the model’s processes run: a pre- or postcondition that depends on it is not enforced at run time. State such a rule so that a reviewer can check it, and do not rely on the running system to catch a breach of it.

Subtracting two points of different kinds — a Date from a DateTime — is reported as types with nothing in common. Decide which you mean and model both fields as that.

A difference can come out negative, although the library’s amounts are never negative. That rule is about the values a field holds; an expression on its way to a comparison may pass through a negative number of hours.

Values are read in the formats the standard library’s types state: RFC 3339 for dates and times (2026-01-31, 2026-01-31T10:00:00+02:00) and ISO 8601 for amounts (PT72H, P1M). They are compared by what they denote, never by their text: 10:00+02:00 equals 08:00Z, and PT72H is longer than PT9H. A time or timestamp computed from another keeps its offset.

A date and a local date-time can also be taken apart:

On Operations Give

On	Operations	Give
`Date`, `LocalDateTime`	`year()`, `month()`, `day()`, `dayOfWeek()` (Monday is 1), `dayOfYear()`	an `Integer`
`LocalTime`, `LocalDateTime`	`hour()`, `minute()`, `second()`	an `Integer`
`Date`	`startOfMonth()`, `endOfMonth()`	a `Date` — `endOfMonth()` of any day in February 2028 is `2028-02-29`
`LocalDateTime`	`date()`, `time()`	a `Date`, a `LocalTime`
any date, time or amount	`toString()`	its text, in its type’s format

Date, LocalDateTime

year(), month(), day(), dayOfWeek() (Monday is 1), dayOfYear()

an Integer

LocalTime, LocalDateTime

hour(), minute(), second()

an Integer

Date

startOfMonth(), endOfMonth()

a Date — endOfMonth() of any day in February 2028 is 2028-02-29

LocalDateTime

date(), time()

a Date, a LocalTime

any date, time or amount

toString()

its text, in its type’s format

DateTime and Time have none of these, deliberately. They are instants, and which day or hour an instant falls on depends on the time zone it is read in: 2026-01-01T01:00+02:00 and 2025-12-31T23:00Z are the same moment, but one is in 2026 and the other in 2025. A rule such as "received on a weekday" is about a place, so model the local date-time or date it means, as LocalDateTime or Date, rather than asking an instant.

1.6.2. Writing a fixed date or amount of time

There is no separate notation for a date or a duration. Write it as text — in single quotes, as all text is in URDAD-OCL — in its type’s format, beside the value it is compared or combined with:

request.dateTime - now() < 'PT240H'
request.closed >= '2026-01-31T10:00:00Z'
request.openedOn > '2026-01-31'
request.receivedAt + 'PT2H' > now()
(respondedAt - receivedAt) / 'PT1H' <= 8

The value beside the text decides what it is. Beside a Duration it is a Duration; beside a Date it is a Date. Beside a date or a time, text beginning with P is the amount that moves it, so in request.receivedAt + 'PT2H' it is two hours, not a second point in time. 'P1M' there is a CalendarPeriod, which + cannot move a point by (see above). Beside anything else — a String field, another piece of text — it stays text, so label = 'PT1H' compares two strings.

Text that is not in the type’s format is reported where it stands, with one that is: '240 hours' is not a Duration — write one like 'PT1H'. A duration has no days, because a day is not always 24 hours: 20 days is 'PT480H'.

Double quotes are not part of the language. They are how JSON writes text — including the Try an example box beside every constraint — so they are an easy slip, and the message says so: "PT240H" is reported with the repair, 'PT240H'.

1.7. Navigating

Use . to reach into a single value and → to reach into a collection:

claim.assessor.name           -- single values throughout
request.covers->size()        -- covers is a collection
request.covers->notEmpty()

Which one is correct is decided by the field’s multiplicity. A field that may hold many is reached with →; one that holds exactly one is reached with .. Getting this the wrong way round is a mistake the tool can catch, which is the reason the two are kept distinct rather than merged into one dot.

1.8. Operators, and how tightly they bind

From tightest to loosest:

Binding Operators

Binding	Operators
tightest	`.` `→`
	`not`, unary `-`
	`*` `/`
	`+` `-`
	`<` `>` `⇐` `>=`
	`=` `<>`
	`and` `or` `xor`
loosest	`implies`

tightest

. →

not, unary -

* /

+ -

< > ⇐ >=

= <>

and or xor

loosest

implies

Two rows of that table surprise people, and both are OCL's own rules rather than choices made here.

and, or and xor all bind equally, left to right. So a or b and c means (a or b) and c — not what most programming languages would make it. If that reads ambiguously to you, write the parentheses; that is the right response.

= binds looser than <, so a < b = c < d means (a < b) = (c < d).

Inequality is <>. It is not !=, which is not part of OCL at all.

1.9. Conditionals

if claim.approved then claim.payout else 0 endif

The else is required. An expression must denote something on every path, and a one-armed if would denote nothing when the condition fails.

1.10. Naming a value once

let total = request.items->collect(i | i.amount)->sum() in
    total > 0 and total < limit

1.11. Working through collections

The iterators are OCL's: select, reject, collect, forAll, exists, one, any, isUnique, sortedBy, iterate.

claims->select(c | c.open)                  -- those that are open
claims->select(c : Claim | c.open)          -- the same, typed
claims->forAll(c | c.amount > 0)            -- true of every one
claims->exists(c | c.disputed)              -- true of at least one
claims->isUnique(c | c.reference)           -- no two share a reference
claims->collect(c | c.amount)->sum()
claims->iterate(c; total : Real = 0 | total + c.amount)

The variable before the | exists only inside the body. iterate names an accumulator after the ;, starts it at the value given, and replaces it with the body’s value for each element in turn: the answer is its last value. Over a Set or a Bag the turn is the order the elements were given in, so an accumulation whose answer depends on the order should iterate over a sortedBy.

1.11.1. Which collections have an order

OCL has four kinds of collection, and whether two of them are equal depends on their kind. A Sequence and an OrderedSet have an order; a Set and a Bag do not. An entity’s population, Claim.allInstances(), is a Set; select and reject keep the kind they are given; collect makes a Bag from an unordered collection and a Sequence from an ordered one; sortedBy makes an ordered one. A list in a request or a response is a Sequence.

Two collections are equal element by element, in order, only when both are ordered. Otherwise they are equal when they hold the same elements, each as many times, in any order:

Set{1, 2} = Sequence{2, 1}                    -- true: a set has no order
Sequence{1, 2} = Sequence{2, 1}               -- false
response.claims = Claim.allInstances()->select(…)->collect(…)                      -- any order
response.claims = Claim.allInstances()->select(…)->sortedBy(c | c.incidentAt)->collect(…)  -- in that order

So a post-condition about a list requires an order only when it says one, with sortedBy. any gives one element the body holds of, and invalid when none does.

1.11.2. Leaving the variable out

An iterator may be written without a variable. Each element is then what a bare name in the body is read from:

claims->select(open)                        -- claims->select(c | c.open)
accounts->select(balance > 0)->size()
orders->collect(amount)->sum()

The element’s field wins. A bare name that is a field of the element means that field, even where the request, the response or a name the process has bound has a field or a value of the same name. A name the element does not have is read from outside, as anywhere else. Where the element is an entity, a name that is nothing else is not reported, because an entity may have a property no view has stated yet.

To read the outer value inside such a body, name it in full, request.amount rather than amount, or declare the variable and the rule does not apply.

1.12. Speaking about a population

The rows above give you the request in hand. A great many conditions are not about it: the claimant has been paid, the policy is in force, more than one account matches are all claims about how many things of some kind exist, and about which.

Name the entity and ask for all of them:

Account.allInstances()

That is a Set of every Account there is, and from there it is an ordinary collection:

-- some account belongs to the person who asked
Account.allInstances()->select(a | a.holder = request.holder)->notEmpty()

-- exactly one matches, which a pre-condition may insist on
Account.allInstances()->select(a | a.number = request.number)->size() = 1

-- nothing is overdrawn, as an invariance
Account.allInstances()->forAll(a | a.balance >= 0)

1.12.1. Only an entity has a population

An entity is a business object with an identity — a real account, a real claim — and a DataStructure is a view onto one: the shape a particular message carries. Views have no population of their own, so AccountSummary.allInstances() is reported, and the message names the entity to ask instead.

That matters more than it sounds. Two services may each carry a different view of one account; if both had extents there would be two different answers to "how many accounts are there".

1.12.2. Naming an entity that shares its name

Give as much of the path as it takes, innermost part last:

Account                           -- when only one entity is called that
Accounts::Account                 -- when two are
Insurer::Accounts::Account        -- the whole way, never required

Where the bare name would be ambiguous the tool offers you the qualified one as you type.

1.12.3. What an entity’s fields are

An entity’s fields are those of every view onto it, taken together — which is what the Entity View draws. The tool types what it finds there, so a.balance > 'x' inside an extent is reported like any other type mismatch.

But it does not report a name no view declares. An entity’s full field set is deliberately not written down anywhere — that is what makes it an entity rather than a data structure — so a name the model has not projected into any message shape may still be a real property of the thing. The tool would be guessing, and it says nothing instead.

Note

An extent is always safe to read. It cannot change anything, so — unlike asking for a service — there is no rule about where you may write one. It is equally at home in an invariance, a pre-condition, a post-condition and a flow condition.

One consequence worth knowing: a while loop whose continuation condition reads an extent is not reported as unable to finish. The population can change while the loop runs, which is exactly why reading one is useful there — see Loops that cannot finish.

1.13. Speaking about the state before

A service changes the world, and the most important thing a post-condition says is often how: the balance went up by the amount deposited, exactly one account was opened, no other account moved. Each of those compares the state after the service with the state before it. @pre reads the state before:

-- the account deposited into gained exactly the amount
Account.allInstances()
    ->select(a | a.number = request.accountNumber)
    ->forAll(a | a.balance = a.balance@pre + request.amount)

-- exactly one account was opened
Account.allInstances()->size() = Account.allInstances@pre()->size() + 1

@pre goes straight after a name, and before any argument list, as in OCL: a.balance@pre, Account.allInstances@pre(), a.holdings@pre→size(). Written after the parentheses — allInstances()@pre — it is reported, with where it belongs.

It marks the name it follows and nothing else. In a.balance@pre, a is the account as it is after the service, and balance@pre is that same account’s balance before it.

1.13.1. Only in a post-condition

@pre may be written in a post-condition, and in its Condition, and nowhere else. A pre-condition is evaluated in the state before already, so it has nothing to add there; an invariance is not about a service at all; and a process step is a part of how a service is realized, not a claim about its whole effect. Anywhere else it is reported as an error.

1.13.2. Only on an entity’s state

State lives in entities (see Section 1.12), so that is what @pre marks:

Written Means

Written	Means
`Account.allInstances@pre()`	Every account there was before the service.
`a.balance@pre`, with `a` an account	That account’s balance before the service.
`request.amount@pre`, `amount@pre`	The same as `request.amount`. The request is one value, before and after, so the marker is redundant — accepted, and saying nothing more.

Account.allInstances@pre()

Every account there was before the service.

a.balance@pre, with a an account

That account’s balance before the service.

request.amount@pre, amount@pre

The same as request.amount. The request is one value, before and after, so the marker is redundant — accepted, and saying nothing more.

Anything else is reported, because it has no state before the service: the response and its fields (there is no response before), caller, a variable the body bound for itself, an operation such as size@pre(), a function applied, and a field of a structure value. That last one is worth a sentence. In a.address.city@pre, a.address is a copy of the account’s address, and the copy has no history; what is meant is the account’s address before, a.address@pre.city.

1.13.3. Which instance "the same" is

An entity is matched with itself before and after by its identifying field — the one a view of it declares as identifying (see What a field means to its entity). That is the only identity the model states, so it is the one @pre uses. Two consequences:

An instance the service created has no state before. Its @pre is invalid, as in OCL, and a condition that needs it is not satisfied.
An entity none of whose views declares an identifying field cannot be matched, and a field read marked @pre on it cannot be decided.

Account.allInstances@pre() needs no identity: it is the whole population, whoever is in it.

1.13.4. Trying it, and running it

Try an example takes the population before under extentsBefore, beside extents — see Trying a constraint on an example.

At run time, the execution environment reads the state before a service as it was when the service started, and enforces @pre. The cases it cannot decide, and so lets through, are listed in What the checks cannot decide.

1.14. Asking for a service

A service contract declared a function (see Services that are functions) may be applied to a request, and the expression denotes its response:

Rating::premiumFor(request.risk).amount > 0
premiumFor(request.risk).amount > 0     -- the same, unambiguously named

Give as much of the path as it takes to be unambiguous, exactly as for an entity. The tool offers you the functions your model declares as you type, by their full path.

The result is the function’s response structure, so you can navigate straight into it — and a field it does not have is reported, like any other.

Three rules follow from what a function is.

Only a function may be applied. An ordinary service changes the world, and a specification that changed the world while being checked would not be a specification. Applying one is reported, and the repair is on the contract: declare it a function, or say something else.

What you pass must be the function’s request. The argument’s type has to be the function’s requestDataStructure, or something that specialises it. Two structures with the same fields are still two different types — URDAD names its types rather than matching their shapes.

That last rule catches people out, so it is worth being concrete. If premiumFor takes a Risk, then:

premiumFor(request.risk)      -- yes: the field holds a Risk
premiumFor(request)           -- no, unless the request *is* a Risk,
                              -- or specialises one

If you find yourself wanting to pass your own request straight through, the model is telling you something: either the function’s parameter is the wrong type, or your request should specialise it.

A function that does not answer gives null. If the request does not meet the function’s own pre-conditions, or the service raises an exception, there is no answer — so the application is null. A condition can ask for exactly that, f(x) <> null, and one that reads a field of the answer is not satisfied when there is none. The execution environment answers it the same way when the condition is checked at run time.

1.14.1. Requiring that a function answers

A common pre-condition is that some other service must be able to answer this request — that asking it will not be refused. When that service is a function, say so by comparing its answer with null:

premiumFor(request.risk) <> null

When the condition goes on to read the answer, bind it once and guard it:

let p = getPolicy(Tuple{policyNumber = request.policyNumber}) in
  p <> null and p.status = PolicyStatus::inForce

Often you do not need the guard. A condition that reads the answer is already not satisfied when there is none — a field of null is not a value — so

premiumFor(request.risk).amount > 0

already requires that premiumFor answers. Write the guard when answering is the whole of what you mean, or when the condition should say plainly what it requires before it reads.

Two limits are worth knowing.

It cannot name the exception. Every way of not answering — an unmet pre-condition of the function, or any exception it raises — gives the same null. You can require that the function answers; you cannot require that it does not raise one particular exception.

It works only for a function. An ordinary service cannot be asked at all (see above), and a pre-condition saying "that service must not raise" would be a claim about how this service is built rather than about what it needs. State the condition itself instead: take what the lower-level service’s own pre-condition requires, restate it in terms of this request, and give it an exception of its own. The process then either handles the lower-level service’s exception or relies on this pre-condition having already ruled it out.

1.15. `now()` and `caller`

Two more things a body may name, both restricted the same way a function that is not one is.

now() is the present moment, as a dateTime — an absolute instant, never a localDateTime. It takes no argument:

now() > request.deadline

It is a call and not a name, unlike everything else in this chapter, because its value depends on when it is asked rather than on anything navigable — the same distinction that puts allInstances() in Section 1.12 rather than in the scope table above.

today() is the Date that now() falls on in the model’s time zone, set on the model itself (Section 1.15.1). It takes no argument, and moves by whole days written as text:

request.dueOn >= today() + 'P3D'

The zone is part of the model, so the same model gives the same date on every deployment. The zone of the machine the tool runs on is never consulted. With no zone set, it is UTC. 23:30 UTC on the 31st is already the 1st in Johannesburg, so the zone decides the date. today() is restricted exactly as now() is, below.

caller is the identity that started this execution — a plain, opaque String, comparable and never absent:

caller <> null                                            -- always true

-- "only for your own account"
Account.allInstances()->exists(a | a.holder = caller and a.number = request.number)

It names a login identity, not a business entity — recording that a given login identity is a given customer is ordinary model content, a field on whichever entity represents that party, compared against caller the same way any other fact would be.

None of now(), today() or caller may appear in a function’s own pre-condition or post-condition. A service contract declared a function (Services that are functions) promises the same value for the same request, always — and a clock reading or an asking identity can make two evaluations of one request disagree. Using either there is reported, the identical rule that reports applying something that is not a function.

1.15.1. The model’s time zone

Select the model itself in the model tree. Its details form has a Time zone field, which holds an IANA time-zone id such as Africa/Johannesburg. Left empty, the zone is UTC.

It is model content like any other change: committed, reviewed and signed off with the model, so changing it is visible in the history and at a phase gate. An execution that is already running keeps the zone it started with, because the zone is fixed into a process when it is deployed, as its expressions are.

An element of an element library is read in its library’s own zone, not in the zone of the model that uses the library.

An id the tool does not know, such as a misspelling or a zone that does not exist, is reported by Verify model on the model itself and blocks a phase transition. Otherwise every today() in the model would rest on a date nobody can work out.

1.16. `randomInteger` and `randomReal`

Two calls draw a random number — for a simulation, a sample, a randomised route or a jittered retry:

Call Bounds Draws

Call	Bounds	Draws
`randomInteger(lo, hi)`	two `Integer`s	an `Integer` from `lo` to `hi`, both included
`randomReal(lo, hi)`	`Integer` or `Real`	a `Real` from `lo` up to but not including `hi` — or `lo` itself when `lo = hi`

randomInteger(lo, hi)

two `Integer`s

an Integer from lo to hi, both included

randomReal(lo, hi)

Integer or Real

a Real from lo up to but not including hi — or lo itself when lo = hi

randomInteger(1, 6) + randomInteger(1, 6)     -- two dice: each call is a new draw
randomReal(0, 1) < 0.3                        -- true about 30 % of the time

A Decimal bound is reported as the wrong type: Decimal is for exact amounts, and a draw is not one. A range that is empty — lo greater than hi — does not denote a number, so the call is invalid.

Only in a process. A draw may be written in any slot of a process — a variable’s initial value or step, a conditional flow’s condition, a loop’s continuation condition, a for-each’s collection, a raw activity’s specification. It may not be written in an invariance, a pre-condition or a post-condition, even an ordinary service’s. A specification says what must hold, and one that holds on some checks and fails on others says nothing anybody could rely on. To constrain a random value, draw it into a process variable and constrain the variable.

Not in a function’s process either. A function (Services that are functions) promises the same value for the same request, and its process is how that value is worked out, so a draw anywhere in it is reported — the same finding as now() in a function’s pre-condition.

When a process runs, each draw comes from the execution’s own random source, so an execution that is replayed after a restart draws the same numbers it drew the first time.

1.17. Comments

Both of OCL's forms:

amount > 0    -- to the end of the line
amount /* or inline */ > 0

1.18. The grammar

What a body may be written as, in full. The rules below are the parser’s own, so a body they do not produce is refused, with a message saying why, rather than accepted as text. The notation is EBNF, as ISO/IEC 14977 writes it: { … } repeats zero or more times, [ … ] is optional, | separates alternatives, and a terminal is quoted.

URDAD-OCL, the syntax

expression        = implication ;
implication       = logical { "implies" logical } ;
logical           = equality { ( "and" | "or" | "xor" ) equality } ;
equality          = relational { ( "=" | "<>" ) relational } ;
relational        = additive { ( "<" | ">" | "<=" | ">=" ) additive } ;
additive          = multiplicative { ( "+" | "-" ) multiplicative } ;
multiplicative    = unary { ( "*" | "/" ) unary } ;
unary             = ( "not" | "-" ) unary | postfix ;
postfix           = primary { ( "." | "->" ) call } ;
call              = path [ "@pre" ] [ arguments ] ;
primary           = literal
                  | "(" expression ")"
                  | ifExpression
                  | letExpression
                  | collectionLiteral
                  | tupleLiteral
                  | path [ "@pre" ] [ arguments ] ;
arguments         = "(" [ iteratorVariables "|" expression
                        | expression { "," expression } ] ")" ;
iteratorVariables = iteratorVariable { ( "," | ";" ) iteratorVariable } ;
iteratorVariable  = identifier [ ":" type ] [ "=" expression ] ;
ifExpression      = "if" expression "then" expression "else" expression "endif" ;
letExpression     = "let" identifier [ ":" type ] "=" expression "in" expression ;
collectionLiteral = collectionKind "{" [ collectionPart { "," collectionPart } ] "}" ;
collectionKind    = "Set" | "OrderedSet" | "Bag" | "Sequence" ;
collectionPart    = expression [ ".." expression ] ;
tupleLiteral      = "Tuple" "{" [ tuplePart { "," tuplePart } ] "}" ;
tuplePart         = identifier [ ":" type ] "=" expression ;
type              = path [ "(" type ")" ] ;
path              = identifier { "::" identifier } ;
literal           = integer | real | string
                  | "true" | "false" | "null" | "invalid" ;

The rules from implication down to unary are the binding order of Section 1.8, loosest first: each operator of a rule binds less tightly than those of the rules below it, and operators of one rule apply left to right. collectionKind and Tuple are names, not keywords: they open a literal only when a { follows them. A body is a single expression; nothing may follow it.

The words of the language are made of these:

URDAD-OCL, the words

identifier = ( letter | "_" ) { letter | digit | "_" } ;   (* not a keyword *)
integer    = digit { digit } ;
real       = digit { digit } ( "." digit { digit } [ exponent ] | exponent ) ;
exponent   = ( "e" | "E" ) [ "+" | "-" ] digit { digit } ;
string     = "'" { character | escape } "'" ;
escape     = "\" ( "n" | "t" | "r" | "b" | "f" | "\" | "'" | '"' ) ;
comment    = "--" { character } end of line
           | "/*" { character } "*/" ;

The keywords are reserved, so none can be a name: and, else, endif, false, if, implies, in, invalid, let, not, null, or, then, true, xor. Letters and digits are those of ASCII. Space, line breaks and comments may stand between any two words (Section 1.17). What OCL has and this grammar leaves out, the message expression ^ among it, is listed in Section 1.19.

Every rule above, in a body that parses:

One example per rule

request.amount > 0 implies account.balance >= request.amount
a.active and not a.closed or b xor c
status = Status::OPEN
total <= limit
amount + fee - discount
price * quantity / 2
-balance
claims->select(c | c.amount > 1000)->size()
balance = balance@pre - request.amount
Account.allInstances@pre()->size()
(a + b) * c
if score > 700 then 'approved' else 'referred' endif
let net: Real = gross - tax in net > 0
Set{1, 2, 3}->includes(x)
Sequence{1..10}->sum()
Tuple{name: String = 'A', amount = 10.5}
claims->forAll(c1, c2 | c1 <> c2 implies c1.id <> c2.id)
claims->iterate(c; total: Integer = 0 | total + c.amount)
Insurer::Policy.allInstances()->select(p | p.active)
amount > 1.5e3 and note <> 'n/a' and x <> null and y <> invalid and flag = true and other = false

1.19. What is deliberately left out

Left out Instead

Left out	Instead
`context`, `inv:`, `pre:`, `post:`, `package`	Nothing. The element the specification is written on is the context.
Message expressions, `^` and `^^`	Nothing. These assert that an operation was called, which is a claim about how a service is built rather than about what must hold of it — and a contract must not make one.
`def:`, `init:`, `derive:`	A derived value belongs in the model as an element, where every reader can see it, not inside one constraint body.

context, inv:, pre:, post:, package

Nothing. The element the specification is written on is the context.

Message expressions, ^ and ^^

Nothing. These assert that an operation was called, which is a claim about how a service is built rather than about what must hold of it — and a contract must not make one.

def:, init:, derive:

A derived value belongs in the model as an element, where every reader can see it, not inside one constraint body.

1.20. When a constraint is not formalisable

Do not write English into a specification body: URDAD-OCL is the only specification language, and prose there is reported as an error. Say it as an informal requirement annotation on the element instead, and leave the specification empty until it can be written. The model then says what is true — that the constraint is meant and is not yet formal. See One specification language.

Each of these is recognised and refused by name, with an explanation — you will not get a puzzling syntax error and go hunting for a typo that is not there.

Appendix A: The standard library

Every model needs somewhere to get Integer, String and Date from. Those definitions used to be declared inside each model, so every model had its own and none of them related to any other’s — two models could not agree that they meant the same thing by a date.

They now live in StandardLib, an element library that ships with the tool. Every new model is associated with it at creation, pinned to the revision current at that moment, so a model can type its first field without any setup.

A.1. What it contains

Domain Holds

Domain	Holds
`BasicDataTypes`	`Byte`, `Decimal`, `FloatingPointNumber`, `Integer`, `NonNegativeInteger`, `String`
`DateTime`	Points in time: `Date`, `Time`, `OffsetDateTime`, `LocalTime`, `LocalDateTime`, `TimeZone`, `ZonedDateTime`, `ZonedTime` Amounts of time: `Duration`, `CalendarPeriod`, `BusinessDayCount`, `BusinessCalendar`, `BusinessDayConvention`, `Frequency`
`Documents`	`Document`

BasicDataTypes

Byte, Decimal, FloatingPointNumber, Integer, NonNegativeInteger, String

DateTime

Points in time: Date, Time, OffsetDateTime, LocalTime, LocalDateTime, TimeZone, ZonedDateTime, ZonedTime
Amounts of time: Duration, CalendarPeriod, BusinessDayCount, BusinessCalendar, BusinessDayConvention, Frequency

Documents

Document

Each primitive names the underlying machine kind it stands for, which is what lets generated artifacts — an OpenAPI document, say — give it a real type rather than an untyped placeholder. Where a type carries a constraint the underlying kind cannot express, it is recorded as an invariance on the type: NonNegativeInteger is an integer that must be at least zero, and Byte an integer between 0 and 255.

A.1.1. `Decimal` and `FloatingPointNumber` are both numbers, and are not alike

Decimal is exact: 0.1 + 0.2 is 0.3, and a ledger that sums a million amounts reconciles rather than drifting. FloatingPointNumber is binary floating point and therefore approximate — right for an interest rate, a yield or a day-count fraction, and wrong for anything that has to balance. The tool computes a Decimal exactly as well — in a demonstration, and in every check at run time — and a decimal travels between systems as text ("23.34"), which no reader of JSON turns into a floating-point number on the way.

Model a monetary amount with Decimal, or with the finance library’s Money, which is a Decimal and the currency it is denominated in. Never with FloatingPointNumber: the discrepancy in a floating-point ledger grows with volume rather than staying inside a tolerance.

The constraint language keeps them apart — neither fits where the other is expected, so crossing between them is written down rather than happening silently — and Decimal carries no number of decimal places, since precision varies by context. Both rules, and the rounding and division operations that go with them, are in Section 1.5.

Every definition carries a short description, and those that are easy to mistake for one another carry a detailed one as well — select a type in the model tree and read it in the element details view rather than inferring the meaning from the name. See Describing what you model.

A.2. Choosing a date or time type

The three kinds differ in what they carry, and picking the wrong one is the most common way a model quietly says something it did not mean.

Use When Because

Use	When	Because
`OffsetDateTime`	Something happened — a claim notified, a payment cleared	It carries a UTC offset, so it denotes an unambiguous instant
`LocalDateTime` inside a `ZonedDateTime`	Something is scheduled — an inception at midnight local, a deadline at close of business somewhere, anything recurring	The offset of a future local time is not knowable in advance: daylight-saving rules can change between now and then, so an offset stored today may be wrong when the date arrives
`Date`	A calendar fact — a date of birth, an inception date	It denotes a whole day

OffsetDateTime

Something happened — a claim notified, a payment cleared

It carries a UTC offset, so it denotes an unambiguous instant

LocalDateTime inside a ZonedDateTime

Something is scheduled — an inception at midnight local, a deadline at close of business somewhere, anything recurring

The offset of a future local time is not knowable in advance: daylight-saving rules can change between now and then, so an offset stored today may be wrong when the date arrives

Date

A calendar fact — a date of birth, an inception date

It denotes a whole day

ZonedDateTime is a structure, not a primitive: a local reading plus the zone it belongs to. It deliberately stores no offset — one would be a second source for something the zone already determines, and the two could then disagree.

Warning

A Date is not midnight. 2027-08-12 denotes the whole of that day; 2027-08-12T00:00:00 is one instant within it, and which instant depends on the zone. Resolve a date to midnight in UTC and it is already 02:00 on the 12th in Johannesburg but still 20:00 on the 11th in New York — so the day is wrong for a large part of the world. Where a rule genuinely means "00:00 local on that date", say so with a ZonedDateTime; do not let the type imply it.

Time carries an offset for the same reason OffsetDateTime does. For a recurring wall-clock time — "17:00 in Johannesburg, every weekday" — use ZonedTime, which pairs a LocalTime with the zone it is read in and so stays correct across a daylight-saving change.

A.3. Choosing a duration type

An amount of time splits the same way a point in time does, and along a line that is just as easy to cross without noticing: does the amount resolve to a fixed length by itself, or does it mean nothing until something else is supplied?

Use For Because

Use	For	Because
`Duration`	A timeout, a retry interval, a session lifetime, a regulatory clock stated in hours — "notify within 72 hours"	It is ISO 8601 time components only (`PT72H`), so it is the same number of seconds wherever and whenever it is read
`CalendarPeriod`	Anything a rule states in calendar terms — a 31-day cooling-off period, a premium grace period, a five-year retention period, a policy term	Months and years are not lengths. One month after 31 January is 28 February; `P1M` and `P30D` land on different dates from the same anchor
`BusinessDayCount`	A turnaround or settlement obligation — T+2 settlement, "acknowledge within five business days"	Only a named `BusinessCalendar` knows which days the institution or market is open
`Frequency`	How often something recurs — premium collection, statement cycles, reporting cadence, review periodicity	It states a rate, not a length: `monthly` says nothing about how many days a month has

Duration

A timeout, a retry interval, a session lifetime, a regulatory clock stated in hours — "notify within 72 hours"

It is ISO 8601 time components only (PT72H), so it is the same number of seconds wherever and whenever it is read

CalendarPeriod

Anything a rule states in calendar terms — a 31-day cooling-off period, a premium grace period, a five-year retention period, a policy term

Months and years are not lengths. One month after 31 January is 28 February; P1M and P30D land on different dates from the same anchor

BusinessDayCount

A turnaround or settlement obligation — T+2 settlement, "acknowledge within five business days"

Only a named BusinessCalendar knows which days the institution or market is open

Frequency

How often something recurs — premium collection, statement cycles, reporting cadence, review periodicity

It states a rate, not a length: monthly says nothing about how many days a month has

Warning

PT24H and P1D are different statements. A day is 23 or 25 hours across a daylight-saving change, which is why days, months and years belong to CalendarPeriod and never to Duration. Writing thirty days where a regulation says one month is the same error a step larger, and it is the one that reaches a regulator.

A Duration and a CalendarPeriod are both magnitudes, and are never negative. State direction in the model — "30 days before the due date" — not as a sign on the value. A negative amount alongside directional wording reads correctly whichever way you take it, and therefore settles nothing.

Since StandardLib v1.4.0 the two are different kinds — duration and calendarPeriod — and not only different names, because constraints treat them differently: a Duration can be compared and added to a time, a CalendarPeriod can do neither on its own. See Section 1.6. A model still pinned to an older StandardLib reads its CalendarPeriod as a duration until it upgrades, so comparisons and arithmetic over it are not yet reported there.

A.3.1. Resolving an amount to a date

A CalendarPeriod or a BusinessDayCount becomes a date only against an anchor, and a model that gives one without the rest of what it needs is under-specified in a way that reads as complete. State all of:

the anchor date, and the zone it is read in;
the BusinessCalendar, whenever open and closed days matter;
the BusinessDayConvention to apply when the result lands on a closed day — following, modifiedFollowing, preceding, modifiedPreceding, endOfMonth, or unadjusted to say explicitly that no adjustment is made.

Without a convention stated, a computed date is ambiguous for roughly a fifth of the year, and two faithful implementations of the same requirement will disagree without either being wrong.

In a constraint, addPeriod and subtractPeriod state them: inceptionDate.addPeriod(term, calendar, BusinessDayConvention::following). See Section 1.6.1, including what the tool can and cannot work out from a calendar it knows only by name.

Note	Day-count conventions — `act/360`, `30/360` and the rest — are not here. They are conventions of a financial product, not of time itself, and what they produce is a year fraction rather than a length of time. Define them in your own model or in a library of your own.

A.4. It is read-only

StandardLib cannot be edited on your instance — not by anyone, administrators included. It is content the tool ships and replaces on upgrade, so an edit would be silently discarded the next time the tool is updated. Attempting one is refused with an explanation rather than accepted and lost.

Reference its definitions from your own model exactly as you would any other library’s. If you need a type it does not have, define it in your own model or in a library of your own.

A.5. Upgrading

A new release of the tool publishes a new revision of StandardLib. Your models stay on the revision they are pinned to: nothing about them changes because the tool was upgraded, and a model that has been signed off still resolves against exactly the definitions it was signed off against.

Moving a model to the newer revision is the ordinary library upgrade, from Dependencies — including the check that refuses a move which would leave references unresolved.

Acronyms and glossary

A&D: Analysis and Design - the process for determining the stakeholder requirements and designing a solution fulfilling those requirements referring to BR.

access right: the level of access a security policy grants on a responsibility domain or a whole model. In increasing order: `deny` (the domain is hidden), `read`, `annotate`, `modify` and `manage` (which additionally permits driving the project life cycle and managing project teams).

ACL: Access Control List - a list attached to a resource, such as a file, naming which users or groups may access it and how, in addition to or in place of the resource’s basic permission bits.

Activate: the last transition of the project life cycle, which merges an approved project’s branch into the main branch once its effective date has arrived, making its work part of the live model.

activity: a step in a process: a service request, a message send or wait, a variable definition, or a construct grouping further activities such as alternate flows or concurrent flows.

adapter: the thin, product-specific part of an integration with an external tool: it realises a bridge's contract for one product — GitLab, Azure DevOps, HashiCorp Vault, Kafka — by mapping the contract’s requests and results to that product’s API, and holds no logic that another product would also need.

Advance: the generic step-forward transition of the project life cycle, moving a project to its next phase; its counterpart is Revert.

AI: Artificial Intelligence - the field of computer science building systems that perform tasks normally requiring human intelligence. In the tool it means the optional assistance an LLM provides, for instance formalising informal requirements.

AKS: Azure Kubernetes Service - Microsoft Azure’s managed Kubernetes platform, on which containers such as an instance’s images can be run.

alternate flows: a branch in a process of which exactly one flow is taken: the first conditional flow, in their modelled order, whose condition holds, or the default flow when none does. All flows rejoin at a merge.

AML: Anti-Money Laundering - the laws, regulations and controls requiring financial institutions to detect and report attempts to disguise the proceeds of crime; they impose record-keeping obligations that can override a request for erasure. Compare KYC.

AMQP: Advanced Message Queuing Protocol - an open wire-level protocol for message-oriented middleware, used by message brokers such as RabbitMQ to pass messages between systems.

ANF: Administrative Normal Form - an intermediate form of a program in which every argument of an operation is a variable or a constant, each intermediate result being bound to a name of its own.

annotation: free text attached to a model element and stored with it. Each annotation has a purpose (short or detailed description, informal requirement, comment, concern, question, response or error) and a markup type.

anonymisation: an irreversible processing of personal data that completely prevents the identification of an individual by any means using any of the stored information. Unlike pseudonymised data, anonymised data is no longer subject to data protection regulations like GDPR.

anonymous instance: an instance of the modelling tool with no sign-in, on which every visitor is the same anonymous reader who may open its models and change nothing — the configuration the public playground runs.

API: Application Programming Interface - a set of rules or protocols that enables software applications to communicate with each other to exchange data and functionality.

applies to the current state: what a service contract declares, with its reason, when its change to a stored entity instance applies to the instance as it is rather than to an entity version its requester read: an increment computed from the stored value inside the change’s own transaction, or a change meant to win.

Approve: the transition from In Review to Approved. It records the approver’s signature and the effective date, and is refused unless every team member has signed off, every mandatory checklist item is signed and the separation-of-duties rules hold.

Approver: the project role whose holder moves the project from In Review to Approved with Approve; assigned on top of the holder’s team-membership role.

archiving: retiring a project that will not be activated by hiding it from the day-to-day project lists. Unlike deletion it is reversible: the branch, history, audit log and team all survive, and the project can be unarchived.

ASCII: American Standard Code for Information Interchange - the 7-bit character encoding of the basic Latin letters, digits and punctuation, of which UTF-8 is a superset.

AsciiDoc: a plain-text markup language for documents, readable as written and rendered by Asciidoctor to HTML, PDF and other formats. The tool writes a model’s generated documentation in it; both manuals are written in it too.

AST: Abstract Syntax Tree - the tree a parser builds from source text, each node standing for one construct of the language, with the punctuation of the concrete syntax dropped.

audit log: the append-only, per-project record of every governance-relevant event — phase transitions, sign-offs, approvals, role changes and the like. Rows are never updated or deleted; the actor is recorded as an opaque identifier.

Author: the default role of every project team member, permitting them to modify the model during the Development phase within their security-policy grants.

await message: an activity that stops a process until a message of a named data structure arrives.

AWS: Amazon Web Services - Amazon’s cloud platform, offering hosted compute, storage and LLM endpoints among other services.

BA: Business Analyst - a person who elicits, analyses and documents the requirements of a business and its stakeholders, typically one of the modellers of a URDAD model.

background flow: a flow of concurrent flows that runs on independently and ends in a flow end of its own instead of arriving at the join.

bounded context: in domain-driven design, the boundary within which one model, and the meaning of its terms, applies consistently; another context may model the same things differently, and exchanges with it are translated at the boundary.

BPMN: Business Process Model and Notation - a public standard of the OMG for documenting and diagrammatically representing business processes.

BR: Business Rule - a precise declarative statement that defines or constrains some aspect of an organization’s operations, behaviour or structure. It asserts business knowledge or intent, independent of the systems or manual processes used to implement it.

bridge: the tool-neutral component through which the tool integrates with one responsibility domain it relies on outside itself — CI/CD gating, secrets, an identity directory, messages from a broker. It holds everything that does not depend on a product, and delegates the rest, through a logic-free contract, to one adapter per product.

BRMS: Business Rule Management System - a repository and execution environment for hosting and executing business rules (BRs).

C4 model: a notation for software architecture that describes a system at four levels of zoom: its context, its containers, their components and their code.

CA: Certificate Authority - an entity that issues the digital certificates with which TLS and similar protocols establish the identity of a server or client.

CAB: Change Advisory Board - the body which, in an ITSM change process, assesses, prioritises and approves or rejects a proposed change to a production service.

cancellable: said of a service contract whose requesters may cancel a request before it is answered. A cancelled request has no net effect: the process realizing it undoes what it committed. A request for a service that is not cancellable is waited for when its requester is interrupted, and then undone through its contract’s compensation.

candidate: a model commit, under an environment's current configuration, that the environment has evaluated and that may be promoted to become its pin.

CDN: Content Delivery Network - a geographically distributed network of servers that caches and serves a site’s static content from a location close to each visitor.

CEF: Common Event Format - ArcSight’s Common Event Format: one line per event, a fixed header of vendor, product, event type, name and severity, then `key=value` extensions. Most SIEMs read it from syslog.

checklist template: an organisation-wide set of review items, authored by auditors, which can be attached to a project so that each item must be signed before the project may be approved.

CI: Continuous Integration - the practice of building and testing every change automatically as it is integrated; also the pipeline that does so. See CI/CD.

CI/CD: Continuous Integration / Continuous Delivery - the practice of building and testing every change automatically as it is integrated (CI), and of delivering or deploying what passes automatically (CD).

CJS: CommonJS - the module format Node.js used before standard JavaScript modules, loading a module with `require` and exporting through `module.exports`.

CLI: Command-Line Interface - a program operated by typing commands and arguments in a terminal rather than through a graphical UI.

client: the party that requests a service: the one the service is offered to, and the one its response is for. A service contract's _Published to_ list names the responsibility domains that may be its clients from outside its own domain. A client need not be a stakeholder, nor a stakeholder a client. The client of one particular request is its _requester_; once a model runs, the identity a request is made as is its _caller_. Not to be confused with a software client, such as the web client or an OIDC client.

cohesion: the degree to which what a component contains belongs together, because it serves one purpose or one responsibility. Good design seeks high cohesion.

compensation: the request that undoes a change a step of a process committed, stated on the step or, as its _Undone by_, on the requested service contract. It runs when the process refuses after the change was made, so that the refusal has no net effect.

Compliance Officer: the project role representing the compliance function on the project; mandatory for a regulated project.

:def-concurrent_flows:a construct of a process whose flows all start together at a fork. Unconditional flows and conditional flows whose condition holds arrive at a join, which waits for all of them; background flows run on independently.

concurrent flows: {def-concurrent_flows}

condition: a named boolean predicate, optionally with a formal specification.

console: the execution environment's operating tool: the `console` command, which creates environments, applies configurations, promotes and rolls back, and the browser application over the API that `console serve` provides.

CORS: Cross-Origin Resource Sharing - the browser mechanism by which a server permits a web page from another origin to call it; a request a server does not so permit is blocked by the browser.

coupling: the degree to which one component depends on another, and so must change when the other does. Good design seeks low coupling.

CPU: Central Processing Unit - the processor of a computer that executes a program’s instructions.

CRUD: Create, Read, Update, Delete - the four basic operations on stored records.

CSI: Container Storage Interface - the standard interface through which a container orchestrator such as Kubernetes mounts storage — and, through the Secrets Store CSI driver, secrets — into a container.

CSS: Cascading Style Sheets - the language in which the presentation — layout, colours, fonts — of an HTML or SVG document is specified.

CSV: Comma-Separated Values - a plain-text tabular format with one record per line and its fields separated by commas.

CVI: Contract Verifying Interceptor - the component of an execution environment that judges each answer to a service request against the service contract it was made under — its pre-conditions, post-conditions and data constraints.

dangling reference: an id held by one model element that does not or no longer resolves to any element in the model.

data controller: the party that decides why and how personal data is processed.

data dictionary: what an entity stores, attribute by attribute: each attribute’s type, role, multiplicity, uniqueness and personal data, the views whose fields of its name are stored in it, and the services that write it and the elements that read it — the entity’s lineage. Generated documentation carries one for every entity.

data owner: whoever is accountable for the data a responsibility domain keeps: in an execution environment, the members of the identity-provider groups named for the domain, who accept each change to the shape of an entity it owns before it is promoted into production.

data processor: a party that processes personal data.

data structure: a structured data type with typed fields. It may specialize another data structure and may carry invariance constraints; a request, a response, an exception and a message are each described by one.

DB: Database - an organised, persistent store of data and the software managing it.

DDAD: Domain-Driven Analysis and Design - an analysis and design method where requirements and design is specified in terms of domain (business) concepts instead of technical concepts.

decision: a model element that works out a response from a request by rules, as a decision table or a single literal expression. A decision changes nothing, so it is a way of realizing a function service.

decision table: a decision made of inputs, outputs and rules, one rule per row; its hit policy says which applicable rules answer.

dependency inversion principle: the design principle that higher-level policy should not depend on lower-level detail, but both on an abstraction; in URDAD, a process and the providers that answer its requests both depend on a service contract.

descriptive level: the lowest verification level, and a new project’s: does each process address its contract’s requirements and state nothing that cannot hold. It does not ask what each request and response carries.

design by contract: specifying what a component requires and what it guarantees as a contract of pre-conditions, post-conditions and invariants, which its client must satisfy and its provider must honour.

DFS: Depth-First Search - a graph traversal that follows each path as far as it leads before backtracking; with three node colours it detects cycles.

DI: Diagram Interchange - the part of the BPMN standard that records the layout of a process’s diagram — each shape’s bounds and each edge’s waypoints — alongside its semantics.

directory feed: how the organisation’s identity provider tells the tool who has left: over SCIM, or by the tool reading the provider’s directory. A person the feed deactivates or deletes loses access and is later erased; the feed also supplies group names to the policy editor. The modelling server and the execution environment each have one.

DNS: Domain Name System - the Internet’s directory, which resolves a host name to the network address of the machine serving it.

DOM: Document Object Model - the browser’s in-memory tree of an HTML or SVG document, through which scripts read and change the page.

domain schema: the PostgreSQL schema in which an execution environment keeps the records of the entities one responsibility domain owns, written only by that domain’s own database role, so that the database itself keeps each domain’s records apart.

DMN: Decision Model and Notation - a standard of the OMG for specifying business decisions as decision tables and expressions; its expression language is FEEL.

DORA: Digital Operational Resilience Act - an EU regulation which stipulates standards for managing ICT risks, third-party provider oversight, sharing of ICT incidents and for testing and auditing ICT processes.

DPO: Data Protection Officer - the person an organisation designates to oversee its compliance with data protection law such as GDPR or POPIA, and the point of contact for data subjects and the regulator.

DSD: Data Structure Diagram - the diagram of a URDAD model showing a data structure: its fields and its relationships to other data structures.

EA: Enterprise Architect - a person responsible for the structure of an organisation’s business, information and technology landscape as a whole, and for keeping individual solutions consistent with it.

EBNF: Extended Backus–Naur Form - a notation for writing down the grammar of a language as rules, each naming the sequences, alternatives, options and repetitions of words a construct is made of; the URDAD-OCL and URDAD-FEEL grammars are written in it, as ISO/IEC 14977 standardises it.

element library: a model whose purpose is to hold definitions shared by several models. A model associates with a fixed published revision of a library and may reference its elements, but never change them.

EMF: Eclipse Modeling Framework - an Eclipse framework and code-generation facility for building tools from a model expressed in EMOF (Ecore).

EMOF: Essential Meta-Object Facility - the compact subset of the OMG's MOF sufficient for defining simple metamodels, in which the URDAD metamodel is also published.

entity: a data object with identity used to store data which is typically persisted in a database.

entity feed: the property of a data structure naming the entity it is a view of. An entity’s fields are not authored directly but are the union of the fields stated by the data structures that feed it.

entity migration: the declared steps that carry an entity's stored instances across a change to its shape, which a promotion applies to every instance, each rewrite recorded in the instance’s history.

entity version: which version of a stored entity instance was read. The store numbers each instance’s versions and fills an entity’s *version* field on every read; a change to the instance names the version it was decided on, and is refused once the instance has moved past it.

environment: in the execution environment, one running deployment of a model — of kind `development`, `test`, `production` or `preview` — with a configuration saying who answers each service contract, a promotion policy and a current pin.

erasure: the deletion of all personal data - a right provided by data protection regulations like GDPR.

event-triggered flows: a branch in a process whose flow is chosen by an event occurring — a message arriving, a duration elapsing or a clock striking — rather than by a condition being tested.

exception: a named data structure raised to tell a service’s client that a pre-condition was violated and the service has been refused.

exception handler: the part of a service request that says what the calling process does when the requested service raises a particular exception. Every exception the requested service may raise must be handled.

executable level: the highest verification level: is each process formal enough to run in the execution environment. What the environment cannot build or follow, or its promotion gate refuses, is an error at this level.

execution environment: the optional deployable that runs a model’s processes for real, on Temporal. It is installed and operated separately from the modelling tool, which does not depend on it.

expanded service request: a service request drawn, in a Process View, as the process that realizes the requested service rather than as a box naming it. Expansion is a viewer’s choice of what to see, not part of the model, and what an expanded request shows is read-only.

expression: a pure expression is a mapping of variables onto some value.

FEEL: Friendly Enough Expression Language - the expression language of DMN, written to read like business prose. URDAD-FEEL, a profile of it, is one of the two notations in which a formal specification may be read and written.

FFI: Foreign Function Interface - the mechanism by which code in one programming language calls functions written in another.

finding: one result of model verification or of evaluating a candidate, carrying a severity.

formal specification: a condition, constraint or expression written in a formal language — URDAD-OCL, or equivalently URDAD-FEEL — so that the tool can check and evaluate it. The model stores every formal specification in URDAD-OCL.

function service: a service whose contract declares it pure: requesting it yields an answer and changes nothing. A process realizing it may only orchestrate other functions.

functional requirement: a requirement a service contract places on the service it specifies — one of its pre-conditions or post-conditions — which a realizing process allocates to the activities that address it.

FX: Foreign Exchange - the exchange of one currency for another, and the market in which it takes place.

gateway: the component of an environment through which external systems request the model’s published services.

GCC: GNU Compiler Collection - the GNU project’s compilers for C, C++ and other languages.

governance profile: per-project metadata captured during Planning and frozen afterwards: whether the project is regulated, its regulatory regimes, risk and data classification, stakeholders, whether its processes will be executed, and its target activation date.

GPU: Graphics Processing Unit - a massively parallel processor, originally for rendering graphics, on which LLMs are run efficiently.

GRC: Governance, Risk and Compliance - the coordinated management of an organisation’s governance, its risks and its compliance with laws, regulations and internal policies; also the class of tools that record its controls and the evidence that each is met.

hash chain: a sequence of records each of which carries a cryptographic hash of its own content and the hash of the record before it, so that altering, removing or reordering a record already written is detected by recomputing the hashes.

HEAD: in git, the commit a branch currently points to — its latest commit; the HEAD of `main` is the current state of the main branch.

high-volume entity: an entity an execution environment's configuration lists as holding too many instances to read whole: a condition reading its population there must be narrowed, by an equality on a stored field or a date-time window, or the promotion is refused.

hit policy: the rule of a decision table saying which of the rules that apply give its answer — for instance `UNIQUE`, `FIRST` or `ANY`.

HMAC: Hash-based Message Authentication Code - a code computed from a message and a secret key with a cryptographic hash function, with which a receiver holding the key verifies that the message is authentic and unaltered.

HSTS: HTTP Strict Transport Security - a response header by which a site instructs browsers to reach it only over HTTPS from then on.

HTML: Hypertext Markup Language - the markup language of web pages.

HTTP: Hypertext Transfer Protocol - the request/response protocol of the web, used by browsers and by systems calling each other’s APIs.

HTTPS: Hypertext Transfer Protocol Secure - HTTP carried over a TLS connection, which encrypts it and authenticates the server.

human task: a request for a service that a person answers. The execution environment offers it to the people of the responsible responsibility domain in the task portal, where one of them claims and completes it.

IANA: Internet Assigned Numbers Authority - the body coordinating the Internet’s global identifiers — among them media types, port numbers and, through the time-zone database, the IANA time zones.

IANA time zone: a time zone named by its identifier in the time zone database maintained by the Internet Assigned Numbers Authority, such as `Africa/Johannesburg`. It, unlike a fixed offset, accounts for daylight-saving rules.

ICT: Information and Communication Technology - encompasses all communication technologies, media, and infrastructure used to capture, process, store, transmit, and display information.

ID: Identifier - a value that names one thing uniquely within some scope, such as a template’s or an event’s ID.

identity provider: the organisation’s sign-in service, which authenticates people and services and states which groups they belong to. The tool holds no passwords of its own and relies on one speaking OIDC.

informal requirement: a requirement as originally stated, in prose, before it has been formalised into model elements. It is held as an annotation.

information hiding: the principle of hiding, behind a component’s interface, the design decisions most likely to change, so that changing them does not affect the component’s users.

integration run: the part of a unit test run in which all of an environment’s processes run together, so that their interactions are tested.

invariance constraint: a constraint which must always hold true, a state where an invariance constraint is not met should not be observable.

invariant: see invariance constraint.

inversion of control: the arrangement in which a component does not choose the components it relies on, but has them chosen and supplied by whatever runs it; in URDAD, an environment chooses who answers each service contract a process requests.

IP: Internet Protocol - the protocol addressing and routing packets between hosts on the Internet; an IP address identifies one host or network interface.

IR: Intermediate Representation - a data structure a compiler or engine translates its input into before producing its output, so that several front ends can share one back end.

ISO: International Organization for Standardization - the international body that develops and publishes standards such as ISO 8601 and ISO/IEC/IEEE 42010.

ISO 8601: ISO 8601 Date and time — Representations for information interchange - the international standard for writing dates, times and amounts of time, such as `2026-10-15T09:30:00+02:00` or the duration `PT72H`.

ISO/IEC/IEEE 42010: ISO/IEC/IEEE 42010:2022 Software, systems and enterprise — Architecture description - the international standard for describing the architecture of software, systems and enterprises. It requires a rationale to be recorded for architectural decisions.

IT: Information Technology - the computer systems, networks and software through which an organisation stores, processes and communicates information, and the function that runs them.

ITSM: IT Service Management - the discipline by which an organisation designs, delivers, operates and changes the IT services it offers, including the requesting, approval and recording of each change to them; also the class of tools, such as ServiceNow, that support it.

JMS: Jakarta Messaging (formerly Java Message Service) - the Java API for sending and receiving messages through message-oriented middleware.

JS: JavaScript - the programming language of the web browser, also run on servers by Node.js.

JSON: JavaScript Object Notation - a lightweight, text-based format for structured data. Models, exports and configurations are stored and exchanged in it.

JWKS: JSON Web Key Set - a JSON document, published by an identity provider, holding the public keys with which the signatures of the tokens it issues are verified.

JWT: JSON Web Token - a compact, signed JSON token carrying claims about a subject, such as the access and ID tokens an OIDC identity provider issues.

KV: Key-Value - a store or cache addressing each value by a key. An LLM runtime’s KV cache holds the attention keys and values computed for a prompt prefix, so a repeated prefix is not recomputed.

KYC: Know Your Customer - the regulatory obligation on financial institutions to verify the identity of their customers and assess their risk, with records they must retain. Compare AML.

lane: one of the flows into which a construct branches a process: a flow of concurrent flows or alternate flows, one outcome of a service request, or one parallel instance of a multi-instance request.

layout engine: the tool’s component, written in Rust, that lays out and draws every diagram of a model — in the browser as WASM, and on the server for generated documentation and the manuals.

LLM: Large Language Model - a machine-learning model trained on large amounts of text, able to read and produce natural language. The tool calls one, through providers an administrator configures, for its AI assistance.

main branch: the branch of a model’s git repository holding the live, approved model. It changes only when a project is activated.

MC/DC: Modified Condition/Decision Coverage - a test-coverage criterion requiring that every condition in a decision be shown, by a pair of tests differing in that condition alone, to affect the decision’s outcome independently; required by some regulatory regimes.

merge base: the most recent commit that a project's branch and the main branch have in common; the common ancestor of a three-way merge.

message correlation: the statement, on a wait for a message, of which running instance of a process the message is for: a key read from the message and the value that key must match.

message handler: the part of a service request that says what the caller does with a message the requested service declares it may send. It runs as a background flow.

microservice: a small, independently deployable service, owning its own data, that provides the capabilities of one business responsibility.

MiFID II: Markets in Financial Instruments Directive II - an EU directive that, together with Regulation (EU) No 600/2014, provides a legal framework for securities markets, investment intermediaries and trading venues.

MIME type: Multipurpose Internet Mail Extensions - the type label of a file or message body, such as `text/html` or `application/json` (also called a media type), registered with IANA.

model root: the top-level element of a URDAD model, which contains its responsibility domains; an access right granted on it applies to the whole model.

model tree: the modelling tool’s panel showing a model’s elements as a tree of responsibility domains and their contents, from which an element is selected, opened or acted on.

model verification: the tool’s on-demand, deterministic check of whether a model is internally consistent — that its references resolve and its processes discharge what their contracts require. It reports findings at a chosen verification level.

MOF: Meta-Object Facility - the OMG standard for defining metamodels, such as that of UML; EMOF is its essential subset.

monitor: one watcher of a stretch of monitored activities: a triggering event — a message, a duration or a clock — and the activities run when it fires, either *interrupting* the monitored activities or running beside them.

monitored activities: a stretch of a process watched for something happening while it runs, by one or more monitors. BPMN’s event sub-process, and its boundary events.

multi-instance request: a service request asking one service of several providers, either in parallel or in sequence.

NFS: Network File System - a protocol through which a host mounts a file system served by another over the network.

notification: a message announcing that something has happened. Any number of parties may react to it, and none is obliged to. Compare work item.

OCL: Object Constraint Language - a standard of the OMG for writing precise constraints and queries over a model. URDAD-OCL, a profile of it, is the language in which the model stores every formal specification.

OIDC: OpenID Connect - an identity layer on top of OAuth 2.0 through which an application lets an identity provider authenticate its users and learns who they are and which groups they belong to.

OMG: Object Management Group - the standards consortium that maintains, among others, BPMN, DMN, OCL and UML.

opaque identifier: a random identifier, such as `u_9f3c1a…`, that stands for a user in every permanent record. Only the user directory links it to a person, so deleting that one entry de-identifies the person everywhere; see pseudonymisation.

OpenAPI: a vendor-neutral format for describing HTTP APIs, from which documentation and client code can be generated.

optimistic concurrency control: a way of keeping concurrent changes from overwriting one another without locking: a change names the version of the data it was decided on, and is refused if the data has changed since. URDAD does this with entity versions.

OS: Operating System - the software managing a computer’s hardware and providing common services to the programs running on it.

OTLP: OpenTelemetry Protocol - the vendor-neutral protocol by which OpenTelemetry exports logs, traces and metrics to a collector or observability back end.

owning domain: the responsibility domain that directly contains an entity. In an execution environment only a realization of a service contract of that same domain may write or delete the entity’s instances; another domain asks for a change through one of the owning domain’s contracts.

PDF: Portable Document Format - a fixed-layout document format that renders the same on any device or printer.

PEM: Privacy-Enhanced Mail - the text encoding of keys and certificates as Base64 between `-----BEGIN …-----` and `-----END …-----` lines.

personal data: any information that can identify a specific person, such as names, addresses, email addresses, and even IP addresses.

phase: one of the six stages a project moves through: Initiation, Planning, Development, In Review, Approved and Active. Each phase constrains what the team may do.

phase gate: the checks the server runs before a transition into In Review or Approved — among them that the branch is not stale, that no semantic conflict exists and that no reference dangles.

PII: Personally Identifiable Information - see personal data.

pin: the model commit and configuration revision on which an environment starts new executions.

PKCE: Proof Key for Code Exchange - an extension of the OAuth 2.0 authorization-code flow that protects the code from interception, allowing a browser application, which cannot keep a secret, to sign in safely.

PKCS: Public-Key Cryptography Standards - a family of standards for public-key cryptography; PKCS #8, for instance, is a format for private keys.

PNG: Portable Network Graphics - a lossless raster image format.

POPIA: Protection of Personal Information Act - South Africa’s data-protection legislation similar to Europe’s GDPR.

ports and adapters: an architectural style, also called hexagonal architecture, in which an application’s core interacts with the outside world only through technology-neutral interfaces, its ports, each connected to a particular person, system or technology by an adapter. The tool’s integration adapters are one instance of it.

POSIX: Portable Operating System Interface - the IEEE family of standards for Unix-like operating systems, which also fixes the syntax of `cron` schedules and of time-zone strings.

post-condition: a condition which must hold true after the service has been provided. A post-condition typically specifies a required result of some of the activities performed in a process realizing the service contract.

pre-condition: a condition which must hold true for the service to be provided. If a pre-condition does not hold true, the service is to be refused.

predicate: an expression which returns true or false.

preview environment: an environment that runs a project's branch rather than the main branch, so the team can try its processes before approval. It may exist only for a project that has consented to it.

process: the business process realizing a service contract: the activities it carries out, and the control flow connecting them.

Process Owner: the project role accountable for the business process the project models — the A of RACI; without their sign-off the project cannot be approved.

project: the unit in which a model is changed. A project works on its own branch of the model, cut from the main branch, and moves through a fixed sequence of phases until it is activated or archived.

Project Manager: the project role that drives the project through its life cycle, held automatically by every user on the project’s leads list.

promotion: making a candidate an environment's current pin, automatically or by a person according to the environment’s promotion policy.

promotion gate: the evaluation an environment makes of each candidate before it can be promoted, producing findings.

provider selector: a path over the data a service request can reach, saying which provider of the requested contract is asked. Left empty, whoever provides the contract is asked.

pseudonymisation: the process of replacing direct identifiers in a dataset with artificial codes or references, such that the data can no longer be attributed to a specific individual without access to a separately held “key” or mapping table. This is less rigid than anonymisation and data protection regulations like GDPR still apply to pseudonymised data.

PSD2: Payment Services Directive 2 - an EU directive that aims to enhance the safety and security of payment services and promote innovation and competition in the market. It covers topics such as authorisation, supervision, information, rights and obligations, and access to accounts and payment systems.

published read model: the entities an owning domain lets other named responsibility domains read directly, entity by entity (an entity’s *Readable by*). A domain listed may read the entity’s stored fields that are not personal data; every other domain asks the owner’s query services.

published to: the set of responsibility domains that may request a service contract. An empty set means the service is internal to its own domain.

purge: the deletion of every record a retired environment leaves in the execution environment, its audit log included, so that nothing of it remains and its name may be used again. It cannot be undone.

query service: a service contract declared a function that answers what an owning domain keeps about one instance of its entity: *get<Entity>* by its identifying field, and *find<Entity>By<Field>* by each field marked unique. The modelling tool generates them from the entity’s view, and another domain’s condition applies one rather than reading the owner’s records.

RACI: Responsible, Accountable, Consulted, Informed - a matrix assigning, for each task or decision, who does it, who answers for it, who is consulted and who is kept informed.

RD: Responsibility Domain - short for responsibility domain.

realization: how a service contract is met. In the model, by a process or a decision; in an environment, by whatever its configuration names — a process, a decision, a person, a coded implementation, an external system or a stub.

rebase: bringing a project's branch up to date with the main branch by a three-way merge, written as a single new commit on top of main. The server does this automatically whenever main moves.

regulated project: a project whose governance profile marks it as subject to compliance requirements. It receives the compliance checklists and cannot be approved without a Compliance Officer’s sign-off.

regulatory regime: a body of regulation a project falls under, such as GDPR or DORA. Regimes are maintained by auditors and decide which checklist templates attach to a regulated project.

reporting view: a typed SQL view of one entity's current records, which an execution environment on PostgreSQL makes at each promotion for other systems to read: one column per stored field that is not personal data, read by a reporting role that can read nothing else.

request frame: how the Process View draws a service request that has handlers or steps on its default path: a rounded frame whose band along the top is the request, holding its success lane and its exception arms. Its heavy bottom edge, the _rail_, is where every path that carries on arrives and where the flow leaves; an arm that raises ends on the rail. Message lanes run outside the frame.

residue: what testing a project could not cover — a partition the generator could not decide, a check that reached no verdict, an unreachable branch, a service the integration run answered with a stand-in; each item must be disposed of on the residue checklist before the project is approved.

REST: Representational State Transfer - an architectural style for HTTP APIs in which resources are addressed by URLs and manipulated with the standard HTTP methods.

Reviewer: the project role indicating that its holder has been asked to take part in the In Review sign-off.

RFC: Request for Comments - a document in the series through which the Internet Engineering Task Force publishes Internet standards, such as RFC 7636, which defines PKCE.

SARIF: Static Analysis Results Interchange Format - an OASIS standard JSON format in which static-analysis and security-scanning tools report their findings.

SASL: Simple Authentication and Security Layer - a framework by which connection-oriented protocols such as AMQP and Kafka’s negotiate an authentication mechanism, for instance `PLAIN` or `SCRAM`.

SAST: Static Application Security Testing - the analysis of an application’s source code, without running it, for security vulnerabilities.

SCSS: Sassy CSS - the syntax of the Sass style-sheet language, a superset of CSS adding variables, nesting and mixins, compiled to CSS at build time.

SDK: Software Development Kit - a set of libraries and tools for building software against a particular platform or service, such as Temporal’s SDK for writing workers.

service request: the activity at which a process requests a service, naming the service contract it requires rather than a particular provider.

responsibility domain: the packaging unit of a URDAD model, mirroring an organisational unit or an external party. It owns service contracts, data types, processes and nested responsibility domains, and is what security policies grant access to.

retired environment: an environment whose retirement has been decided: its components are stopped, its executions cancelled and its stored data deleted, while its record and audit log are kept until it is purged.

Revert: the generic step-back transition of the project life cycle, returning a project to an earlier phase.

scheduled trigger: the statement on a service contract that its service runs on the calendar’s initiative: a cron expression and the IANA time zone it is read against.

SCIM: System for Cross-domain Identity Management - an open standard (RFC 7643, 7644) by which an identity provider provisions people and groups to an application — creating, updating, deactivating and deleting them — rather than the application asking. The tool’s directory feed may take this form.

secret reference: the name a configuration gives a credential instead of the credential itself — `ai-gateway-api-key`, `directory-client`. The tool resolves it, when the credential is needed, from an environment variable, an owner-only file or the deployment’s secret store, so no configuration file, response or log line holds the value.

secret store: where a deployment keeps the credentials its secret references name: the organisation’s vault (HashiCorp Vault, Azure Key Vault), or the tool’s own local store of owner-only files when it has none.

security policy: an administrator-defined rule granting users whose identity-provider groups match its selector an access right on a responsibility domain or a whole model.

semantic conflict: the case in which a project and the main branch have both changed the same model element since their merge base. The tool reports it for a person to reconcile rather than choosing a side.

separation of duties: SoD - the principle that no one person both produces a change and approves it. The tool enforces it at the Approve gate.

service contract: the specification of a service’s functional requirements: its request and response data structures, pre-conditions, post-conditions and the stakeholders requiring them. It is offered to its clients. A contract may specialize another.

severity: how a finding is to be read. An error says the model states something that cannot hold; a warning, that the model is silent where it could speak; information, that a default applies.

SIEM: Security Information and Event Management - the system in which an organisation’s security operations centre collects, correlates and searches security events from its applications and infrastructure, and raises alerts on them. The tool streams its own to one (security event export).

sign-off: a team member’s declaration, during In Review, that the project is acceptable and ready to be approved. Every team member must sign off before Approve.

single responsibility principle: the design principle that a component should have a single responsibility, and hence a single reason to change.

SLA: Service-Level Agreement - an agreement between a service’s provider and its consumer on the service’s measurable qualities, such as its availability and response time.

SMB: Server Message Block - the network file-sharing protocol of Windows, also served by Samba.

SMTP: Simple Mail Transfer Protocol - the protocol by which e-mail is sent and relayed between mail servers.

Solvency II: an EU directive that codifies and harmonises the EU insurance regulations covering aspects like the capital that an insurance company must hold to prevent insolvency.

specialization: the relation in which one service contract or data structure extends another, its base. A specializing contract inherits its base’s requirements, may add post-conditions and may waive, but never add, pre-conditions.

specified level: the middle verification level: each request and response says what it carries, each contract promises what it must and each field has a type, without saying how a payload is built.

SQL: Structured Query Language - the standard language for defining, querying and changing data in a relational database.

SSH: Secure Shell - a protocol for authenticated, encrypted remote login and command execution, also used to authenticate git over the network.

SSO: Single Sign-On - an arrangement in which a user signs in once with an identity provider and is then signed in to several applications.

stakeholder: a party with an interest in a service, and hence one that may place requirements on it — among them the business itself, a regulator, legislation on behalf of the population as a whole, and even a service provider that needs something in order to provide the service. In a model, a service contract's stakeholders are the parties, usually responsibility domains, that its pre-conditions and post-conditions name as requiring them. A stakeholder need not be a client. A project's governance profile lists the stakeholders of what the project delivers.

stale: the state of a project whose merge base is no longer the head of the main branch because main has moved since; the opposite is fresh.

SVG: Scalable Vector Graphics - the XML-based vector image format of the web, in which the tool renders its diagrams.

syslog: the standard way (RFC 5424) of sending log messages over the network to a collector; the transport most SIEMs accept, usually carrying CEF.

task portal: the web page on which people claim and complete the human tasks of their responsibility domains. Each task service serves it for its environment.

task service: the component of an environment that holds its human tasks and the tasks external systems claim, and serves the task portal.

TCK: Technology Compatibility Kit - a suite of tests published alongside a specification to check that an implementation conforms to it, such as the DMN TCK.

TCP: Transmission Control Protocol - the Internet protocol providing reliable, ordered byte streams between two hosts, over which HTTP and AMQP run.

Temporal: an open-source durable-execution platform that keeps the state of long-running workflows so they survive restarts and failures. The execution environment runs a model’s processes on it.

tenant: one instance of the modelling tool, serving one organisation; tenants are separate instances rather than partitions of one.

three-way merge: combining two versions of a model using the version they share, their merge base, element by element and field by field. A change made on one side only is carried through; one made on both sides is a conflict.

TLS: Transport Layer Security - the cryptographic protocol securing network connections, such as HTTP as HTTPS.

transition: a deliberate move of a project between phases: Advance, Revert, Approve or Activate. Each is recorded as a git tag, an audit-log row and a notification.

ubiquitous language: a shared language with defined concepts which is understood across business and technical role players as well as across responsibility domains. Terms map directly onto responsibility domains, data types and entities, and onto services and operations.

UI: User Interface - the part of a system through which a person operates it, such as the modelling tool’s browser client.

UML: Unified Modeling Language - the OMG's general-purpose graphical language for specifying, visualising and documenting software and business systems.

UMT: URDAD Modeling Tool - a tool enabling cross-functional teams across the organization to collaboratively develop and maintain an URDAD business model.

Undo step: a step that undoes everything its process has committed so far, by the same compensations a refusal runs, and then carries on. It is how a process takes back what it did when the outcome is not a refusal, such as a withdrawal after acceptance.

unit test run: a run of an environment's processes — typically a project’s preview — against cases generated wholly from the model: each process on its own with what it requests stubbed, then all of them together in the integration run.

URDAD: Use-Case/Responsibility Driven Analysis & Design - a systematic Domain-Driven Analysis and Design method used to develop and maintain an organization-wide business model containing service contracts, business process specifications across levels of granularity and domains of responsibility.

URDAD-Admin: the organisation-scoped role, conferred by membership of an identity-provider group, of administering the tool: creating models and libraries, defining security policies and configuring the instance.

URDAD-Auditor: the organisation-scoped role, conferred by membership of an identity-provider group, of auditing: reading every audit log and maintaining the checklist templates and regulatory regimes.

URDAD-FEEL: the profile of FEEL in which a formal specification may be read and written instead of URDAD-OCL.

URDAD-OCL: the profile of OCL in which the model stores every formal specification: pre- and post-conditions, invariances, flow conditions and loop continuation conditions.

URI: Uniform Resource Identifier - a string identifying a resource, such as an OIDC redirect URI; a URL is a URI that also locates the resource.

URL: Uniform Resource Locator - the address of a resource on the web, such as `https://urdad.example.org`.

use case: a service a stakeholder requires, specified in URDAD by a service contract and realized by a process.

UTC: Coordinated Universal Time - the world’s primary time standard, against which every time-zone offset is stated.

UUID: Universally Unique Identifier - a 128-bit identifier generated so that it is, for practical purposes, unique without any central coordination.

UX: User Experience - the overall experience of a person using a product, including how easy and pleasant it is to use.

value object: a data object used to exchange information.

verification level: what model verification asks of a model, depending on what it is for: one of three ordered levels, the descriptive, specified and executable, each asking everything the one below it does. A project’s level is set on its governance profile and can be raised, never lowered.

VM: Virtual Machine - a computer emulated in software on a physical host, running its own operating system.

waived pre-condition: a pre-condition inherited from a base contract that a specializing service contract does not impose, so that the specialization accepts requests its base would refuse.

WAL: Write-Ahead Log - a database’s log of changes, written before the changes themselves are applied, from which it recovers after a crash and through which a replica or backup is kept up to date.

WASM: WebAssembly - a portable binary instruction format that browsers execute at near-native speed; the tool’s diagram layout engine, written in Rust, runs in the browser as WASM.

work item: a message dispatching a unit of work that exactly one consumer must discharge, however many are listening. Compare notification.

worker: the component of an environment that executes its processes, polling Temporal for work, and offers the coded implementations of `automated` realizations.

workload identity: an identity a cloud platform gives a running workload — an Azure managed identity for a host, a workload identity for a Kubernetes pod — with which it obtains tokens for other services without holding any key or secret of its own.

XHTML: Extensible Hypertext Markup Language - HTML expressed as well-formed XML, as Confluence’s storage format requires.

XMI: XML Metadata Interchange - the OMG standard for exchanging models and metamodels as XML.

XML: Extensible Markup Language - a markup language for structured documents and data, nesting named elements carrying attributes.

YAML: YAML Ain’t Markup Language - a human-readable data-serialisation format, a superset of JSON, used chiefly for configuration files.

URDAD-OCL Language Specification

About this specification

Licence

1. URDAD-OCL, the constraint language

1.1. The cheat sheet

1.2. A body is an expression

1.3. What is in scope

1.4. Values

1.5. Exact and approximate numbers

1.5.1. Rounding

1.5.2. Decimal has no /

1.5.3. Scale belongs to the field, not to the type

1.6. Dates, times and amounts of time

1.6.1. Moving a date by a calendar period

1.6.2. Writing a fixed date or amount of time

1.7. Navigating

1.8. Operators, and how tightly they bind

1.9. Conditionals

1.10. Naming a value once

1.11. Working through collections

1.11.1. Which collections have an order

1.11.2. Leaving the variable out

1.12. Speaking about a population

1.12.1. Only an entity has a population

1.12.2. Naming an entity that shares its name

1.12.3. What an entity’s fields are

1.13. Speaking about the state before

1.13.1. Only in a post-condition

1.13.2. Only on an entity’s state

1.13.3. Which instance "the same" is

1.13.4. Trying it, and running it

1.14. Asking for a service

1.14.1. Requiring that a function answers

1.15. now() and caller

1.15.1. The model’s time zone

1.16. randomInteger and randomReal

1.17. Comments

1.18. The grammar

1.19. What is deliberately left out

1.20. When a constraint is not formalisable

Appendix A: The standard library

A.1. What it contains

A.1.1. Decimal and FloatingPointNumber are both numbers, and are not alike

A.2. Choosing a date or time type

A.3. Choosing a duration type

A.3.1. Resolving an amount to a date

A.4. It is read-only

A.5. Upgrading

Acronyms and glossary

1.5.2. `Decimal` has no `/`

1.15. `now()` and `caller`

1.16. `randomInteger` and `randomReal`

A.1.1. `Decimal` and `FloatingPointNumber` are both numbers, and are not alike