Knora IRIs
The IRIs used in Knora repositories and in the DSP-API v2 follow certain conventions.
Project Short-Codes
A project short-code is a hexadecimal number of at least four digits, assigned by the DaSCH to uniquely identify a Knora project regardless of where it is hosted. The IRIs of ontologies that are built into Knora do not contain shortcodes; these ontologies implicitly belong to the Knora system project.
A user-created ontology IRI must always include its project shortcode.
Project ID 0000 is reserved for shared ontologies
(see Shared Ontologies).
The range of project IDs from 0001 to 00FF inclusive is reserved for
local testing. Thus, the first useful project will be 0100.
In the beginning, Unil will use the IDs 0100 to 07FF, and Unibas
0800 to 08FF.
IRIs for Ontologies and Ontology Entities
Internal Ontology IRIs
Knora makes a distinction between internal and external ontologies. Internal ontologies are used in the triplestore, while external ontologies are used in API v2. For each internal ontology, there is a corresponding external ontology. Some internal ontologies are built into Knora, while others are user-created. Knora automatically generates external ontologies based on user-created internal ontologies.
Each internal ontology has an IRI, which is also the IRI of the named graph that contains the ontology in the triplestore. An internal ontology IRI has the form:
http://www.knora.org/ontology/PROJECT_SHORTCODE/ONTOLOGY_NAME
For example, the internal ontology IRI based on project code 0001 and ontology
name example would be:
http://www.knora.org/ontology/0001/example
An ontology name must be a valid XML NCName and must be URL safe. The following names are reserved for built-in internal DSP ontologies:
knora-basestandoffsalsah-gui
Names starting with knora are reserved for future built-in Knora
ontologies. A user-created ontology name may not start with the
letter v followed by a digit, and may not contain these reserved
words:
knoraontologysimpleshared
External Ontology IRIs
Unlike internal ontology IRIs, external ontology IRIs are meant to be dereferenced as URLs. When an ontology IRI is dereferenced, the ontology itself can be served either in a machine-readable format or as human-readable documentation.
The IRI of an external Knora ontology has the form:
http://HOST[:PORT]/ontology/PROJECT_SHORTCODE/ONTOLOGY_NAME/API_VERSION
For built-in and shared ontologies, the host is always api.knora.org. Otherwise,
the hostname and port configured in application.conf under
app.http.knora-api.host and app.http.knora-api.http-port are used
(the port is omitted if it is 80).
This means that when a built-in or shared external ontology IRI is dereferenced,
the ontology can be served by a DSP-API server running at
api.knora.org. When the external IRI of a non-shared, project-specific ontology is
dereferenced, the ontology can be served by Knora that
hosts the project. During development and testing, this could be
localhost.
The name of an external ontology is the same as the name of the
corresponding internal ontology, with one exception: the external form
of knora-base is called knora-api.
The API version identifier indicates not only the version of the API, but also an API 'schema'. The DSP-API v2 is available in two schemas:
- A complex schema, which is suitable both for reading and for editing
data. The complex schema represents values primarily as complex
objects. Its version identifier is
v2. - A simple schema, which is suitable for reading data but not for
editing it. The simple schema facilitates interoperability between
DSP ontologies and non-DSP ontologies, since it represents
values primarily as literals. Its version identifier is
simple/v2.
Other schemas could be added in the future for more specific use cases.
When requesting an ontology, the client requests a particular schema. (This will also be true of most DSP-API v2 requests: the client will be able to specify which schema the response should be provided in.)
For example, suppose a DSP-API server is running at
knora.example.org and hosts an ontology whose internal IRI is
http://www.knora.org/ontology/0001/example. That ontology can then be
requested using either of these IRIs:
http://knora.example.org/ontology/0001/example/v2(in the complex schema)http://knora.example.org/ontology/0001/example/simple/v2(in the simple schema)
While the internal example ontology refers to definitions in
knora-base, the external example ontology that is served by the API
refers instead to a knora-api ontology, whose IRI depends on the
schema being used:
http://api.knora.org/ontology/knora-api/v2(in the complex schema)http://api.knora.org/ontology/knora-api/simple/v2(in the simple schema)
Ontology Entity IRIs
DSP ontologies use 'hash namespaces' (see URI
Namespaces).
This means that the IRI of an ontology entity (a class or property
definition) is constructed by adding a hash character (#) to the
ontology IRI, followed by the name of the entity. In Knora, an entity
name must be a valid XML
NCName.
Thus, if there is a class called ExampleThing in an ontology whose
internal IRI is http://www.knora.org/ontology/0001/example, that class
has the following IRIs:
http://www.knora.org/ontology/0001/example#ExampleThing(in the internal ontology)http://HOST[:PORT]/ontology/0001/example/v2#ExampleThing(in the API v2 complex schema)http://HOST[:PORT]/ontology/0001/example/simple/v2#ExampleThing(in the API v2 simple schema)
Shared Ontology IRIs
As explained in Shared Ontologies, a user-created ontology can be defined as shared, meaning that it can be used by multiple projects, and that its creators will not change it in ways that could affect other ontologies or data that are based on it.
There is currently one project for shared ontologies:
http://www.knora.org/ontology/knora-base#DefaultSharedOntologiesProject
Its project code is 0000. Additional projects for shared ontologies may be supported
in future.
The internal and external IRIs of shared ontologies always use the hostname
api.knora.org, and have an additional segment, shared, after ontology.
The project code can be omitted, in which case the default shared ontology
project, 0000, is assumed. The sample shared ontology, example-box, has these IRIs:
http://www.knora.org/ontology/shared/example-box(internal)http://api.knora.org/ontology/shared/example-box/v2(external, complex schema)http://api.knora.org/ontology/shared/example-box/simple/v2(external, simple schema)
IRIs for Data
Knora generates IRIs for data that it creates in the triplestore. Each generated data IRI contains one or more UUID identifiers to make it unique. To keep data IRIs relatively short, each UUID is base64url-encoded, without padding; thus each UUID is a 22-character string. DSP-API supports UUID version 4 or 5.
Data IRIs are not currently intended to be dereferenced as URLs. Instead, each Knora resource has a separate permalink.
A Knora value does not have a stable IRI throughout its version history. Each time a new version of a value is made, the new version gets a new IRI. Therefore, it would not make sense to publish Knora value IRIs. When designing ontologies for Knora projects, keep in mind that if you want something be directly citable, it needs to be a resource, not a value.
The formats of generated data IRIs for different types of objects are as follows:
- Resource:
http://rdfh.ch/PROJECT_SHORTCODE/RESOURCE_UUID. - Value:
http://rdfh.ch/PROJECT_SHORTCODE/RESOURCE_UUID/values/VALUE_UUID - Standoff tag:
http://rdfh.ch/PROJECT_SHORTCODE/RESOURCE_UUID/values/VALUE_UUID/STANDOFF_UUID - XML-to-standoff mapping:
http://rdfh.ch/projects/PROJECT_SHORTCODE/mappings/MAPPING_NAME - XML-to-standoff mapping element:
http://rdfh.ch/projects/PROJECT_SHORTCODE/mappings/MAPPING_NAME/elements/MAPPING_ELEMENT_UUID - Project:
http://rdfh.ch/projects/PROJECT_UUID - Group:
http://rdfh.ch/groups/PROJECT_SHORTCODE/GROUP_UUID - Permission:
http://rdfh.ch/permissions/PROJECT_SHORTCODE/PERMISSION_UUID - Lists:
http://rdfh.ch/lists/PROJECT_SHORTCODE/LIST_UUID - User:
http://rdfh.ch/users/USER_UUID