Touchstone
Reference

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_LITERAL

Names 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 foundReference kind
the rule's context Conceptthe individual under test
another Conceptvalid only as the argument of individuals(…)
an «Attribute» or a «Relation»a navigation step
an EnumerationLiterala literal value
a «MaturityRule»a verdict, that rule's predicate applied to the receiver
anything else, or nothinga 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.

constrainedElementContext Concept
a «Concept»that Concept
an «Attribute» or a «Relation»the Concept owning it
none, several, or another kind of elementnone; the rule is malformed

Chains

A chain denotes a set of values, elements or Attribute values, built left to right from its start.

StartDenotes
the context Conceptthe one individual under test
itthe member bound by the innermost enclosing braces
individuals(C)every individual of the Concept C, through Ontology.individuals
StepDenotes, over the incoming set S
.a, a an Attributethe union of attributeValues(x, a) over x ∈ S
.r, r a Relationthe 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.

FormHolds 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 alonethat 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 wthe 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

LiteralWrittenCompared to an Attribute value
number2, 0.5numerically, when the value is a Number or a String that parses as one
booleantrue, falseby value, when the value is a Boolean or the strings true/false
string"Departure"by string equality
enumerationan anchor to an EnumerationLiteralby 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.

RuleExpression
a Scenario has at least one ExchangeScenario.inverse(scenario).isNotEmpty()
an Exchange has an integrity levelExchange.integrityLevel.isNotEmpty()
an Exchange requires a capability at one end at leastExchange.requiredOfSource.union(Exchange.requiredOfTarget).isNotEmpty()
an Exchange's source Role belongs to its ScenarioExchange.source.scenario.subsetOf(Exchange.scenario)
an Exchange's source and target differExchange.source.disjointFrom(Exchange.target)
a Role is an end of some ExchangeRole.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.

FailureDetail logged
zero or several constrained elements, or one of the wrong kindthe 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 includedthe token where parsing stopped, and its offset
a hyperlink that resolves to nothingthe id it carries, and its offset
a hyperlink that names an element that is no ontology element, no literal and no rulethe element it names, and its offset
a . step or inverse(…) whose hyperlink names anything but an Attribute or a Relationits offset
inverse(…) of a property no Concept ownsits offset
a chain starting from an anchor to a Concept other than the context Conceptthat 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 ruleits offset
individuals(…) naming anything but a Conceptits offset
an anchor inside contains(…) that names no EnumerationLiteralits offset
an anchor standing alone as a verdict that names no ruleits offset
it outside bracesits offset
a rule anchor applied, inside braces, to the members of an Attribute, whatever its type, an Enumeration-typed Attribute includedthe anchor's offset
a referenced rule that constrains no Concept, or whose predicate the engine cannot buildthe referenced rule's name
a reference cycle among rulesthe 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.

On this page