Skip to content

Alignment in practice

The field, what validates it, and what reaches RDF. Read this once you have picked an alignment, or when a class is not exporting what you expected.

The field

One field per class, in <class>.ont.yml:

# illustrative — not a run
class: marriage
label: Marriage
foundational_type:
  ontology: ufo
  type: relator
  iri: https://purl.org/nemo/gufo#Relator
description: |
  The bond two people enter at a wedding, and which the records attest indirectly.

Three keys, and only two are required.

KeyRequiredWhat it is
ontologyyesbfo or ufo. Nothing else validates.
typeyesThe type in that ontology — relator, continuant, role.
irinoThe identifier that type has in BFO or gUFO.

Omit the whole field for none alignment. An empty or partial one is worse than an absent one. The corpus then asserts an alignment nothing can resolve.

Why the IRI is optional

iri is where skos:exactMatch comes from, and a corpus that has not looked one up should still be able to state its alignment.

The alternative was deriving the IRI from type with a BFO and gUFO term table compiled into yidam. That table would be a second copy of somebody else's vocabulary. It would be wrong the moment either project revised it, and would refuse terms a corpus is right to use. So the corpus supplies the IRI or does not, and the alignment exports either way.

For the same reason type is not checked against a term list. ontology is checked because it is two values and they are ours.

What validates it

yidam schema publishes the shape, so an editor underlines a malformed field as it is typed. Two lint checks gate on it:

CheckFails on
foundational-type-malformedAn ontology: outside bfo|ufo, an empty type:, or an iri: that is not absolute
foundational-field-misspelledbfo_type:, ufo_type: or bfo_anchor: — three spellings that are read by nothing

The second one exists because those three spellings were real, and for a long time nothing said so. bootstrap.md told authors to write bfo_type: in prose while its own template wrote foundational_type:. The RDF export read a third field, bfo_anchor:, that nothing produced. None of it went red. The class body accepts undeclared keys, so a wrong field name simply sat there. And no corpus this repository ships declares an alignment, so the path was never exercised. Issue #613 has the history.

If you are carrying one of those fields, the check names the repair. A bfo_anchor: URI moves to foundational_type.iri.

What reaches RDF

yidam export-rdf emits Turtle and JSON-LD with identical triple sets. A class carrying an alignment gets:

# illustrative — not a run
yidam:marriage a owl:Class ;
    rdfs:label "marriage" ;
    yidam:foundationalOntology "ufo" ;
    yidam:foundationalType "relator" ;
    skos:exactMatch <https://purl.org/nemo/gufo#Relator> .

foundationalOntology and foundationalType are emitted whenever the field is present. skos:exactMatch is emitted only when iri: is. So an alignment without an IRI still exports the fact that the corpus made the decision. That is what a consumer needs to know before asking anything else.

A class with no foundational_type: emits none of these. That is the none answer, and it is silent by design.

Changing your mind

Adding, removing or changing an alignment is an edit to each .ont.yml. No instance moves, no edge changes, and no index rebuild is required — the field is read at export time.

What does change is the RDF a consumer has already fetched. A corpus published as a .yiz bundle carries its classes, so a downstream repository that installed yours sees the old alignment until it updates. That is the ordinary versioning story, and sharing a derivation covers it.

Why align at allChoosing an alignment
What a class declaresWhat an ontology is here
The full file schemasInformation architecture
The export surfaceDomain computer