Editing vocabularies and terms

Ontomasticon is a simple, lightweight ontology and glossary server written in PHP and making use of MariaDB or MySQL.

This page describes how to add, edit and delete controlled vocabularies (CVs) and terms, what each field of the forms means, and the addresses (URIs) vocabularies and terms are given. Users, roles and site settings are described on the page Administering Ontomasticon.

Who can edit

What a user can do depends on their role (see Administering Ontomasticon).

Page	Address	Roles
Add controlled vocabulary	[base_url]/admin/cv/add	Editor and CV creator, Admin
Edit controlled vocabulary	[base_url]/admin/cv/edit/[short name]	Editor, Editor and CV creator, Admin
Delete controlled vocabulary	From the edit page	Admin
Add term	[base_url]/admin/term/add	Editor, Editor and CV creator, Admin
Edit or delete term	[base_url]/admin/term/edit/[short name]	Editor, Editor and CV creator, Admin

When you are logged in with permission to edit, an [edit] link is shown next to each term, and next to each vocabulary in the list of controlled vocabularies on the home page and at [base_url]/cv/. The administration menu has links to add a term and, if you can, to add a controlled vocabulary.

Descriptions and term references are shown on the site exactly as they are entered, including any HTML, so only give editing roles to people you trust.

Editors can also see the linked data readiness report, which lists vocabularies and terms with missing or invalid details, each linked to the page where it can be fixed.

Addresses of vocabularies and terms

Each vocabulary and term is identified by a URI made from the site's base URL (see Administering Ontomasticon) and its short name. The same address shows the HTML page to browsers and returns JSON-LD or Turtle to linked data clients (for a term in a vocabulary, the part after the # is not sent to the server, so the vocabulary is returned; the API returns a single term). See Linked data and the API. For a site with the base URL glossary.example.org/:

What	URI
A term that is not in a controlled vocabulary	https://glossary.example.org/song
A controlled vocabulary with the short name `calls`	https://glossary.example.org/cv/calls
A term in that controlled vocabulary	https://glossary.example.org/cv/calls#song
An opaque term, with the id 42, that is not in a controlled vocabulary	https://glossary.example.org/42
An opaque term, with the id 42, in the `calls` vocabulary	https://glossary.example.org/cv/calls#42

