Classes, constructors, constraints and properties of the dataspace's domain model

Ontologies

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

Ontologies can import other ontologies, both user-defined\n and system ones provided by LinkedDataHub. The dataspace's namespace ontology is resolved as a native owl:imports union graph —\n the transitive closure of its imports — which is cached per ontology URI. No inference is materialized: the terms are served exactly as declared.

An ontology URI is resolved against the store first and the platform's bundled copies second: a document in the admin dataspace that declares\n the ontology (<uri> a owl:Ontology) is the graph that resolves, even for a vocabulary the platform ships a copy of. That is what lets\n an imported vocabulary and its annotations live in one document under the vocabulary's own URI.

Package ontologies join the dataspace's imports closure automatically. They are derived from the dataspace's\n ldh:import declarations at ontology load time and declared as owl:imports of the namespace ontology, so they resolve\n like any other import. On the first request after the import, the package ontology is materialized: copied verbatim into a document under the\n admin dataspace's ontologies/ container, named after the package's path (ontologies/editor-taxonomy/ for the taxonomy editor),\n with the ontology as its foaf:primaryTopic. From then on that document is what the closure resolves the package ontology to, and its constructors,\n constraints and views are edited like the namespace ontology's. A later change to the published package does not reach the dataspace until the document\n is deleted, after which the next request materializes the package again.

\n warning\n

\n Best practice: avoid using owl:imports with uploaded files\n

Do not use owl:imports declarations that point to paths under uploads/. This can cause circular dependency deadlocks\n during system initialization, as the ontology loading process cannot access uploaded files without creating a circular reference.

Instead:

Host ontologies as proper documents (not uploaded files)
Import them using their document URIs
If you need to use an ontology that was uploaded, create it as a proper ontology document first

For more information, see the file upload documentation.

Main ontology properties:

Imports: The URI of another ontology whose terms are pulled into this ontology's imports closure (owl:imports)
Version: Version identifier of the ontology (owl:versionInfo)

System ontologies

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

System ontologies and their prefixes
Ontology	Title	Prefix
`https://w3id.org/atomgraph/linkeddatahub/default#`	Default	`def:`
`https://w3id.org/atomgraph/linkeddatahub/dataspaces#`	Dataspaces	`lds:`
`https://w3id.org/atomgraph/linkeddatahub/admin/acl#`	Access control	`lacl:`
`https://w3id.org/atomgraph/linkeddatahub/admin#`	Admin	`adm:`
`https://w3id.org/atomgraph/linkeddatahub#`	LinkedDataHub	`ldh:`
`https://w3id.org/atomgraph/linkeddatahub/document-hierarchy#`	Document hierarchy	`dh:`

Classes

Classes are RDFS/OWL classes declared in the dataspace's namespace ontology. Their instances live in the dataspace dataset.

The main class properties, explained in the sub-sections below:

Constructors: Queries that construct a new class instance
Constraints: Commands or command templates that validate a class instance

Constructors

Constructors are SPARQL CONSTRUCT queries that serve as templates for class instances.\n They specify the properties (both mandatory and optional) that the instance is supposed to have, as well as expected datatypes of their\n values. Constructors drive the resource creation and editing forms. A class can have multiple constructors.

The Northwind demo wires a constructor onto schema:Product, which is what makes the Product create form offer the right controls:

schema:Product spin:constructor :ProductConstructor ;\n    spin:constraint :MissingName .\n\n:ProductConstructor a ldh:Constructor ;\n    rdfs:label \"Product constructor\" ;\n    dct:title \"Product constructor\" ;\n    sp:text \"\"\"\n        PREFIX schema:  <https://schema.org/>\n        PREFIX dct:     <http://purl.org/dc/terms/>\n        PREFIX xsd:     <http://www.w3.org/2001/XMLSchema#>\n\n        CONSTRUCT {\n            $this dct:title [ a xsd:string ] ;\n                schema:name [ a xsd:string ] ;\n                schema:identifier [ a xsd:string ] ;\n                schema:description [ a xsd:string ] ;\n                schema:category [ a schema:ProductGroup ] ;\n                schema:provider [ a schema:Corporation ] ;\n                schema:offers [ a schema:Offer ] .\n        }\n        WHERE {}\"\"\" ;\n    rdfs:isDefinedBy : .

Source: admin/model/ns.ttl

A constructor can also supply a default value — the built-in ldh:XHTML constructor seeds new blocks with an empty XHTML literal:

PREFIX rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#>\n\nCONSTRUCT {\n  $this rdf:value \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\"></div>\"^^rdf:XMLLiteral .\n}\nWHERE {}

