Linked data and the API

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

This page describes how Ontomasticon publishes vocabularies and terms for other software: as linked data (JSON-LD and Turtle) at their own addresses, through the API, and to search engines. It also describes the search box and how pages are cached. What each field of a vocabulary or term becomes in linked data is described alongside the field on the page Editing vocabularies and terms.

Linked data at the site's own addresses

The addresses of the home page, of each controlled vocabulary and of each term that is not in a vocabulary show an HTML page to browsers, and return RDF to linked data clients that ask for it, either with an Accept header or with ?format=:

To get	Send
JSON-LD	`Accept: application/ld+json`, or add `?format=jsonld` to the address
Turtle	`Accept: text/turtle`, or add `?format=ttl` to the address

RDF is only returned when the Accept header prefers it to HTML. Clients that accept HTML as much as RDF, such as browsers, get the HTML page, and a client that accepts JSON-LD and Turtle equally gets JSON-LD. */* and application/json don't ask for RDF. Responses say that they depend on the Accept header (Vary: Accept), and each HTML page links to its JSON-LD and Turtle with <link rel="alternate">. For a site with the base URL glossary.example.org/:

Address	RDF returned
https://glossary.example.org/	The site's own concept scheme, followed by the terms that are not in a controlled vocabulary
https://glossary.example.org/cv/calls	The `calls` vocabulary as a concept scheme, followed by its terms
https://glossary.example.org/song	The term `song`
https://glossary.example.org/cv/calls#song	The part after the # is not sent to the server, so the `calls` vocabulary, which includes the term. Use the API for the term on its own.

If there is no vocabulary or term at the address, the response is 404 Not Found, with an empty body. The list of vocabularies, [base_url]/cv/, has no RDF.

The API

Each site describes its API at [base_url]/api/.

Address	Returns
[base_url]/api/term/?shortname=[short name]	The term's database record as a JSON object, with each value as a string and the term's URI as `url`. `null` if there is no such term.
[base_url]/api/term/?term=[URI]	The same, for the term with this URI. URL-encode the URI.
Either of the above with `&format=jsonld` or `&format=ttl`	The term as RDF, in JSON-LD or Turtle. 404 Not Found, with an empty body, if there is no such term.
[base_url]/api/cv/?shortname=[short name]	The vocabulary as a concept scheme followed by its terms, in JSON-LD, or in Turtle with `&format=ttl`. 404 Not Found, with an empty body, if there is no such vocabulary.
[base_url]/api/cv/	The site's own concept scheme, followed by the terms that are not in a controlled vocabulary, in JSON-LD, or in Turtle with `?format=ttl`.
[base_url]/api/search/?q=[text]	Suggestions for the search box, as a JSON array of up to ten terms (see Searching). Each has `name`, `shortname`, `acronym` (or null), `uri`, `vocabulary` (the name of the term's vocabulary, or null) and `synonym_of` (for a synonym, the name of the term it is a synonym of, whose URI is given; otherwise null).

What the RDF says

Controlled vocabularies, and the site's own terms that are not in one, are SKOS concept schemes (skos:ConceptScheme). A scheme has its title, description, publisher, license and preferred namespace prefix, its references, and its top concepts (skos:hasTopConcept). The site's own scheme also has the site's author as its creator. See the site settings on the page Administering Ontomasticon.

Terms are SKOS concepts (skos:Concept), with the properties that TDWG's Standards Documentation Specification requires of controlled vocabulary terms:

a label (rdfs:label and skos:prefLabel) and definition (rdfs:comment and skos:definition), tagged with the term's language;
the short name as the controlled value (rdf:value);
the scheme the term is in (skos:inScheme), and, for a term without a broader term, that it is a top concept (skos:topConceptOf);
broader, narrower and related terms (skos:broader, skos:narrower and skos:related);
alternative labels (skos:altLabel): the term's acronym and the names of its synonyms;
for a synonym, that it is deprecated (owl:deprecated) and replaced by (dcterms:isReplacedBy) the term it is a synonym of;
the dates the term was added and last changed (dcterms:created and dcterms:modified), as dates (xsd:date);
its references, as sources (dcterms:source) or bibliographic citations (dcterms:bibliographicCitation).

Properties are also rdf:Property, and classes rdfs:Class, and a property's values are given as its range or in a note: see the Type and Values fields on the page Editing vocabularies and terms. The linked data readiness report lists what stops the vocabularies giving complete, clean RDF.

Glossaries: OntoLex and LexInfo

On a site marked as a glossary (the Glossary setting on the page Administering Ontomasticon), the words for each term are also published as a dictionary would publish them, as OntoLex lexical entries (ontolex:LexicalEntry), with LexInfo saying what kind of word each one is. Each entry has a written form (ontolex:canonicalForm, with ontolex:writtenRep) and denotes (ontolex:denotes) the term's concept.

Word	Entry address	LexInfo
The term's name	The term's URI followed by `#entry`, or `:entry` for a term in a controlled vocabulary, whose URI already has a #. For example https://glossary.example.org/pam#entry and https://glossary.example.org/cv/calls#song:entry.	The preferred term (lexinfo:normativeAuthorization lexinfo:preferredTerm). If the term has an acronym, the name is its full form (lexinfo:termType lexinfo:fullForm).
The term's acronym	The term's URI followed by `#acronym`, or `:acronym`	An acronym (lexinfo:termType lexinfo:acronym) for the name's entry (lexinfo:acronymFor).
A synonym's name	The synonym's URI followed by `#entry`, or `:entry`	An admitted term (lexinfo:normativeAuthorization lexinfo:admittedTerm), denoting the concept the synonym is a synonym of.

On a glossary, a term's RDF is a graph (@graph in JSON-LD) of its concept followed by its entries, rather than a single object, and a vocabulary's RDF gives the entries after its terms. The namespaces are http://www.w3.org/ns/lemon/ontolex# (ontolex) and http://www.lexinfo.net/ontology/3.0/lexinfo# (lexinfo).

Pages for search engines

A term that is not in a controlled vocabulary has a page of its own at its URI, with its entry and a link to all of the site's terms. Terms in a vocabulary are entries on the vocabulary's page. The pages of terms, vocabularies and the home page each have:

a title made of the term's or vocabulary's name, then the site's name;
a description (the description meta tag) made from the term's definition or the vocabulary's description, as plain text of up to 300 characters, or otherwise the site's description;
a canonical address (<link rel="canonical">): the term's or vocabulary's URI, or the site's address;
schema.org data in the page, which search engines and other crawlers read:
- the home page describes the terms that are not in a vocabulary as a set of defined terms (DefinedTermSet), with the site's name, description, language, author, publisher and license;
- a vocabulary's page describes the vocabulary as a DefinedTermSet of its terms, with its references as citations;
- a term's page describes the term as a defined term (DefinedTerm) in its set, with its short name as its code, and its acronym and synonyms' names as other names.

An address that should be a term's or a vocabulary's, but isn't, is sent as 404 Not Found. Its page says so and still lists the site's terms, or its vocabularies, as an old or mistyped link may be meant for one of them.

Ontomasticon also makes these files at the top of the site:

File	Contents
[base_url]/robots.txt	Asks crawlers to keep out of [base_url]/admin/ and [base_url]/user/, and gives the address of the sitemap.
[base_url]/sitemap.xml	The home page, each vocabulary's page and each term's page, with the date each term was last changed when it is known.
[base_url]/favicon.ico	The site's icon.

Don't put files with these names at the top of the installation, as the web server would send them instead.

Searching

Every page has a search box in its header. As you type two or more characters, it suggests terms and synonyms whose name, short name or acronym contains the text, those starting with it first. Choose a suggestion with the arrow keys and Enter, or click it, to go to the term; a synonym goes to the term it is a synonym of. Esc closes the suggestions.

Pressing Search, or Enter without choosing a suggestion, opens the results page at [base_url]/?q=[text]. It lists the terms whose name, short name, acronym or definition contains the text, or that have a synonym whose name, short name or acronym does. Search engines are asked not to index the results page. The search box works without JavaScript, though without suggestions.

The suggestions are made by the file js/search.js, so js can't be the short name of a term that is neither opaque nor in a controlled vocabulary (see Short names).

Caching

Visitors don't get a session cookie unless they need one: when they log in or use the user and administration pages, submit a form, or choose a language with ?lang=, which is then remembered for the rest of their visit. Pages, linked data and API responses for visitors without a session may be kept by browsers, crawlers and caches for five minutes (Cache-Control: public, max-age=300), so a change can take up to five minutes to reach them. These responses vary by cookie (Vary: Cookie), so logging in shows fresh pages, and pages for visitors with a session are not kept, so editors see their changes at once.

Stylesheets and scripts are linked with the time they were last changed added to their address (?v=), so browsers fetch them again after an update.

If the site is behind a CDN or caching proxy, remember that a page and its JSON-LD and Turtle share one address and differ by Accept header. A cache that ignores Vary: Accept could send a browser JSON-LD, or a linked data client HTML. Either leave the site's pages out of the cache, or include the Accept header in the cache key. Cloudflare, for example, doesn't cache HTML by default, but a "Cache Everything" rule would ignore Vary: Accept.