# Onto Class Reference

> This is an informative document. Manipulation of the contents of the tables should always be performed with the functions of the package.

## Sources (ontology@sources)

Each row in the sources table represents a source of one or more concepts and/or classes. A source is typically some form of a knowledge organization system (KOS); e.g., a vocabulary. A source record features the nine properties:

id (generated): Unique identifier of this source record. Built by counting upwards, starting with `1`.

label (mandatory): A speaking label for the source.

version (optional): The version of the source.

date (optional): The creation date of the source.

description (optional): A description of the source.

homepage (optional): Homepage of the source.

uri_prefix (optional): Prefix of the resources of the ontology. See also [https://www.w3.org/TR/turtle/] at 2.4 IRIs. If no `uri_prefix` for the harmonized resources of the ontology is given, the `export_as_rdf()` function, inserts the placeholder value `http:[slash][slash] www[dot]example[dot]org[slash]ontologics`. If non-harmonized sources are provided without a `uri_prefix` they are ignored by the `export_as_rdf()` function.

license (mandatory): Licensing information of the source-KOS.

notes (optional): Further notes about the source.

The first row of the sources table refers the ontology itself as a source. Every harmonized concept and class is considered to belong to this source.

## External Classes (ontology@classes$external)

A record in this table identifies an external class. External denotes that the definition, label, etc. of this class was initially done somewhere else, i.e. not in this ontology. An external class record features five properties:

id (generated): NOT IMPLEMENTED YET. Unique identifier of this external class record. The ID is generated automatically by the software. The generation logic concatenates the source label of this concept with a counter. The concatenation string is `:class_` (:class_, e.g., wikidata:class_1).

label (optional): The label of the external class as it is defined by the source.

description (optional): The description of the external class as it is defined by the source.

has_source (mandatory): Foreign key to the according source ID. Has to be a value that is present in ontology@sources$id.

url (optional): NOT IMPLEMENTED YET. If existing: The URL to the place on the web where the class is defined.

## Harmonised Classes (ontology@classes$harmonised)

A harmonised class record describes a harmonised class. Harmonised indicates that the label and definition of this class are used by this ontology. A harmonised class record features eight properties:

id (generated): NOT IMPLEMENTED YET. Unique identifier of this harmonised class record. The ID is generated automatically by the software.

The ID consists of multiple 3-digit codes that begin with prefixed a dot, e.g. `.004.002.007`. The number of the codes indicates the hierarchical level of the class - third level in the example - where the first level is the broadest. The ID is read from right to left. The example ID means that the according class is the 7th class that was defined in the 3rd hierarchical level, it has a narrower meaning than 2nd the class that was defined in the 2nd hierarchical level, which in turn has a narrower meaning than the 4th class that was defined in the 1st (the broadest) hierarchical level.

label (mandatory): The label of the harmonised class.

description (optional): The description of the harmonised class. It is strongly recommended to provide a description.

has_broader (optional): Relates this harmonised class to another harmonised class that conveys a broader meaning. As an example, with this relation, a class land-use could be related to a class landcover, which has a semantically broader meaning. Values are foreign keys to IDs in this table (`ontology@classes$harmonised$id`).

has_exact_match (optional): Identifies any number of external classes as classes that have exactly the same meaning (they can be used interchangeably in any context). Since, the ID generation logic for external classes is not implemented yet, values are strings of concatenated foreign keys to labels in the external classes table (`ontology$classes$external$label`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3, e.g., land-usage.3. The number indicates the certainty of the match, where 3 means most certain. An exact match entry for the harmonised class land-use could therefore be landuse.3 | use-of-land.2 | land-usage.3. (IN THE FUTURE: values are strings of concatenated foreign keys to IDs in the external classes table (`ontology$classes$external$id`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3, e.g., wikidata:class_1.3. The number indicates the certainty of the match, where 3 means most certain. An exact match entry for the harmonised class land-use could therefore be wikidata:class_1.3 | wikidata:class_46.2 | agrovoc:class_42.3. )

has_close_match (optional): Identifies any number of external classes as classes that have a similar meaning (they can be used interchangeably in some contexts). Since, the ID generation logic for external classes is not implemented yet, values are strings of concatenated foreign keys to labels in the external classes table (`ontology$classes$external$label`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3 (see has_exact_match). (IN THE FUTURE: values are strings of concatenated foreign keys to IDs in the external classes table (`ontology$classes$external$id`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3 (see has_exact_match). )

has_narrow_match (optional): Identifies any number of external classes as classes that have a narrower meaning. Since, the ID generation logic for external classes is not implemented yet, values are strings of concatenated foreign keys to labels in the external classes table (`ontology$classes$external$label`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3 (see has_exact_match). (IN THE FUTURE: values are strings of concatenated foreign keys to IDs in the external classes table (`ontology$classes$external$id`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3 (see has_exact_match). )

has_broad_match (optional): Identifies any number of external classes as classes that have a broader meaning. Since, the ID generation logic for external classes is not implemented yet, values are strings of concatenated foreign keys to labels in the external classes table (`ontology$classes$external$label`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3 (see has_exact_match). (IN THE FUTURE: values are strings of concatenated foreign keys to IDs in the external classes table (`ontology$classes$external$id`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3 (see has_exact_match). )

## External Concepts (ontology@concepts$external)

A record in this table identifies an external concept. External denotes that the definition, label, etc. of this concept was initially done somewhere else, i.e. not in this ontology. An external concept record features five properties:

id (generated): Unique identifier of this external concept record. The ID is generated automatically by the software. The generation logic concatenates the source label of this concept with a counter (_).

label (optional): The label of the external concept as it is defined by the source.

description (optional): The description of the external concept as it is defined by the source.

has_source (mandatory): Foreign key to the according source ID.

url (optional): NOT IMPLEMENTED YET. If existing: The URL to the place on the web where the concept is defined.

## Harmonised Concepts (ontology@concepts$harmonised)

A harmonised concept record describes a harmonised concept. Harmonised indicates that label and definition of this class are used by this ontology. Each harmonised concept has to be assigned to harmonised class. A harmonised concept record features nine properties:

id (generated): Unique identifier of this harmonised concept record. The ID is generated automatically by the software. The generation logic take the hierarchical level of the concept (as constructed by has broader relations) into account.

The ID consists of multiple 3-digit codes that begin with prefixed a dot, e.g. `.004.002.007`. The number of the codes indicates the hierarchical level of the concept - third level in the example - where the first level is the broadest. The ID is read from right to left. The example ID means that the according concept is the 7th concept that was defined in the 3rd hierarchical level, it has a narrower meaning than 2nd the concept that was defined in the 2nd hierarchical level, which in turn has a narrower meaning than the 4th concept that was defined in the 1st (the broadest) hierarchical level.

label (mandatory): The label of the harmonized concept.

class (mandatory): Assigns the harmonized concept to a specific class. Each concept can only be assigned to one specific class. As an example: The concept permanent grazing could be a concept of the class land-use or permanent cropland could be a concept of the class landcover. The values are foreign keys to labels in the harmonized classes table (`ontology@classes$harmonised$label`), since the ID-generation logic for the harmonized classes is not implemented yet. (IN THE FUTURE: The values are foreign keys to IDs in the harmonized classes table (`ontology@classes$harmonised$id`). )

description (optional): The description of the harmonized concept. It is strongly recommended to provide a description.

has_broader (optional): Relates this harmonized concept to another harmonized concept that conveys a broader meaning. As an example, with this relation, a concept permanent grazing could be related to a concept permanent cropland, which has a semantically broader meaning. Values are foreign keys to IDs in this table (`ontology@concepts$harmonised$id`).

has_exact_match (optional): Identifies an external concept as a concept that has exactly the same meaning (they can be used interchangeably in any context). Values are strings of concatenated foreign keys to IDs in the external concepts table (`ontology$concepts$external$id`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3, e.g., wikidata_1.3. The number indicates the certainty of the match, where 3 means most certain. An exact match entry for the harmonized concept permanent grazing could therefore be wikidata_1.3 | wikidata_24.2 | agrovoc_32.3. )

has_close_match (optional): Identifies an external concept as a concept that has a similar meaning (they can be used interchangeably in some contexts). Values are strings of concatenated foreign keys to IDs in the external concepts table (`ontology$concepts$external$id`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3.

has_narrow_match (optional): Identifies an external concept as a concept that has a narrower meaning. Values are strings of concatenated foreign keys to IDs in the external concepts table (`ontology$concepts$external$id`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3.

has_broad_match (optional): Identifies an external concept as a concept that has a broader meaning. Values are strings of concatenated foreign keys to IDs in the external concepts table (`ontology$concepts$external$id`). Concatenation is performed with `|`. Each foreign key is furthermore suffixed with a dot and a number in the range from 1 to 3.