The IRIs used in Knora repositories and in the Knora API v2 follow certain conventions.
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.
0000 is reserved for shared ontologies (see Shared Ontologies).
The range of project IDs from
00FF inclusive is reserved for local testing. Thus, the first useful project will be
In the beginning, Unil will use the IDs
07FF, and Unibas
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:
For example, the internal ontology IRI based on project code
0001 and ontology name
example would be:
An ontology name must be a valid XML NCName. The following names are reserved for built-in internal Knora ontologies:
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:
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:
For built-in and shared ontologies, the host is always
api.knora.org. Otherwise, the hostname and port configured in
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 Knora 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
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
The API version identifier indicates not only the version of the API, but also an API ‘schema’. The Knora 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
- A simple schema, which is suitable for reading data but not for editing it. The simple schema facilitates interoperability between Knora ontologies and non-Knora ontologies, since it represents values primarily as literals. Its version identifier is
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 Knora API v2 requests: the client will be able to specify which schema the response should be provided in.)
For example, suppose a Knora 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)
Knora 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)
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:
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,
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://api.knora.org/ontology/shared/example-box/v2(external, complex schema)
http://api.knora.org/ontology/shared/example-box/simple/v2(external, simple schema)
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.
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:
- Standoff tag:
- XML-to-standoff mapping:
- XML-to-standoff mapping element: