Obligations and findings

An obligation is the unit of conformance. An implementation of the specification demonstrates conformance one obligation at a time.

The obligation identifier

The name of an obligation is the stable identifier across implementations. Two implementations report the same name for the same departure, in any language and in any wording of their own message.

An invariant carries the name the specification gives it, such as AConceptHasOnePreferredLabelPerLanguage or AMappingJoinsTwoDifferentSchemes.

Every other obligation carries the identifier that the Allium plan of specs/ubiquitous-language.allium gives it. The forms are entity-fields.Concept, entity-optional.Mapping.note, entity-relationship.Atlas.links, enum-comparable.ConceptStatus, value-equality.Label, derived.Concept.has_a_definition, config-default.minimum_definitions_per_concept and surface-exposure.Glossary.

The specification declares 36 obligations. The conformance kit holds 74 cases: 38 conformant inputs and 36 non-conformant inputs.

Named invariants

Invariant	Condition
AConceptHasOnePreferredLabelPerLanguage	Each pair of distinct entries of one prefLabels set differs in language
AConceptCarriesADefinition	The count of definitions reaches minimumDefinitionsPerConcept. The count is checked and not the wording
PreferredLabelsAreUniqueWithinAScheme	No two concepts of one scheme carry a preferred label with the same language and the same text. Across two schemes the collision passes
ConceptIdsAreUniqueWithinAScheme	No two concepts of one scheme carry the same id. Across two schemes the same id passes
ABoundedContextNamesOneGlossary	No two glossaries carry the same boundedContext. The check runs over every glossary an atlas resolves
AHiddenLabelCarriesAReason	The reason of each hidden label has a length of at least one character. An empty text is a departure
AStandardTermNamesItsStandard	A concept with origin: standard carries a standardRef that is not null
AnLlmCoinageIsConfirmedOnlyByARecordedDecision	A concept with origin: llm and status: confirmed carries a historyNote that is not null. Every other pair of origin and status passes
AMappingJoinsTwoDifferentSchemes	For each link of an atlas, the scheme of from differs from the scheme of to
BroaderStaysWithinOneScheme	A broader that is not null names a concept of the same scheme
RelatedStaysWithinOneScheme	Every member of related names a concept of the same scheme

The finding contract

A validator produces a verdict and a set of findings. A finding carries three compared fields.

Field	Content
obligation	The name of the obligation that fired
document	The file that the path is read against
path	The place of the departure inside that document

A path starts at the root of one document. $ is the document itself. $.concepts[2].prefLabels is the prefLabels of the third concept, counted from zero. $.links[0].from is the from of the first link of the atlas.

Findings compare as a set. Order is not part of the expectation. No fourth field is compared, so the wording of a message is free.

A conformant input yields a verdict of conformant: true and an empty finding set.

case: AHiddenLabelCarriesAReason/a-rejected-word-carries-its-reason
obligation: AHiddenLabelCarriesAReason
inputs:
  - sales.glossary.yaml
conformant: true
findings: []

A non-conformant input yields one finding per departure.

case: AHiddenLabelCarriesAReason/a-rejected-word-without-a-reason
obligation: AHiddenLabelCarriesAReason
inputs:
  - sales.glossary.yaml
conformant: false
findings:
  - obligation: AHiddenLabelCarriesAReason
    document: sales.glossary.yaml
    path: $.concepts[2].hiddenLabels[0]

The directory name of a case is the obligation the case exercises. The obligation of a finding is the obligation that fired. The two differ where one obligation is observable only through another. A case under config-default.minimum_definitions_per_concept raises the minimum and then reports AConceptCarriesADefinition.

Obligations that no document expresses

Two obligations carry no case directory. The manifest lists them under notExpressibleAsDocuments.

surface-actor.Glossary asks that an implementation offers the reader no way to write: no create, no update and no delete. No input document witnesses the absence of a writer. An implementation checks this against its own public interface.

TheAtlasMarksTheSearchRoot covers the walk up from the working directory, the rule that the nearest atlas wins, the stop at the home directory or at the root of the filesystem, and the error on two atlas files in one directory. All of that is filesystem behavior, settled before a document is read. An implementation checks it against a filesystem it builds itself.

One clause of the second obligation does appear in the cases: many cases hold a glossary and no atlas, and expect a verdict.