-
Notifications
You must be signed in to change notification settings - Fork 42
OGIT ontology details
Here we take a more technical view of OGIT.
Reading this will help you give a deeper understanding of the ontology and make it much easier to read the ontology documentation.
Reading this is a must if you want to contribute to the ontology.
The ontology defines
- attributes
- entities
- verbs
Entities define the objects we are dealing with in OGIT. Any instance of an entitiy type can have attributes, which are predefined by attribute definitions from the ontology. Verb definitions declare which relationships are possible between instances of entity types.
The actual data will be stored in GraphIT. GraphIT is based on a graph database and used the OGIT ontology to ensure that only valid data gets stored. We have the following relation between graph data and ontology definitions:
- Each vertex in the graph must be a valid instance of an entity type defined by the ontology
- All vertex properties must be valid w.r.t. the the attribute definitions from the ontology (what attribute validity means will be explained below)
- All edges in the graph must have labels defined by some verb type in the ontology.
- All triples defined by graph data must be valid according to the ontology (see below for more details)
Note: to prevent some confusion from now on we will use the terms attribute, entity, and verb whenever referring to elements from the ontology and property, vertex, and edge when talking about instance data.
The ontology is represented in YAML format. By convention we are maintaining an individual YAML file for each attribute, verb, and entity definition.
Defining an attribute in OGIT ontology will require a YAML stanza like this (the exact format can be found in Attribute.yaml.tpl):
- Attribute:
id: http://www.purl.org/ogit/color
name: color
description: "can be used to store the color of objects"The example contains the following details
| Parameter | Description |
|---|---|
| id | a unique id for that ontology element (see "IDs of ontology elements" below) |
| name | by convention this repeats the last part of ID. It is only used as display name. |
| description | should describe the semantics of that attribute as clear as possible. This will be the main source of information if somebody needs to decide if that attribute can be re-used |
Defining an entity in OGIT ontology will require a YAML stanza like this (the exact format can be found in Entity.yaml.tpl):
- Entity:
id: http://www.purl.org/biology/Tree
name: Tree
description: "This entity type models a tree"
scope: SGO
parent: http://www.purl.org/ogit/Factual
attributes:
any: false
mandatory:
- id: http://www.purl.org/ogit/type
optional:
- id: http://www.purl.org/ogit/color
validation-type: "regex"
validation-parameter: "^(blue|red|yellow)$"The example contains the following details
| Parameter | Description |
|---|---|
| id | a unique id for that ontology element (see "IDs of ontology elements" below) |
| name | by convention this repeats the last part of ID. It is only used as display name. |
| description | description of the purpose of that entity. This should be detailed enough to let others decide whether this entity can be re-used |
| scope | either "SGO" (stating that this entity definition is considered as part of the core ontology) or "NTO" (meaning that this entity definition is part of some domain specific extension) |
| parent | contains the id of another entity definition (see section about "Inheritance" below) |
| attributes | used for the property validation of all instances (vertices) of that entity type: 'mandatory' defines all properties that must be present in a vertex to be valid. This corresponds to the Specific Node Required Attributes 'optional' defines all properties that can be present in a vertex and the semantics of which is well-defined. This corresponds to the Specific Node Best Practice Attributes 'any: true' ensures any vertex property with a name starting with '/' will be accepted. This corresponds to the Specific Node Free Attributes |
| validation-type, validation-parameter | allow to define an optional attribute value validation: if an entity definition refers to that attribute definition and a vertex of that entity is to be created, then actual value of that attribute will be the validated according to the requirements defined by validation-type and validation-parameter. Possible validation-types are 'regex', 'xml' and 'generator'. Empty values, as in our example, will skip any further validation. (see "Attribute Validation") |
Defining a verb in OGIT ontology will require a YAML stanza like this (the exact format can be found in Verb.yaml.tpl):
- Verb:
id: http://www.purl.org/ogit/likes
name: likes
description: |
expresses that the 'from' entity 'likes' the 'to' entity
cardinality:
allowed:
- from: http://www.purl.org/ogit/Person
to: http://www.purl.org/biology/Tree
- from: http://www.purl.org/biology/Animal
to: http://www.purl.org/ogit/PersonThe example contains the following details
| Parameter | Description |
|---|---|
| id | a unique id for that ontology element (see "IDs of ontology elements" below) |
| name | by convention this repeats the last part of ID. It is only used as display name. |
| description | description of the semantics of this verb. This should be detailed enough to let others decide whether this verb can be re-used |
| cardinality | possible values are: one2one, one2many, many2one, many2many. An empty value defaults to many2many. This is used by the GraphIT validator during edge creation. See https://github.com/thinkaurelius/titan/wiki/Type-Definition-Overview#cardinality-constraints for the specification of cardinality constraints |
| allowed | this is used by GraphIT validator during edge creation. It is a list of ['from', 'to'] pairs. An edge of that verb type can be created if the pair ['entity type of source vertex', 'entity type of destination vertex'] is compatible with one of the ['from', 'to'] pairs. This comparison takes "inheritance" into account. |
For most operations on a vertex ("create", "update", ...) attribute validation takes place. This consists of two steps. The basis for attribute validation will be entity definition of the type the vertex belongs to.
- check the list of properties provided along with the vertex operation:
- during "create" (and "replace") any attribute defined as "mandatory" must be present (an empty value is possible though). If it is present the value validation will take place.
- if any attribute defined as "optional" is present the value validation will take place
- if request contains properties neither defined by "mandatory" nor "optional" attributes then the 'any' switch is checked. If it is true and the property names start with a '/' it will be accepted (without any value validation). Otherwise the whole vertex data is considered invalid.
- value validation will be based on validation-type, validation-parameter of the corresponding entity definition. This means, that an attribute can be validated different for each entity it belongs. Empty values mean: no further validation.
IDs of ontology elements, e.g. http://www.purl.org/ogit/color must be unique across the whole ontology (i.e. across the union of all attributes, verbs, and entities).
To ensure uniqueness we register a suitable Persistent URL for each ontology element at www.purl.org.
Note: When using GraphIT REST API those IDs are always used without the prefix http://www.purl.org/. In our examples you would use ogit/color to address that attribute type within an application.
Each Ontology element has a unique ID. Each ID consists of three parts:
http://www.purl.org/<namespace><short name of ontology element>
In general we allow:
- characters: lowercase and uppercase
- digits
- '-' (minus sign)
namespace may also contain '/'.
For the last part (short name of ontology element) the conventions are described here.
Each entity definition contains a parent entity type. Using this the new entity type
- "inherits" attribute declarations from ancestor types
- "inherits" allowed verbs ('from' and 'to' end) from ancestor types. This is mainly for convenience: it prevents ontology maintainers from repeating the same definitions again and again. Especially each entity will automatically have all the default attributes which are used by GraphIT for proper handling of vertex data (e.g. 'ogit/_id', 'ogit/_type', and so on).
Those parent/child relationships of entity definitions must form a tree (e.g. must not contain any loops)
Note: This inheritance mechanism exists just to simplify the ontology definitions. It is not real inheritance as you know from OO design! For example: let's assume the ontology defines an entity 'ogit/Plant' and 'ogit/Tree' having the first one as parent type. Now let's assume you create a vertex A of type 'ogit/Plant' and a vertex B of type 'ogit/Tree' in GraphIT. If you then query for all vertices of type 'ogit/Plant' GraphIT will return A but not B!