Wacom Ontology Description Language

Purpose

At a fundamental level, digital ink is designed for producing content, such as text, math, diagrams, sketches etc.

The Wacom Ontology Description Language (WODL) provides a standardized, JSON-based way of annotating ink with a specialized schema definition.

The following document defines a framework for describing ontologies / semantic networks, incorporated within the Universal Ink Model.

Schema definition

The schema container is a JSON object with the following definition:

Property	Data type	Description	Mandatory
head	JSON Object	The schema's HEAD section. Contains general definitions and metadata.	Yes
body	JSON Object	The schema's BODY section. Contains class definitions and semantic knowledge statements.	Yes

info

JSON keys preceded with '@' are treated as comments.

Schema Head

The schema head is encoded as a JSON object with the following definition:

Property	Data type	Description	Mandatory
uri	string	URI identifying the current schema.	Yes
version	string	Schema version.	Yes
description	string	Free-form textual description of the schema.	Yes
classUriTemplate	string	URI template, which should be used for composing fully qualified class names.	Yes
propertyUriTemplate	string	URI template, which should be used for composing fully qualified class property names.	Yes
includes	JSON array of WODL schema inclusions	Specifies a list of included schemas.	No

A schema inclusion is encoded as a JSON object and is encoded as follows:

JSON Property	Value	Mandatory
namespace	<alias>	No
schema	<schema URI>	Yes

The namespace property defines a namespace or a schema alias. The schema property specifies the included schema.

If namespace is provided, classes and properties defined in the schema can be used in the Body section in their short-form notation (using the : character as delimiter) instead of in their fully-qualified form.

Example: Consider a schema https://wacom.com/schema with class definition Class1 with property prop. The schema can be included in another schema by defining the following inclusion:

{"namespace": "ns", "schema": "https://wacom.com/schema"}

The short form of Class1 is ns:Class1.

The short form of property prop is ns:Class1#prop1.

info

• Both classUriTemplate and propertyUriTemplate may contain tokens, which should be replaced during the URI composition. A token is being denoted using square brackets, for instance [class].
• Known tokens are:
  • [class] - replaced with a class name
  • [property] - replaced with a class property name

Schema Body

The schema body is encoded as a JSON object (considered a dictionary) with the following definition:

Property	Data type	Description	Mandatory
classes	JSON object	Body subsection Classes definitions - contains class definitions.	Yes if Class Extensions subsection is not defined.
extensions	JSON object	Body subsection Class Extensions - contains extensions of known classes.	Yes if Classes is not defined.
statements	JSON array	Body subsection Statements - contains a list of statements in form of semantic triples (subject, predicate, object).	No

Body: Classes

The body subsection Classes is encoded as JSON object, defined as follows:

Property	Data type	Description
<class name>	JSON object	Holds a class definition. For more information on the class definition syntax refer to section Class Definition.
...

Body: Class Extensions

The body subsection Class Extensions is encoded as JSON object, defined as follows:

Property	Data type	Description
<class name>	JSON object	Holds a class extension definition. The class, which is being extended, must be defined and known by the ontology machine. For more information on the class definition syntax refer to section Class Extension Definition.
...

Body: Statements

The body subsection Statements is encoded as JSON array. An element of the array is defined as a fixed-size JSON array of 3 elements and represents a semantic triple definition.

Element index	Data type	Description
0	string	The subject of the semantic triple.
1	string	The predicate of the semantic triple.
2	string, number or boolean	The object of the semantic triple.

info

Any statements contained within a WODL schema are considered an integral part of the ontology and can't be amended or discarded.

Class Definition

A class definition is encoded as a JSON object and defined as follows:

Property	Data type	Description	Mandatory	Default value
subclassOf	string	Specifies the parent class name.	Yes
isAbstract	bool	Whether or not the class is considered abstract.	No	false
isFinal	bool	Whether or not the class is considered final. If set to true, the property can't be overridden.	No	false
allowLooselyDefinedProps	bool	Whether or not "loosely defined properties" are allowed for instances of this class. Loosely defined properties should be accepted by ontology machine implementations without further validation. A loosely defined property is considered "unknown" but will not result in an exception.	No	false
properties	JSON object (dictionary)	Specifies a dictionary, which holds a map of class properties. The key of a key/value pair of the dictionary defines a property name. The value of a key/value pair of the dictionary holds a property definition, encoded as JSON object. For more information about the property definition syntax refer to section Property Definition.	No

info

• Multiple inheritance is not supported yet.
• An instance of a class represents a vertex in the semantic network.
• Each instance of a class is assigned with the reserved property hasURI of data type @uri, which should be auto-resolved by the implementations.
• Each instance of a class is assigned with the reserved property isInstanceOf, which should be auto-resolved by the implementations and should hold the fully qualified class name.

Class Extension Definition

A class extension definition is encoded as a JSON object and defined as follows:

Property	Data type	Description	Mandatory	Default value
properties	JSON object (dictionary)	Specifies a dictionary, which holds a map of class properties. The key of a key/value pair of the dictionary defines a property name. The value of a key/value pair of the dictionary holds a property definition, encoded as JSON object. For more information about the property definition syntax refer to section Property Definition.	No

Property Definition

A class property definition is encoded as a JSON object as follows:

