Skip to content

RITSO Naming Conventions

The naming conventions for the ITS ontology are designed to:

  • Keep a single logical ontology IRI per ITS topic area (e.g. your existing https://w3id.org/itsdata/location/v1/) while allowing the ontology to be split across many files (e.g. for Alert C location, OpenLR, GDF, etc.).
  • Make modular files easy for automation scripts to detect and convert into website “Patterns” (each sub-file becomes its own documented pattern page).
  • Follow established Semantic Web best practices (W3C, ontology-design-patterns.org, Financial Industry Business Ontology, etc.) for readability, consistency, and tool compatibility.

1. Overall Ontology IRI and Namespace (Single IRI)

  • Ontology IRI (the owl:Ontology resource): All ITS ontologies shall follow the pattern: https://w3id.org/itsdata/<topic>/v#/<SubModuleName>, where:

    • the base IRI of https://w3id.org/itsdata/ is a redirect configured to take browsers to the GitHub Pages site that contains the explanation of the ontology while taking ontology tools directly to the ttl files.
    • <topic> is the topic area of the ontology (e.g., location, time, regulation)
    • v# is the major version number of the ontology
    • <SubModuleName> is the name of a submodule within a larger topic area (e.g., AlertCLocationPattern within the location topic area); the main module within the topic area does not use a SubModuleName.

  • Namespace prefix: its-<topic>:, where <topic> is as defined above. All submodules within the same topic area use the same base ontology IRI and prefix.

  • Versioning strategy:

    • The ontology IRI only changes when a non-backwards-compatible change is made, which should be rare based on other guidelines.
    • Each main ontology file within a topic area includes owl:versionInfo, owl:versionIRI, and owl:priorVersion. The major version is included in the ontology IRI while the minor version and patch number are shown as a release in the version IRI (e.g. r0.2). the versionInfo combines the three into a normal semantic version (e.g. v1.0.2).
    • All files are under version control within GitHub with GitHub releases created when each revision is approved.

This keeps each topic area under one ontology while files remain independently loadable.

2. Directory Structure

A separate GitHub repository is maintained for each ontology (i.e. topic area). This allows for better management of changes using a potentially different set of domain experts within each topic area. It also allows for the modularization of version control so that a major change in one topic area does not reset the entire ITS ontology.

The GitHub repository is used to generate a website with the assistance of Material for MkDocs, which imposes some of its own directory structure rules. Importantly, the files that are to be posted on the website should be stored in the docs directory of the repository. This includes all *.ttl files for each project. The overall directory structure should be based on the current template for RITSO projects, as shown below.

Directory layout example

ontology-its-location-v1/
├── .github/
│   ├── workflows/
│   │   ├── auto_assign.yml
│   │   ├── triage_label.yml
│   │   ├── update_release.yml
│   ├── CODEOWNERS
│   ├── PULL_REQUEST_TEMPLATE.md
├── .vscode/
│   ├── settings.json
├── docs/
│   ├── diagrams/                        # directory for generated diagrams based on ttl files
│   ├── javascripts/
│   │   ├── tablesort.js                 # script that enables alphabetical table sorting by column
│   │   └── ...
│   ├── stylesheets/
│   │   ├── extra.css                    # style sheet for website
│   │   ├── pdf.css                      # style sheet for printing to PDF
│   │   └── ...
│   ├── alert-c-pattern.ttl              # Sub module that imports Core.ttl
│   ├── alert-c-shacl.ttl                # Validation rules for Alert C Location Pattern
│   ├── core.ttl                         # imported by all (most) submodules
│   ├── master.ttl                       # directly or indirectly imports Core.ttl and all patterns of the repository
│   ├── open-lr-pattern.ttl              # Sub module that imports Core.ttl
│   ├── open-lr-shacl.ttl                # Validation rules for Open LR Pattern
│   └── *.md                             # markdown files used to generate the website; generated by script for each concept in ttl files
├── .gitignore
├── .markdownlint.json
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE.md
├── README.md
├── mkdocs.yml
│   ...

3. File Naming Conventions (Critical for Website Automation)

When naming files, use kebab-case (mixed-case with hyphens). If a topic area has submodules, each submodule file shall end with its type (e.g. -pattern.ttl or -shacl.ttl), with the exception of the core.ttl file and the master.ttl file. The core.ttl file is used to define any general-purpose concepts for the topic area (e.g. the TopicAreaThing class), which needs to be imported by every submodule within the topic area. The master.ttl file (directly or indirectly) imports the core and all of the submodules into a single master ontology.

This structure allows other ontology files to easily import the entire topic area or to import a selected subset of a topic area(e.g. to prevent overloading reasoning engines with unnecessary details).

File Type Example Name Purpose
Main topic area ontology master.ttl Aggregates all submodules into single ontology
Core for topic area core.ttl Imported by all pattern submodules in topic area; defines organizational concepts for topic area
Reusable SHACL library shacl.ttl If needed, most reusable rules should be in its-core-sh
Topic area module (OWL) alert-c-location-pattern.ttl Defines basic semantics for submodule concepts
Topic area module (SHACL) alert-c-location-shacl.ttl Defines value validation rules for submodule concepts

The -pattern.ttl and -shacl.ttl ending is used by the scripts to identify type of file so that they can more easily process the files to produce the website.

4. Internal Concept Naming (Classes, Properties, Shapes)

ITS ontology files shall using the following naming conventions for ontology concepts:

Concept Naming Convention Example Rationale
Classes UpperCamelCase Person, PostalAddress Standard in OWL (Protégé, FIBO, etc.)
Object/Data Properties lowerCamelCase hasName, hasOid Reads naturally (e.g. Person hasName "Alice"); prevents complications with overlapping IRIs with only capitalization differences (e.g. Person owl:onProperty name owl:allValuesFrom Name)
Annotation properties camelCase prefLabel, definition Matches SKOS/RDFS
NodeShapes UpperCamelCase + Shape PersonShape, AddressShape Clear and reusable
PropertyShapes UpperCamelCase + Shape ExactlyOneShape, OidShape As in your coreSHACL.ttl
SHACL messages Full English sentence sh:message "Exactly one value required." User-friendly validation reports

Additional rules:

  • Always use singular for classes (Person not People).
  • Define separate prefixes only when needed to parse complexity and facilitate version control (e.g. its-sh:OidShape).
  • Never use spaces or underscores.
  • Avoid numbers.

5. SHACL-Specific Naming and Structure

  • Keep reusable shapes in file and namespace that reflects their reusability. For example, shapes that are reusable across ITS and potentially other domains should be stored in a namespace separate from its-core, while shapes that are reusable only across ITS should use the its-core namespace. .

  • In domain shape files, reference the reusable ones instead of duplicating:

    its-core:PersonShape a sh:NodeShape ;
    sh:targetClass its-core:Person ;
    sh:property [ sh:path its-core:hasOid ; sh:node its-sh:OidShape ] ;
    sh:property [ sh:path its-core:hasName ; sh:node its-sh:ExactlyOneShape ; sh:datatype xsd:string ] .

  • Use rdfs:label on every shape.

6. Modularity & Imports

Use the main ontology IRI in the master.ttl file of an ontology and for all concepts in all submodules of the ontology (except for the ontology concept of the submodules). 

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix its-location: <https://w3id.org/itsdata/location/v1/> .

its-core: a owl:Ontology ;
    rdfs:label "ITS Topic Area Master Ontology" ;
    owl:imports 
        <https://w3id.org/itsdata/location/v1/AlertCPattern/> ,
        # which imports https://w3id.org/itsdata/location/v1/Core/
        <https://w3id.org/itsdata/location/v1/patterns/OpenLRPattern/> ,
        <https://w3id.org/itsdata/location/v1/AlertCSHACL/> ;
        <https://w3id.org/itsdata/location/v1/OpenLRSHACL/> ;
    owl:versionInfo "2026-03-30" .
        owl:versionIRI <https://w3id.org/itsdata/location/v1/r0.3> .

Extend the IRI of the ontology concept declared within each submodule to reflect the name of that submodule. This allows defining appropriate metadata for each submodule while also being able to consolidate all submodules into a single master ontology.

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix its-location: <https://w3id.org/itsdata/location/v1/> .

its-core:AlertCPattern/ a owl:Ontology ;
    rdfs:label "ITS Sub-Module Ontology" ;
    owl:imports 
        <https://w3id.org/itsdata/location/v1/Core/> ,
    owl:versionInfo "2026-03-30" .

6. Website Automation Support

This structure allows scripts to:

  1. Easily find every *-pattern.ttl and *-shacl.ttl file.
  2. Generate one HTML page per pattern and concept and entitle it based on the rdfs:label.
  3. Use standard tools for processing.
  4. Include cross-links between patterns (via rdfs:seeAlso or owl:imports).

These conventions are consistent, human-readable, machine-friendly, and future-proof.