Terms that are not in a controlled vocabulary are listed on the home page, and each also has a page of its own at its URI. Terms in a vocabulary are listed on the vocabulary's page, where each term's entry is the fragment (after the #) of its URI. The id of a term is a number given to it by the database when it is added.

Short names cannot be changed once a vocabulary or term has been added. Moving a term to a different vocabulary, or changing whether it is opaque, changes its URI, so decide these before the URIs are used elsewhere.

Short names

Short names are used as they are in URIs, so:

They can only use the letters A to Z (upper or lower case), digits, hyphens, underscores and full stops, and cannot start with a full stop.
Every term must have a different short name, even if the terms are in different vocabularies. Every controlled vocabulary must have a different short name too.
Term short names can be up to 45 characters long, and vocabulary short names up to 30.
A short name made only of digits can only be used for an opaque term, as it could be mistaken for another term's id.
A term that is neither opaque nor in a controlled vocabulary cannot have a short name that the site already uses for something else: api, cv, ping, dbping, update, user, admin, settings, robots.txt, sitemap.xml, favicon.ico, the name of any file or directory at the top of the Ontomasticon installation (such as css, images, inst, js, lang or index.php), or any name ending in .php. These are compared ignoring upper and lower case. Such a term can still be added to a controlled vocabulary, or made opaque.

When editing a term, the change is refused if taking it out of its vocabulary or making it no longer opaque would break these rules.

Controlled vocabularies

A controlled vocabulary is a named list of terms with a page of its own. In linked data each vocabulary is a SKOS concept scheme. Terms that are not in any vocabulary belong to the site's own concept scheme, which is described by the site's settings.

Adding a controlled vocabulary

Use the Add controlled vocabulary link in the administration menu. The form has these fields:

Field	Meaning
Shortname	Required. Used in the vocabulary's URI, [base_url]/cv/[short name], and to identify it in the API. See Short names. It cannot be changed later.
Name	The name of the vocabulary, up to 50 characters, shown in the list of vocabularies and as the heading of its page. In linked data it is the vocabulary's title (dcterms:title, rdfs:label and skos:prefLabel).
Description	Shown below the heading of the vocabulary's page. HTML can be used, and is shown as it is entered. In linked data it is the vocabulary's description (dcterms:description), with HTML tags removed.
Reference	Where the vocabulary comes from, up to 255 characters. It is not shown on the vocabulary's page. Several references can be separated with `<br>`. In linked data each web address starting with http:// or https:// is given as a source (dcterms:source), and anything else as a bibliographic citation (dcterms:bibliographicCitation). In the schema.org data in the vocabulary's page, each reference is a citation.
Namespace prefix	A short prefix for the vocabulary's terms in RDF, for example `calltype`. It must start with a letter, use only letters, digits, hyphens and underscores, and be at most 20 characters long, or be left empty. In linked data it is the vocabulary's preferred namespace prefix (vann:preferredNamespacePrefix), with the vocabulary's URI followed by # as its namespace (vann:preferredNamespaceUri).

The site's publisher and license settings are given for every vocabulary.

Editing a controlled vocabulary

The edit page has the same fields as the add page, apart from the short name, which cannot be changed.

Deleting a controlled vocabulary

Admins see a Delete button on the edit page. Deleting is refused while terms outside the vocabulary are synonyms of its terms, as they would no longer say which term they are a synonym of: the page lists them, so their parent can be changed, or they can be deleted, first. After confirming, the vocabulary and all of its terms are deleted. Terms in other vocabularies that had one of the deleted terms as their parent or broader term are left without one, the deleted terms are removed from other terms' related terms, and properties whose values came from the vocabulary no longer say where their values come from. This cannot be undone.

Terms

In linked data each term is a SKOS concept, with the properties TDWG requires of controlled vocabulary terms as well.

Adding a term

Use the Add term link in the administration menu. The form has these fields:

Field	Meaning
Shortname	Required. Identifies the term, and ends its URI unless the term is opaque. See Short names. It cannot be changed later. In linked data it is the term's value (rdf:value), even for an opaque term.
Name	The name of the term, up to 200 characters, shown as the heading of its entry. In linked data it is the term's label (rdfs:label and skos:prefLabel).
Acronym	An acronym or initialism the term is also known by, for example `PAM` for passive acoustic monitoring, up to 50 characters. It is found by the search, and shown in search suggestions. On a glossary (see the Glossary setting on the page Administering Ontomasticon) it is also shown in the term's entry as "Acronym: PAM", and listed under its own letter as "PAM, see Passive acoustic monitoring"; on other sites it is not shown in the term's entry. In linked data it is an alternative label (skos:altLabel), and in the schema.org data in the term's page another name (alternateName).
Description	The definition of the term, shown below its name. HTML can be used, and is shown as it is entered. In linked data it is the term's definition (rdfs:comment and skos:definition), with HTML tags removed.
Language	The language the name and description are written in, as a language tag of up to 35 characters, for example `en`, `en-GB` or `zh-Hant`. It is shown in the term's entry. In linked data the name and description are tagged with this language. See Translating Ontomasticon.
Type	Concept (the default), Property or Class. A concept is a term or a value, such as a type of call. A property is a characteristic that is measured or recorded, such as pulse duration. A class is a kind of thing, such as a syllable. Properties and classes are marked as such in the term's entry. In linked data every term is a SKOS concept, so any term can be used as, for example, a Darwin Core measurement type. A property is also an rdf:Property and a class an rdfs:Class, both defined by (rdfs:isDefinedBy) their vocabulary, or the site's own concept scheme. A property or class whose broader term is of the same type is a sub-property (rdfs:subPropertyOf) or sub-class (rdfs:subClassOf) of it.
Values	For a property, where its values come from: Not stated, one of the site's controlled vocabularies, or a datatype (Numbers, Whole numbers, Text, Yes or no, or Dates). It is shown in the term's entry as "Values:", linking to the vocabulary. Other types of term don't have values, so saving a concept or class clears them. In linked data a datatype is the property's range (rdfs:range): xsd:decimal, xsd:integer, xsd:string, xsd:boolean or xsd:date. There is no agreed way to say in RDF that values come from a vocabulary, so this is given as a note (skos:scopeNote) naming the vocabulary and giving its URI.
Opaque	If ticked, the term's URI ends with its id (a number given by the database) instead of its short name, as shown in Addresses of vocabularies and terms. Use it when URIs should not carry meaning that might later change.
Controlled vocabulary	The vocabulary the term belongs to, or None. A term is in at most one vocabulary. This decides which page the term is listed on and the start of its URI.
Invalidity	None, or Synonym if the term is a synonym of another term. Give the term it is a synonym of as the parent. See Parents, synonyms, broader and related terms.
Parent	The short name of a related term, or empty. For a synonym, this is the term it is a synonym of. The term must already exist, but can be in any vocabulary. A term has at most one parent, so to relate a term to several others, use Related terms.
Broader term	The short name of a more general term, or empty, for building a hierarchy of terms. The term must already exist, but can be in any vocabulary.
Related terms	The short names of other terms related to this one, such as terms to see also, separated by commas or spaces, or empty. The terms must already exist, but can be in any vocabulary, and a term can't be related to itself. Each term is listed as related to the other, so removing a term from the list also removes this term from that term's related terms. See Parents, synonyms, broader and related terms.
References	Where the term or its definition comes from, one reference per line. In the definition, [1] cites the first reference, [2] the second, and so on. They are shown in the term's entry, numbered [1], [2] and so on, and HTML can be used. In linked data each reference that is a web address starting with http:// or https:// is given as a source (dcterms:source), and each other one as a bibliographic citation (dcterms:bibliographicCitation), with HTML tags removed. The linked data readiness report lists terms whose definition cites a reference, such as [2], that the term doesn't have.

The dates when a term was added and last changed are recorded automatically, and given in linked data as dcterms:created and dcterms:modified. Terms added before version 0.4 have no date added, and no date changed until they are next edited.

Parents, synonyms, broader and related terms

Broader terms build a hierarchy. A term's entry lists its broader term, and the broader term's entry lists it under Narrower terms. In linked data these are skos:broader and skos:narrower, and terms without a broader term are top concepts of their scheme. Synonyms are not listed as narrower terms.

Synonyms are terms with the Invalidity Synonym and the term they are a synonym of as their parent. A synonym is not listed on the home page or its vocabulary's page, but under Related terms in its parent's entry, marked Synonym and with its language. A synonym that is not in a controlled vocabulary still has its own page at its URI, which gives the term it is a synonym of under Related terms, marked Synonym of. In linked data the synonym's name is an alternative label (skos:altLabel) of the parent, unless it is the same as the parent's name, and the synonym itself is marked as deprecated (owl:deprecated) and replaced by its parent (dcterms:isReplacedBy). A synonym without a parent is not listed anywhere, though it is still included in linked data, and the linked data readiness report lists it.

Related terms are terms that are connected, such as terms to see also, without one being broader than the other. A term can have any number of related terms. Being related goes both ways: each term is listed under Related terms in the other's entry, and in linked data the two terms are related to each other (skos:related). A related term that is also the term's parent or one of its children is listed, and linked, only once.

Other parents: a term that has a parent but is not a synonym is listed on its own as usual, with its parent under Related terms, and is also listed under Related terms in its parent's entry. In linked data the two terms are related to each other (skos:related).

A term can't be its own parent or broader term. A change is also refused if following the parent terms, or the broader terms, up from the term being saved would lead back to it, as that would make a loop.

Editing a term

The edit page has the same fields as the add page, apart from the short name, which cannot be changed. Saving records the date the term was changed.

Deleting a term

The edit page has a Delete button. Deleting a term that has synonyms is refused, as the synonyms would no longer say which term they are a synonym of: the page lists them, so their parent can be changed, or they can be deleted, first. After confirming, the term is deleted, other terms that had it as their parent or broader term are left without one, and it is removed from other terms' related terms. This cannot be undone.