• construct: refers to an OWL class, object property, or data property
  OWL Reference

• entity (object): item that is perceivable or conceivable
  Note 1 to entry: The terms ‘entity’ and ‘object’ are catch-all terms analogous to ‘something’. In terminology circles
  [ISO/IEC 21838-1:2021(E)]

• particular: individual entity
  Note 1 to entry: In contrast to classes or types, particulars are not exemplified or instantiated by further entities
  Note 2 to entry: only relevant to first-order logic
  [ISO/IEC 21838-1:2021(E)]

• instance: particular that instantiates some universal
  Note 1 to entry: two types of particular, one XX is an instance of a universal and the other is not
  Note 2 to entry: only relevant to first-order logic
  [ISO/IEC 21838-1:2021(E)]

• individual: instance of an OWL class
  OWL Reference

• primitive: expression for which no non-circular definition can be provided
  Note 1 to entry: construct lacking necessary or sufficient conditions
  [ISO 21838-2:2021 (E)]
  Note 2 to entry: definition refers to a first-order logic definition or OWL definition

• universal: item that is perceivable or conceivable that has indefinitely many instances
  Note 1 to entry: only relevant to first-order logic
  [ISO 21838-2:2021 (E)]

• axiom: statement that is asserted as true but which is not derivable from other statements
  Note 1 to entry: Axioms may be formulated as natural language sentences or as formulae in a formal language. In the OWL community, ‘Axiom’ is used to refer to statements that say what is true in the domain that are ‘basic’ in the sense that they are not inferred from other statements.

  [ISO/IEC 21838-1:2021(E)]
  Note 2 to entry: A statement may be a formula of first-order logic or a sentence of natural language or of the semi-formal counterpart
  
  

The IOF AnnotationVocabulary (AV) OWL file (AnnotationVocabulary) is the normative source for IOF annotation properties. It includes a superset of the annotation properties discussed in this document along with the metadata about them. This document’s purpose is to provide the requirements and instructions for authors of IOF ontologies. The AV should be imported into IOF ontologies under development to make these annotation properties available; however, since the IOF Core imports IOF AV, using AV requires no explicit owl:imports statement.

All approved ontologies MUST adhere to the following annotation requirements for all constructs.

The following rules MUST be followed when using this document; these are taken from IETF RFC 2119 (simplified):

1. MUST: This word means that the definition is an absolute requirement of the specification.

2. MUST NOT: This phrase means that the definition is an absolute prohibition of the specification.

3. SHOULD: This word means 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 means 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 means that an item is truly optional. One user 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.

