TSV Specification – Full Detailed Reference

This document provides a complete technical specification of all TSV files used by uml2semantics.
Each TSV controls part of the UML → OWL2 transformation pipeline.
All files must be UTF-8 encoded, tab‑separated, and include headers.

1. Overview of the TSV Ecosystem

uml2semantics loads the following TSV files:

1. Classes.tsv
2. Enumerations.tsv (optional)
3. EnumerationNamedValues.tsv (optional)
4. Datatypes.tsv (optional)
5. Attributes.tsv
6. AnnotationProperties.tsv (optional)
7. Annotations.tsv (optional)

Resolution and validation happen during ontology build; classes, datatypes, and enumerations must exist before attributes and annotations can reference them.

2. Classes.tsv – Class Declarations and ISO 20022 Choice Patterns

Defines all OWL classes in the model, including inheritance and exclusive choice logic.

2.1 Required Columns

2.2 Choice Logic Interpretation

When ChoiceOf is populated:

• ChoiceClass ⊑ ChoiceOptionA ⊔ ChoiceOptionB ⊔ ...
• If ChoiceSemantics = exclusive:
• The choice class and members are pairwise disjoint (via owl:AllDisjointClasses)
• If ChoiceSemantics is empty:
• No exclusivity constraints are applied

Example Row

Curie    Name              ParentNames  Definition      ChoiceOf                               ChoiceSemantics
iso:QtyChoice  Quantity6Choice   Amount    ISO pattern    FinInstrmQtyChoice|OrigAndCurrQty      exclusive

3. Attributes.tsv – Object & Datatype Properties, Multiplicities, Facets

Defines UML attributes mapped to OWL object or datatype properties.

3.1 Required Columns

3.2 Facet Columns (inline datatype restrictions)

These generate owl:DatatypeRestriction:

Example Inline Facet Attribute

Class    Name         ClassEnumOrPrimitiveType  MinMultiplicity  MaxMultiplicity  Pattern  MinLength  MaxLength
Account  OwnerId      xsd:string                1                1                [A-Z0-9]+  16         16

Produces:

OwnerId ⊑ DatatypeRestriction( xsd:string xsd:minLength "16"^^xsd:int xsd:maxLength "16"^^xsd:int )

4. Datatypes.tsv – Named Datatypes with Facet Restrictions

Defines reusable datatype restrictions.

4.1 Required Columns

4.2 Facet Columns

Same as in Attributes.tsv.

Example

Curie   Name     BaseDatatype  Pattern        MinLength  MaxLength
iso:LEI LEI20    xsd:string    [A-Z0-9]{20}   20         20

Generates:

Datatype: LEI20
  EquivalentTo: 
    xsd:string[pattern "[A-Z0-9]{20}", minLength 20, maxLength 20]

5. Enumerations.tsv – Enumeration Classes

Defines OWL classes whose instances are individuals declared in EnumerationNamedValues.tsv.

Columns

6. EnumerationNamedValues.tsv – Enumeration Individuals

Defines actual named values.

Columns

Example

Enumeration   Curie    Name   Definition
CurrencyCode  iso:GBP  GBP    Pound Sterling

Generates:

Individual: GBP
  Types: CurrencyCode

7. AnnotationProperties.tsv – Annotation Vocabulary

Defines custom annotation properties.

Columns

8. Annotations.tsv – Annotation Assertions

Assigns metadata to classes, properties, datatypes, individuals.

Columns

Example

iso:Account  rdfs:label  "Account Details"  en  xsd:string

9. Validation Rules (Implemented)

• Missing or duplicate identifiers (CURIE/Name) for classes, enumerations, datatypes, attributes, and annotation properties raise errors.
• Attribute multiplicities must be non-negative and consistent (min ≤ max).
• Attribute types must resolve to a class, enumeration, named datatype, or xsd: primitive.
• Prefixes used in CURIEs must be declared; missing prefixes are logged as warnings.
• Choice members that do not resolve to a class or attribute are logged as warnings.

Additional constraints (e.g. regex validity, numeric facet ranges) are recommended but are not currently enforced by the converter.

10. Relationship Between TSV Files

graph TD
  C[Classes.tsv] --> A[Attributes.tsv]
  C --> E[Enumerations.tsv]
  E --> V[EnumerationNamedValues.tsv]
  D[Datatypes.tsv] --> A
  AP[AnnotationProperties.tsv] --> AN[Annotations.tsv]
  A --> OWL[Ontology Output]

11. Next Steps

Continue to: - [[Choice-Patterns]] for exclusive union modelling
- [[Datatypes-and-Facets]] for datatype restriction logic
- [[CLI-Usage]] for full command reference

Return to [[Home]].