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.
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.
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 are used as they are in URIs, so:
api, cv, ping, 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.
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.
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.
The edit page has the same fields as the add page, apart from the short name, which cannot be changed.
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, and properties whose values came from the vocabulary no longer say where their values come from. This cannot be undone.
In linked data each term is a SKOS concept, with the properties TDWG requires of controlled vocabulary terms as well.
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 and broader 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. |
| 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. |
| 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.
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.
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.
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.
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, and other terms that had it as their parent or broader term are left without one. This cannot be undone.