• MUST provide non-versioned ontology IRI (See: https://oagi.atlassian.net/wiki/spaces/IOF/pages/4532142135 )

• When released, MUST provide version IRI (owl:VersionIRI)(See: https://oagi.atlassian.net/wiki/spaces/IOF/pages/4532142135 )

• MUST provide label

• MUST provide title

• MUST provide abstract

• MUST provide copyright

• MUST provide license

• MUST provide maturity

• MUST provide a versionInfo

• MUST provide changeNotes for each release.

• MUST provide label

• MUST provide natural language definition

• If the is primitive annotation is set to true:

  • MUST provide a primitiveRationale

  • MAY provide first-order language axioms and semi-formal natural language axioms

• If the is primitive annotation is set to false or not specified:

  • MUST provide first-order logic definition

  • MUST provide semi-formal natural language definition

• MAY provide first-order language axioms and semi-formal natural language axioms

• SHOULD provide example

In cases where a text annotation is needed, an American English language version of that annotation is required and MUST use the American English language tag ( xml:lang="en-US"). Spelling in American English annotations MUST conform to an American dictionary, such as Merriam-Webster. Additional annotations covering the same material but expressed in a different natural language are allowed as long as they incorporate the proper language tag. Text annotations that include a language tag have a default datatype of rdf:langString. By definition from the RDFS 1.1 specification, one MUST NOT include an explicit datatype when adding an annotation.

The following is an example of the Ontology annotations from Core. Annotations in the “Active Ontology” tab in Protégé.

• label - rdfs:label

• Each construct MUST have at least one natural language label, as follows:

  • Exactly one American English language label MUST be provided and language tagged

  • Labels MUST be unique across all IOF ontologies and SHOULD be unique across all imported non-IOF ontologies in a given natural language

  • Labels for other natural languages MAY be provided, but if so they must be language tagged

  • Data property MUST be a verb phrase starting with is for boolean (true/false) or has for any other data type.

    • Example: is transferable

  • Data property SHOULD end with value

    • Example: has numeric value

  • label text MUST be given in lowercase with spaces between words

    • Exception: proper names MUST use initial upper-case

    • Exception: Words like DNA that are capitalized in the Oxford English Dictionary (Home: OED ) MUST remain in uppercase

  • Acronyms MUST NOT be used for label values

    • Exception: Words like RADAR and DNA with dictionary definitions MAY be used and will be considered by the architecture TG

    • Acronyms are shortened alternative labels that are composed of a letter from each word of a longer signifier for the notion

    • Acronyms that are not found in dictionaries may be provided as an alternative label for a resource using the acronym annotation property described below

• Note - The IOF annotation vocabulary does not include an annotation property for preferred label. Instead, an annotation directly asserted as an rdfs:label in IOF OWL content is treated as the preferred label.

• Alternative (non-preferred) labels MAY also be provided for a construct using the following annotations

  • iof-av:synonym annotation MUST be used for alternative labels that are not abbreviations

  • iof-av:abbreviation annotation MUST be used for shortened alternative labels other than acronyms

  • iof-av:acronym annotation MUST be used for shortened alternative labels that are composed of a letter from each word of the preferred label (aka acronyms) and that are not found in a dictionary

    • Acronyms that are found in the dictionary MAY be used as the rdfs:label (preferred label) for the notion (as noted in the exception above)

• natural language definition – iof-av:naturalLanguageDefinition

  • Definition: plain text for industry practitioner understanding

  • Exactly one natural language definition MUST be given for any construct

    • Note: this definition MUST be present for both primitive and non-primitive constructs

    • State the source as a class, property, or other. Check if the serializer removes annotations on annotations. Open Issue regarding how the serializer does this.

    • No nested annotations in the serializer and moved to the bottom of the file. Should fix the serializer. See: ARCH-86

  • The definition MUST adhere to ISO 704 rules and requirements for terminology

    • For non-primitive constructs, the natural language definition MUST NOT be circular

    • For primitive constructs, the natural language definition SHOULD NOT be circular

    • The definition MUST be substitutable in a sentence where the term appears

      • We MAY reconsider this as a requirement if there is no way to express it as a formal substitutable definition. There MUST be a rationale, expressed as an explanatory note, for why this is the case and the rationale MUST be agreed to by the Architecture TG.

    • The definition MUST NOT begin with an article (The, A or An).

    • One SHOULD avoid jargon and domain-specific terminology

  • It MUST be understandable by a practitioner in the industrial domain

    • It MUST NOT use specialized ontological terminology

      • Examples: perdurant, endurant, continuant, etc.

    • Ontological construct label MUST be provided in parenthesis

      • Example: role ​⁠held by (bearer of) ​⁠a material entity when it is a proper part of another material entity or is planned to be a proper part of another material entity

    • It MUST NOT use special formatting for properties or classes referenced in the definition

      • MUST NOT use upper camel case capitalization

      • MUST NOT use apostrophes to contain terms as a parenthetical

        • Examples: must not be as follows: ‘part-of’, ‘Information Content Entity', InformationContentEntity

    • It MUST NOT contain acronyms or abbreviations

      • Acronyms MAY be accepted if they appear in the dictionary and are widely used in conversation. Use of such an acronym use MUST be approved by the Architecture TG.

  • If the definition is taken from another source, dcterms:source or one of its sub-properties MUST cite the original reference. See dcterms:source in the Source Annotations section below.

  • Examples:

    • shipment preparation process: planned process in which some material entities are prepared to be transported together to a receiver’s location

    • postal address: designation of a location (site) to which mail is delivered

• elucidation -- iof-av:elucidation

  • elucidation MUST NOT be used and is deprecated.

• is primitive – iof-av:isPrimitive

  • Definition: boolean flag indicating that necessary and sufficient conditions are not provided at this time

  • is primitive MUST be present if the term does not have necessary and sufficient conditions and the value of the annotation MUST be set to true (w3c boolean)

  • MUST only apply to classes

  • Otherwise, if necessary and sufficient conditions are present, then the annotation MAY be provided and the value MUST be set to false

  • is primitive MUST default to set to false

  • If possible, terms SHOULD have necessary and sufficient conditions

  • Note: the term may not always remain primitive if necessary and sufficient conditions can be defined in a later version

  • Example:

    • person: true

    • shipment preparation process: true

• primitive rationale – iof-av:primitiveRationale

  • Definition: reason why the necessary and sufficient conditions were not or could not be provided at this time

  • MUST only apply to classes

  • When is primitive is set to true , the primitive rationale MUST be provided

  • The primitive rationale MUST explain why necessary and sufficient conditions are not possible

  • The rationale SHOULD indicate what is missing if additional work is required to define necessary and sufficient conditions

  • Example:

    • person: insufficient constructs to create necessary and sufficient conditions

    • shipment preparation process: shipment preparation process often includes at least one picking, internal movement, packaging, marking, weighing, or loading process, but since those processes are not added to the ontology yet, it is not possible to generate necessary and sufficient conditions at this time for this entity

• The following rules MUST be followed when using variables in a first-order logic axiom (formalization) or definition and semi-formal natural language axiom or definition

  • MUST NOT nest variables in single quotes

    • Examples: 'instance i' ‘, 'continuant c’

  • MUST use lower case variable for particular (individual or instance) of a universal

  • Multiple first-order logic axioms MUST be considered as a combined set using the ∧ (conjunction operator).

    • The axioms can be rewritten using the conjunction operator and remain logically consistent

  • Variable SHOULD use the first letter of a construct’s label when possible

  • Variable MUST only be one letter

  • MUST append numeric suffixes (x1, x2, etc.) OR one or more primes (x', x'', etc.) for multiple instances of the same construct

  • MUST reserve the use of t, t', etc., for temporal regions; expressions such as 'for all times' SHOULD be interpreted as meaning ‘for all temporal regions’

  • MUST only use r, r', s, s', etc., for spatial and spatiotemporal regions

  • MUST only the use of R, R', etc. for relations

  • MUST NOT use the character a or A

• The following rules MUST be followed in a first-order logic axiom (formalization) or definition

  • References to classes and properties MUST use the label. The label MUST be transformed where the spaces are removed and classes labels MUST use UpperCamelCase and properties MUST use lowerCamelCase.