OML v2

Note that this is a Living Document; its contents is frequently being edited.

Summary

The openCAESAR project has recently released OML v2, with improvements to OML’s textual syntax, graphical notation, and API. In this page, we highlight the notable changes from v1. For context, please view the original OML v2 Proposal outlined back in Feb 2023.

Syntax Changes

In v1 ontologies, only a subset of details could be specified on a ref to a <Member>. In OML v2, (almost) all details can be specified on a ref. This widens significantly the ability to split OML statements about a member in different ontologies, which better supports the ability to federate and extend descriptions. This also means that (most of) the previously required details of members have been relaxed to be optional.

For example:
```
ref relation entity R1 [
   from C1 // this adds C1 as another source of R1
]

ref scalar property name [
   domain Pet // this adds Pet as another domain of name
   functional // this adds the functional flag
]
```
In v2 ontologies, an annotation have now specify a value that is either a literal (as before) or an IRI of a member (new capability).

For example:
```
@rdfs:label "Aggregates" // literal
@rdfs:seeAlso base:Contains // reference to base:Contains
relation entity Aggregtes
```
In v2 vocabularies, the specialization axiom symbol :> has changed into < to better align with the semantics that a subclass is a subset of its superclass.
In v2 vocabularies (since v2.3), the restricts statement syntax does not have property kind (scalar property, structured property, and relation) keywords any longer (e.g., restricts all performs to mission:Function).

In v2 vocabularies, it has been clarified that the restricts statements, which used to be placed with other details about a term between [], actually belong to the specialization axiom. This has caused the general term syntax to change from:

 Term ::= <keyword> NAME (`<` Specializations)? (`[` Details? Restrictions? `]`)?
 Specializations ::= REF (`,` REF)*

to:

 Term ::= <keyword> NAME (`[` Details `]`)? (`<` Specializations)?
 Specializations ::= (REF (`,` REF)*)? (`[` Restriction*`]`)?

For example:

aspect A1 [
key id // detail
] < A2

concept C1 [
  oneOf c11, c12, c13 // detail
] < C2, C3 [
  restricts all p1 to "abc"
]

concept C2 < C3, C4, C5 [
  restricts all p1 to "abc"
  restricts p2 to 2.0
]

relation entity R1 [ 
  from C1     // detail
  to A1       // detail
  forward r1  // detail
] < R2 [
  restricts some p2 to 2.0
]

scalar S1 [
  oneOf "abc", "xyz" // detail
] < S2

scalar property p1 [
  domain D1   // detail
  range R1    // detail
] < p2

In v2 vocabularies, a new equivalence axiom (=) has been added to the term syntax in addition to the specialization axiom (<). While a specialization axiom says that a term is a sub of another term, an equivalence axiom says that the term is both a sub and a super of another term. The general term’s syntax is now:

Term ::= <keyword> NAME (`[` Details `]`)? (`<` Specializations)? (`=` Equivalences)?
Specializations ::= (REF (`,` REF)*)? (`[` Restriction*`]`)?
Equivalences ::= Equivalence (`,` Equivalance)*

In the case of classifiers, a single equivalence has the syntax:

Equivalence ::= (REF (`&` REF)*)? (`[` Restriction*`]`)  // equals the intersection of other named terms and restrictions

In the case of scalars and properties, a single equivalence has the syntax:

Equivalence ::= REF // equals another named term

For example:

// A pizza that has a spicy topping is classified as a spicy pizza
concept SpicyPizza = Pizza [
   restricts some hasTopping to SpicyTopping
]
// A woman that is married is classified as a married woman
aspect MarriedWoman = Married & Woman
// A string that has a particular pattern is an SSN
scalar ssn = xsd:string [
  pattern "[0-9]{3}-[0-9]{2}-[0-9]{4}"
]
// Saying food is spicy is the same as saying that it is hot and vice versa
scalar property isSpicy [
   domain Food
   range xsd:boolean
   functional
] = isHot

In v2 vocabularies, a concept or scalar enumeration can now be specified consistently with a oneOf statement in the the details between []. This also removes the special type enumerated scalar in v1 and retains only the scalar type.

For enumerated literals, the syntax has changed from:

EnumeratedScalar ::= enumerated scalar NAME [
  Literal (, Literal)*
]

Scalar ::= scalar NAME [
  (oneOf Literal (, Literal)*)?
  // other details ...
]

For enumerated concept instances, the syntax has changed from:

Concept ::= concept NAME [
  (enumerates REF (, REF)*)?
  // other details ...
]

Concept ::= concept NAME [
  (oneOf REF (, REF)*)?
  // other details ...
]

For example:

scalar RGB [
  oneOf "Red", "Green", "Blue" // literals
]

concept RockyPlanet [
  oneOf Mercury, Venus, Earth, Mars // instances
]

In v2 vocabularies, it has been clarified that scalar facets (e.g., length, pattern, etc.) do not belong to the scalar’s details between [], but rather to the new scalar equivalence axiom. This allows such facets to be specified on a per equivalence basis.