LinkedDataHub reuses SPIN constructors for the implementation, but adds a\n special syntax convention using blank nodes to indicate the expected resource type ([ a ex:Person ]) or literal datatype\n ([ a xsd:string ]). The magic variable $this refers to the instance being constructed. It starts as a blank node\n resource and is skolemized to a URI when the form is submitted to the server.

Note that classes inherit constructors from superclasses at runtime. A subclass constructor only needs to declare the properties its\n superclasses do not already declare.

Constructor instances are instantiated client-side: the constructors of the resource's types (including the superclass closure) are expanded\n onto a single instance. For that to work, a constructor has to have an empty WHERE clause, as in the example above.

Constraints

Constraints are SPARQL queries or SPIN command templates that validate submitted\n RDF data during document creation and editing. A constraint applies to instances of the class it is declared on and reports violations —\n missing mandatory properties, malformed values and so on. For example, an instance of\n dh:Item without dct:title will fail validation because titles are mandatory for LinkedDataHub documents.

The most common constraint shape is the missing-property check. The Northwind demo requires every Product to have a name:

:MissingName a ldh:MissingPropertyValue ;\n    rdfs:label \"Missing schema:name\" ;\n    sp:arg1 schema:name ;\n    rdfs:isDefinedBy : .

Submitting a Product without schema:name is then rejected with 422 Unprocessable Entity, and the response body\n describes the violation in RDF:

[ a spin:ConstraintViolation ;\n    rdfs:label \"Missing schema:name\" ;\n    spin:violationRoot <#this> ;\n    spin:violationPath schema:name ] .

LinkedDataHub reuses SPIN constraints. Classes inherit constraints from superclasses.

SHACL constraint validation is supported as well: SHACL shapes declared in the ontology\n (or in any ontology of its imports closure) are validated with Jena SHACL\n alongside the SPIN constraints, and a violation is likewise rejected with 422 Unprocessable Entity.

Properties

You can define new properties. Like classes, properties are declared in the dataspace's namespace ontology.\n The expected values of a property on a class are described either with a SPIN property constraint (a mandatory-property check)\n or with an OWL restriction, both of which the creation and editing forms enforce.

Restrictions

An owl:Restriction pins the cardinality of a property. The Northwind model, for example, declares its properties with\n domains and ranges, and pins the sales-rep cardinality with a restriction — every order has exactly one:

schema:broker a owl:ObjectProperty ;\n    rdfs:label \"Sales rep\";\n    rdfs:domain schema:Order ;\n    rdfs:range schema:Person ;\n    rdfs:isDefinedBy : .\n\n[] a owl:Restriction ;\n    owl:onProperty schema:broker ;\n    owl:minCardinality 1 ;\n    owl:maxCardinality 1 ;\n    rdfs:isDefinedBy : .

Source: admin/model/ns.ttl

Importing external vocabularies

The Import ontology action loads an external vocabulary into a document of the admin dataspace and derives instance\n constructors for its classes. The vocabulary stays in that document, under its own URI and with its own header, and the\n derived constructors are appended beside it; the document names the vocabulary as its foaf:primaryTopic rather than claiming to be an ontology\n itself. The dataspace's namespace ontology imports the vocabulary URI, which resolves to that document because it declares the vocabulary — so the\n constructors are edited where the vocabulary is, and nothing has to be re-fetched from the network or a bundled copy.

\n $\"The$ \n

Importing the SKOS vocabulary, for example, leaves the target document with content of this shape (abridged):

<> a dh:Item ;\n    foaf:primaryTopic <http://www.w3.org/2004/02/skos/core> .    # the document is about the vocabulary\n\n<http://www.w3.org/2004/02/skos/core> a owl:Ontology .          # the vocabulary's own header and terms follow\n\nskos:Concept spin:constructor [ a ldh:Constructor ;\n    sp:text \"\"\"\n        PREFIX skos: <http://www.w3.org/2004/02/skos/core#>\n        PREFIX xsd:  <http://www.w3.org/2001/XMLSchema#>\n\n        CONSTRUCT {\n            $this skos:prefLabel [ a xsd:string ] ;\n                skos:broader [ a skos:Concept ] .\n        }\n        WHERE {}\"\"\" ] .                                       # …one derived constructor per class

Management

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Ontology actions and their CLI commands
Action	CLI command
Create ontology	`ldh admin create ontology`
Import external vocabulary	`ldh admin import ontology`
Add ontology import	`ldh admin add ontology-import`
Clear ontology from cache	`ldh admin clear ontology`
Create class	`ldh admin add class`
Add constructor	`ldh admin add constructor`
Add property constraint	`ldh admin add property-constraint`
Add restriction	`ldh admin add restriction`

To evolve your dataspace's model in practice, follow the Change model guide.