-
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 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:
mandatory:
- id: http://www.purl.org/ogit/type
optional:
- id: http://www.purl.org/ogit/color
validation-type: "regex"
validation-parameter: "^(blue|red|yellow)$"
indexed: true or false (default is false)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 |
| 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") |
| indexed | if 'true', the attribute will be indexed for ngram search |
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>
Guidelines for all OGIT elements including NTO's can be found [here] (../tree/master/SGO/format/README.md).
Currently inheritance is not being supported in OGIT for it's based on semantic graphs and not object oriented.
The so-called //Specific Node Free Attributes// are not part of the ontology. All entity types can have free attributes.
Technically this is implemented within graphit and no special handling in the ontology is needed.
Any attribute name starting with a slash '/', i.e. belonging to the empty namespace, will be accepted.
For example the following JSON will be valid node definition for entity type biology/Tree according to our sample definition above:
{
"ogit/type": "elm",
"/size": "15",
"/size-unit": "m",
}
See GraphIT REST API Documentation for more details (registration required).
Except the leading slash we recommend to adopt the same naming convention as for regular attributes. Hence check guidelines here.