-
-
Notifications
You must be signed in to change notification settings - Fork 0
Golden Tests
This document explains the Golden Test framework used by uml2semantics-python to ensure deterministic and reproducible ontology generation.
Golden Tests are especially important for standards-based ontologies, such as ISO 20022, where stability and version control are critical.
Golden tests validate:
- Deterministic OWL output across runs
- Consistent choice semantics
- Stable datatype facet handling
- Enumeration value generation
- Correct annotation attachment
- Proper prefix management
- No unexpected changes caused by refactoring or dependency updates
They serve as a contract between the TSV specification and the OWL generator.
A typical folder layout:
tests/
golden/
case-001-basic/
Classes.tsv
Attributes.tsv
expected.ttl
case-002-datatypes/
Classes.tsv
Attributes.tsv
Datatypes.tsv
expected.ttl
case-003-enumerations/
Enumerations.tsv
EnumerationNamedValues.tsv
expected.ttl
case-004-choice-exclusive/
Classes.tsv
expected.ttl
case-005-full-model/
Classes.tsv
Attributes.tsv
Datatypes.tsv
Enumerations.tsv
EnumerationNamedValues.tsv
AnnotationProperties.tsv
Annotations.tsv
expected.ttl
Each case includes:
- A self-contained set of TSV inputs
- An
expected.ttloutput - Optional annotations TSV files
Golden tests rely on canonical Turtle so that diffs reflect meaningful changes only.
The canonicaliser enforces:
- Alphabetical prefix ordering
- Alphabetical triple ordering
- Deterministic blank node ordering
- Consistent indentation
- Stable union/disjoint representation
This prevents false test failures caused by:
- OS differences
- Python library serialisation differences
- Metadata or timestamp variance
Each golden test follows a standard pipeline:
Test runner reads .tsv files in the case folder.
The converter constructs the ontology graph.
Turtle is normalised using the canonicaliser.
If equal → pass
If not equal → fail (with diff)
Example diff:
--- expected.ttl
+++ actual.ttl
@@ -12,7 +12,7 @@
iso:GBP a iso:CurrencyCode .
-iso:EUR a iso:CurrencyCode .
+iso:EUR a iso:CurrencyCode ; rdfs:label "Euro" .
Curie Name ChoiceOf ChoiceSemantics
ex:Choice PartyIdentifierChoice LEIId|BICId exclusive
ex:LEIId LEIId
ex:BICId BICId
ex:PartyIdentifierChoice rdfs:subClassOf [
owl:unionOf ( ex:LEIId ex:BICId )
] .
ex:PartyIdentifierChoice owl:disjointWith ex:LEIId .
ex:PartyIdentifierChoice owl:disjointWith ex:BICId .
Tests confirm:
- Correct union construction
- Correct disjoint axioms
- Correct prefix usage
- Deterministic ordering
Curie Name
iso:CurrencyCode CurrencyCode
Enumeration Curie Name
CurrencyCode iso:GBP GBP
CurrencyCode iso:EUR EUR
iso:GBP a iso:CurrencyCode .
iso:EUR a iso:CurrencyCode .
Golden test checks:
- Enumeration class is declared
- Individuals generated correctly
- No unintended disjoint axioms
- Proper CURIE resolution
Curie Name BaseDatatype Pattern MinLength MaxLength
iso:LEI20 LEI20 xsd:string [A-Z0-9]{20} 20 20
iso:LEI20 owl:equivalentClass [
owl:onDatatype xsd:string ;
owl:withRestrictions (
[ xsd:pattern "[A-Z0-9]{20}" ]
[ xsd:minLength "20"^^xsd:integer ]
[ xsd:maxLength "20"^^xsd:integer ]
)
] .
Golden test verifies:
- Facet rendering
- Proper XSD integer encoding
- Deterministic ordering
To create a new golden test:
- Create a folder under
tests/golden/case-XXX-name/ - Add relevant TSV inputs
- Run
uml2semanticsto generateactual.ttl - Canonicalise using the canonicaliser script
- Rename canonical output to
expected.ttl - Commit the case folder
The test suite will automatically discover and run it.
graph TD
A[TSV Inputs] --> B[uml2semantics Generator]
B --> C[Turtle Output]
C --> D[Canonicaliser]
D --> E[Expected.ttl]
E --> F[Diff Engine]
F --> G[Test Result]
- Keep TSV inputs alphabetically ordered
- Use stable CURIE prefixes
- Add separate golden cases per feature (choice, enum, facets, annotations)
- Update expected.ttl only for intentional improvements
- Use CI to run golden tests automatically
- Back to Examples
- Back to TSV-Specification
- Continue to CLI-Usage
- Return to Home