Property	Data type	Description	Mandatory	Default value
propertyType	string	The type of the property.	No	value
dataType	string	The data type of the property.	Yes
dataRange	JSON array	Defines a list of allowed property values. Useful for restricting property values and constant properties definitions. Closest analogy: Enumeration.	No
minCardinality	int	Min cardinality value. If overridden it can't be set to a value smaller than the inherited value.	No	0
maxCardinality	int	Max cardinality value. If overridden it can't be set to a value greater than the inherited value. A value of -1 means 'infinity'. Otherwise the max cardinality should be greater than or equal to the min cardinality.	No	1
isOrdered	boolean	Orders the class properties if maxCardinality > 1.
inverseOf	string	The name of a property of the referenced entity.	No
isFinal	bool	Whether or not the property is considered final. If set to true, the property can't be overridden.	No	false

info

Properties could be referred to in the BODY section using their:

• fully-qualified name or
• short-form name, with the following syntax: <classname>#<propertyname>

In case a property is defined in the BODY section in its short form, the following definitions apply:

• <classname> - A class name in its short-form notation.
• <property> - The property name.

For more information about short-form notations of classes and properties refer to section Schema Head (schema inclusion).

Property type

Type	Description
value	Represents a data value or an entity 'passed by value'. The association type between the current entity and the referenced entity is composition - the referenced entity is owned by the current class instance and cannot exist independently.
reference	Represents a reference to an entity. The association type between the current entity and the referenced entity is aggregation - the referenced entity exists independently of the current class instance.

Data type

It may be:

• a generic data type (as defined in section Generic Types)
• applicable only if propertyType is set to value, a class name or a comma-separated list of class names
• in this case, the class property holds a reference to another entity

If a property's dataType is a class name, the class property represents an edge in the semantic network.

If dataType is overridden, it should be a specialization of the inherited class property's dataType.

Ordered Property

Applicable only if maxCardinality > 1 or maxCardinality = -1 (inf).

info

If maxCardinality > 1 or maxCardinality = -1 the property definition represents a list (of values or references). In this case isOrdered specifies whether this list is ordered or not.

The property can't be overridden.

If maxCardinality > 1 and isOrdered = true the class property represents an ordered list.

info

When expressed as a semantic triple an ordered property should have the following syntax:

<propertyName>-<index>

index is a non-negative number

For example, consider classes X and Y and the following property definition for X#hasChild:

• propertyType: value
• dataType: Y
• minCardinality: 0
• maxCardinality: 10
• isOrdered: true

Based on this definition the property X#hasChild represents an ordered list of instances of type Y, which are owned by an entity of type X.

The statement below, expressed as semantic triple, declares the parent-child relationship between an entity of X and an entity of Y and specifies the exact position of this relationship within the ordered list hasChild.

<uri-of-a-node-of-type-X> X**#hasChild**-0 <uri-of-a-node-of-type-Y>

Inverse of

This property is considered inverse of the currently being defined property. The dataType of the referenced property must be the same as or a specialization of the current property's dataType.

info

Useful for encoding bidirectional paths within a semantic network.

Generic Types

Type name	Description
@string	A string value.
@i18n_string	A i18n string value with language locale information. Syntax: "<string_value>"@<language_locale> language_locale should be a BCP47 language code (en-US, de-DE etc). (Relaxed BCP47 codes are also allowed: en_US, de_DE etc.) If language_locale is not provided, the i18n string value is considered an ordinary string and should be encoded as such (according to @string type definition).
@language	Language locale value - should be a BCP47 language code (en-US, de-DE etc). (Relaxed BCP47 codes are also allowed: en_US, de_DE etc.)
@int / @int32	32-bit integer value
@int64	64-bit signed integer value
@uint / @uint32	32-bit unsigned integer value
@uint64	64-bit unsigned integer value
@float / @float32	32-bit float value
@float64	64-bit float value
@latex	A Latex expression.
@mathml	A MathML expression.
@uri	Uniform Resource Identifier (URI)
@uri	Uniform Resource Identifier (URI)
@iri	Internationalized Resource Identifier (IRI)
@url	Uniform Resource Locator (URL)
@uuid	Universally unique identifier (UUID)
@timestamp	UNIX timestamp in seconds encoded as 32-bit unsigned integer value
@timestampAsFloat	UNIX timestamp in seconds with fractions of seconds, encoded as 64-bit float value
@timestampInMs	UNIX timestamp in milliseconds encoded as 64-bit unsigned integer value

Reserved Keywords

Keyword	Usage
@	Could be used as a predicate of a semantic triple and denotes entity type declaration.
@null	Could be used as an object of a semantic triple and denotes NULL reference.
@sameas	Could be used as a predicate of a semantic triple and denotes that the object and the subject of the semantic triple are the same entity.

Semantic Knowledge Definition

• Semantic relationships between logical entities, defined in ontology description schemas as proposed by the current specification, could be described as an unordered collection of semantic triples (as defined in RDF).
• WODL implementations should use the reserved keyword @ to specify WODL entity types. In order to enable eventual consistency with RDF the reserved keyword @ may be replaced with http://www.w3.org/1999/02/22-rdf-syntax-ns#type and vice-versa.
• WODL classes should be specified in fully-qualified notation when describing an ontology as semantic triples.
• WODL class properties are specified only by their name when describing an ontology as semantic triples.