The expression language
A «MaturityRule» carries its rule in the expression tag, as HTML with element hyperlinks, written
in the tool's HTML editor. The expression denotes one verdict per individual of the rule's context
Concept: true when the rule holds for that individual, false when it does not. Every reference in it
is a hyperlink to a Concept, an Attribute, a Relation, an EnumerationLiteral or another rule, and the
engine resolves each one by the id in its mdel:// href. A rename changes the label a reader sees
and nothing the engine reads.
Grammar
rule := verdict
verdict := 'not' verdict
| verdict ('and' | 'or' | 'implies') verdict
| '(' verdict ')'
| chain -- whose last step is an assertion,
| -- or a lone anchor naming a rule
chain := start ('.' step)*
start := CONTEXT_CONCEPT | 'it' | 'individuals' '(' CONCEPT ')'
step := ATTRIBUTE | RELATION
| 'inverse' '(' (ATTRIBUTE | RELATION) ')'
| 'union' '(' chain ')' | 'intersect' '(' chain ')' | 'minus' '(' chain ')'
| 'filter' lambda | 'all' lambda | 'any' lambda | 'none' lambda
| 'isEmpty' '(' ')' | 'isNotEmpty' '(' ')' | 'isSingle' '(' ')'
| 'hasSize' '(' NUMBER ')' | 'hasAtLeast' '(' NUMBER ')' | 'hasAtMost' '(' NUMBER ')'
| 'subsetOf' '(' chain ')' | 'disjointFrom' '(' chain ')'
| 'contains' '(' (chain | literal) ')'
lambda := '{' verdict '}'
literal := NUMBER | 'true' | 'false' | STRING | ENUMERATION_LITERALNames in capitals are reference tokens. Precedence among connectives is not, then and, then
or, then implies, all left-associative except not; parentheses override it. Whitespace between
tokens is free, and the HTML editor's line breaks are whitespace.
What a reference may point at
The engine resolves each id in the open project, used projects included, and classifies the element it finds.
| Element found | Reference kind |
|---|---|
| the rule's context Concept | the individual under test |
| another Concept | valid only as the argument of individuals(…) |
| an «Attribute» or a «Relation» | a navigation step |
| an EnumerationLiteral | a literal value |
| a «MaturityRule» | a verdict, that rule's predicate applied to the receiver |
| anything else, or nothing | a malformed reference |
The engine performs no name resolution. Every reference is an identifier, so the language has no scoping rules and no ambiguity.
The context Concept
A rule constrains exactly one element, and that element decides which individuals the rule is evaluated on.
constrainedElement | Context Concept |
|---|---|
| a «Concept» | that Concept |
| an «Attribute» or a «Relation» | the Concept owning it |
| none, several, or another kind of element | none; the rule is malformed |
Chains
A chain denotes a set of values, elements or Attribute values, built left to right from its start.
| Start | Denotes |
|---|---|
| the context Concept | the one individual under test |
it | the member bound by the innermost enclosing braces |
individuals(C) | every individual of the Concept C, through Ontology.individuals |
| Step | Denotes, over the incoming set S |
|---|---|
.a, a an Attribute | the union of attributeValues(x, a) over x ∈ S |
.r, r a Relation | the union of relationTargets(x, r) over x ∈ S |
.inverse(p) | the individuals y of the Concept owning p such that p evaluated on y meets S |
.union(t), .intersect(t), .minus(t) | set algebra between S and the set t denotes |
.filter { v } | the members x ∈ S for which v holds with it = x |
A Relation step applied to an element that is not an individual of the Relation's Concept yields
nothing, as relationTargets does, and the language performs no type checking beyond the reference
kinds above. A Relation keeps only the targets that are individuals of its type Concept, a rule on a
general Concept sees the individuals of its specializations, and every value is a set.
Verdicts
A verdict denotes true or false.
| Form | Holds when |
|---|---|
S.isEmpty(), S.isNotEmpty(), S.isSingle() | S has no member, at least one, exactly one |
S.hasSize(n), S.hasAtLeast(n), S.hasAtMost(n) | the size of S equals, meets, does not exceed n |
S.subsetOf(t) | every member of S is a member of t |
S.disjointFrom(t) | no member of S is a member of t |
S.contains(t) | every member of t is a member of S |
S.contains(literal) | some member of S equals the literal |
S.all { v }, S.any { v }, S.none { v } | v holds for every, at least one, no member of S, with it bound to the member |
| a «MaturityRule» anchor standing alone | that rule's predicate holds for it inside braces, and for the individual under test at the top level of an expression |
not v, v and w, v or w, v implies w | the usual truth tables |
all over an empty set holds and any over an empty set fails, as in Kotlin. A rule that needs the
outer member inside nested braces is written as two rules; the language offers no named lambda
parameter.
Literals
| Literal | Written | Compared to an Attribute value |
|---|---|---|
| number | 2, 0.5 | numerically, when the value is a Number or a String that parses as one |
| boolean | true, false | by value, when the value is a Boolean or the strings true/false |
| string | "Departure" | by string equality |
| enumeration | an anchor to an EnumerationLiteral | by identity when the value is an EnumerationLiteral, as an Enumeration-typed Attribute yields; by name when the value is a String |
A literal is legal only as the argument of contains and of the three size assertions.
hasSize, hasAtLeast and hasAtMost take a whole number, so hasSize(0.5) is a syntax error.
A rule states what should hold
A rule states what should hold. failing is then the list of findings and score reads the same way
for every rule: the fraction of individuals in order. A rule phrased as what fires, "a capability
required by some exchange and provided by no asset", is rewritten as its positive form, "a capability
required by some exchange is provided by some asset", and its findings appear in failing.
Examples
Bold names stand for hyperlinks; the leading one is the context Concept.
| Rule | Expression |
|---|---|
| a Scenario has at least one Exchange | Scenario.inverse(scenario).isNotEmpty() |
| an Exchange has an integrity level | Exchange.integrityLevel.isNotEmpty() |
| an Exchange requires a capability at one end at least | Exchange.requiredOfSource.union(Exchange.requiredOfTarget).isNotEmpty() |
| an Exchange's source Role belongs to its Scenario | Exchange.source.scenario.subsetOf(Exchange.scenario) |
| an Exchange's source and target differ | Exchange.source.disjointFrom(Exchange.target) |
| a Role is an end of some Exchange | Role.inverse(source).union(Role.inverse(target)).isNotEmpty() |
| an Exchange is covered (engineering) | Exchange.requiredOfSource.subsetOf(Exchange.source.filledBy.provides) and Exchange.requiredOfTarget.subsetOf(Exchange.target.filledBy.provides) |
| a required Capability is provided by someone (engineering) | Capability.inverse(requiredOfSource).union(Capability.inverse(requiredOfTarget)).isNotEmpty() implies Capability.inverse(provides).isNotEmpty() |
When a rule has no verdicts
The engine resolves the expression of a rule in full before it evaluates the first individual, so a
Concept with no individuals still surfaces every failure below except one. The exception is the row
for a referenced rule that constrains no Concept or whose predicate the engine cannot build: resolution
does not enter a referenced rule, so that failure surfaces only when an individual reaches the
reference. The engine reports each failure once per evaluation, as one WARN line under the
Touchstone log category naming the rule, and the rule then shows no passing, no failing and no
score. The Touchstone Maturity validation suite reports these defects as rules M1 to M7, listed in
the validation rules.
| Failure | Detail logged |
|---|---|
| zero or several constrained elements, or one of the wrong kind | the three kinds a rule may constrain |
an empty expression and no reachable «MaturityRuleImplementation» | the two conditions |
| a syntax error, a verdict that ends without an assertion included | the token where parsing stopped, and its offset |
| a hyperlink that resolves to nothing | the id it carries, and its offset |
| a hyperlink that names an element that is no ontology element, no literal and no rule | the element it names, and its offset |
a . step or inverse(…) whose hyperlink names anything but an Attribute or a Relation | its offset |
inverse(…) of a property no Concept owns | its offset |
| a chain starting from an anchor to a Concept other than the context Concept | that Concept's name, its offset, and individuals(…) as the form that reads a Concept's extent |
| a chain starting from an anchor to an Attribute, a Relation, a literal or a rule | its offset |
individuals(…) naming anything but a Concept | its offset |
an anchor inside contains(…) that names no EnumerationLiteral | its offset |
| an anchor standing alone as a verdict that names no rule | its offset |
it outside braces | its offset |
| a rule anchor applied, inside braces, to the members of an Attribute, whatever its type, an Enumeration-typed Attribute included | the anchor's offset |
| a referenced rule that constrains no Concept, or whose predicate the engine cannot build | the referenced rule's name |
| a reference cycle among rules | the rules in the cycle, outermost first |
A second failure of the same rule in the same call is dropped, so one call writes one line per rule. A failure inside a navigation step stays inside the ontology runtime, which logs it and yields nothing for that individual; the rule's verdicts stand. A validation rule behind a «MaturityRuleImplementation» that throws is contained by the tool, which reports nothing, so the individual passes and no line is written. Nothing in the model records a failure.
The ontology carries no multiplicity
An «Attribute» or a «Relation» keeps the multiplicity the tool gives a property by default. A bound
such as 1..* is a rule, written as hasAtLeast(1) or isNotEmpty(), and it lives on a
«ModelingRule» like any other statement. The engine reads no multiplicity, so an ontology author who
encodes a rule in a bound encodes it where nothing enforces it.