Touchstone
How-to guides

Declare a maturity rule

A maturity rule states one thing every individual of a Concept must satisfy, or one ratio worth reading. This page declares one, places it, and writes it in the Touchstone expression language, the expression tag the engine evaluates.

Choose the kind

The rule saysCreate
a complete model satisfies this for every individual, such as "every Function is allocated to a System Component"a Modeling Rule
the ratio is a finding to act on, such as "the share of Capabilities covered by a System Function"an Engineering Rule

A modeling rule aggregates into the completeness of its Concept and of the Objectives that justify it. An engineering rule is read on its own and never aggregates.

Choose what it constrains

Set constrainedElement to the element the rule is about:

The rule is aboutConstrain
the individuals of a Concept, such as "a Function has a name"the Concept
a value, such as "a Requirement's text is set"the Attribute
a link, such as "a Function's performs is filled"the Relation

The context of evaluation, the "for each x in C", is the constrained Concept or the Concept owning the constrained Attribute or Relation. Constraining the Attribute or the Relation rather than the Concept makes the rule roll up to the Objective that justifies that Attribute or Relation, which is the precise trace.

Place it

Own the rule by its context Concept, or by the module's «OntologyPackage» when several rules are managed together. Either owner is accepted; the Concept's modelingRules and engineeringRules list the rule in both cases.

Write the rule

The rule's specification states it in English, as a sentence a reviewer can agree or disagree with. The rule's expression tag states the same rule in the Touchstone expression language, over the ontology's names and never over metaclasses or stereotypes.

  1. Open the rule's specification window and edit expression with the HTML editor.
  2. Insert a hyperlink to the rule's Concept (Insert hyperlink → Element), then type . and insert a hyperlink to one of its Attributes or Relations, and so on along the navigation.
  3. Close with an assertion, such as .isNotEmpty(), and save.

For "every Function is performed by exactly one System Component", on a rule constraining Function:

Function.performedBy.isSingle()

where Function and performedBy are hyperlinks. The anchor to the rule's own Concept stands for the individual under test; individuals(System Component) names every individual of another Concept. The expression language lists every operator.

A rule states what should hold. Write "a required Capability is provided by some Asset", and read the Capabilities that break it in failing; do not write the condition that fires.

Implement it in the tool only when needed

Leave expression empty when the rule states something the language cannot, such as a check on a diagram or a comparison between numbers. Create a Maturity Rule Implementation in the «ImplementationPackage», point its validationRule at a validation rule of the tool implementing the check, in any language the tool runs, and draw «Implements» to the rule. The engine runs that validation rule on each individual of the rule's Concept; an individual passes when the validation rule reports nothing on it.

Constrain the validation rule to the metaclasses of the individuals it receives: a validation rule that constrains another metaclass is handed nothing, flags nobody, and the rule reads as fully satisfied. Write the check so that it never throws: the tool contains the exception, reports nothing on the individual, and the individual passes.

Read the result

Open the rule's specification window: passing and failing list the individuals by verdict, and score is the passing over all. A rule whose Concept has no individuals shows no score. A rule whose expression the engine cannot evaluate shows nothing, and one line under Touchstone in the log says why. Each Concept, Attribute and Relation shows completeness, the mean of score over its modeling rules, and each Objective the mean over what it justifies, unless its status is Postponed or Rejected. Engineering rules keep their own score and enter no completeness.

On this page