Ontology File Formats¶

General¶

The registry for ITS ontologies (RITSO) intends to capture ontologies for ITS documented in widely accepted file formats that can be managed with a modern version control system and that can easily be translated into a website, including diagrams showing key references. The following technologies have been selected to achieve this management:

GitHub: for version control
Web Ontology Language (OWL): for specifying the semantics of the ontology
W3C Turtle (*.ttl) file format: for formally specifying the core semantics of OWL content.
SHACL: for defining constraints
The python scripts developed by this registry effort: to convert the *.ttl files into markdown files and diagrams to provide a user-friendly website.
GraphViz: to convert the text description of graphics into actual graphics
Material for MkDocs: to convert the source files into a website

GitHub Repository Organization¶

A separate ITS repository is maintained within GitHub for each ontology namespace.

Ontology repository names follow the pattern of ontology-domain-topic-v#, where # is replaced with the major version number and domain is replaced with one of the following:

its: For ontologies developed and managed by this project, in which case, topic is replaced by a unique topic area name.
cdm: For ontologies of the city data model, in which case, topic is replaced by part#, with the # indicating the part number of ISO/IEC 5087.
import: For other imported ontologies, in which case, topic is replaced by the preferred prefix for the ontology.

Imported Ontologies¶

ITS ontologies are built upon several widely-referenced ontologies. The ITS ontologies import the official versions of these ontologies, as needed (e.g. PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>). However, to provide a coherent and all-encompassing web-based explantation of the ITS ontology, the imported ontologies are replicated in the RITSO to enable visualization and linking between concepts. The replicated ontology is often revised from the official version to:

translate to *.ttl so that the web content can be easily generated,
tweaked to follow the RITSO formatting policies, which often requires annotation properties to be re-characterized so that the generated website displays the intended information (e.g., an rdfs:comment can be changed to a skos:definition).

RITSO Formatting Policies¶

Namespaces¶

ITS ontologies should only declare prefixes used within the document, which often includes the following:

: (i.e., the default) typically the ontology namespace
dcterms: http://purl.org/dc/terms/
owl: http://www.w3.org/2002/07/owl#
dash: http://datashapes.org/dash# (when used)
rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs: http://www.w3.org/2000/01/rdf-schema#
skos: http://www.w3.org/2004/02/skos/core#
vann: http://purl.org/vocab/vann/
xsd: http://www.w3.org/2001/XMLSchema#
cdm1: https://w3id.org/citydata/part1/v1/
cdm2: https://w3id.org/citydata/part2/v1/
cdm3: https://w3id.org/citydata/part3/v1/
ITS-specific ontologies

In addition, ITS ontologies shall declare a namespace prefix for each ontology referenced, even if the prefix is not used in the ontology file. Declaring the prefix allows the diagrams that are generated by the python scripts to shorten the IRI to just the prefix to make diagrams more readable. The prefixes shall use the preferred prefix for the referenced ontology (when declared) and it does not cause a conflict. Ideally, ITS ontologies should only reference ontologies already included in the RITSO.

Ontology Annotations¶

The RITSO recommends using the following annotations, in the order shown, when describing ontologies.

Annotation	Rationale and Usage Notes
### Ontology Definition ###
`dcterms:title`	The name of the resource.
`skos:definition`	Definition; only once per language. If not present, script uses dcterms:description as fallback.
`vann:preferredNamespaceUri`	Although shown elsewhere, this is needed for some tools to pair with the preferred prefix.
`vann:preferredNamespacePrefix`	The preferred prefix to use when referring to items in this resource.
`dcterms:license`	Identifies the legal usage terms; CC-BY 4.0 is recommended.
`its-core:draft`	Indicates whether this is a draft (i.e. whether the website should include the draft logo at the top of each page).
### Provenance Information ###
`dcterms:creator`	Primary author; can be more than one.
`dcterms:created`	The date of the last full release of the ontology file.
`dcterms:modified`	The date on which this file was last modified.
### Additional provenance information for main ontology file ###
`owl:versionInfo`	The semantic version number of the ontology.
`owl:versionIRI`	The version IRI of the ontology.
`owl:priorVersion`	The version IRI of the prior ontology version.
### Imports ###
`owl:imports`	For each imported ontology (that is not imported by one of the prior imports).

While the RITSO allows the use of any defined annotation, the following are recommended as preferred optional annotations to be used as appropriate for ontologies.

Annotation	Rationale and Usage Notes
`dcterms:bibliographicCitation`	Provides the textual identifier of the document that formalizes or explains this ontology.
`dcterms:contributor`	Contributor to the ontology for which credit is to be provided but not a primary author.
`dcterms:issued`	Year that the associated document (e.g. standard) was formally issued.
`rdfs:seeAlso`	Provides the URI of the document that formalizes or explains this ontology.
`skos:changeNote`	Provides a description of the updates made since the last version

Annotations for Ontology Elements¶

The RITSO recommends using the following annotations when describing ontology elements (e.g., classes and properties).

Annotation	Rationale and Usage Notes
`skos:definition`	Normative definition of the entity. Use no more than once per language.

The RITSO recommends using the following annotations when describing ontology elements (e.g., classes and properties), as needed.

Annotation	Rationale and Usage Notes
`dash:abstract`	Indicates that the class is not intended for direct instantiation.
`dcterms:created`	For creation date; if different than the ontology creation date.
`dcterms:isReplacedBy`	Identifies a new element that replaces a historic element; repeatable if needed. Inverse of the above
`dcterms:modified`	Date of an update; pair with repeatable `skos:changeNote`
`dcterms:replaces`	Identifies a historic ontological element that is replaced by a new ontological element; repeatable if needed.
`its-core:pii`	Boolean (true for personally identifiable information)
`owl:deprecated`	Boolean (true for deprecated/obsolete)
`rdfs:label`	Allows language-specific labels that can change with backward compatibility
`skos:changeNote`	Provides a description of the update date; pair with `dcterms:modified`
`skos:example`	Illustrative example; can use multiples.
`skos:note`	Informative details as needed; can use multiples.