Sitemap

Ontologies

Ontologies are sets of domain concepts. The domain can span both documents (information resources) and abstract/physical things (non-information resources).

Ontologies can import other ontologies, both user-defined and system ones provided by LinkedDataHub. The imports are retrieved during application initialization, and the ontology becomes a transitive union, i.e. is merged with its imports and imports of the imports etc.

Main ontology properties:

Imports: Ontology to be imported
Version: Unique version of this ontology

All concepts managed in the sitemap and explained below (templates parameters etc.) belong to exactly one ontology. The membership is specified using the rdfs:isDefinedBy property.

System ontologies

LinkedDataHub ontologies

AtomGraph Platform templates (APLT) is the default templates ontology used by LinkedDataHub.

Template ontologies
Ontology	Title	Prefix	Imports	Document hierarchy	Primary topics	Named graphs
`https://w3id.org/atomgraph/linkeddatahub/templates#`	AtomGraph Platform	`aplt:`	`thgt:`	✓	✓	✓
`https://www.w3.org/ns/ldt/topic-hierarchy-graphs/templates#`	Topic hierarchy graphs	`thgt:`	`tht:`	✓	✓	✓
`https://www.w3.org/ns/ldt/topic-hierarchy/templates#`	Topic hierarchy	`tht:`	`dht:`	✓	✓	✕
`https://www.w3.org/ns/ldt/document-hierarchy/templates#`	Document hierarchy	`dht:`	`ct:`	✓	✕	✕
`https://www.w3.org/ns/ldt/named-graphs/templates#`	Named graphs	`ngt:`	`ct:`	✕	✕	✓
`https://www.w3.org/ns/ldt/core/templates#`	Core	`ct:`		✕	✕	✕

Templates

LinkedDataHub uses Linked Data Templates to define operations on applications resources. A template combines a URI pattern wit a SPARQL command (or its template).

Templates can extend each other. A sub-template inherits the LDT properties of the super-template (such as path, command, parameters etc.), unless the sub-template defines its own property. The mechanism is similar to object-oriented class inheritance. Classes inherit SPIN properties the same way.

There is a number of built-in templates provided in template ontologies. The default APLT templates are tailored to match the LinkedDataHub dataset structure. If they do not match your dataset structure, you can extend a lower-level template (e.g. ct:Document) or create your own base template which other templates can extend.

The main template properties are:

Extends: Super-template that this template will inherit properties from
Match: Relative URI path pattern that has to match request URI.
Command: SPARQL query or update executed during request. It can also be a SPIN command template.
Parameters: A template can have any number of request parameters.
Priority: Similar to XSLT template priority, you can specify a priority value which is used to resolve a conflict when two templates match the same template. Template with higher priority gets selected. The default priority is 0.
Cache control: Specifies the Cache-Control header value that will be used for responses generated by this template

Match

Match is a relative URI (path) pattern that HTTP requests are matched against. It does not include the base URI (starts with a leading slash) or the URL query string. Match paths pattern are defined using JAX-RS URI template syntax.

Some examples:

Path	Request URI	Match?
`/`	`/`	Yes
`/`	`/some`	No
`/{path}`	`/some`	Yes
`/{path}/`	`/some`	No
`/{path}/`	`/other/`	Yes

Note that the captured variable values are discarded. URIs are opaque identifiers and they should be used for lookup of RDF resources. It is bad practice to "slice" URIs into literal values that are used for such lookup.

Parameters

Parameters define what values the template allows in the request URI query string (which is not considered during template matching). For example, query string ?givenName=Tim&familyName=Berners-Lee includes 2 parameters: givenName with value Tim and familyName with value Berners-Lee. Except for some system parameters, parameters are normally used to supply values from the request URI into the SPARQL query string. Supplying parameters that are not defined by the matching template will produce a 400 Bad Request response.

A parameter has the following properties:

Property: The RDF property that this parameter maps to. Following SPIN convention, the local name of the property is the name of the parameter. For example, if foaf:givenName is the parameter property, then givenName is the parameter name.
Value type: The RDF datatype to which the parameter value will be cast before it is used as a query binding. If the value is to be interpreted as a URI, rdfs:Resource should be used. Parameter values that cannot be cast to its value type will produce a 400 Bad Request response.
Requiredness: Indicates whether this parameter is mandatory or optional. If the matching template has a mandatory (non-optional) parameter for which a value is not supplied in the URI query string, a 400 Bad Request response will be produced.

Query bindings are produced from parameters for matching templates that satisfy all of the following conditions:

request method is GET and the template uses query template, as opposed to a concrete query
request method is PUT or DELETE and the template uses an update template, as opposed to a concrete update
command template has parameter(s) with the same property as the template parameter(s)

If the conditions are satisfied, all parameters from #3 will become SPARQL query bindings. For example: (?familyName, "Berners-Lee").

Queries

Queries are SPARQL 1.1 queries expressed as RDF resources using the SPIN RDF syntax. Queries are used to retrieve resource description from SPARQL service when the template they belong to matches GET request (DESCRIBE and CONSTRUCT queries).

Queries should define a special ?this variable, which is bound to the absolute path of the matching request URI (i.e. without the query string) before execution. For example, if a template matched request with URI https://linkeddatahub.com/linkeddatahub/docs/?limit=20, a variable binding (?this, <https://linkeddatahub.com/linkeddatahub/docs/>) will be applied on the query of that template. Additional variable bindings can be introduced using template parameters.

The query strings must follow SPARQL 1.1 syntax, otherwise you will not be able to store them.

Updates

Updates are SPARQL 1.1 DELETE updates expressed as RDF resources using the SPIN RDF syntax. Updates are used to:

update resource description from SPARQL service when the template they belong to matches PUT request (DELETE is combined with INSERT DATA generated from the request body)
remove resource description from SPARQL service when the template they belong to matches DELETE request

It is possible to use updates that include not only DELETE but also INSERT block, but their behavior is undefined in terms of LDT.

Command templates

Command templates are SPIN templates for SPARQL queries and updates that have 2 parts:

body which is a query or update
arguments with predicate and value type

Instances of command templates can be used instead of queries and updates.