For example:
```
scalar ssn = xsd:string [
  pattern "[0-9]{3}-[0-9]{2}-[0-9]{4}"
]

scalar positiveReal = xsd:real [
  minInclusive 0
], xsd:real [
  maxInclusive 9999
]
```
In v2 vocabularies, a new (unreified) relation can now be specified as an alternative to a (refieid) relation entity. This supports cases where instances of the relation are not foreseen in descriptions. It also helps avoid synthesizing relation entity names when mapping oml vocabularies from other formats that do not natively support reified relations. The syntax of an unreified relation resembles closely that of a relation entity (except for the forward statement). The syntax of an unreieifed relation is (partially) as follows:
```
Relation ::= relation NAME ([
 from REF
 to REF
 (reverse NAME)? // notice there is no forward NAME statement
 // other details in a relation entity
])? // specialization and equivalence axioms to other relations
```
For example:
```
relation isHusbandOf [
  from Man
  to Woman
  reverse isWifeOf
]

relation entity IsTeacherOf [
 from Teacher
 to Student
 forward isTeacherOf
 reverse isStudentOf
]
```
In v2 vocabularies, an unreified relation can now be referenced anywhere other relations (like forward, reverse) can. This includes restriction statements (restricts REL_REF), specialization statements (< REL_REF), equivalence statements (= REL_REF), rule predicates (REL_REF(ARG1, ARG2)), assertion axioms (REL_REF TARGET_REF), etc. Also, a relation is a kind of property in v2, whereas a relation entity is a kind of type. Therefore, a relation cannot be a supertype of a relation entity (and vice versa). But, an unreified relation can have any relation (including forward and reverse) as a super relstion.
In v2 vocabularies, the from and to statements (of relations), as well as the domain and range statements (of properties), can now specify more than one type as a value (both on the original definition or on a ref of the member)`. The semantics of having multiple types is equivalent to the intersection of those types. This makes a value asserted as a subject (or object) of a property (or relation) to be classified by all the types at once.

For example:
```
// In a vocabulary
relation isBoxedIn [
   from Red, Ball
   to Box
]
relation isPetOf [
   from Cat, Dog
   to Person
]
// In a description
instance Ball1 [
  isBoxedIn Box1 // this will cause Ball1 to be classified by both Red and Ball
]
instance Tom [
   isPetOf Jack // this will cause Tom to be classified by both Cat and Dog (which could be disjoined leding to a contradiction)
]
```
In v2 vocabularies, the symbol ^ separating rule predicates has changed to & to better reflect the AND semantics between predicates.

In v2 vocabularies, a new term builtIn has been added to define a builtin function that can be referenced by a rule antecedant predicate. A standard set of builtins has been added to the core-vocabularies library in the <ttp://www.w3.org/2003/11/swrlb#> vocabulary. Note that a custom builtIn function cannot be specified yet.

 // in the <ttp://www.w3.org/2003/11/swrlb#> vocabulary
 @rdfs:comment "Satisfied iff the first argument is equal to the string resulting from the concatenation of the strings the second argument through the last argument."
 builtin stringConcat

 // in a vocabulary
 rule FullName [
       firstName(?x, ?first) & 
       lastName(?x, ?last) &
       swrlb:stringConcat(?full, ?first, " ", ?last) // builtins can only be referenced in antecedent
       -> fullName(?x, ?full)
 ]

In v2 descriptions, the symbol ci for a concept instance has now changed to the more readable instance. Also, such instances can also now be typed by both Concepts and Aspects (whereas only Concepts were the only valid types in v1).
In v2 descriptions, the symbol ri for a relation instance has now changed to the more readable relation instance. Also, such instances can also now be typed by both Relation Entities and Aspects (whereas only Relation Entities were the only valid types in v1).

API Changes

The above changes to the textual syntax have induced some changes to the OML Java API. Other changes were done done to simplify the API. The following is a list of main changes to the OML API:

Merged (and removed) class AnnotatedElement into class IdentifiedElement (the impact is that Import statements can no longer be annotated).
Collapsed the Import class hierarchy into a single Import class with an enumeration kind that has literals: extends, uses, and includes.
Renamed class Feature to Property, made the latter the supertype of classes AnnotatedProperty and SemanticProperty, and made class Relation extend from SemanticProperty.
Collapsed the Restriction class hierarchy into 3 subclasses restricting range, cardinality, or value of a property, and made class Entity has a single collection for restrictions.
Removed class LinkAssertion (replaced by PropertyValueAssertion) and made class NamedInstance has a single collection of property value assertions.
Moved the types collection (now of concrete type TypeAssertion) from both classes ConceptInstance and RelationInstance into their superclass NamedInstance.
Made class RelationEntityPredicate a subclass of both UniaryPredicate and BinaryPredicate.
Removed the Reference class hierarchy entirely and merged it into the Member class hierarchy (a member can have either a name or a ref to another member).

Migration Guide

Migrating OML v1 textual syntax to that of v2 can be done using the following process:

Replace the symbol :> by <.
Replace the symbol ci by instance .
Replace the symbol ri by relation instance .
Replace the syntax keyword NAME < REFS [Details] by the syntax keyword NAME [Details] < REFs.
Replace the syntax keyword NAME [Restrictions] by the syntax keyword NAME < [Restrictions].
Replace the syntax keyword NAME < REFS [Details Restrictions] by the syntax keyword NAME [Details] < REFS [Restrictions].
Replace the syntax concept NAME [ enumerates REFS ] by the syntax concept NAME [ oneOf REFS ].
Replace the syntax enumerated scalar NAME < REFS [ LITERALS ] by the syntax scalar NAME [ oneOf LITERALS ].
Replace the syntax scalar NAME < REFS [ FACETS ] by the syntax scalar NAME = REFS [ FACETS ].

Migrating OML v1 XMI syntax for Descriptions to that of v2 can be done using the following process:

Replace ConceptTypeAssertion by TypeAssertion.
Replace ScalarPropertyValueAssertion by PropertyValueAssertion.
Replace LinkAssertion by PropertyValueAssertion.
Replace <value by <literalValue.
Replace <ownedLinks by <ownedPropertyValues.
Replace <relation by <property.
Replace target= by referencedValue=.

Please provide your feedback by posting a discussion thread.

Team

Maged Elaasar, Ph.D.

Summary

Syntax Changes

API Changes

Migration Guide

Team

Sponsors