Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Overview

The IRI structure of the IOF references the OWL documents providing a versioned and not-versioned form. The latter form will always refer to the latest released version of the documents. For the IRI syntax, please refer to RFC 3987 from The Internet Engineering Task Force (IETF).

This document provides the normative requirements for all IRIs created in the IOF for consistency and usability. An English language class and property naming scheme was selected after considering a numerical identity scheme to facilitate the use of the ontologies. The following sections define the rules for constructing the IRI and version IRI per OWL 2 specifications (reference below).

The following rules MUST be followed when reviewing this document, these are taken from IETF https://datatracker.ietf.org/doc/html/rfc2119 :

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in https://datatracker.ietf.org/doc/html/rfc2119

  1. MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

  2. MUST NOT: This phrase, or the phrase "SHALL NOT", mean that the definition is an absolute prohibition of the specification.

  3. SHOULD: This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course.

  4. SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

  5. MAY: This word, or the adjective "OPTIONAL", mean that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)

Protocol and Authority

All IOF IRIs must MUST be resolvable and refer to a resource that can be retrieved from the internet. The form of the IRI must MUST specify the protocol as HTTPS and the authority must MUST be a domain administered and owned by the IOF or its parent organization. The IOF must MUST choose a single authority for all ontologies released by the IOF.

The authority must MUST be a domain administered and owned by the IOF or its parent organization. The IOF must MUST choose a single authority for all ontologies released by the IOF. The authority must MUST be www.industrialontologies.org unless it is not possible due to technical reasons. Otherwise, the authority may begin with an alternative such as www.industrialontologies.org or onto.industrialontologies.org.

Path Root

The root of the path must MUST be /ontology. This provides the ability to have documentation and other supporting resources referenced in alternate root directories, such as /documentation or /references. The IOF must MUST designate each root resource name for a specified use.

Topic Area

The topic areas MUST form the second portion of the IRI. The topic areas are MUST be all lower case with no separation or punctuation between words. All acronyms must MUST be spelled out, except for words defined in the dictionary like radar (RADAR) always given in lowercase. The following are examples of topic areas:

...

IRI and Version IRI

IOF ontologies must MUST provide an IRI and version IRI. The version IRI must MUST use the release date of the version in YYYYMMDD form, such as 20210601 for June 1, 2021. When a versioned IRI is formed, the date must MUST appear after the topic. In the following examples, the sub-topic area is given to illustrate the placement of the version (see next fort sub-topic). The IRI will MUST always reference the latest released IRIversion of the ontology.

  • Versioned IRI: https://www.industrialontologies.org/ontology/supplychain/20210621/meta

  • Non-Versioned IRI: https://www.industrialontologies.org/ontology/supplychain/meta

...

Each ontology may have an ontology IRI, which is used to identify an ontology. If an ontology has an ontology IRI, the ontology may additionally have a version IRI, which is used to identify the version of the ontology. The version IRI may be, but need not be, equal to the ontology IRI. An ontology without an ontology IRI must notMUST NOT contain a version IRI.

Sub-Topic

When specified, a sub-topic must MUST appear after the version date in a versioned IRI or after the topic in a non-versioned IRI. In this case, metadata associated with the supplychain model is placed in the meta location. The sub-topic must MUST be lowercase with no separation or punctuation between words.

The meta sub-topic area must MUST be used for annotations. For example:

...

Following the topic and sub-topic resource locations, the ontology module name is MUST be given without extension as follows:

  • https://www.industrialontologies.org/ontology/foundation/meta/AnnotationVocabulary/

The module name must MUST be in Upper Camel Case, each word capitalized with no separation between words. All acronyms must MUST be spelled out except when in the dictionary, like RADAR.

The file module name must not MUST NOT have any extensions in the IRI. The following parts of the IRI, class and property names, are MUST be separated from the file name by a forward slash /.

Class Names

Class names must MUST be given in Upper Camel Case, each word capitalized, and no separation or punctuation between words. As with the file module names, no acronyms are permitted MUST NOT occur except those in the dictionary, such as RADAR.

...

Property Names (Relations)

All property names must MUST be in lower Camel Case, the first word lower case and each subsequent word capitalized with no separation or punctuation between words.

...

All object property names must MUST be verbs or a verb phrase. For example:

...

Data Properties

A data property must MUST be a verb phrase starting with has. Examples:

...

Must follow property capitalization rules and must MUST be placed in the meta sub-topic area, as follows.

  • .../ontology/foundation/20210611/meta/AnnotationVocabulary/usageNote

  • .../ontology/foundation/20210611/meta/AnnotationVocabulary/adaptedFrom

...

Old notes for reference…

IRI Structural Rules in the following order

  • Authority: www.industrialontologies.org

  • Top: /ontology

  • Topic areas are lowercase with no punctuation or separation:

    • /supplychain

    • /foundation

  • Versioned IRI:

    • Release date after highest level topic area

    • Date format: YYYYMMDD

    • /supplychain/20210601

    • /foundation/20210601/meta

  • File-name Upper Camel Case with no punctuation: AnnotationVocabulary

    • Uppercase first letter of each word, no separation

    • All acronyms are spelled out

      • Exceptions like RADAR, words appearing in the dictionary

  • Class and properties separated from path with a /

    • /ontology/foundation/meta/AnnotationVocabulary/usageNote

  • Class name Upper Camel Case:

    • Uppercase first letter of each word, no separation

    • All acronyms are spelled out

      • Exceptions like RADAR, words appearing in the dictionary

  • Object property Lower Camel Case:

    • Lowercase first letter, uppercase each following word

    • All property names must MUST be verb or verb phrase

    • hasParticipant

  • Data properties and annotation names Lower Camel Case

    • Lowercase first letter, uppercase each following word

    • Verb phrase starting with has

    • hasTag

    • hasDateValue

  • Annotation properties

    • Lowercase first letter, uppercase each following word

    • usageNote

    • adaptedFrom

  • Versioned and unversioned forms must MUST be provided.

Examples

  • Unversioned: /ontology/foundation/meta/AnnotationVocabulary/usageNote

  • Versioned: /ontology/foundation/20210601/meta/AnnotationVocabulary/usageNote

  • /ontology/supplychain/

...