This section introduces some of the basic concepts involved in creating
+ontologies for DSP projects, by means of a relatively simple example
+project. Before reading this document, it will be helpful to have some
+familiarity with the basic concepts explained in knora-base.
+
DSP-API comes with two example projects, called incunabula and
+images-demo. Here we will consider the incunabula example, which is
+a reduced version of a real research project on early printed books. It
+is designed to store an image of each page of each book, as well as RDF
+data about books, pages, their contents, and relationships between them.
+
The Incunabula Ontology
+
Here we will just focus on some of the main aspects of the ontology. An
+ontology file typically begins by defining prefixes for the IRIs of
+other ontologies that will be referred to. First there are some prefixes
+for ontologies that are very commonly used in RDF:
The rdf, rdfs, and owl ontologies contain basic properties that
+are used to define ontology entities. The xsd ontology contains
+definitions of literal data types such as string and integer. (For
+more information about these ontologies, see the references in
+knora-base.) The foaf ontology contains classes and properties for
+representing people. The dcterms ontology represents Dublin
+Core metadata.
The knora-base ontology contains DSP-API's core abstractions, and is
+described in knora-base. The salsah-gui ontology includes properties
+that DSP projects must use to enable SALSAH, DSP-API's generic virtual
+research environment.
+
For convenience, we can use the empty prefix to refer to the
+incunabula ontology itself:
However, outside the ontology file, it would make more sense to define
+an incunabula prefix to refer to the incunabula ontology.
+
Properties
+
All the content produced by a DSP project must be stored in Knora
+resources (see incunabula-resource-classes). Resources have properties
+that point to different parts of their contents; for example, the
+incunabula project contains books, which have properties like title.
+Every property that poitns to a DSP value must be a subproperty of
+knora-base:hasValue, and every property that points to another Knora
+resource must be a subproperty of knora-base:hasLinkTo.
+
Here is the definition of the incunabula:title property:
The definition of incunabula:title consists of a list of triples, all
+of which have :title as their subject. To avoid repeating :title for
+each triple, Turtle syntax allows us to use a semicolon (;) to
+separate triples that have the same subject. Moreover, some triples also
+have the same predicate; a comma (,) is used to avoid repeating the
+predicate. The definition of :title says:
+
+
rdf:type owl:ObjectProperty: It is an owl:ObjectProperty. There are
+ two kinds of OWL properties: object properties and datatype properties.
+ Object properties point to objects, which have IRIs and
+ can have their own properties. Datatype properties point to literal
+ values, such as strings and integers.
+
rdfs:subPropertyOf knora-base:hasValue, dcterms:title: It is a
+ subproperty of knora-base:hasValue and dcterms:title. Since the
+ objects of this property will be Knora values, it must be a
+ subproperty of knora-base:hasValue. To facilitate searches, we
+ have also chosen to make it a subproperty of dcterms:title. In the
+ DSP-API v2, if you do a search for resources that have a certain
+ dcterms:title, and there is a resource with a matching
+ incunabula:title, the search results could include that resource.
+
rdfs:label "Titel"@de, etc.: It has the specified labels in
+ various languages. These are needed, for example, by user
+ interfaces, to prompt the user to enter a value.
+
knora-base:subjectClassConstraint :book: The subject of the
+ property must be an incunabula:book.
+
knora-base:objectClassConstraint knora-base:TextValue: The object
+ of this property must be a knora-base:TextValue (which is a
+ subclass of knora-base:Value).
+
salsah-gui:guiElement salsah-gui:SimpleText: When SALSAH asks a
+ user to enter a value for this property, it should use a simple text
+ field.
+
salsah-gui:guiAttribute "size=80" , "maxlength=255": The SALSAH
+ text field for entering a value for this property should be 80
+ characters wide, and should accept at most 255 characters.
+
+
The incunabula ontology contains several other property definitions
+that are basically similar. Note that different subclasses of Value
+are used. For example, incunabula:pubdate, which represents the
+publication date of a book, points to a knora-base:DateValue. The
+DateValue class stores a date range, with a specified degree of
+precision and a preferred calendar system for display.
+
A property can point to a Knora resource instead of to a Knora value.
+For example, in the incunabula ontology, there are resources
+representing pages and books, and each page is part of some book. This
+relationship is expressed using the property incunabula:partOf:
+
:partOf rdf:type owl:ObjectProperty ;
+
+ rdfs:subPropertyOf knora-base:isPartOf ;
+
+ rdfs:label "ist ein Teil von"@de ,
+ "est un part de"@fr ,
+ "e una parte di"@it ,
+ "is a part of"@en ;
+
+ rdfs:comment """Diese Property bezeichnet eine Verbindung zu einer anderen Resource, in dem ausgesagt wird, dass die vorliegende Resource ein integraler Teil der anderen Resource ist. Zum Beispiel ist eine Buchseite ein integraler Bestandteil genau eines Buches."""@de ;
+
+ knora-base:subjectClassConstraint :page ;
+
+ knora-base:objectClassConstraint :book ;
+
+ salsah-gui:guiElement salsah-gui:Searchbox .
+
+
The key things to notice here are:
+
+
rdfs:subPropertyOf knora-base:isPartOf: The knora-base ontology provides a generic isPartOf property to express
+ part-whole relationships. A project may use knora-base:isPartOf directly, however creating a subproperty such as
+ incunabula:partOf will allow to customize the property further, e.g. by giving it a more descriptive label.
+ It is important to note that knora-base:isPartOf is a subproperty of knora-base:hasLinkTo. Any property that
+ points to a knora-base:Resource must be a subproperty of knora-base:hasLinkTo. Such a
+ property is called a link property.
+
knora-base:objectClassConstraint :book: The object of this property must be a member of the class incunabula:book,
+ which, as we will see below, is a subclass of knora-base:Resource.
+
salsah-gui:guiElement salsah-gui:Searchbox: When SALSAH prompts a user to select the book that a page is part of, it
+ should provide a search box enabling the user to find the desired book.
+
+
Because incunabula:partOf is a link property, it must always
+accompanied by a link value property, which enables Knora to store
+metadata about each link that is created with the link property. This
+metadata includes the date and time when the link was created, its
+owner, the permissions it grants, and whether it has been deleted.
+Storing this metadata allows Knora to authorise users to see or modify
+the link, as well as to query a previous state of a repository in which
+a deleted link had not yet been deleted. (The ability to query previous
+states of a repository is planned for DSP-API version 2.)
+
The name of a link property and its link value property must be related
+by the following naming convention: to determine the name of the link
+value property, add the word Value to the name of the link property.
+Hence, the incunabula ontology defines the property partOfValue:
As a link value property, incunabula:partOfValue must point to a
+knora-base:LinkValue. The LinkValue class is an RDF reification of
+a triple (in this case, the triple that links a page to a book). For
+more details about this, see knora-base-linkvalue.
+
Note that the property incunabula:hasAuthor points to a
+knora-base:TextValue, because the incunabula project represents
+authors simply by their names. A more complex project could represent
+each author as a resource, in which case incunabula:hasAuthor would
+need to be a subproperty of knora-base:hasLinkTo.
+
Resource Classes
+
The two main resource classes in the incunabula ontology are book
+and page. Here is incunabula:book:
Like every Knora resource class, incunabula:book is a subclass of
+knora-base:Resource. It is also a subclass of a number of other
+classes of type owl:Restriction, which are defined in square brackets,
+using Turtle's syntax for anonymous blank nodes. Each owl:Restriction
+specifies a cardinality for a property that is allowed in resources of
+type incunabula:book. A cardinality is indeed a kind of restriction:
+it means that a resource of this type may have, or must have, a certain
+number of instances of the specified property. For example,
+incunabula:book has cardinalities saying that a book must have at
+least one title and at most one publication date. In the DSP-API
+version 1, the word 'occurrence' is used instead of 'cardinality'.
+
The OWL cardinalities supported by Knora are described in
+OWL Cardinalities.
+
Note that incunabula:book specifies a cardinality of
+owl:minCardinality 0 on the property incunabula:hasAuthor. At first
+glance, this might seem as if it serves no purpose, since it says that
+the property is optional and can have any number of instances. You may
+be wondering whether this cardinality could simply be omitted from the
+definition of incunabula:book. However, Knora requires every property
+of a resource to have some cardinality in the resource's class. This is
+because Knora uses the cardinalities to determine which properties are
+possible for instances of the class, and the DSP-API relies on this
+information. If there was no cardinality for incunabula:hasAuthor,
+Knora would not allow a book to have an author.
+
Each owl:Restriction specifying a cardinality can include the predicate
+salsah-gui:guiOrder, which tells the SALSAH GUI the order the properties
+should be displayed in.
The incunabula:page class is a subclass of
+knora-base:StillImageRepresentation, which is a subclass of
+knora-base:Representation, which is a subclass of
+knora-base:Resource. The class knora-base:Representation is used for
+resources that contain metadata about files stored by Knora. Each It has
+different subclasses that can hold different types of files, including
+still images, audio, and video files. A given Representation can store
+metadata about several different files, as long as they are of the same
+type and are semantically equivalent, e.g. are different versions of the
+same image with different colorspaces, so that coordinates in one file
+will work in the other files.
+
In Knora, a subclass inherits the cardinalities defined in its
+superclasses. Let's look at the class hierarchy of incunabula:page,
+starting with knora-base:Representation:
+
:Representation rdf:type owl:Class ;
+
+ rdfs:subClassOf :Resource , [
+ rdf:type owl:Restriction ;
+ owl:onProperty :hasFileValue ;
+ owl:minCardinality "1"^^xsd:nonNegativeInteger
+ ] ;
+
+ rdfs:comment "A resource that can store one or more FileValues"@en .
+
+
This says that a Representation must have at least one instance of the
+property hasFileValue, which is defined like this:
The subject of hasFileValue must be a Representation, and its object
+must be a FileValue. There are different subclasses of FileValue for
+different kinds of files, but we'll skip the details here.
+
This is the definition of knora-base:StillImageRepresentation:
+
:StillImageRepresentation rdf:type owl:Class ;
+
+ rdfs:subClassOf :Representation , [
+ rdf:type owl:Restriction ;
+ owl:onProperty :hasStillImageFileValue ;
+ owl:minCardinality "1"^^xsd:nonNegativeInteger
+ ] ;
+
+ rdfs:comment "A resource that can contain two-dimensional still image files"@en .
+
+
It must have at least one instance of the property
+hasStillImageFileValue, which is defined as follows:
Because hasStillImageFileValue is a subproperty of hasFileValue, the
+cardinality on hasStillImageFileValue, defined in the subclass
+StillImageRepresentation, overrides the cardinality on hasFileValue,
+defined in the superclass Representation. In other words, the more
+general cardinality in the superclass is replaced by a more specific
+cardinality in the base class. Since incunabula:page is a subclass of
+StillImageRepresentation, it inherits the cardinality on
+hasStillImageFileValue. As a result, a page must have at least one
+image file value attached to it.
+
Here's another example of cardinality inheritance. The class
+knora-base:Resource has a cardinality for knora-base:seqnum. The
+idea is that resources of any type could be arranged in some sort of
+sequence. As we saw above, incunabula:page is a subclass of
+knora-base:Resource. But incunabula:page has its own cardinality for
+incunabula:seqnum, which is a subproperty of knora-base:seqnum. Once
+again, the subclass's cardinality on the subproperty replaces the
+superclass's cardinality on the superproperty: a page is allowed to have
+an incunabula:seqnum, but it is not allowed to have a
+knora-base:seqnum.
Currently, only a limited number of file formats is accepted to be uploaded onto DSP.
+Some metadata is extracted from the files during the ingest but the file formats are not validated.
+Only image file formats are currently migrated into another format.
+Both, the migrated version of the file and the original are kept.
+
The following table shows the accepted file formats:
Standoff markup
+is text markup that is stored separately from the content it describes. DSP-API's
+Standoff/RDF markup stores content as a simple Unicode string, and represents markup
+separately as RDF data. This approach has some advantages over commonly used markup systems
+such as XML:
+
First, XML and other hierarchical markup systems assume that a document is a hierarchy, and
+have difficulty representing non-hierarchical structures
+or multiple overlapping hierarchies. Standoff markup can easily represent these structures.
+
Second, markup languages are typically designed to be used in text files. But there is no
+standard system for searching and linking together many different text files containing
+markup. It is possible to do this in a non-standard way by using an XML database
+such as eXist, but this still does not allow for queries that include
+text as well as non-textual data not stored in XML.
+
By storing markup as RDF, DSP-API can search for markup structures in the same way as it
+searches for any RDF data structure. This makes it possible to do searches that combine
+text-related criteria with other sorts of criteria. For example, if persons and events are
+represented as resources, and texts are represented in Standoff/RDF, a text can contain
+tags representing links to persons or events. You could then search for a text that mentions a
+person who lived in the same city as another person who is the author of a text that mentions an
+event that occurred during a certain time period.
+
In DSP-API's Standoff/RDF, a tag is an RDF entity that is linked to a
+text value. Each tag points to a substring
+of the text, and has semantic properties of its own. You can define your own tag classes
+in your ontology by making subclasses of knora-base:StandoffTag, and attach your own
+properties to them. You can then search for those properties using DSP-API's search language,
+Gravsearch.
+
The built-in knora-base and standoff ontologies
+provide some basic tags that can be reused or extended. These include tags that represent
+DSP-API data types. For example, knora-base:StandoffDateTag represents a date in exactly the
+same way as a date value, i.e. as a
+calendar-independent astronomical date. You can use this tag as-is, or extend it by making
+a subclass, to represent dates in texts. Gravsearch includes built-in functionality for
+searching for these data type tags. For example, you can search for text containing a date that
+falls within a certain date range.
+
DSP-API supports automatic conversion between XML and Standoff/RDF. To make this work,
+Standoff/RDF stores the order of tags and their hierarchical relationships. You must define an
+XML-to-Standoff Mapping for your standoff tag classes and properties.
+Then you can import an XML document into DSP-API, which will store it as Standoff/RDF. The text and markup
+can then be searched using Gravsearch. When you retrieve the document, DSP-API converts it back to the
+original XML.
+
To represent overlapping or non-hierarchical markup in exported and imported XML, DSP-API supports
+CLIX tags.
+
As XML-to-Standoff has proved to be complicated and not very well performing,
+the use of standoff with custom mappings is discouraged.
+Improved integration of text with XML mark up, particularly TEI-XML, is in planning.
The DaSCH Service Platform (DSP) is
+a content management system for the long-term preservation and reuse of
+humanities data. It is designed to accommodate data with a complex internal
+structure, including data that could be stored in relational databases.
+
DSP aims to solve key problems in the long-term preservation and reuse
+of humanities data:
+
First, traditional archives preserve data, but do not facilitate reuse. Typically,
+only metadata can be searched, not the data itself. You have to first identify
+an information package that might be of interest, then download it, and only
+then can you find out what's really in it. This is time-consuming, and
+makes it impractical to reuse data from many different sources.
+
DSP solves this problem by keeping the data alive. You can query all the data
+in a DSP repository, not just the metadata. You can import thousands of databases into
+DSP, and run queries that search through all of them at once.
+
Another problem is that researchers use a multitude of different file formats, many of
+which are proprietary and quickly become obsolete. It is not practical to maintain
+all the programs that were used to create and read old files, or even
+all the operating systems that these programs ran on. Therefore, DSP only accepts a
+certain number of file formats.
+
+
Non-binary data is stored as
+ RDF, in a dedicated
+ database called a triplestore. RDF is an open, vendor-independent standard
+ that can express any data structure.
+
Binary media files (images, audio, and video) are converted to a few specialised
+ archival file formats and stored by Sipi,
+ with metadata stored in the triplestore.
+
+
DSP makes this data available for reuse via its generic, standards-based
+application programming interface DSP-API. A virtual research environment
+(VRE) can use DSP-API to query, link, and add to data
+from different research projects in a unified way.
+
Humanities-Focused Data Storage
+
Each project creates its own data model (or ontology), describing the types of
+items it wishes to store, using basic data types defined in Knora's
+base ontology.
+This gives projects the freedom to describe their data in a way that makes
+sense to them, while allowing DSP to support searching and linking across projects.
+
DSP has built-in support for data structures that are commonly needed in
+humanities data, and that present unique challenges for any type of database storage.
+
Calendar-Independent Dates
+
In the humanities, a date could be based on any sort of calendar (e.g.
+Gregorian, Julian, Islamic, or Hebrew). The DSP stores dates using a calendar-independent,
+astronomical representation, and converts between calendars as needed. This makes
+it possible to search for a date in one calendar, and get search results in other calendars.
+
Flexible, Searchable Text Markup
+
Commonly used text markup systems, such as TEI/XML,
+have to represent a text as a hierarchy, and therefore have trouble supporting
+overlapping markup. DSP supports Standoff/RDF markup: the markup is stored
+as RDF data, separately from the text, allowing for overlapping markup. The DSP
+can import any XML document (including TEI/XML) for storage as standoff/RDF,
+and can regenerate the original XML document at any time.
+
Powerful Searches
+
DSP-API provides a search language, Gravsearch,
+that is designed to meet the needs of humanities researchers. Gravsearch supports DSP-API's
+humanities-focused data structures, including calendar-independent dates and standoff markup, as well
+as fast full-text searches. This allows searches to combine text-related criteria with any other
+criteria. For example, you could search for a text that contains a certain word
+and also mentions a person who lived in the same city as another person who is the
+author of a text that mentions an event that occurred during a certain time period.
+
Access Control
+
The RDF standards do not include any concept of permissions. DSP-API's permission
+system allows project administrators and users to determine who can see or
+modify each item of data. DSP-API filters search results according to each
+user's permissions.
+
Data History
+
RDF does not have a concept of data history. DSP-API maintains all previous
+versions of each item of data. Ordinary searches return only the latest version,
+but you can
+obtain
+and
+cite
+an item as it was at any point in the past.
+
Data Consistency
+
RDF triplestores do not implement a standardised way of ensuring the consistency
+of data in a repository. DSP-API ensures that all data is consistent, conforms
+the project-specific data models, and meets DSP-API's minimum requirements
+for interoperability and reusability of data.
+
Linked Open Data
+
DSP-API supports publishing data online as Linked Open Data,
+using open standards to allow interoperability between different repositories
+on the web.
The DSP ontologies provide a generic framework for describing humanities
+research data, allowing data from different projects to be combined, augmented,
+and reused.
+
Resource Description Framework (RDF)
+
DSP-API uses a hierarchy of ontologies based on the Resource Description
+Framework
+(RDF), RDF
+Schema (RDFS), and
+the Web Ontology Language
+(OWL). Both RDFS and OWL
+are expressed in RDF. RDF expresses information as a set of statements
+(called triples). A triple consists of a subject, a predicate, and an
+object:
+
+
The object may be either a literal value (such as a name or number) or
+another subject. Thus it is possible to create complex graphs that
+connect many subjects, like this:
+
+
In RDF, each subject and predicate has a unique, URL-like identifier
+called an Internationalized Resource Identifier
+(IRI). Within a given project,
+IRIs typically differ only in their last component (the "local part"),
+which is often the fragment following a # character. Such IRIs share a
+long "prefix". In Turtle and similar
+formats for writing RDF, a short prefix label can be defined to
+represent the long prefix. Then an IRI can be written as a prefix label
+and a local part, separated by a colon (:). For example, if the
+"example" project's long prefix is http://www.example.org/rdf#, and it
+contains subjects with IRIs like http://www.example.org/rdf#book, we
+can define the prefix label ex to represent the prefix label, and
+write prefixed names for IRIs:
+
+
Built-in Ontologies and User-Created Ontologies
+
To ensure the interoperability of data produced by different projects,
+each project must describe its data model by creating one or more ontologies that
+extend Knora's built-in ontologies. The main built-in ontology in Knora
+is knora-base.
+
Shared Ontologies
+
Knora does not normally allow a project to use classes or properties defined in
+an ontology that belongs to another project. Each project must be free to change
+its own ontologies, but this is not possible if they have been used in ontologies
+or data created by other projects.
+
However, an 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. Specifically, in a shared
+ontology, existing classes and properties cannot safely be changed, but new ones
+can be added. (It is not even safe to add an optional cardinality to an existing
+class, because this could cause subclasses to violate the rule that a class cannot
+have a cardinality on property P as well as a cardinality on a subproperty of P;
+see Restrictions on Classes.)
The Knora base ontology is the main built-in Knora ontology. Each project that uses DSP-API must describe its data model
+by creating ontologies that extend this ontology.
+
The Knora base ontology is identified by the IRI http://www.knora.org/ontology/knora-base. In the DSP-API
+documentation in general, it is identified by the prefix knora-base, but for brevity, in this document, we use kb or
+omit the prefix entirely.
+
The Knora Data Model
+
The Knora data model is based on the observation that, in the humanities, a value or literal is often itself structured
+and can be highly complex. Moreover, a value may have its own metadata, such as its creation date, information about
+permissions, and so on. Therefore, the Knora base ontology describes structured value types that can store this type of
+metadata. In the diagram below, a book (ex:book2) has a title
+(identified by the predicate ex:title) and a publication date
+(ex:pubdate), each of which has some metadata.
+
+
Projects
+
In DSP-API, each item of data belongs to some particular project. Each project using DSP-API must define a
+kb:knoraProject, which has these properties (cardinalities are indicated in parentheses after each property name):
+
+
+
projectShortname (1): A short name that can be used to identify the project in configuration files and the like.
+
+
+
projectLongname (0-1): The full name of the project.
+
+
+
projectShortcode (1): A hexadecimal code that uniquely identifies the project. These codes are assigned to projects
+ by the DaSCH.
+
+
+
projectDescription (1-n): A description of the project.
+
+
+
Ontologies and resources are associated with a project by means of the
+kb:attachedToProject property, as described in Ontologies
+and Properties of Resource). Users are associated with a project by means of
+the kb:isInProject property, as described in
+Users and Groups.
+
Ontologies
+
Each user-created ontology must be defined as an owl:Ontology with the properties rdfs:label
+and kb:attachedToProject.
+Since DSP-API v20kb:lastModificationDate property is
+also required.
+
Resources
+
All the content produced by a project (e.g. digitised primary source materials or research data) must be stored in
+objects that belong to subclasses of kb:Resource, so that DSP-API can query and update that content. Each project using
+the Knora base ontology must define its own OWL classes, derived from kb:Resource, to represent the types of data it
+deals with. A subclass of kb:Resource may additionally be a subclass of any other class, e.g. an industry-standard
+class such as foaf:Person; this can facilitate searches across projects.
+
Resources have properties that point to different parts of the content they contain. For example, a resource
+representing a book could have a property called hasAuthor, pointing to the author of the book. There are two possible
+kinds of content in a Knora resource: Knora values (see Values) or links to other resources (see
+Links Between Resources). Properties that point to Knora values must be subproperties
+of kb:hasValue, and properties that point to other resources must be subproperties of kb:hasLinkTo. Either of these
+two types of properties may also be a subproperty of any other property, e.g. an industry-standard property such
+as foaf:name; this can facilitate searches across projects. Each property definition must specify the types that its
+subjects and objects must belong to (see
+Constraints on the Types of Property Subjects and Objects
+for details).
+
Each user-created resource class definition must use OWL cardinality restrictions to specify the properties that
+resources of that class can have (see OWL Cardinalities for details).
+
Resources are not versioned; only their values are versioned (see
+Values).
+
Every resource is required to have an rdfs:label. The object of this property is an xsd:string, rather than a Knora
+value; hence it is not versioned. A user who has modify permission on a resource (see
+Authorisation) can change its label.
+
A resource can be marked as deleted; DSP-API does this by adding the predicate kb:isDeleted true to the resource. An
+optional kb:deleteComment may be added to explain why the resource has been marked as deleted. Deleted resources are
+normally hidden. They cannot be undeleted, because even though resources are not versioned, it is necessary to be able
+to find out when a resource was deleted. If desired, a new resource can be created by copying data from a deleted
+resource.
+
Properties of Resource
+
+
+
creationDate (1): The time when the resource was created.
+
+
+
attachedToUser (1): The user who owns the resource.
+
+
+
attachedToProject (1): The project that the resource is part of.
+
+
+
lastModificationDate (0-1): A timestamp indicating when the resource (or one of its values) was last modified.
+
+
+
seqnum (0-1): The sequence number of the resource, if it is part of an ordered group of resources, such as the pages
+ in a book.
+
+
+
isDeleted (1): Indicates whether the resource has been deleted.
+
+
+
deleteDate (0-1): If the resource has been deleted, indicates when it was deleted.
+
+
+
deleteComment (0-1): If the resource has been deleted, indicates why it was deleted.
+
+
+
Resources can have properties that point to other resources; see
+Links Between Resources. A resource grants permissions to groups of users;
+see Authorisation.
+
Representations
+
It is not practical to store all data in RDF. In particular, RDF is not a good storage medium for binary data such as
+images. Therefore, DSP-API stores such data outside the triplestore, in ordinary files. A resource can have metadata about
+a file attached to it. The technical term for such a resource in the Knora ontology is a Representation. For each file, there is
+a kb:FileValue in the triplestore containing metadata about the file (see FileValue). DSP-API
+uses Sipi to store files. The DSP-API provides ways to create file values.
+
A resource that has a file value must belong to one of the subclasses of
+kb:Representation. Its subclasses include:
+
+
+
StillImageRepresentation: A representation referring to a still image file which can be stored in Sipi or an external IIIF server.
+
+
+
MovingImageRepresentation: A representation containing a video file.
+
+
+
AudioRepresentation: A representation containing an audio file.
+
+
+
DDDrepresentation: A representation containing a 3D image file.
+
+
+
TextRepresentation: A representation containing a formatted text file, such as an XML file.
+
+
+
DocumentRepresentation: A representation containing a document (such as a PDF file) that is not a text file.
+
+
+
ArchiveRepresentation: A representation containing an archive file (such as a zip archive).
+
+
+
These classes can be used directly in data, but it is often better to make subclasses of them, to include metadata about
+the files being stored.
+
The base class of all these classes is Representation, which is not intended to be used directly. It has this
+property, which its subclasses override:
+
+
hasFileValue (1): Points to a file value.
+
+
There are two ways for a project to design classes for representations. The simpler way is to create a resource class
+that represents a thing in the world (such as ex:Painting) and also belongs to a subclass of Representation. This is
+adequate if the class can have only one type of file attached to it. For example, if paintings are represented only by
+still images, ex:Painting could be a subclass of StillImageRepresentation.
+
The more flexible approach, which is supported by DSP-API v2, is for each ex:Painting to
+link (using kb:hasRepresentation or a subproperty) to other resources containing files that represent the painting.
+Each of these other resources can extend a different subclass of Representation. For example, a painting could have a
+StillImageRepresentation as well as a DDDrepresentation.
+
Standard Resource Classes
+
In general, each project must define its own subclasses of kb:Resource. However, the Knora base ontology
+provides some standard subclasses of kb:Resource, which are intended to be used by any project:
+
+
+
Region: Represents a region of a Representation (see Representations).
+
+
+
Annotation: Represents an annotation of a resource.
+ The hasComment property points to the text of the annotation, represented as a kb:TextValue.
+
+
+
LinkObj: Represents a link that connects two or more resources.
+ A LinkObj has a hasLinkTo property pointing to each resource that it connects, as well as a hasLinkToValue
+ property pointing to a reification of each of these direct links (
+ see Links Between Resources).
+ A LinkObj is more complex (and hence less convenient and readable) than a simple direct link, but it has the
+ advantage that it can be annotated using an Annotation. For improved readability, a project can make its own
+ subclasses of LinkObj with specific meanings.
+
+
+
Values
+
The Knora base ontology defines a set of OWL classes that are derived from kb:Value and represent different types of
+structured values found in humanities data. This set of classes may not be extended by user-created ontologies.
+
A value is always part of one particular resource, which points to it using some property derived from hasValue. For
+example, a user-created ontology could specify a Book class with a property hasSummary (derived from hasValue),
+and that property could have a knora-base:objectClassConstraint of TextValue. This would mean that the summary of
+each book is represented as a TextValue.
+
Knora values are versioned. Existing values are not modified. Instead, a new version of an existing value is created.
+The new version is linked to the old version via the previousValue property.
+
Since each value version has a different IRI, there is no IRI that can be used to cite the value, such that it will
+always refer to the latest version of the value. Therefore, the latest version of each value has a separate UUID, as the
+object of the property valueHasUUID. When a new version of the value is created, this UUID is moved to the new
+version. This makes it possible to cite the latest version of a value by searching for the UUID.
+
"Deleting" a value means marking it with kb:isDeleted. An optional kb:deleteComment may be added to explain why the
+value has been marked as deleted. Deleted values are normally hidden.
+
Most types of values are marked as deleted without creating a new version of the value. However, link values must be
+treated as a special case. Before a LinkValue can be marked as deleted, its reference count must be decremented to 0.
+Therefore, a new version of the LinkValue is made, with a reference count of 0, and it is this new version that is
+marked as deleted.
+
To simplify the enforcement of ontology constraints, and for consistency with resource updates, no new versions of a
+deleted value can be made; it is not possible to undelete. Instead, if desired, a new value can be created by copying
+data from a deleted value.
+
Properties of Value
+
+
+
valueCreationDate (1): The date and time when the value was created.
+
+
+
attachedToUser (1): The user who owns the value.
+
+
+
valueHasString (1): A human-readable string representation of the value's contents, which is available to DSP-API's
+ full-text search index.
+
+
+
valueHasOrder (0-1): A resource may have several properties of the same type with different values (which will be of
+ the same class), and it may be necessary to indicate an order in which these values occur. For example, a book may
+ have several authors which should appear in a defined order. Hence, valueHasOrder, when present, points to an
+ integer literal indicating the order of a given value relative to the other values of the same property. These
+ integers will not necessarily start at any particular number, and will not necessarily be consecutive.
+
+
+
previousValue (0-1): The previous version of the value.
+
+
+
valueHasUUID (0-1): The UUID that refers to all versions of the value. Only the latest version of the value has this
+ property.
+
+
+
isDeleted (1): Indicates whether the value has been deleted.
+
+
+
deleteDate (0-1): If the value has been deleted, indicates when it was deleted.
+
+
+
deleteComment (0-1): If the value has been deleted, indicates why it was deleted.
+
+
+
Each Knora value can grant permissions (see Authorisation).
+
Subclasses of Value
+
TextValue
+
Represents text, possibly including markup. The text is the object of the valueHasString property. A line break is
+represented as a Unicode line feed character (U+000A). The non-printing Unicode character
+INFORMATION SEPARATOR TWO (U+001E) can be used to separate words that are separated only by standoff markup (see
+below), so they are recognised as separate in a full-text search index.
valueHasMapping (0-1): Points to the mapping used to create the standoff markup and to convert it back to the
+ original XML. See Mapping to Create Standoff From XML.
+
+
+
A text value can have a specified language:
+
+
valueHasLanguage (0-1): An ISO 639-1 code as string specifying the language of the text.
+
+
DateValue
+
Humanities data includes many different types of dates. A date has a specified calendar, and is always
+represented as a period with start and end points (which may be equal), each of which has a precision (DAY, MONTH,
+or YEAR). For GREGORIAN and JULIAN calendars, an optional ERA indicator term (BCE, CE, or BC, AD) can be
+added to the date, when no era is provided the default era AD will be considered. Internally, the start and end points
+are stored as two Julian Day Numbers. This calendar-independent representation makes it possible to compare and search
+for dates regardless of the calendar in which they were entered. Properties:
+
+
+
valueHasCalendar (1): The name of the calendar in which the date should be displayed. Currently GREGORIAN,
+ JULIAN, and ISLAMIC civil calendars are supported.
+
+
+
valueHasStartJDN (1): The Julian Day Number of the start of the period (an xsd:integer).
+
+
+
valueHasStartPrecision (1): The precision of the start of the period.
+
+
+
valueHasEndJDN (1): The Julian Day Number of the end of the period (an xsd:integer).
+
+
+
valueHasEndPrecision (1): The precision of the end of the period.
+
+
+
TimeValue
+
A Knora time value represents a precise moment in time in the Gregorian calendar. Since nanosecond precision can be
+included, it is suitable for use as a timestamp. Properties:
+
+
valueHasTimeStamp (1): An xsd:dateTimeStamp, stored as an xsd:dateTime (because SPARQL does not support
+ xsd:dateTimeStamp).
+
+
IntValue
+
Represents an integer. Property:
+
+
valueHasInteger (1): An xsd:integer.
+
+
ColorValue
+
+
valueHasColor (1): A string representing a color. The string encodes a color as hexadecimal RGB values, e.g.
+ \#FF0000.
+
+
DecimalValue
+
Represents an arbitrary-precision decimal number. Property:
+
+
valueHasDecimal (1): An xsd:decimal.
+
+
UriValue
+
Represents a non-Knora URI. Property:
+
+
valueHasUri (1): An xsd:anyURI.
+
+
BooleanValue
+
Represents a boolean value. Property:
+
+
valueHasBoolean (1): An xsd:boolean.
+
+
GeomValue
+
Represents a geometrical object as a JSON string, using normalized coordinates. Property:
+
+
valueHasGeometry (1): A JSON string.
+
+
GeonameValue
+
Represents a geolocation, using the identifiers found at GeoNames. Property:
+
+
valueHasGeonameCode (1): The identifier of a geographical feature from GeoNames, represented
+ as an xsd:string.
+
+
IntervalValue
+
Represents a time interval, with precise start and end times on a timeline, e.g. relative to the beginning of an audio
+or video file. Properties:
+
+
+
valueHasIntervalStart (1): An xsd:decimal representing the start of the interval in seconds.
+
+
+
valueHasIntervalEnd (1): An xsd:decimal representing the end of the interval in seconds.
+
+
+
ListValue
+
Projects often need to define lists or hierarchies of categories that can be assigned to many different resources. Then,
+for example, a user interface can provide a drop-down menu to allow the user to assign a category to a resource.
+The ListValue class provides a way to represent these sorts of data structures. It can represent either a flat list or
+a tree.
+
A ListValue has this property:
+
+
valueHasListNode (1): Points to a ListNode.
+
+
Each ListNode can have the following properties:
+
+
+
isRootNode (0-1): Set to true if this is the root node.
+
+
+
hasSubListNode (0-n): Points to the node's child nodes, if any.
+
+
+
hasRootNode (0-1): Points to the root node of the list (absent if isRootNode is true).
+
+
+
listNodePosition (0-1): An integer indicating the node's position in the list of its siblings (absent
+ if isRootNode is true).
+
+
+
listNodeName (0-1): The node's human-readable name (absent if isRootNode is true).
+
+
+
FileValue
+
DSP-API can store certain kinds of data outside the triplestore, in files (see Representations). Each
+digital object that is stored outside the triplestore has associated metadata, which is stored in the triplestore in
+a kb:FileValue. The base class FileValue, which is not intended to be used directly, has these properties:
+
+
+
internalFilename (1): The name of the file as stored by Knora.
+
+
+
internalMimeType (1): The MIME type of the file as stored by Knora.
+
+
+
originalFilename (0-1): The original name of the file when it was uploaded to the DSP-API server.
+
+
+
originalMimeType (0-1): The original MIME type of the file when it was uploaded to the Knora API server.
+
+
+
isPreview (0-1): A boolean indicating whether the file is a preview, i.e. a small image representing the contents of
+ the file. A preview is always a StillImageAbstractFileValue, regardless of the type of the enclosing Representation.
+
+
+
The subclasses of FileValue, which are intended to be used directly in data, include:
+
+
+
StillImageAbstractFileValue: Contains metadata about a still image file, which can be either StillImageFileValue (an image stored in Sipi) or StillImageExternalFileValue (a reference to an image stored in an external IIIF service).
+
+
+
MovingImageFileValue: Contains metadata about a video file.
+
+
+
AudioFileValue: Contains metadata about an audio file.
+
+
+
DDDFileValue: Contains metadata about a 3D image file.
+
+
+
TextFileValue: Contains metadata about a text file.
+
+
+
DocumentFileValue: Contains metadata about a document (such as PDF) that is not a text file.
+
+
+
ArchiveFileValue: Contains metadata about an archive (such as zio archive).
+
+
+
Each of these classes contains properties that are specific to the type of file it describes. For example, still image
+files have dimensions, video files have frame rates, and so on.
+
FileValue objects are versioned like other values, and the actual files stored by DSP-API are also versioned. Version 1
+of the DSP-API does not provide a way to retrieve a previous version of a file, but this feature will be added in a
+subsequent version of the API.
+
LinkValue
+
A LinkValue is an RDF "reification" containing metadata about a link between two resources. It is therefore a subclass
+of rdf:Statement as well as of Value. It has these properties:
+
rdf:subject (1)
+
: The resource that is the source of the link.
+
rdf:predicate (1)
+
: The link property.
+
rdf:object (1)
+
: The resource that is the target of the link.
+
valueHasRefCount (1)
+
: The reference count of the link. This is meaningful when the
+LinkValue describes resource references in Standoff text markup
+(see StandoffLinkTag). Otherwise, the reference count will always be 1 (if the link exists) or 0 (if
+it has been deleted).
Represents a resource that is not stored in the RDF triplestore managed by DSP-API, but instead resides in an external
+repository managed by some other software. The ExternalResValue contains the information that DSP-API needs in order to
+access the resource, assuming that a suitable gateway plugin is installed.
+
extResAccessInfo (1)
+
: The location of the repository containing the external resource
+(e.g. its URL).
+
extResId (1)
+
: The repository-specific ID of the external resource.
+
extResProvider (1)
+
: The name of the external provider of the resource.
+
Links Between Resources
+
A link between two resources is expressed, first of all, as a triple, in which the subject is the resource that is the
+source of the link, the predicate is a "link property" (a subproperty of kb:hasLinkTo), and the object is the resource
+that is the target of the link.
+
It is also useful to store metadata about links. For example, DSP-API needs to know who owns the link, who has permission
+to modify it, when it was created, and so on. Such metadata cannot simply describe the link property, because then it
+would refer to that property in general, not to any particular instance in which that property is used to connect two
+particular resources. To attach metadata to a specific link in RDF, it is necessary to create an RDF "reification". A
+reification makes statements about a particular triple (subject, predicate, object), in this case the triple that
+expresses the link between the resources. DSP-API uses reifications of type kb:LinkValue (described in
+LinkValue) to store metadata about links.
+
For example, suppose a project describes paintings that belong to collections. The project can define an ontology as
+follows (expressed here in Turtle format, and simplified for the purposes of
+illustration):
To link the paintings to the collection, we must add a "link property"
+to the ontology. In this case, the link property will point from a painting to the collection it belongs to. Every link
+property must be a subproperty of kb:hasLinkTo.
We must then add a "link value property", which will point from a painting to a kb:LinkValue (described in
+LinkValue), which will contain metadata about the link between the property and the collection. In
+particular, the link value specifies the creator of the link, the date when it was created, and the permissions that
+determine who can view or modify it. The name of the link value property is constructed using a simple naming
+convention: the word Value is appended to the name of the link property. In this case, since our link property is
+called
+:isInCollection, the link value property must be called
+:isInCollectionValue. Every link value property must be a subproperty of kb:hasLinkToValue.
This creates a link (paintings:isInCollection) between the painting and the collection, along with a reification
+containing metadata about the link. We can visualise the result as the following graph:
+
+
DSP-API allows a user to see a link if the requesting user has permission to see the source and target resources as well
+as the kb:LinkValue.
+
Part-Whole-Relations between Resources
+
isPartOf
+
A special case of linked resources are part-of related resources, i.e. a resource consisting of several other
+resources. In order to create a part-of relation between two resources, the resource that is part of another resource
+needs to have a property that is either kb:isPartOf or a subproperty thereof.
+kb:isPartOf itself is a subproperty of kb:hasLinkTo. Same as described above for link properties, a corresponding
+part-of value property is created automatically. This value property has the same name as the part-of property with
+Value appended. For example, if in an ontology data a property data:partOf was defined, the corresponding value
+property would be named data:partOfValue. This newly created property data:partOfValue is defined as a subproperty
+of kb:isPartOfValue.
+
Part-of relations are recommended for resources of type kb:StillImageRepresentation. In that case, the resource that
+is part of another resource needs to have a property kb:seqnum or a subproperty thereof, with an integer as value. A
+client can then use this information to leaf through the parts of the compound resource (p.ex. to leaf through the pages
+of a book like in this example).
+
Segment
+
DSP-API supports the creation of segment resources.
+A segment is a part of a resource which has a temporal extent;
+the segment is defined by a start and end time relative to the resource.
+Segments are modelled as resources of type kb:Segment,
+having the properties kb:isSegmentOf, a LinkValue pointing to the resource the segment is part of,
+and kb:hasSegmentBounds, a IntervalValue representing the temporal extent of the segment.
+However, kb:Segment is "abstract" and cannot be used directly in data.
+
Segments have a number of optional, generic properties to add additional information:
+kb:hasTitle (0-1), kb:hasDescription (0-n), kb:hasKeyword (0-n),
+kb:relatesTo/kb:relatesToValue (0-n), and kb:hasComment (0-1).
+
There are two concrete subclasses of kb:Segment for video and audio resources.
+
It is possible to create subclasses of kb:AudioSegment and kb:VideoSegment to add additional properties,
+but this is discouraged and may not be supported in future versions of DSP-API.
+Instead, instances of kb:Annotation pointing to the segment should be used to add additional information.
+
AudioSegment
+
Audio segments are defined by the following properties:
kb:hasSegmentBounds (1): An IntervalValue representing the temporal extent of the segment.
+
kb:hasTitle (0-1): A TextValue for adding a title or name to the segment.
+
kb:hasDescription (0-n): A TextValue for providing one or more descriptions of the segment.
+
kb:hasKeyword (0-n): A TextValue for adding one or more keywords to the segment.
+
kb:relatesTo/kb:relatesToValue (0-n): A LinkValue for relating the segment to another resource.
+
kb:hasComment (0-1): A TextValue for a comment on the segment.
+
+
Text with Standoff Markup
+
DSP-API is designed to be able to store text with markup, which can indicate formatting and structure, as well as the
+complex observations involved in transcribing handwritten manuscripts. One popular way of representing text in the
+humanities is to encode it in XML using the Text Encoding
+Initiative (TEI)
+guidelines. In DSP-API, a TEI/XML document can be stored as a file with attached metadata, but this is not recommended,
+because it does not allow to perform searches across multiple documents.
+
The recommended way to store text with markup in DSP-API is to use the built-in support for "standoff" markup, which
+is stored separately from the text. This has some advantages over embedded markup such as XML. While XML requires markup
+to have a hierarchical structure, and does not allow overlapping tags, standoff nodes do not have these limitations
+(see
+Using Standoff Properties for Marking-up Historical Documents in the Humanities).
+A standoff tag can be attached to any substring in the text by giving its start and end positions. Unlike in corpus
+linguistics, we do not use any tokenisation resulting in a form of predefined segmentation, which would limit the user's
+ability to freely annotate any ranges in the text.
This would require just two standoff tags: (italic, start=5, end=29) and (bold, start=14, end=36).
+
Moreover, standoff makes it possible to mark up the same text in different, possibly incompatible ways, allowing for
+different interpretations without making redundant copies of the text. In the Knora base ontology, any text value can
+have standoff tags.
+
By representing standoff as RDF triples, DSP-API makes markup searchable across multiple text documents in a repository.
+For example, if a repository contains documents in which references to persons are indicated in standoff, it is
+straightforward to find all the documents mentioning a particular person. DSP-API's standoff support is intended to make
+it possible to convert documents with embedded, hierarchical markup, such as TEI/XML, into RDF standoff and back again,
+with no data loss, thus bringing the benefits of RDF to existing TEI-encoded documents.
+
In the Knora base ontology, a TextValue can have one or more standoff tags. Each standoff tag indicates the start and
+end positions of a substring in the text that has a particular attribute. The OWL class
+kb:StandoffTag, which is the base class of all standoff node classes, has these properties:
+
+
standoffTagHasStart (1): The index of the first character in the text that has the attribute.
+
standoffTagHasEnd (1): The index of the last character in the text that has the attribute, plus 1.
+
standoffTagHasUUID (1): A UUID identifying this instance and those corresponding to it in later versions of
+ the TextValue it belongs to.
+ The UUID is a means to maintain a reference to a particular range of a text also when new versions are made and
+ standoff
+ tag IRIs change.
+
standoffTagHasOriginalXMLID (0-1): The original ID of the XML element that the standoff tag represents, if any.
+
standoffTagHasStartIndex (1): The start index of the standoff tag. Start indexes are numbered from 0 within the
+ context of a particular text.
+ When several standoff tags share the same start position, they can be nested correctly with this information when
+ transforming them to XML.
+
standoffTagHasEndIndex (1): The end index of the standoff tag. Start indexes are numbered from 0 within the context
+ of a particular text.
+ When several standoff tags share the same end position, they can be nested correctly with this information when
+ transforming
+ them to XML.
+
standoffTagHasStartParent (0-1): Points to the parent standoff tag. This corresponds to the original nesting of tags
+ in XML. If a standoff tag has no parent, it represents the XML root element.
+ If the original XML element is a CLIX tag, it represents the start of a virtual (non syntactical) hierarchy.
+
standoffTagHasEndParent (0-1): Points to the parent standoff tag if the original XML element is a CLIX tag and
+ represents the end of a virtual (non syntactical) hierarchy.
+
+
The StandoffTag class is not used directly in RDF data; instead, its subclasses are used. A few subclasses are
+currently provided in standoff-onto.ttl, and more will be added to support TEI semantics.
+Projects are able to define their own custom standoff tag classes (direct subclasses of StandoffTag
+or one of the standoff data type classes or subclasses of one of the standoff classes defined in standoff-onto.ttl).
+
Subclasses of StandoffTag
+
Standoff Data Type Tags
+
Associates data in some Knora value type with a substring in a text. Standoff data type tags are subclasses
+of ValueBase classes.
+
+
StandoffLinkTag Indicates that a substring refers to another kb:Resource. See StandoffLinkTag.
+
StandoffInternalReferenceTag Indicates that a substring refers to another standoff tag in the same text value.
+ See Internal Links in a TextValue.
+
StandoffUriTag Indicates that a substring is associated with a URI, which is stored in the same form that is used
+ for kb:UriValue. See UriValue.
+
StandoffDateTag Indicates that a substring represents a date, which is stored in the same form that is used
+ for kb:DateValue. See DateValue.
+
StandoffColorTag Indicates that a substring represents a color, which is stored in the same form that is used
+ for kb:ColorValue. See ColorValue.
+
StandoffIntegerTag Indicates that a substring represents an integer, which is stored in the same form that is used
+ for kb:IntegerValue. See IntValue.
+
StandoffDecimalTag Indicates that a substring represents a number with fractions, which is stored in the same form
+ that is used for kb:DecimalValue. See DecimalValue.
+
StandoffIntervalTag Indicates that a substring represents an interval, which is stored in the same form that is used
+ for kb:IntervalValue. See IntervalValue.
+
StandoffBooleanTag Indicates that a substring represents a Boolean, which is stored in the same form that is used
+ for kb:BooleanValue. See BooleanValue.
+
StandoffTimeTag Indicates that a substring represents a timestamp, which is stored in the same form that is used
+ for kb:TimeValue. See TimeValue.
+
+
StandoffLinkTag
+
A StandoffLinkTag Indicates that a substring is associated with a Knora resource. For example, if a repository
+contains resources representing persons, a text could be marked up so that each time a person's name is mentioned,
+a StandoffLinkTag connects the name to the Knora resource describing that person. It has the following property:
+
standoffTagHasLink (1): The IRI of the resource that is referred to.
+
One of the design goals of the Knora base ontology is to make it easy and efficient to find out which resources contain
+references to a given resource. Direct links are easier and more efficient to query than indirect links. Therefore, when
+a text value contains a resource reference in its standoff nodes, DSP-API automatically creates a direct link between the
+containing resource and the target resource, along with an RDF reification (a kb:LinkValue) describing the link, as
+discussed in Links Between Resources. In this case, the link property is
+always kb:hasStandoffLinkTo, and the link value property (which points to the LinkValue) is always
+kb:hasStandoffLinkToValue.
+
DSP-API automatically updates direct links and reifications for standoff resource references when text values are
+updated.
+To do this, it keeps track of the number of text values in each resource that contain at least one standoff reference to
+a given target resource. It stores this number as the reference count of the LinkValue (see
+LinkValue) describing the direct link. Each time this number changes, it makes a new version of
+the LinkValue, with an updated reference count. When the reference count reaches zero, it removes the direct link and
+makes a new version of the LinkValue, marked with kb:isDeleted.
+
For example, if data:R1 is a resource with a text value in which the resource data:R2 is referenced, the repository
+could contain the following triples:
Link values created automatically for resource references in standoff are visible to all users, and the creator of these
+link values is always
+kb:SystemUser (see Users and Groups). The DSP-API server allows a user to see a standoff link if
+the user has permission to see the source and target resources.
+
Internal Links in a TextValue
+
Internal links in a TextValue can be represented using the data type standoff class StandoffInternalReferenceTag or
+a subclass of it. It has the following property:
+
standoffTagHasInternalReference (1): Points to a StandoffTag that belongs to the same TextValue. It has
+an objectClassConstraint of StandoffTag.
A mapping allows for the conversion of an XML document to RDF-standoff and back. A mapping defines one-to-one relations
+between XML elements (with or without a class) and attributes and standoff classes and properties (see
+XML to Standoff Mapping).
+
A mapping is represented by a kb:XMLToStandoffMapping which contains one or more kb:MappingElement.
+A kb:MappingElement maps an XML element (including attributes) to a standoff class and standoff properties. It has the
+following properties:
+
+
mappingHasXMLTagname (1): The name of the XML element that is mapped to a standoff class.
+
mappingHasXMLNamespace (1): The XML namespace of the XML element that is mapped to a standoff class. If no namespace
+ is given, noNamespace is used.
+
mappingHasXMLClass (1): The name of the class of the XML element. If it has no class, noClass is used.
+
mappingHasStandoffClass (1): The standoff class the XML element is mapped to.
+
mappingHasXMLAttribute (0-n): Maps XML attributes to standoff properties using MappingXMLAttribute. See below.
+
mappingHasStandoffDataTypeClass (0-1): Indicates the standoff data type class of the standoff class the XML element
+ is mapped to.
+
mappingElementRequiresSeparator (1): Indicates if there should be an invisible word separator inserted after the XML
+ element in the RDF-standoff representation.
+ Once the markup is stripped, text segments that belonged to different elements may be concatenated.
+
+
A MappingXMLAttribute has the following properties:
+
+
mappingHasXMLAttributename: The name of the XML attribute that is mapped to a standoff property.
+
mappingHasXMLNamespace: The namespace of the XML attribute that is mapped to a standoff property. If no namespace is
+ given, noNamespace is used.
+
mappingHasStandoffProperty: The standoff property the XML attribute is mapped to.
+
+
DSP-API includes a standard mapping used by the DSP APP. It has the
+IRI http://rdfh.ch/standoff/mappings/StandardMapping and defines mappings for a few elements used to write texts with
+simple markup.
+
Standoff in Digital Editions
+
DSP-API's standoff is designed to make it possible to convert XML documents to standoff and back. One application for
+this
+feature is an editing workflow in which an editor works in an XML editor, and the resulting XML documents are converted
+to standoff and stored in the DSP, where they can be searched and annotated.
+
If an editor wants to correct text that has been imported from XML into standoff, the text can be exported as XML,
+edited, and imported again. To preserve annotations on standoff tags across edits, each tag can automatically be given a
+UUID. In a future version of the Knora base ontology, it may be possible to create annotations that point to UUIDs
+rather than to IRIs. When a text is exported to XML, the UUIDs can be included in the XML. When the edited XML is
+imported again, it can be converted to new standoff tags with the same UUIDs. Annotations that applied to standoff tags
+in the previous version of the text will therefore also apply to equivalent tags in the new version.
+
When text is converted from XML into standoff, tags are also given indexes, which are numbered from 0 within the context
+of a particular text. This makes it possible to order tags that share the same position, and to preserve the hierarchy
+of the original XML document. An ordinary, hierarchical XML tag is converted to a standoff tag that has one index, as
+well as the index of its parent tag, if any. The Knora base ontology also supports non-hierarchical markup such as
+CLIX, which enables overlapping
+markup to be represented in XML. When non-hierarchical markup is converted to standoff, both the start position and the
+end position of the standoff tag have indexes and parent indexes.
+
To support these features, a standoff tag can have these additional properties:
+
+
standoffTagHasStartIndex (0-1): The index of the start position.
+
standoffTagHasEndIndex (0-1): The index of the end position, if this is a non-hierarchical tag.
+
standoffTagHasStartParent (0-1): The IRI of the tag, if any, that contains the start position.
+
standoffTagHasEndParent (0-1): The IRI of the tag, if any, that contains the end position, if this is a
+ non-hierarchical tag.
+
standoffTagHasUUID (0-1): A UUID that can be used to annotate a standoff tag that may be present in different
+ versions of a text,
+ or in different layers of a text (such as a diplomatic transcription and an edited critical text).
+
+
Querying Standoff in SPARQL
+
A future version of DSP-API may provide an API for querying standoff markup. In the meantime, it is possible to query it
+directly in SPARQL. For example, here is a SPARQL query (using RDFS inference) that finds all the text values that
+have a standoff date tag referring to Christmas Eve 2016, contained in a StandoffItalicTag:
Each DSP-API user is represented by an object belonging to the class
+kb:User, which is a subclass of foaf:Person, and has the following properties:
+
userid (1)
+
: A unique identifier that the user must provide when logging in.
+
password (1)
+
: A cryptographic hash of the user's password.
+
email (0-n)
+
: Email addresses belonging to the user.
+
isInProject (0-n)
+
: Projects that the user is a member of.
+
isInGroup (0-n)
+
: user-created groups that the user is a member of.
+
foaf:familyName (1)
+
: The user's family name.
+
foaf:givenName (1)
+
: The user's given name.
+
DSP-API's concept of access control is that an object (a resource or value) can grant permissions to groups of users (but
+not to individual users). There are several built-in groups:
+
knora-admin:UnknownUser
+
: Any user who has not logged into DSP-API is automatically assigned to this group.
+
knora-admin:KnownUser
+
: Any user who has logged into DSP-API is automatically assigned to this group.
+
knora-admin:ProjectMember
+
: When checking a user's permissions on an object, the user is automatically assigned to this group if she is a member
+of the project that the object belongs to.
+
knora-admin:Creator
+
: When checking a user's permissions on an object, the user is automatically assigned to this group if he is the
+creator of the object.
+
knora-admin:ProjectAdmin
+
: When checking a user's permissions on an object, the user is automatically assigned to this group if she is an
+administrator of the project that the object belongs to.
+
knora-admin:SystemAdmin
+
: The group of DSP-API system administrators.
+
A user-created ontology can define additional groups, which must belong to the OWL class knora-admin:UserGroup.
+
There is one built-in knora-admin:SystemUser, which is the creator of link values created automatically for resource
+references in standoff markup (see StandoffLinkTag).
+
Permissions
+
Each resource or value can grant certain permissions to specified user groups. These permissions are represented as the
+object of the predicate kb:hasPermissions, which is required on every kb:Resource
+and on the current version of every kb:Value. The permissions attached to the current version of a value also apply to
+previous versions of the value. Value versions other than the current one do not have this predicate.
+
The following permissions can be granted:
+
+
Restricted view permission (RV) Allows a restricted view of the object, e.g. a view of an image with a watermark.
+
View permission (V) Allows an unrestricted view of the object. Having view permission on a resource only affects
+ the user's ability to view information about the resource other than its values. To view a value, she must have view
+ permission on the value itself.
+
Modify permission (M) For values, this permission allows a new version of a value to be created. For resources,
+ this allows the user to create a new value (as opposed to a new version of an existing value), or to change
+ information about the resource other than its values. When he wants to make a new version of a value, his permissions
+ on the containing resource are not relevant. However, when he wants to change the target of a link, the old link must
+ be deleted and a new one created, so he needs modify permission on the resource.
+
Delete permission (D) Allows the item to be marked as deleted.
+
Change rights permission (CR) Allows the permissions granted by the object to be changed.
+
+
Each permission in the above list implies all lower-numbered permissions. A user's permission level on a particular
+object is calculated in the following way:
+
+
Make a list of the groups that the user belongs to, including
+ Creator and/or ProjectMember if applicable.
+
Make a list of the permissions that she can obtain on the object, by iterating over the permissions that the object
+ grants. For each permission, if she is in the specified group, add the specified permission to the list of
+ permissions she can obtain.
+
From the resulting list, select the highest-level permission.
+
If the result is that she would have no permissions, give her whatever permission UnknownUser would have.
+
+
To view a link between resources, a user needs permission to view the source and target resources. He also needs
+permission to view the
+LinkValue representing the link, unless the link property is
+hasStandoffLinkTo (see StandoffLinkTag).
+
The format of the object of kb:hasPermissions is as follows:
+
+
Each permission is represented by the one-letter or two-letter abbreviation given above.
+
Each permission abbreviation is followed by a space, then a comma-separated list of groups that the permission is
+ granted to.
+
The IRIs of built-in groups are shortened using the knora-admin
+ prefix.
+
Multiple permissions are separated by a vertical bar (|).
+
+
For example, if an object grants view permission to unknown and known users, and modify permission to project members,
+the resulting permission literal would be:
+
V knora-admin:UnknownUser,knora-admin:KnownUser|M knora-admin:ProjectMember
+
+
Consistency Checking
+
DSP-API tries to enforce repository consistency by checking constraints that are specified in the Knora base ontology and
+in user-created ontologies. Three types of consistency rules are enforced:
+
+
Cardinalities in OWL class definitions must be satisfied.
+
Constraints on the types of the subjects and objects of OWL object properties must be satisfied.
+
A datatype property may not have an empty string as an object.
+
+
OWL Cardinalities
+
As noted in Resources, each subclass of
+Resource must use OWL cardinality restrictions to specify the properties it can have. More specifically, a resource is
+allowed to have a property that is a subproperty of kb:hasValue or kb:hasLinkTo only if the resource's class has
+some cardinality for that property. Similarly, a value is allowed to have a subproperty of kb:valueHas
+only if the value's class has some cardinality for that property.
+
DSP-API supports, and attempts to enforce, the following cardinality constraints:
+
+
+
owl:cardinality 1:
+ Exactly One 1 - A resource of this class must have exactly one instance of the specified property.
+
+
+
owl:minCardinality 1:
+ At Least One 1-n - A resource of this class must have at least one instance of the specified property.
+
+
+
owl:maxCardinality 1:
+ Zero Or One 0-1 - A resource of this class must have either zero or one instance of the specified property.
+
+
+
owl:minCardinality 0:
+ Unbounded 0-n - A resource of this class may have zero or more instances of the specified property.
+
+
+
DSP-API requires cardinalities to be defined using blank nodes, as in the following example from knora-base:
The cardinality of a link property must be the same as the cardinality of the corresponding link value property.
+
Each owl:Restriction may have the predicate salsah-gui:guiOrder to indicate the order in which properties should be
+displayed in a GUI
+(see The SALSAH GUI Ontology).
+
A resource class inherits cardinalities from its superclasses. This follows from the rules of
+RDFS inference. Also, in DSP-API, cardinalities in the subclass can
+override cardinalities that would otherwise be inherited from the superclass. Specifically, if a superclass has a
+cardinality on a property P, and a subclass has a cardinality on a subproperty of P, the subclass's cardinality
+overrides the superclass's cardinality. In the example above,
+hasStillImageFileValue is a subproperty of hasFileValue. Therefore, the cardinality on hasStillImageFileValue
+overrides (i.e. replaces)
+the one on hasFileValue.
+
Note that, unlike cardinalities, predicates of properties are not inherited. If :foo rdfs:subPropertyOf :bar, this
+does not mean that
+:foo inherits anything from :bar. Any predicates of :foo that are also needed by :bar must be defined explicitly
+on :bar. This design decision was made because property predicate inheritance is not provided by RDFS inference, and
+would make it more difficult to check the correctness of ontologies, while providing little practical benefit.
+
For more information about OWL cardinalities, see
+the OWL 2 Primer.
+
Constraints on the Types of Property Subjects and Objects
+
When a user-created ontology defines a property, it must indicate the types that are allowed as objects (and, if
+possible, as subjects) of the property. This is done using the following Knora-specific properties:
+
subjectClassConstraint
+
: Specifies the class that subjects of the property must belong to. This constraint is recommended but not required.
+DSP-API will attempt to enforce this constraint.
+
objectClassConstraint
+
: If the property is an object property, specifies the class that objects of the property must belong to. Every
+subproperty of
+kb:hasValue or a kb:hasLinkTo (i.e. every property of a resource that points to a kb:Value or to another resource)
+is required to have this constraint, because DSP-API relies on it to know what type of object to expect for the property.
+DSP-API will attempt to enforce this constraint.
+
objectDatatypeConstraint
+
: If the property is a datatype property, specifies the type of literals that can be objects of the property. DSP-API
+will not attempt to enforce this constraint, but it is useful for documentation purposes.
+
Note that it is possible for a subproperty to have a more restrictive contraint than its base property, by specifing a
+subject or object class that is a subclass of the one specified in the base property. However, it is not possible for
+the subproperty to make the base property's constraint less restrictive.
Summary of Restrictions on User-Created Ontologies
+
An ontology can refer to a Knora ontology in another project only if the other ontology is built-in or shared
+(see Shared Ontologies).
+
Restrictions on Classes
+
+
Each class must be a subclass of either kb:Resource or
+ kb:StandoffTag, but not both (note that this forbids user-created subclasses of kb:Value).
+
All the cardinalities that a class defines directly (i.e. does not inherit from kb:Resource) must be on properties
+ that are defined in the triplestore.
+
Within the cardinalities of a class, there must be a link value property for each link property and vice versa.
+
The cardinality of a link property must be the same as the cardinality of the corresponding link value property.
+
A cardinality on a property with a boolean value must be
+ owl:cardinality 1 or owl:maxCardinality 1.
+
Each class must be a subclass of all the classes that are subject class constraints of the properties in its
+ cardinalities.
+
If it's a resource class, all its directly defined cardinalities must be on Knora resource properties (subproperties
+ of kb:hasValue
+ or kb:hasLinkTo), and all its base classes with Knora IRIs must also be resource classes. A cardinality
+ on kb:resourceProperty or
+ kb:hasValue is forbidden. It must also have an rdfs:label.
+
If it's a standoff class, none of its cardinalities may be on Knora resource properties, and all its base classes with
+ Knora IRIs must also be standoff classes.
+
A class cannot have a cardinality on property P as well as a cardinality on a subproperty of P.
+
+
Restrictions on properties
+
+
The property's subject class constraint, if provided, must be a subclass of kb:Resource or kb:StandoffTag, and
+ must be a subclass of the subject class constraints of all its base properties.
+
Its object class constraint, if provided, must be a subclass of the object class constraints of all its base
+ properties.
+
If the property is a Knora resource property, it must have an object class constraint and an rdfs:label.
+
It can't be a subproperty of both kb:hasValue and kb:hasLinkTo.
+
It can't be a subproperty of kb:hasFileValue.
+
Each of its base properties that has a Knora IRI must also be a Knora resource property.
+
+
Standardisation
+
The DaSCH intends to coordinate the standardisation of generally useful entities proposed in
+user-created ontologies. We envisage a process in which two or more projects would initiate the process by starting a
+public discussion on proposed entities to be shared. Once a consensus was reached, the
+DaSCH would publish these entities in a
+Shared Ontology).
+
Knora Ontology Versions
+
The Knora base ontology has the property kb:ontologyVersion, whose object is a string that indicates the deployed
+version of all the DSP-API built-in ontologies. This allows the
+repository update program to determine which repository updates are needed
+when DSP-API is upgraded.
The SALSAH GUI ontology provides entities that can be used in
+user-created ontologies to indicate to SALSAH (or to another GUI)
+how data should be entered and displayed.
+
The SALSAH GUI ontology is identified by the IRI
+http://www.knora.org/ontology/salsah-gui. In the Knora documentation
+in general, it is identified by the prefix salsah-gui, but for
+brevity, we omit the prefix in this document.
+
Properties
+
guiOrder
+
guiOrder can be attached to a cardinality
+in a resource class, to indicate the order in which properties
+should be displayed in the GUI. The object is a non-negative
+integer. For example, a property with guiOrder 0 would be
+displayed first, followed by a property with guiOrder 1, and so
+on.
+
guiElement
+
guiElement can be attached to a property definition to indicate which
+GUI element should be used to enter data for the property. This
+should be one of the individuals of class Guielement described
+below.
+
guiAttribute
+
guiAttribute can be attached to a property definition to provide attributes for
+the GUI element specified in guiElement. The objects of this
+predicate are written in a DSL with the following syntax:
+
object =attribute name,"=",attribute value ;
+attribute name =identifier ;
+identifier =letter ,{letter };
+attribute value =integer |decimal |percent |string |iri ;
+percent =integer,"%";
+iri ="<",string,">";
+
+
The attributes used with each GUI element are described below under
+Individuals.
+
guiAttributeDefinition
+
guiAttributeDefinition is used only in the salsah-gui ontology itself, as a predicate
+attached to instances of Guielement (see Individuals),
+to specify the attributes that can be given as objects of guiAttribute when a given
+Guielement is used. The objects of this predicate are written in
+a DSL with the following syntax:
+
object =attribute name,["(required)"],":",attribute type,[enumerated values ];
+enumerated values ="(",enumerated value,{"|",enumerated value }")";
+attribute name =identifier ;
+attribute type ="integer"|"decimal"|"percent"|"string"|"iri";
+enumerated value =identifier ;
+identifier =letter ,{letter };
+
+
Enumerated values are allowed only if attribute type is string.
+If enumerated values are provided for an attribute, the attribute
+value given via guiAttribute must be one of the enumerated values.
+
Classes
+
Guielement
+
The instances of class Guielement are individuals representing GUI
+elements for data entry.
+
Individuals
+
Colorpicker
+
Colorpicker is a GUI element for selecting a color. A property definition that uses
+this element may also contain a guiAttribute predicate whose
+object is a string in the form "ncolors=N", where N is an
+integer specifying the number of colors to display.
+
Date
+
Date is a GUI element for selecting a date.
+
Geometry
+
Geometry is a GUI element for selecting the geometry of a two-dimensional
+region.
+
Geonames
+
Geonames is a GUI element for selecting a Geonames
+identifier.
+
Interval
+
Interval is a GUI element for selecting a time interval in an audio or video
+recording.
+
List
+
List is a GUI element for selecting an item in a hierarchical list (see
+ListValue). A property definition that
+uses this element must also contain this guiAttribute predicate:
+
"hlist=<LIST_IRI>", where LIST_IRI is the IRI of a
+knora-base:ListNode that is the root node of a hierarchical list.
+
Pulldown
+
Pulldown is a GUI element for selecting an item in a flat list (see
+ListValue) using a pull-down menu. A
+property definition that uses this element must also contain this
+guiAttribute predicate:
+
"hlist=<LIST_IRI>", where LIST_IRI is the IRI of a
+knora-base:ListNode that is the root node of a hierarchical list.
+
Radio
+
Radio is a GUI element for selecting an item in a flat list (see
+ListValue) using radio buttons. A property
+definition that uses this element must also contain this
+guiAttribute predicate:
+
"hlist=<LIST_IRI>", where LIST_IRI is the IRI of a
+knora-base:ListNode that is the root node of a hierarchical list.
+
Richtext
+
Richtext is a GUI element for editing multi-line formatted text.
+
Searchbox
+
Searchbox is a GUI element for searching for a resource by matching text in its rdfs:label.
+
SimpleText
+
SimpleText is a GUI element for editing a single line of unformatted text. A
+property definition that uses this element may also contain a
+guiAttribute predicate with one or both of the following objects:
+
+
"size=N", where N is an integer specifying the size of the
+ text field.
+
"maxlength=N", where N is an integer specifying the maximum
+ length of the string to be input.
+
+
Slider
+
Slider is a GUI element for choosing numerical values using a slider. A
+property definition that uses this element must also contain a
+guiAttribute predicate with both of the following objects:
+
+
"min=N", where N is an integer specifying the minimum value
+ of the input.
+
"max=N", where N is an integer specifying the maximum value
+ of the input.
+
+
Spinbox
+
Spinbox is a GUI element for choosing numerical values using a spinbox. A
+property definition that uses this element may also contain a
+guiAttribute predicate with one or both of the following objects:
+
+
"min=N", where N is an integer specifying the minimum value
+ of the input.
+
"max=N", where N is an integer specifying the maximum value
+ of the input.
+
+
Textarea
+
Textarea is a GUI element for editing multi-line unformatted text. A property
+definition that uses this element may also contain a guiAttribute
+predicate with one or more of the following objects:
+
+
"width=N", where N is a percentage of the window width (an
+ integer followed by %).
+
"cols=N", where N is an integer representing the number of
+ colums in the text entry box.
+
"rows=N", where N is an integer specifying the height of the
+ text entry box in rows.
Additionally, each group can have an optional custom IRI (of @ref:Knora IRI
+form)
+specified by the id in the request body as below:
+
{
+"id":"http://rdfh.ch/groups/00FF/a95UWs71KUklnFOe1rcw1w",
+"name":"GroupWithCustomIRI",
+"descriptions":[
+{
+"value":"A new group with a custom IRI",
+"language":"en"
+}
+],
+"project":"http://rdfh.ch/projects/00FF",
+"status":true,
+"selfjoin":false
+}
+
We provide an OpenAPI specification for certain endpoints and are working on providing this for all endpoints.
+The latest version is located at api.dasch.swiss/api/docs/docs.yaml.
+For an interactive documentation of all API endpoints, please visit api.dasch.swiss/api/docs/.
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
Checks if a list can be deleted (none of its nodes is used in data).
+
+
Input parameters
+
+
+
+
Parameter
+
In
+
Type
+
Default
+
Nullable
+
Description
+
+
+
+
+
p1
+
path
+
string
+
+
No
+
The IRI of the list.
+
+
+
+
+
+ Response 200OK
+
+
+
+
+
+
{
+"listIri":"string",
+"canDeleteList":true
+}
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
Update an existing default object access permission. The request may update
+the hasPermission and/or any allowed combination of group, resource class
+and property for the permission.
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
Returns all unique keywords for all projects as a list.
+
+
+ Response 200OK
+
+
+
+
+
+
{
+"keywords":[
+"string"
+]
+}
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
!ATTENTION! Erase a project with the given shortcode.
+This will permanently and irrecoverably remove the project and all of its
+assets.
+Authorization: Requires system admin permissions.
+Only available if the feature has been configured on the server side.
+
+
Input parameters
+
+
+
+
Parameter
+
In
+
Type
+
Default
+
Nullable
+
Description
+
+
+
+
+
httpAuth1
+
header
+
string
+
N/A
+
No
+
Basic authentication
+
+
+
httpAuth
+
header
+
string
+
N/A
+
No
+
JWT Bearer token
+
+
+
keepAssets
+
query
+
boolean
+
False
+
No
+
If set to true the assets in ingest will not be removed.
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
The shortcode of a project. Must be a 4 digit hexadecimal String.
+
+
+
+
+
+ Response 200OK
+
+
+
+
+
+
{
+"location":"string"
+}
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
Resets the content of the triplestore, only available if configuration
+allowReloadOverHttp is set to true.
+
+
Input parameters
+
+
+
+
Parameter
+
In
+
Type
+
Default
+
Nullable
+
Description
+
+
+
+
+
prependDefaults
+
query
+
boolean
+
True
+
No
+
Prepend defaults to the data objects.
+
+
+
+
Request body
+
+
+
+
+
[
+{
+"path":"string",
+"name":"string"
+}
+]
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the request body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
+⚠️This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
+
+Schema of the response body
+
The DSP Admin API makes it possible to administrate projects, users, user groups, permissions, and hierarchical lists.
+
RESTful API
+
The Knora Admin API is a RESTful API that allows for reading and adding of
+administrative resources from and to Knora and changing their values
+using HTTP requests. The actual data is submitted as JSON (request and
+response format). The various HTTP methods are applied according to the
+widespread practice of RESTful APIs: GET for reading, POST for adding,
+PUT for changing resources and values, and DELETE to delete resources or
+values (see
+Using HTTP Methods for RESTful Services).
+
Knora IRIs in the Admin API
+
Every resource that is created or hosted by Knora is identified by a
+unique ID called an Internationalized Resource Identifier (IRI).
+The IRI is required for every API operation to identify the resource in question.
+A Knora IRI has itself the format of a URL.
+For some API operations, the IRI has to be URL-encoded (HTTP GET requests).
+
Unlike the DSP-API v2, the admin API uses internal IRIs, i.e. the actual IRIs
+that are stored in the triplestore (see Knora IRIs).
+
Admin Path Segment
+
Every request to Admin API includes admin as a path segment, e.g.
+http://host/admin/users/iri/http%3A%2F%2Frdfh.ch%2Fusers%2Froot.
+
Admin API Response Format
+
If an API request is handled successfully, Knora responds
+with a 200 HTTP status code. The actual answer from Knora (the
+representation of the requested resource or information about the
+executed API operation) is sent in the HTTP body, encoded as JSON.
+
Placeholder host in sample URLs
+
Please note that all the sample URLs used in this documentation contain
+host as a placeholder. The placeholder host has to be replaced by
+the actual hostname (and port) of the server the Knora instance is
+running on.
+
Authentication
+
For all API operations that target at changing resources or values, the
+client has to provide credentials (username and password) so that the
+API server can authenticate the user making the request. Credentials can
+be sent as a part of the HTTP header or as parts of the URL (see
+Authentication in Knora).
+
Admin API Endpoints
+
An overview over all admin API endpoints can be found here.
GET: /admin/lists[?projectIri=<projectIri>] : return all lists optionally filtered by project
+
GET: /admin/lists/<listItemIri> : return complete list with all children if IRI of the list (i.e. root node) is given.
+ If IRI of the child node is given, return the node with its immediate children
+
GET: /admin/lists/infos/<listIri> : return list information (without children)
+
GET: /admin/lists/nodes/<nodeIri> : return list node information (without children)
+
GET: /admin/lists/<listIri>/info : return list basic information (without children)
+
+
GET: /admin/lists/candelete/<listItemIri> : check if list or its node is unused and can be deleted
+
+
+
POST: /admin/lists : create new list
+
+
+
POST: /admin/lists/<parentNodeIri> : create new child node under the supplied parent node IRI
+
+
+
PUT: /admin/lists/<listItemIri> : update node information (root or child)
+
+
PUT: /admin/lists/<listItemIri>/name : update the name of the node (root or child)
+
PUT: /admin/lists/<listItemIri>/labels : update labels of the node (root or child)
+
PUT: /admin/lists/<listItemIri>/comments : update comments of the node (root or child)
+
+
PUT: /admin/lists/<nodeIri>/position : update position of a child node within its current parent
+ or by changing its parent node
+
+
+
DELETE: /admin/lists/<listItemIri> : delete a list (i.e. root node) or a child node and all its children, if not used
+
+
DELETE: /admin/lists/comments/<nodeIri> : delete comments of a node (child only)
+
+
List Item Operations
+
Get lists
+
+
Required permission: none
+
Return all lists optionally filtered by project
+
GET: /admin/lists[?projectIri=<projectIri>]
+
+
Get list
+
+
Required permission: none
+
Return complete list (or node) including basic information of the list (or child node),
+ listinfo (or nodeinfo), and all its children
+
GET: /admin/lists/<listIri>
+
+
Get list's information
+
+
Required permission: none
+
Return list information, listinfo (without children).
Additionally, each list can have an optional custom IRI (of Knora IRI form)
+specified by the id in the request body as below:
+
{
+"id":"http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
+"projectIri":"http://rdfh.ch/projects/0001",
+"name":"a new list",
+"labels":[{"value":"New list with IRI","language":"en"}],
+"comments":[{"value":"New comment","language":"en"}]
+}
+
+
The response will contain the basic information of the list, listinfo and an empty list of its children, as below:
+
{
+"list":{
+"children":[],
+"listinfo":{
+"comments":[{"value":"New comment","language":"en"}],
+"id":"http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
+"isRootNode":true,
+"labels":[
+{
+"value":"New list with IRI",
+"language":"en"
+}
+],
+"name":"a new list",
+"projectIri":"http://rdfh.ch/projects/0001"
+}
+}
+}
+
Appends a new child node under the supplied nodeIri. If the supplied nodeIri
+ is the listIri, then a new child node is appended to the top level. If a position is given
+ for the new child node, the node will be created and inserted in the specified position, otherwise
+ the node is appended to the end of parent's children.
+
POST: /admin/lists/<parentNodeIri>
+
BODY:
+
+
{
+"parentNodeIri":"http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
+"projectIri":"http://rdfh.ch/projects/0001",
+"name":"a child",
+"labels":[{"value":"New List Node","language":"en"}]
+}
+
+
Additionally, each child node can have an optional custom IRI (of Knora IRI
+form) specified by the id in the request body as below:
+
{"id":"http://rdfh.ch/lists/0001/8u37MxBVMbX3XQ8-d31x6w",
+"parentNodeIri":"http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
+"projectIri":"http://rdfh.ch/projects/0001",
+"name":"a child",
+"labels":[{"value":"New List Node","language":"en"}]
+}
+
+
The response will contain the basic information of the node, nodeinfo, as below:
+
{
+"nodeinfo":{
+"comments":[],
+"hasRootNode":"http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
+"id":"http://rdfh.ch/lists/0001/8u37MxBVMbX3XQ8-d31x6w",
+"labels":[
+{
+"value":"New List Node",
+"language":"en"
+}
+],
+"name":"a new child",
+"position":1
+}
+}
+
+
The new node can be created and inserted in a specific position which must be given in the payload as shown below.
+If necessary, according to the given position, the sibling nodes will be shifted.
+Note that position cannot have a value higher than the number of existing children.
+
{"parentNodeIri":"http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
+"projectIri":"http://rdfh.ch/projects/0001",
+"name":"Inserted new child",
+"position":0,
+"labels":[{"value":"New List Node","language":"en"}]
+}
+
+
In case the new node should be appended to the list of current children, either position: -1 must be given in the
+payload or the position parameter must be left out of the payload.
+
Update list's or node's information
+
The basic information of a list (or node) such as its labels, comments, name, or all of them can be updated.
+The parameters that must be updated together with the new value must be given in the JSON body of the request
+together with the IRI of the list and the IRI of the project it belongs to.
+
+
Required permission: SystemAdmin / ProjectAdmin
+
Required fields: listIri, projectIri
+
Update list information
+
PUT: /admin/lists/<listIri>
+
BODY:
+
+
{
+"listIri":"http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
+"projectIri":"http://rdfh.ch/projects/0001",
+"name":"new name for the list",
+"labels":[{"value":"a new label for the list","language":"en"}],
+"comments":[{"value":"a new comment for the list","language":"en"}]
+}
+
+
The response will contain the basic information of the list, listinfo (or nodeinfo), without its children, as below:
+
{
+"listinfo":{
+"comments":[
+{
+"value":"a new comment for the list",
+"language":"en"
+}
+],
+"id":"http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
+"isRootNode":true,
+"labels":[
+{
+"value":"a new label for the list",
+"language":"en"
+}
+],
+"name":"new name for the list",
+"projectIri":"http://rdfh.ch/projects/0001"
+}
+}
+
+
If only name of the list must be updated, it can be given as below in the body of the request:
There is no need to specify the project IRI because it is automatically extracted using the given <listItemIRI>.
+
Repositioning a child node
+
The position of an existing child node can be updated. The child node can be either repositioned within its
+current parent node, or can be added to another parent node in a specific position. The IRI of the parent node
+and the new position of the child node must be given in the request body.
+
If a node is supposed to be repositioned to the end of a parent node's children, give position: -1.
+
Suppose a parent node parentNode1 has five children in positions 0-4, to change the position of its child node
+childNode4 from its original position 3 to position 1 the request body should specify the IRI of its parent node
+and the new position as below:
Then the node childNode4 will be put in position 1, and its siblings will be shifted accordingly. The new position given
+in the request body cannot be the same as the child node's original position. If position: -1 is given, the node will
+be moved to the end of children list, and its siblings will be shifted to left. In case of repositioning the node
+within its current parent, the maximum permitted position is the length of its children list, i.e. in this example the
+highest allowed position is 4.
+
To reposition a child node childNode4 to another parent node parentNode2 in a specific position, for
+example position: 3, the IRI of the new parent node and the position the node must be placed within children of
+parentNode2 must be given as:
In this case, the childNode4 is removed from the list of children of its old parent parentNode1 and its old
+siblings are shifted accordingly. Then the node childNode4 is added to the specified new parent, i.e. parentNode2, in
+the given position. The new siblings are shifted accordingly.
+
Note that, the furthest the node can be placed is at the end of the list of the children of parentNode2. That means
+if parentNode2 had 3 children with positions 0-2, then childNode4 can be placed in position 0-3 within children
+of its new parent node. If the position: -1 is given, the node will be appended to the end of new parent's children,
+and new siblings will not be shifted.
+
Values less than -1 are not permitted for parameter position.
+
+
Required permission: SystemAdmin / ProjectAdmin
+
Response: returns the updated parent node with all its children.
+
Put /admin/lists/<nodeIri>/position
+
+
Delete a list or a node
+
An entire list or a single node of it can be completely deleted, if not in use. Before deleting an entire list
+(i.e. root node), the data and ontologies are checked for any usage of the list or its children. If not in use, the list
+and all its children are deleted.
+
Similarily, before deleting a single node of a list, it is verified that the node itself and none of its children are used.
+If not in use, the node and all its children are deleted. Once a node is deleted, its parent node is updated by shifting the
+remaining child nodes with respect to the position of the deleted node.
+
+
Required permission: SystemAdmin / ProjectAdmin
+
+
Response:
+
+
If the IRI of the list (i.e. root node) is given, the iri of the deleted list with a flag deleted: true is returned.
+
If the IRI of a child node is given, the updated parent node is returned.
+
+
+
+
Delete /admin/lists/<listItemIri>
+
+
+
Delete child node comments
+
Performing a DELETE request to route /admin/lists/comments/<nodeIri> deletes the comments of that node.
+As a response sipmle JSON is returned:
For the management of users, projects, groups, lists, and permissions, the DSP-API following a resource
+centric approach, provides the following endpoints corresponding to the respective classes of objects that they have an
+effect on, namely:
deprecated, use /admin/permissions/doap/{permissionIri} instead
+
+
+
/admin/permissions/{doap_permissionIri}/property
+
PUT
+
deprecated, use /admin/permissions/doap/{permissionIri} instead
+
+
+
+
Permission Operations
+
Note: For the following operations, the requesting user must be either a systemAdminor a projectAdmin.
+
Getting Permissions
+
+
+
GET: /admin/permissions/<projectIri> : return all permissions for a project.
+As a response, the IRI and the type of all permissions of a project are returned.
+
+
+
GET: /admin/permissions/ap/<projectIri>: return all administrative permissions
+for a project. As a response, all administrative_permissions of a project are returned.
+
+
+
GET: /admin/permissions/ap/<projectIri>/<groupIri>: return the administrative
+permissions for a project group. As a response, the administrative_permission defined
+for the group is returned.
+
+
+
GET: /admin/permissions/doap/<projectIri>: return all default object access
+permissions for a project. As a response, all default_object_acces_permissions of a
+project are returned.
+
+
+
Creating New Administrative Permissions
+
+
POST: /admin/permissions/ap: create a new administrative permission. The type of
+permissions, the project and group to which the permission should be added must be
+included in the request body, for example:
In addition, in the body of the request, it is possible to specify a custom IRI (of
+DSP IRI form) for a permission through
+the @id attribute which will then be assigned to the permission; otherwise the permission will get a unique random IRI.
+A custom permission IRI must be http://rdfh.ch/permissions/PROJECT_SHORTCODE/ (where PROJECT_SHORTCODE
+is the shortcode of the project that the permission belongs to), plus a custom ID string. For example:
additionalInformation: should be left empty, otherwise will be ignored.
+
name : indicates the type of the permission that can be one of the followings:
+
ProjectAdminAllPermission: gives the user the permission to do anything
+ on project level, i.e. create new groups, modify all
+ existing groups
+
ProjectAdminGroupAllPermission: gives the user the permission to modify
+ group info and group membership on all groups
+ belonging to the project.
+
ProjectAdminGroupRestrictedPermission: gives the user the permission to modify
+ group info and group membership on certain groups
+ belonging to the project.
+
ProjectAdminRightsAllPermission: gives the user the permission to change the
+ permissions on all objects belonging to the project
+ (e.g., default permissions attached to groups and
+ permissions on objects).
+
ProjectResourceCreateAllPermission: gives the permission to create resources
+ inside the project.
+
ProjectResourceCreateRestrictedPermission: gives restricted resource creation permission
+ inside the project.
+
+
+
permissionCode: should be left empty, otherwise will be ignored.
+
+
Note that during the creation of a new project,
+a default set of administrative permissions are added to its ProjectAdmin and ProjectMember groups
+(See Default set of permissions for a new project).
+Therefore, it is not possible to create new administrative permissions
+for the ProjectAdmin and ProjectMember groups of a project.
+However, the default permissions set for these groups can be modified
+(See update permission).
+
Creating New Default Object Access Permissions
+
+
POST: /admin/permissions/doap : create a new default object access permission.
+A single instance of knora-admin:DefaultObjectAccessPermission must
+always reference a project, but can only reference either a group
+(knora-admin:forGroup property), a resource class
+(knora-admin:forResourceClass), a property (knora-admin:forProperty),
+or a combination of resource class and property. For example, to create a new
+default object access permission for a group of a project the request body would be
additionalInformation: To whom the permission should be granted: project members, known users, unknown users, etc.
+
name : indicates the type of the permission that can be one of the followings.
+
RV: restricted view permission (least privileged)
+
V: view permission
+
M modify permission
+
D: delete permission
+
CR: change rights permission (most privileged)
+
+
+
permissionCode: The code assigned to a permission indicating its hierarchical level. These codes are as below:
+
1: for restricted view permission (least privileged)
+
2: for view permission
+
6: for modify permission
+
7: for delete permission
+
8: for change rights permission (most privileged)
+
+
+
+
Note that, at least either name or permissionCode must be provided. If one is missing, it will be extrapolated from the other.
+For example, if permissionCode= 1 is given but name was left empty, its value will be set to name = RV.
+
Similar to the previous case a custom IRI can be assigned to a permission specified by the id in the request body.
+The example below shows the request body to create a new default object access permission with a custom IRI defined for
+a resource class of a specific project:
Note that during the creation of a new project,
+a set of default object access permissions are created for its ProjectAdmin and ProjectMember groups
+(See Default set of permissions for a new project).
+Therefore, it is not possible to create new default object access permissions
+for the ProjectAdmin and ProjectMember groups of a project.
+However, the default permissions set for these groups can be modified; see below for more information.
+
Updating an existing Default Object Access Permission
+
+
PUT: /admin/permissions/doap/<doap_permissionIri> to change the attributes of an existing default object
+ access permission, identified by its IRI <doap_permissionIri>.
+
+
This is an example of a request body to update an existing default object access permission:
All attributes of the default object access permission are optional and may be combined.
+
+
Warning
+
Only certain combinations of attributes are allowed. Only exactly one of the following combinations is allowed:
+
+
forGroup
+
forResourceClass
+
forProperty
+
forResourceClass and forProperty
+
+
+
If the combination of attributes is not allowed, the request will fail with a 400 Bad Request error.
+Any valid combination of attributes will replace the existing values.
PUT: /admin/permissions/<permissionIri>/group to change the group for which an administrative or a default object
+access permission, identified by its IRI <permissionIri>, is defined. The request body must contain the IRI of the new
+group as below:
When updating an administrative permission, its previous forGroup value will be replaced with the new one.
+When updating a default object access permission, if it originally had a forGroup value defined, it will be replaced
+with the new group. Otherwise, if the default object access permission was defined for a resource class or a property or
+the combination of both, the permission will be defined for the newly specified group and its previous
+forResourceClass and forProperty values will be deleted.
PUT: /admin/permissions/<permissionIri>/hasPermissions to change the scope of permissions assigned to an administrative
+ or a default object access permission identified by it IRI, <permissionIri>. The request body must contain the new set
+ of permission types as below:
Each permission item given in hasPermissions, must contain the necessary parameters with respect to the type of the
+permission. For example, if you wish to change the scope of an administrative permission, follow the
+guidelines for the
+content of its hasPermissions property. Similarly, if you wish to change the scope of a default object access permission,
+follow the guidelines given about the content of its hasPermissions property.
+Either the name or the permissionCode must be present; it is not necessary to provide both.
+
The previous permission set is replaced by the new permission set. In order to remove a permission for a group
+entirely, you can provide a new set of permissions, leaving out the permission specification for the group.
+
Deleting a Permission
+
+
DELETE: /admin/permissions/<permissionIri> to delete an administrative, or a default object access permission. The
+IRI of the permission must be given in encoded form.
shortname (unique, 3-20 characters long, can contain small and capital letters, numbers, special characters: -
+and _, cannot start with number nor allowed special characters, should be in the form of a
+xsd:NCNAME and URL safe)
+
description (collection of descriptions as strings with language tag)
+
keywords (collection of keywords)
+
status (true, if project is active. false, if project is inactive)
+
selfjoin
+
+
Optional payload:
+
+
id (unique, custom DSP IRI, e.g. used for migrating a project from one server to another)
400 Bad Request if the project already exists or any of the provided properties is invalid.
+
401 Unauthorized if authorization failed.
+
+
Default set of RestrictedViewSize
+
Starting from DSP 2023.10.02 release, the creation of new project will also set the RestrictedViewSize to default
+value, which is: !512,512. It is possible to change the value using dedicated routes.
+
Default set of permissions for a new project
+
When a new project is created, following default permissions are added to its admins and members:
+
+
+
ProjectAdmin group receives an administrative permission to do all project level operations
+ and to create resources within the new project.
+ This administrative permission is retrievable through its IRI:
+ http://rdfh.ch/permissions/[projectShortcode]/defaultApForAdmin
+
+
+
ProjectAdmin group also gets a default object access permission to change rights
+ (which includes delete, modify, view, and restricted view permissions) of any entity that belongs to the project.
+ This default object access permission is retrievable through its IRI:
+ http://rdfh.ch/permissions/[projectShortcode]/defaultDoapForAdmin
+
+
+
ProjectMember group receives an administrative permission to create resources within the new project.
+ This administrative permission is retrievable through its IRI:
+ http://rdfh.ch/permissions/[projectShortcode]/defaultApForMember
+
+
+
ProjectMember group also gets a default object access permission to delete
+ (which includes modify, view and restricted view permissions) of any entity that belongs to the project.
+ This default object access permission is retrievable through its IRI:
+ http://rdfh.ch/permissions/[projectShortcode]/defaultDoapForMember
+
+
+
Get Project by ID
+
The ID can be shortcode, shortname or IRI.
+
Permissions: No permissions required
+
Request definition:
+
+
GET /admin/projects/shortcode/{shortcode}
+
GET /admin/projects/shortname/{shortname}
+
GET /admin/projects/iri/{iri}
+
+
Description: Returns a single project identified by shortcode, shortname or IRI.
!d,d The returned image is scaled so that the width and height of the returned image are not greater than d,
+ while maintaining the aspect ratio.
+
pct:n The width and height of the returned image is scaled to n percent
+ of the width and height of the original image. 1<= n <= 100.
+
+
If the watermark is set to true, the returned image will be watermarked, otherwise the default size !128,128 is set.
+It is only possible to set either the size or the watermark, not both at the same time.
+
Permissions: ProjectAdmin/SystemAdmin
+
Request definition:
+
+
POST /admin/projects/iri/{iri}/RestrictedViewSettings
+
POST /admin/projects/shortcode/{shortcode}/RestrictedViewSettings
+
+
Description: Set the project's restricted view
+
The endpoint accepts either a size or a watermark but not both.
This endpoint allows manipulation of the triplestore content.
+
POST admin/store/ResetTriplestoreContent resets the triplestore content, given that the allowReloadOverHttp
+configuration flag is set to true. This route is mostly used in tests.
A client can obtain an access token by sending a POST request (e.g., {"identifier_type":"identifier_value",
+"password":"password_value"}) to the /v2/authentication route with
+identifier and password in the body. The identifier_type can be iri, email, or username.
+If the credentials are valid, a JSON WEB Token (JWT) will be sent back in the
+response (e.g., {"token": "eyJ0eXAiOiJ..."}). Additionally, for web browser clients a session cookie
+containing the JWT token is also created, containing KnoraAuthentication=eyJ0eXAiOiJ....
+
To logout, the client sends a DELETE request to the same route /v2/authentication and
+the access token in one of the three described ways. This will invalidate the access token,
+thus not allowing further request that would supply the invalidated token.
+
Checking Credentials
+
To check the credentials, send a GET request to /v2/authentication with the credentials
+supplied as URL parameters or HTTP authentication headers as described before.
+
Usage Scenarios
+
+
Create token by logging-in, send token on each subsequent request, and logout when finished.
The body of the request is a JSON-LD document in the
+complex API schema, specifying the type,rdfs:label, and its Knora resource properties
+and their values. The representation of the resource is the same as when it is returned in a GET request, except that
+its knora-api:attachedToUser is not given, and the resource IRI and those of its values can be optionally specified.
+The format of the values submitted is described in Creating and Editing Values.
+If there are multiple values for a property, these must be given in an array.
+
For example, here is a request to create a resource with various value types:
Permissions for the new resource can be given by adding knora-api:hasPermissions, a custom creation date can be
+specified by adding knora-api:creationDate
+(an xsd:dateTimeStamp), and the resource's creator can be specfied
+by adding knora-api:attachedToUser. For example:
To create a resource, the user must have permission to create resources of that class in that project.
+
The predicate knora-api:attachedToUser can be used to specify a creator other than the requesting user only if the
+requesting user is an administrator of the project or a system administrator. The specified creator must also have
+permission to create resources of that class in that project.
+
In addition to the creation date, in the body of the request, it is possible to specify a custom IRI (
+of Knora IRI form) for a resource through the @id attribute which will then be assigned
+to the resource; otherwise the resource will get a unique random IRI.
+
A custom resource IRI must be http://rdfh.ch/PROJECT_SHORTCODE/ (where PROJECT_SHORTCODE
+is the shortcode of the project that the resource belongs to) plus a custom ID string.
+
Similarly, it is possible to assign a custom IRI to the values using their @id attributes; if not given, random IRIs
+will be assigned to the values.
+
A custom value IRI must be the IRI of the containing resource, followed by a /values/ and a custom ID string.
+
An optional custom UUID of a value can also be given by adding knora-api:valueHasUUID. Each custom UUID must
+be base64url-encoded without padding. Each value of the new resource
+can also have a custom creation date specified by adding knora-api:creationDate
+(an xsd:dateTimeStamp). For example:
You can modify the following metadata attached to a resource:
+
+
label
+
permissions
+
last modification date
+
+
To do this, use this route:
+
HTTP PUT to http://host/v2/resources
+
+
The request body is a JSON-LD object containing the following information about the resource:
+
+
@id: the resource's IRI
+
@type: the resource's class IRI
+
knora-api:lastModificationDate: an xsd:dateTimeStamp representing the last modification date that is currently
+ attached to the resource, if any. This is used to make sure that the resource has not been modified by someone else
+ since you last read it.
+
+
The submitted JSON-LD object must also contain one or more of the following predicates, representing the metadata you
+want to change:
+
+
rdfs:label: a string
+
knora-api:hasPermissions, in the format described
+ in Permissions
{
+"@id":"http://rdfh.ch/0001/a-thing",
+"@type":"anything:Thing",
+"rdfs:label":"this is the new label",
+"knora-api:hasPermissions":"CR knora-admin:Creator|M knora-admin:ProjectMember|V knora-admin:ProjectMember",
+"knora-api:lastModificationDate":{
+"@type":"xsd:dateTimeStamp",
+"@value":"2017-11-20T15:55:17Z"
+},
+"knora-api:newModificationDate":{
+"@type":"xsd:dateTimeStamp",
+"@value":"2018-12-21T16:56:18Z"
+},
+"@context":{
+"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+"knora-api":"http://api.knora.org/ontology/knora-api/v2#",
+"rdfs":"http://www.w3.org/2000/01/rdf-schema#",
+"xsd":"http://www.w3.org/2001/XMLSchema#",
+"anything":"http://0.0.0.0:3333/ontology/0001/anything/v2#"
+}
+}
+
+
If you submit a knora-api:lastModificationDate that is different from the resource's actual last modification date,
+you will get an HTTP 409 (Conflict) error.
+
If you submit a knora-api:newModificationDate that is earlier than the resource's knora-api:lastModificationDate,
+you will get an HTTP 400 (Bad Request) error.
+
A successful response is an HTTP 200 (OK) status containing the resource's metadata.
+
Deleting a Resource
+
Knora does not normally delete resources; instead, it marks them as deleted, which means that they do not appear in
+normal query results.
+
To mark a resource as deleted, use this route:
+
HTTP POST to http://host/v2/resources/delete
+
+
The request body is a JSON-LD object containing the following information about the resource:
+
+
@id: the resource's IRI
+
@type: the resource's class IRI
+
knora-api:lastModificationDate: an xsd:dateTimeStamp representing the last modification date that is currently
+ attached to the resource, if any. This is used to make sure that the resource has not been modified by someone else
+ since you last read it.
+
+
{
+"@id":"http://rdfh.ch/0001/a-thing",
+"@type":"anything:Thing",
+"knora-api:lastModificationDate":{
+"@type":"xsd:dateTimeStamp",
+"@value":"2019-02-05T17:05:35.776747Z"
+},
+"knora-api:deleteComment":"This resource was created by mistake.",
+"@context":{
+"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+"knora-api":"http://api.knora.org/ontology/knora-api/v2#",
+"rdfs":"http://www.w3.org/2000/01/rdf-schema#",
+"xsd":"http://www.w3.org/2001/XMLSchema#",
+"anything":"http://0.0.0.0:3333/ontology/0001/anything/v2#"
+}
+}
+
+
The optional property knora-api:deleteComment specifies a comment to be attached to the resource, explaining why it
+has been marked as deleted.
+
The optional property knora-api:deleteDate
+(an xsd:dateTimeStamp)
+indicates when the resource was marked as deleted; if not given, the current time is used.
+
The response is a JSON-LD document containing the predicate knora-api:result with a confirmation message.
+
Requesting Deleted Resources
+
Resources marked as deleted are not found in search queries. It is however possible to request them directly or from an
+ARK URL. In these instances, the API will not return the deleted resource, but instead a generic resource of type
+knora-base:DeletedResource. This resource will be similar to the requested resource, having e.g. the same IRI.
+The resource will contain the deletion date and optionally the deletion comment.
+
The response to requesting a deleted resource will look as the following example:
If resource A has a link to resource B, and resource
+B is later marked as deleted, A's link will still exist. DSP-API v2 will still return the link when A is queried,
+but without any information about B (except for B's IRI). If A's link is necessary to meet the requirements of a
+cardinality, marking B as deleted will not violate the cardinality.
+
The reason for this design is that A and B might be in different projects, and each project must retain control of
+its resources and be able to mark them as deleted, even if they are used by another project.
+
Erasing a Resource from the Triplestore
+
Normally, resources are not actually removed from the triplestore; they are only marked as deleted (see
+Deleting a Resource). However, sometimes it is necessary to erase a resource from the
+triplestore. To do so, use this route:
+
HTTP POST to http://host/v2/resources/erase
+
+
The request body is the same as for Deleting a Resource, except that knora-api:deleteComment
+is not relevant and will be ignored.
+
To do this, a user must be a system administrator or an administrator of the project containing the resource. The user's
+permissions on the resource are not otherwise checked.
+
A resource cannot be erased if any other resource has a link to it. Any such links must first be changed or marked as
+deleted (see Updating a Value and
+Deleting a Value). Then, when the resource is erased, the deleted link values that
+referred to it will also be erased.
+
This operation cannot be undone (except by restoring the repository from a backup), so use it with care.
To create a value in an existing resource, use this route:
+
HTTP POST to http://host/v2/values
+
+
The body of the request is a JSON-LD document in the
+complex API schema, specifying the resource's IRI and type, the resource property, and the
+content of the value. The representation of the value is the same as when it is returned in a GET request, except that
+its IRI and knora-api:attachedToUser are not given. For example, to create an integer value:
Each value can have an optional custom IRI (of Knora IRI form) specified by the @id
+attribute, a custom creation date specified by adding knora-api:valueCreationDate (an
+xsd:dateTimeStamp), or a custom UUID given by
+knora-api:valueHasUUID. Each custom UUID must be base64url-encoded, without padding. If a custom
+UUID is provided, it will be used in value IRI. If a custom IRI is given for the value, its UUID should match the given
+custom UUID. If a custom IRI is provided, but there is no custom UUID provided, then the UUID given in the IRI will be
+assigned to the knora-api:valueHasUUID. A custom value IRI must be the IRI of the containing resource, followed by
+a /values/ and a custom ID string. For example:
To create a value, the user must have modify permission on the containing resource.
+
The response is a JSON-LD document containing:
+
+
@id: the IRI of the value that was created.
+
@type: the value's type.
+
knora-api:valueHasUUID, the value's UUID, which remains stable across value versions
+ (except for link values, as explained below).
+
+
Creating a Link Between Resources
+
To create a link, you must create a knora-api:LinkValue, which represents metadata about the link. The property that
+connects the resource to the LinkValue is a link value property, whose name is constructed by adding Value to the
+name of the link property (see
+Links Between Resources). The triple representing the
+direct link between the resources is created automatically. For example, if the link property that should connect the
+resources is anything:hasOtherThing, we can create a link like this:
As with ordinary values, permissions on links can be specified by adding knora-api:hasPermissions.
+
The response is a JSON-LD document containing:
+
+
@id: the IRI of the value that was created.
+
@type: the value's type.
+
knora-api:valueHasUUID, the value's UUID, which remains stable across value versions, unless the link is changed to
+ point to a different resource, in which case it is considered a new link and gets a new UUID. Changing a link's
+ metadata, without changing its target, creates a new version of the link value with the same UUID.
+
+
Creating a Text Value Without Standoff Markup
+
Use the predicate knora-api:valueAsString of knora-api:TextValue:
+
{
+"@id":"http://rdfh.ch/0001/a-thing",
+"@type":"anything:Thing",
+"anything:hasText":{
+"@type":"knora-api:TextValue",
+"knora-api:valueAsString":"This is a text without markup."
+},
+"@context":{
+"knora-api":"http://api.knora.org/ontology/knora-api/v2#",
+"anything":"http://0.0.0.0:3333/ontology/0001/anything/v2#"
+}
+}
+
+
Creating a Text Value with Standoff Markup
+
Currently, the only way to create a text value with standoff markup
+is to submit it in XML format using an XML-to-standoff mapping.
+See here for more detials.
+
Creating a Text Value with Standard Mapping
+
To create a value with the standard mapping (http://rdfh.ch/standoff/mappings/StandardMapping), we can make an XML
+document like this:
This document can then be embedded in a JSON-LD request, using the predicate knora-api:textValueAsXml:
+
{
+"@id":"http://rdfh.ch/0001/a-thing",
+"@type":"anything:Thing",
+"anything:hasText":{
+"@type":"knora-api:TextValue",
+"knora-api:textValueAsXml":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<text>\n This text links to another <a class=\"salsah-link\" href=\"http://rdfh.ch/0001/another-thing\">resource</a>.\n</text>",
+"knora-api:textValueHasMapping":{
+"@id":"http://rdfh.ch/standoff/mappings/StandardMapping"
+}
+},
+"@context":{
+"knora-api":"http://api.knora.org/ontology/knora-api/v2#",
+"anything":"http://0.0.0.0:3333/ontology/0001/anything/v2#"
+}
+}
+
+
Note that quotation marks and line breaks in the XML must be escaped, and that the IRI of the mapping must be provided.
+
Creating a Text Value with a Custom Mapping
+
To create a text value with custom mapping, the following steps are required:
+
+
Optionally, an XSL transformation resource (kb:XSLTransformation) can be created that may be defined as the default
+ transformation of the mapping.
+
The mapping resource (kb:XMLToStandoffMapping) must be created, if it does not already exist.
+
The text value can be created as in the example above, using the mapping resource IRI in kb:textValueHasMapping.
+
+
The kb:XSLTransformation resource is a subclass of kb:TextRepresentation, so it has a kb:hasTextFileValue pointing
+to a kb:TextFileValue
+which represents the XSLT file stored in SIPI. For more Details, see Creating File Values.
+
The kb:XMLToStandoffMapping resource requires the mapping XML as
+specified here.
+If an XSL transformation has been defined, the IRI the transformation can be placed in the <defaultXSLTransformation>
+tag of the mapping XML.
+
If a mapping has been defined, then requesting the text value will return both the kb:textValueAsXml and
+the kb:textValueAsHtml properties,
+where the XML can be used for editing the value, while the HTML can be used to display it.
+If no mapping has been defined, only kb:textValueAsXml can be returned.
+
Creating File Values
+
DSP-API supports the storage of certain types of data as files, using SIPI
+(see FileValue). DSP-API v2 currently supports using SIPI to store
+the following types of files:
+
+
Images: JPEG, JPEG2000, TIFF, or PNG which are stored internally as JPEG2000
+
Documents: PDF
+
Audio: MPEG or Waveform audio file format (.wav, .x-wav, .vnd.wave)
Support for other types of files will be added in the future.
+
The following sections describe the steps for creating a file value.
+
Files can be ingested into DSP using SIPI or DSP-INGEST (experimental).
+
Upload Files to SIPI
+
The first step is to upload one or more files to SIPI, using a multipart/form-data request, where sipihost
+represents the host and port on which SIPI is running:
+
HTTP POST to http://sipihost/upload?token=TOKEN
+
+
The token parameter must provide the JSON Web Token that DSP-API returned when the client logged in.
+Each body part in the request must contain a parameter filename, providing the file's original filename, which both
+DSP-API and SIPI will store; these filenames can be descriptive and need not be unique.
+
SIPI stores the file in a temporary location. If the file is an image, it is converted first to JPEG2000 format, and the
+converted file is stored.
+
SIPI then returns a JSON response that looks something like this:
In this example, we uploaded two files to SIPI, so uploadedFiles is an array with two elements. For each file, we
+have:
+
+
the originalFilename, which we submitted when uploading the file
+
the unique internalFilename that SIPI has randomly generated for the file
+
the temporaryBaseIIIFUrl, which we can use to construct a IIIF URL for previewing the file
+
+
In the case of an image file, the client may now wish to get a thumbnail of each uploaded image, to allow the user to
+confirm that the correct files have been uploaded. This can be done by adding IIIF parameters to temporaryBaseIIIFUrl.
+For example, to get a JPG thumbnail image that is 150 pixels wide, you would add /full/150,/0/default.jpg.
+
Upload Files to DSP-INGEST
+
Support for DSP-INGEST is in its early stage and currently mainly intended for ingesting large amounts of data.
+When a file has been ingested through DSP-INGEST,
+it is necessary to send the header X-Asset-Ingested
+along with the request to create the file value resource in DSP-API.
+
Submit A File Value to DSP-API
+
A DSP-API Representation (i.e. a resource containing information about a file) must always have exactly one file value
+attached to it. (see Representations). Therefore, a request
+to create a new file value must always be submitted as part of a request to create a new resource (see
+Creating a Resource). You can also update a file value in an existing
+Representation; see Updating a Value.
+
Instead of providing the file's complete metadata to DSP-API, you just provide the unique internal filename generated by
+SIPI.
+
Still Images
+
Still Image may be stored in SIPI or in an external IIIF server.
+
Images stored in SIPI
+
Here is an example of a request to create a resource of class anything:ThingPicture with a still image stored in SIPI.
+The resource's class is a subclass of knora-api:StillImageRepresentation and therefore has the property knora-api:hasStillImageFileValue.
+The file value is of type knora-api:StillImageFileValue:
In the case of a knora-api:StillImageFileValue DSP-API gets the rest of the file's metadata from SIPI.
+If the client's request to DSP-API is valid, DSP-API saves the file value in the triplestore and instructs SIPI to move the file to permanent storage.
+Otherwise, the temporary file that was stored by SIPI is deleted.
+
Images stored in an external IIIF server
+
In the case of a Still image stored in an external IIIF server, the request is similar to the one above, but the file value is of type knora-api:StillImageExternalFileValue
+and the knora-api:externalUrl property is used to provide the URL of the image in the IIIF server:
Note: For backwards compatibility, we support using knora-api:fileValueHasExternalUrl and
+knora-api:stillImageFileValueExternalFileValue properties if the value is submitted as a
+String literal, i.e. "knora-api:stillImageFileValueExternalFileValue" : "https://example.com/iiif/3UIsXH9bP0j-BV0D4sN51Xz.jp2/full/max/0/default.jpg".
+Support for String literals and the knora-api:fileValueHasExternalUrl property is
+deprecated and will be removed in the future.
+The knora-api:stillImageFileValueHasExternalUrl property with a xsd:anyURI type is
+correct and must be used for reading and writing.
+
PDF Documents
+
If you're submitting a PDF document, use the resource class knora-api:DocumentRepresentation, which has the property
+knora-api:hasDocumentFileValue, pointing to a knora-api:DocumentFileValue.
+
Text Files
+
For a text file, use knora-api:TextRepresentation, which has the property knora-api:hasTextFileValue, pointing to a
+knora-api:TextFileValue.
+
Archive Files
+
For an archive like zip, use knora-api:ArchiveRepresentation, which has the property knora-api:hasArchiveFileValue,
+pointing to a knora-api:ArchiveFileValue.
+
Updating a Value
+
To update a value, use this route:
+
HTTP PUT to http://host/v2/values
+
+
Updating a value means creating a new version of an existing value. The new version will have a different IRI. The
+request is the same as for creating a value, except that the @id of the current value version is given. For example,
+to update an integer value:
The value can be given a comment by using knora-api:valueHasComment. To change only the comment of a value, you can
+resubmit the existing value with the updated comment.
+
Permissions can be specified by adding knora-api:hasPermissions. Otherwise, the new version has the same permissions
+as the previous one. To change the permissions on a value, the user must have change rights permission on the value.
+
To update only the permissions on a value, submit it with the new permissions and with its @id and @type but without
+any other content, like this:
A custom value IRI must be the IRI of the containing resource, followed by a /values/ and a custom ID string.
+
The response is a JSON-LD document containing only @id and @type, returning the IRI and type of the new value
+version.
+
If you submit an outdated value ID in a request to update a value, the response will be an HTTP 404 (Not Found) error.
+
The response to a value update request contains:
+
+
@id: the IRI of the value that was created.
+
@type: the value's type.
+
knora-api:valueHasUUID, the value's UUID, which remains stable across value versions, unless the value is a link
+ value and is changed to point to a different resource, in which case it is considered a new link and gets a new UUID.
+
+
Deleting a Value
+
DSP-API does not normally delete values; instead, it marks them as deleted, which means that they do not appear in normal
+query results.
+
To mark a value as deleted, use this route:
+
HTTP POST to http://host/v2/values/delete
+
+
The request must include the resource's ID and type, the property that points from the resource to the value, and the
+value's ID and type. For example:
+
{
+"@id":"http://rdfh.ch/0001/a-thing",
+"@type":"anything:Thing",
+"anything:hasInteger":{
+"@id":"http://rdfh.ch/0001/a-thing/values/vp96riPIRnmQcbMhgpv_Rg",
+"@type":"knora-api:IntValue",
+"knora-api:deleteComment":"This value was created by mistake."
+},
+"@context":{
+"knora-api":"http://api.knora.org/ontology/knora-api/v2#",
+"anything":"http://0.0.0.0:3333/ontology/0001/anything/v2#"
+}
+}
+
+
The optional property knora-api:deleteComment specifies a comment to be attached to the value, explaining why it has
+been marked as deleted
+
The optional property knora-api:deleteDate (an
+xsd:dateTimeStamp)
+specifies a custom timestamp indicating when the value was deleted. If not specified, the current time is used.
+
The response is a JSON-LD document containing the predicate knora-api:result with a confirmation message.
+
Requesting Deleted Values
+
Values marked as deleted are not found in search queries. But when requesting a resource that has deleted values, these
+will show up as generic knora-api:DeletedValue values. This value will be similar to the deleted value, having e.g.
+the same IRI. The DeletedValue will contain the deletion date and optionally the deletion comment.
+
The response to requesting a deleted resource will look as the following example:
Every request to API v2 includes v2 as a path segment, e.g.
+http://host/v2/resources/http%3A%2F%2Frdfh.ch%2Fc5058f3a.
+Accordingly, requests using any other version of the API will require
+another path segment.
Our preferred format for data exchange is
+JSON-LD. JSON-LD allows the
+DSP-API server to provide responses that are relatively easy for
+automated processes to interpret, since their structure and semantics is
+explicitly defined. For example, each user-created Knora resource
+property is identified by an IRI, which can be dereferenced to get more
+information about it (e.g. its label in different languages). Moreover,
+each value has a type represented by an IRI. These are either standard
+RDF types (e.g. XSD datatypes) or more complex types whose IRIs can be
+dereferenced to get more information about their structure.
+
At the same time, JSON-LD responses are relatively easy for software
+developers to work with, and are more concise and easier to read than
+the equivalent XML. Items in a response can have human-readable names,
+which can nevertheless be expanded to full IRIs. Also, while a format such as
+Turtle just provides a
+set of RDF triples, an equivalent JSON-LD response can explicitly
+provide data in a hierarchical structure, with objects nested inside
+other objects.
+
Hierarchical vs. Flat JSON-LD
+
The client can choose between hierarchical and flat JSON-LD. In hierarchical
+JSON-LD, entities with IRIs are inlined (nested) where they are used. If the
+same entity is used in more than one place, it is inlined only once, and other
+uses just refer to its IRI. In Knora's flat JSON-LD, all entities with IRIs are located
+at the top level of the document (in a @graph if there is more than one of them).
+This setting does not affect blank nodes, which are always inlined (unlike in standard
+flat JSON-LD). DSP ontologies are always returned in the flat rendering; other kinds
+of responses default to hierarchical. To use this setting, submit the HTTP header
+X-Knora-JSON-LD-Rendering with the value hierarchical or flat.
+
Knora IRIs
+
Resources and entities are identified by IRIs. The format of these IRIs
+is explained in Knora IRIs.
+
API Schema
+
DSP-API v2 uses RDF data structures that are simpler than the ones
+actually stored in the triplestore, and more suitable for the development
+of client software. Thus we refer to the internal schema of data
+as it is stored in the triplestore, and to external schemas which
+are used to represent that data in API v2.
+
DSP-API v2 offers a complex schema and a simple one. The main difference
+is that the complex schema exposes the complexity of value objects, while
+the simple version does not. A client that needs to edit values must use the
+complex schema in order to obtain the IRI of each value. A client that reads
+but does not update data can use the simplified schema. The simple schema is
+mainly intended to facilitate interoperability with other RDF-based systems in the
+context of Linked Open Data. It is therefore designed to use the
+simplest possible datatypes and to require minimal knowledge of Knora.
+
In either case, the client deals only with data whose structure and
+semantics are defined by external DSP-API ontologies, which are distinct from
+the internal ontologies that are used to store date in the triplestore. The Knora
+API server automatically converts back and forth between these internal
+and external representations. This approach encapsulates the internals
+and adds a layer of abstraction to them.
+
IRIs representing ontologies and ontology entities are different in different
+schemas; see Knora IRIs.
+
Some API operations inherently require the client to accept responses in
+the complex schema. For example, if an ontology is requested using an IRI
+indicating the simple schema, the ontology will be returned in the simple schema (see
+Querying, Creating, and Updating Ontologies).
+
Other API operations can return data in either schema. In this case, the
+complex schema is used by default in the response, unless the request specifically
+asks for the simple schema. The client can specify the desired schema by using
+an HTTP header or a URL parameter:
+
+
the HTTP header X-Knora-Accept-Schema
+
the URL parameter schema
+
+
Both the HTTP header and the URL parameter accept the values simple or
+complex.
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:
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-base
+
standoff
+
salsah-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:
+
+
knora
+
ontology
+
simple
+
shared
+
+
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:
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:
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:
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:
The response format uses prefixes to shorten IRIs, making them more
+human-readable. A client may wish to convert these to full IRIs for
+processing. This can be done with responses in JSON-LD by using a library
+that implements the JSON-LD API
+to compact the document with an empty JSON-LD @context.
+
Querying Ontology Metadata
+
Requests for ontology metadata can return information about more than one
+ontology, unlike other requests for ontology information. To get metadata
+about all ontologies:
+
HTTP GET to http://host/v2/ontologies/metadata
+
+
If you submit a project IRI in the X-Knora-Accept-Project header, only the
+ontologies for that project will be returned.
+
The response is in the complex API v2 schema. Sample response:
An ontology can be queried either by using an API route directly or by
+simply dereferencing the ontology IRI. The API route is as follows:
+
HTTP GET to http://host/v2/ontologies/allentities/ONTOLOGY_IRI
+
+
The ontology IRI must be URL-encoded, and may be in either the complex
+or the simple schema. The response will be in the same schema. For
+example, if the server is running on 0.0.0.0:3333, you can request
+the knora-api ontology in the complex schema as follows:
+
HTTP GET to http://0.0.0.0:3333/v2/ontologies/allentities/http%3A%2F%2Fapi.knora.org%2Fontology%2Fknora-api%2Fv2
+
+
By default, this returns the ontology in JSON-LD; to request Turtle
+or RDF/XML, add an HTTP Accept header
+(see Response Formats).
+
If the client dereferences a project-specific ontology IRI as a URL, the
+DSP-API server running on the hostname in the IRI will serve the
+ontology. For example, if the server is running on 0.0.0.0:3333, the
+IRI http://0.0.0.0:3333/ontology/00FF/images/simple/v2 can be
+dereferenced to request the images sample ontology in the simple
+schema.
+
If the client dereferences a built-in Knora ontology, such as
+http://api.knora.org/ontology/knora-api/simple/v2, there must be a
+DSP-API server running at api.knora.org that can serve the ontology.
+The DaSCH intends to run such as server. For
+testing, you can configure your local /etc/hosts file to resolve
+api.knora.org as localhost.
+
Differences Between Internal and External Ontologies
+
The external ontologies used by DSP-API v2 are different to the internal
+ontologies that are actually stored in the triplestore (see
+API Schema). In general, the external
+ontologies use simpler data structures, but they also provide additional
+information to make it easier for clients to use them. This is illustrated
+in the examples in the next sections.
+
The internal predicates knora-base:subjectClassConstraint and
+knora-base:objectClassConstraint (see
+Constraints on the Types of Property Subjects and Objects)
+are represented as knora-api:subjectType and knora-api:objectType in
+external ontologies.
+
JSON-LD Representation of an Ontology in the Simple Schema
+
The simple schema is suitable for client applications that need to read
+but not update data in Knora. For example, here is the response for the
+images sample ontology in the simple schema,
+http://0.0.0.0:3333/ontology/00FF/images/simple/v2 (simplified for
+clarity):
+
{
+"@id":"http://0.0.0.0:3333/ontology/00FF/images/simple/v2",
+"@type":"owl:Ontology",
+"rdfs:label":"The images demo ontology",
+"@graph":[{
+"@id":"images:bild",
+"@type":"owl:Class",
+"knora-api:resourceIcon":"bild.png",
+"rdfs:comment":"An image of the demo image collection",
+"rdfs:label":"Image",
+"rdfs:subClassOf":[{
+"@id":"knora-api:StillImageRepresentation"
+},{
+"@type":"owl:Restriction",
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:creationDate"
+}
+},{
+"@type":"owl:Restriction",
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasIncomingLink"
+}
+},{
+"@type":"owl:Restriction",
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasStandoffLinkTo"
+}
+},{
+"@type":"owl:Restriction",
+"owl:minCardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:hasStillImageFile"
+}
+},{
+"@type":"owl:Restriction",
+"owl:maxCardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:lastModificationDate"
+}
+},{
+"@type":"owl:Restriction",
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"rdfs:label"
+}
+},{
+"@type":"owl:Restriction",
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"images:description"
+}
+},{
+"@type":"owl:Restriction",
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"images:erfassungsdatum"
+}
+},{
+"@type":"owl:Restriction",
+"owl:maxCardinality":1,
+"owl:onProperty":{
+"@id":"images:urheber"
+}
+}]
+},{
+"@id":"images:description",
+"@type":"owl:DatatypeProperty",
+"knora-api:objectType":{
+"@id":"xsd:string"
+},
+"knora-api:subjectType":{
+"@id":"images:bild"
+},
+"rdfs:label":"Description",
+"rdfs:subPropertyOf":[{
+"@id":"knora-api:hasValue"
+},{
+"@id":"http://purl.org/dc/terms/description"
+}]
+},{
+"@id":"images:erfassungsdatum",
+"@type":"owl:DatatypeProperty",
+"knora-api:objectType":{
+"@id":"knora-api:Date"
+},
+"knora-api:subjectType":{
+"@id":"images:bild"
+},
+"rdfs:label":"Date of acquisition",
+"rdfs:subPropertyOf":[{
+"@id":"knora-api:hasValue"
+},{
+"@id":"http://purl.org/dc/terms/date"
+}]
+},{
+"@id":"images:firstname",
+"@type":"owl:DatatypeProperty",
+"knora-api:objectType":{
+"@id":"xsd:string"
+},
+"knora-api:subjectType":{
+"@id":"images:person"
+},
+"rdfs:comment":"First name of a person",
+"rdfs:label":"First name",
+"rdfs:subPropertyOf":{
+"@id":"knora-api:hasValue"
+}
+},{
+"@id":"images:lastname",
+"@type":"owl:DatatypeProperty",
+"knora-api:objectType":{
+"@id":"xsd:string"
+},
+"knora-api:subjectType":{
+"@id":"images:person"
+},
+"rdfs:comment":"Last name of a person",
+"rdfs:label":"Name",
+"rdfs:subPropertyOf":{
+"@id":"knora-api:hasValue"
+}
+},{
+"@id":"images:person",
+"@type":"owl:Class",
+"knora-api:resourceIcon":"person.png",
+"rdfs:comment":"Person",
+"rdfs:label":"Person",
+"rdfs:subClassOf":[{
+"@id":"knora-api:Resource"
+},{
+"@type":"owl:Restriction",
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:creationDate"
+}
+},{
+"@type":"owl:Restriction",
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasIncomingLink"
+}
+},{
+"@type":"owl:Restriction",
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasStandoffLinkTo"
+}
+},{
+"@type":"owl:Restriction",
+"owl:maxCardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:lastModificationDate"
+}
+},{
+"@type":"owl:Restriction",
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"rdfs:label"
+}
+},{
+"@type":"owl:Restriction",
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"images:lastname"
+}
+},{
+"@type":"owl:Restriction",
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"images:firstname"
+}
+}]
+},{
+"@id":"images:urheber",
+"@type":"owl:ObjectProperty",
+"knora-api:objectType":{
+"@id":"images:person"
+},
+"knora-api:subjectType":{
+"@id":"images:bild"
+},
+"rdfs:comment":"An entity primarily responsible for making the resource. Examples of a Creator include a person, an organization, or a service. Typically, the name of a Creator should be used to indicate the entity.",
+"rdfs:label":"Creator",
+"rdfs:subPropertyOf":{
+"@id":"knora-api:hasLinkTo"
+}
+}],
+"@context":{
+"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+"images":"http://0.0.0.0:3333/ontology/00FF/images/simple/v2#",
+"knora-api":"http://api.knora.org/ontology/knora-api/simple/v2#",
+"owl":"http://www.w3.org/2002/07/owl#",
+"rdfs":"http://www.w3.org/2000/01/rdf-schema#",
+"xsd":"http://www.w3.org/2001/XMLSchema#"
+}
+}
+
+
The response format is an RDF graph. The top level object describes the ontology
+itself, providing its IRI (in the @id member) and its rdfs:label.
+The @graph member (see
+Named Graphs in the
+JSON-LD specification) contains an array of entities that belong to the
+ontology.
+
In a class definition, cardinalities for properties of the class are
+represented as in OWL, using objects of type owl:Restriction. The
+supported cardinalities are the ones indicated in
+OWL Cardinalities.
+
The class definitions include cardinalities that are directly defined on
+each class, as well as cardinalities inherited from base classes. For
+example, we can see cardinalities inherited from knora-api:Resource,
+such as knora-api:hasStandoffLinkTo and http://schema.org/name
+(which represents rdfs:label).
+
In the simple schema, Knora value properties can be datatype properties.
+The knora-base:objectType of a Knora value property such as
+images:description is a literal datatype, in this case
+xsd:string. Moreover, images:description is a subproperty of
+the standard property dcterms:description, whose object can be a
+literal value. A client that understands rdfs:subPropertyOf, and is
+familiar with dcterms:description, can then work with
+images:description on the basis of its knowledge about
+dcterms:description.
+
By default, values for rdfs:label and rdfs:comment are returned only
+in the user's preferred language, or in the system default language. To
+obtain these values in all available languages, add the URL parameter
+?allLanguages=true. For example, with this parameter, the definition
+of images:description becomes:
To find out more about the knora-api entities used in the response,
+the client can request the knora-api ontology in the simple schema:
+http://api.knora.org/ontology/knora-api/simple/v2. For example,
+images:erfassungsdatum has a knora-api:objectType of
+knora-api:Date, which is a subtype of xsd:string with a
+Knora-specific, human-readable format. In the knora-api simple
+ontology, there is a definition of this type:
+
{
+"@id":"http://api.knora.org/ontology/knora-api/simple/v2",
+"@type":"owl:Ontology",
+"rdfs:label":"The knora-api ontology in the simple schema",
+"@graph":[{
+"@id":"knora-api:Date",
+"@type":"rdfs:Datatype",
+"rdfs:comment":"Represents a date as a period with different possible precisions.",
+"rdfs:label":"Date literal",
+"rdfs:subClassOf":{
+"@type":"rdfs:Datatype",
+"owl:onDatatype":{
+"@id":"xsd:string"
+},
+"owl:withRestrictions":{
+"xsd:pattern":"(GREGORIAN|JULIAN|ISLAMIC):\\d{1,4}(-\\d{1,2}(-\\d{1,2})?)?( BC| AD| BCE| CE)?(:\\d{1,4}(-\\d{1,2}(-\\d{1,2})?)?( BC| AD| BCE| CE)?)?"
+}
+}
+}],
+"@context":{
+"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+"knora-api":"http://api.knora.org/ontology/knora-api/simple/v2#",
+"owl":"http://www.w3.org/2002/07/owl#",
+"rdfs":"http://www.w3.org/2000/01/rdf-schema#",
+"xsd":"http://www.w3.org/2001/XMLSchema#"
+}
+}
+
+
JSON-LD Representation of an Ontology in the Complex Schema
+
The complex schema is suitable for client applications that need to
+update data in Knora. For example, here is the response for the images
+sample ontology in the complex schema, http://0.0.0.0:3333/ontology/00FF/images/v2
+(simplified for clarity):
+
{
+"@id":"http://0.0.0.0:3333/ontology/00FF/images/v2",
+"@type":"owl:Ontology",
+"knora-api:attachedToProject":{
+"@id":"http://rdfh.ch/projects/00FF"
+},
+"rdfs:label":"The images demo ontology",
+"@graph":[{
+"@id":"images:bild",
+"@type":"owl:Class",
+"knora-api:canBeInstantiated":true,
+"knora-api:isResourceClass":true,
+"knora-api:resourceIcon":"bild.png",
+"rdfs:comment":"An image of the demo image collection",
+"rdfs:label":"Image",
+"rdfs:subClassOf":[{
+"@id":"knora-api:StillImageRepresentation"
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:attachedToProject"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:attachedToUser"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:creationDate"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasIncomingLink"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:hasPermissions"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasStandoffLinkTo"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasStandoffLinkToValue"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:minCardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:hasStillImageFileValue"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:maxCardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:lastModificationDate"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"rdfs:label"
+}
+},{
+"@type":"owl:Restriction",
+"salsah-gui:guiOrder":3,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"images:description"
+}
+},{
+"@type":"owl:Restriction",
+"salsah-gui:guiOrder":8,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"images:erfassungsdatum"
+}
+},{
+"@type":"owl:Restriction",
+"salsah-gui:guiOrder":12,
+"owl:maxCardinality":1,
+"owl:onProperty":{
+"@id":"images:urheber"
+}
+},{
+"@type":"owl:Restriction",
+"salsah-gui:guiOrder":12,
+"owl:maxCardinality":1,
+"owl:onProperty":{
+"@id":"images:urheberValue"
+}
+}]
+},{
+"@id":"images:description",
+"@type":"owl:ObjectProperty",
+"knora-api:isEditable":true,
+"knora-api:isResourceProperty":true,
+"knora-api:objectType":{
+"@id":"knora-api:TextValue"
+},
+"knora-api:subjectType":{
+"@id":"images:bild"
+},
+"salsah-gui:guiAttribute":["rows=10","width=95%","wrap=soft"],
+"salsah-gui:guiElement":{
+"@id":"salsah-gui:Textarea"
+},
+"rdfs:label":"Description",
+"rdfs:subPropertyOf":[{
+"@id":"knora-api:hasValue"
+},{
+"@id":"http://purl.org/dc/terms/description"
+}]
+},{
+"@id":"images:erfassungsdatum",
+"@type":"owl:ObjectProperty",
+"knora-api:isEditable":true,
+"knora-api:isResourceProperty":true,
+"knora-api:objectType":{
+"@id":"knora-api:DateValue"
+},
+"knora-api:subjectType":{
+"@id":"images:bild"
+},
+"salsah-gui:guiElement":{
+"@id":"salsah-gui:Date"
+},
+"rdfs:label":"Date of acquisition",
+"rdfs:subPropertyOf":[{
+"@id":"knora-api:hasValue"
+},{
+"@id":"http://purl.org/dc/terms/date"
+}]
+},{
+"@id":"images:firstname",
+"@type":"owl:ObjectProperty",
+"knora-api:isEditable":true,
+"knora-api:isResourceProperty":true,
+"knora-api:objectType":{
+"@id":"knora-api:TextValue"
+},
+"knora-api:subjectType":{
+"@id":"images:person"
+},
+"salsah-gui:guiAttribute":["maxlength=32","size=32"],
+"salsah-gui:guiElement":{
+"@id":"salsah-gui:SimpleText"
+},
+"rdfs:comment":"First name of a person",
+"rdfs:label":"First name",
+"rdfs:subPropertyOf":{
+"@id":"knora-api:hasValue"
+}
+},{
+"@id":"images:lastname",
+"@type":"owl:ObjectProperty",
+"knora-api:isEditable":true,
+"knora-api:isResourceProperty":true,
+"knora-api:objectType":{
+"@id":"knora-api:TextValue"
+},
+"knora-api:subjectType":{
+"@id":"images:person"
+},
+"salsah-gui:guiAttribute":["maxlength=32","size=32"],
+"salsah-gui:guiElement":{
+"@id":"salsah-gui:SimpleText"
+},
+"rdfs:comment":"Last name of a person",
+"rdfs:label":"Name",
+"rdfs:subPropertyOf":{
+"@id":"knora-api:hasValue"
+}
+},{
+"@id":"images:person",
+"@type":"owl:Class",
+"knora-api:canBeInstantiated":true,
+"knora-api:isResourceClass":true,
+"knora-api:resourceIcon":"person.png",
+"rdfs:comment":"Person",
+"rdfs:label":"Person",
+"rdfs:subClassOf":[{
+"@id":"knora-api:Resource"
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:attachedToProject"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:attachedToUser"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:creationDate"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasIncomingLink"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:hasPermissions"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasStandoffLinkTo"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:minCardinality":0,
+"owl:onProperty":{
+"@id":"knora-api:hasStandoffLinkToValue"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:maxCardinality":1,
+"owl:onProperty":{
+"@id":"knora-api:lastModificationDate"
+}
+},{
+"@type":"owl:Restriction",
+"knora-api:isInherited":true,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"rdfs:label"
+}
+},{
+"@type":"owl:Restriction",
+"salsah-gui:guiOrder":0,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"images:lastname"
+}
+},{
+"@type":"owl:Restriction",
+"salsah-gui:guiOrder":1,
+"owl:cardinality":1,
+"owl:onProperty":{
+"@id":"images:firstname"
+}
+}]
+},{
+"@id":"images:urheber",
+"@type":"owl:ObjectProperty",
+"knora-api:isEditable":true,
+"knora-api:isLinkProperty":true,
+"knora-api:isResourceProperty":true,
+"knora-api:objectType":{
+"@id":"images:person"
+},
+"knora-api:subjectType":{
+"@id":"images:bild"
+},
+"salsah-gui:guiAttribute":"numprops=2",
+"salsah-gui:guiElement":{
+"@id":"salsah-gui:Searchbox"
+},
+"rdfs:comment":"An entity primarily responsible for making the resource. Examples of a Creator include a person, an organization, or a service. Typically, the name of a Creator should be used to indicate the entity.",
+"rdfs:label":"Creator",
+"rdfs:subPropertyOf":{
+"@id":"knora-api:hasLinkTo"
+}
+},{
+"@id":"images:urheberValue",
+"@type":"owl:ObjectProperty",
+"knora-api:isEditable":true,
+"knora-api:isLinkValueProperty":true,
+"knora-api:isResourceProperty":true,
+"knora-api:objectType":{
+"@id":"knora-api:LinkValue"
+},
+"knora-api:subjectType":{
+"@id":"images:bild"
+},
+"salsah-gui:guiAttribute":"numprops=2",
+"salsah-gui:guiElement":{
+"@id":"salsah-gui:Searchbox"
+},
+"rdfs:comment":"An entity primarily responsible for making the resource. Examples of a Creator include a person, an organization, or a service. Typically, the name of a Creator should be used to indicate the entity.",
+"rdfs:label":"Creator",
+"rdfs:subPropertyOf":{
+"@id":"knora-api:hasLinkToValue"
+}
+}],
+"@context":{
+"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+"images":"http://0.0.0.0:3333/ontology/00FF/images/v2#",
+"knora-api":"http://api.knora.org/ontology/knora-api/v2#",
+"owl":"http://www.w3.org/2002/07/owl#",
+"salsah-gui":"http://api.knora.org/ontology/salsah-gui/v2#",
+"rdfs":"http://www.w3.org/2000/01/rdf-schema#",
+"xsd":"http://www.w3.org/2001/XMLSchema#"
+}
+}
+
+
In the complex schema, all Knora value properties are object properties,
+whose objects are IRIs, each of which uniquely identifies a value that
+contains metadata and can potentially be edited. The
+knora-base:objectType of a Knora value property such as
+images:description is a Knora value class, in this case
+knora-api:TextValue. Similarly, images:erfassungsdatum has a
+knora-api:objectType of knora-api:DateValue, which has a more
+complex structure than the knora-api:Date datatype shown in the
+previous section. A client can find out more about these value classes
+by requesting the knora-api ontology in the complex schema,
+http://api.knora.org/ontology/knora-api/v2.
+
Moreover, additional information is provided in the complex schema, to
+help clients that wish to create or update resources and values. A Knora
+resource class that can be instantiated is identified with the boolean
+properties knora-api:isResourceClass and
+knora-api:canBeInstantiated, to distinguish it from built-in abstract
+classes. Knora resource properties whose values can be edited by clients
+are identified with knora-api:isResourceProperty and
+knora-api:isEditable, to distinguish them from properties whose values
+are maintained automatically by Knora. Link value
+properties are shown along with link properties, because a client that
+updates links will need the IRIs of their link values. The predicate
+salsah-gui:guiOrder tells a GUI client in what order to display the
+properties of a class, and the predicates salsah-gui:guiElement and
+salsah-gui:guiAttribute specify how to configure a GUI element for
+editing the value of a property. For more information on the
+salsah-gui ontology, see The SALSAH GUI Ontology.
+
Querying class definition
+
To get the definition of a class, use the following route:
+
HTTP GET to http://host/v2/ontologies/classes/CLASS_IRI
+
The ontology update API must ensure that the ontologies it creates are
+valid and consistent, and that existing data is not invalidated by a
+change to an ontology. To make this easier to enforce, the ontology
+update API allows only one entity to be created or modified at a time.
+It is not possible to submit an entire ontology all at once. Each
+update request is a JSON-LD document providing only the information that is
+relevant to the update.
+
Moreover, the API enforces the following rules:
+
+
An entity (i.e. a class or property) cannot be referred to until it has been created.
+
An entity cannot be modified or deleted if it is used in data,
+ except for changes to its rdfs:label or rdfs:comment.
+
An entity cannot be modified if another entity refers to it, with
+ one exception: a knora-api:subjectType or knora-api:objectType
+ that refers to a class will not prevent the class's cardinalities
+ from being modified.
+
+
Because of these rules, some operations have to be done in a specific
+order:
+
+
Properties have to be defined before they can be used in the
+ cardinalities of a class, but a property's knora-api:subjectType
+ cannot refer to a class that does not yet exist. The recommended
+ approach is to first create a class with no cardinalities, then
+ create the properties that it needs, then add cardinalities for
+ those properties to the class.
+
To delete a class along with its properties, the client must first
+ remove the cardinalities from the class, then delete the property
+ definitions, then delete the class definition.
+
+
When changing an existing ontology, the client must always supply the
+ontology's knora-api:lastModificationDate, which is returned in the
+response to each update or when querying the ontology.
+If user A attempts to update an ontology, but
+user B has already updated it since the last time user A received the
+ontology's knora-api:lastModificationDate, user A's update will be
+rejected with an HTTP 409 Conflict error. This means that it is possible
+for two different users to work concurrently on the same ontology, but
+this is discouraged since it is likely to lead to confusion.
+
An ontology can be created or updated only by a system administrator, or
+by a project administrator in the ontology's project.
+
Ontology updates always use the complex schema.
+
Creating a New Ontology
+
An ontology is always created within a particular project.
The ontology name must follow the rules given in
+Knora IRIs.
+
The ontology metadata can have an optional comment given in the request
+body as:
+
"rdfs:comment": "some comment",
+
+
If the ontology is to be shared by multiple projects, it must be
+created in the default shared ontologies project,
+http://www.knora.org/ontology/knora-base#DefaultSharedOntologiesProject,
+and the request must have this additional boolean property:
A successful response will be a JSON-LD document providing only the
+ontology's metadata, which includes the ontology's IRI. When the client
+makes further requests to create entities (classes and properties) in
+the ontology, it must construct entity IRIs by concatenating the
+ontology IRI, a # character, and the entity name. An entity name must
+be a valid XML NCName.
+
Changing an Ontology's Metadata
+
One can modify an ontology's metadata by updating its rdfs:label or rdfs:comment
+or both. The example below shows the request for changing the label of an ontology.
The request body can also contain a new label and a new comment for the ontology's metadata.
+A successful response will be a JSON-LD document providing only the
+ontology's metadata.
+
Deleting an Ontology's comment
+
HTTP DELETE to http://host/v2/ontologies/comment/ONTOLOGY_IRI?lastModificationDate=ONTOLOGY_LAST_MODIFICATION_DATE
+
+
The ontology IRI and the ontology's last modification date must be
+URL-encoded.
+
A successful response will be a JSON-LD document containing the ontology's
+updated metadata.
+
Deleting an Ontology
+
An ontology can be deleted only if it is not used in data.
+
HTTP DELETE to http://host/v2/ontologies/ONTOLOGY_IRI?lastModificationDate=ONTOLOGY_LAST_MODIFICATION_DATE
+
+
The ontology IRI and the ontology's last modification date must be
+URL-encoded.
+
A successful response will be a JSON-LD document containing a
+confirmation message.
+
To check whether an ontology can be deleted:
+
HTTP GET to http://host/v2/ontologies/candeleteontology/ONTOLOGY_IRI
+
Values for rdfs:label must be submitted in at least
+one language, either as an object or as an array of objects.
+
Values for rdfs:comment are optional, but if they are provided, they must include a language code.
+
At least one base class must be provided, which can be
+knora-api:Resource or any of its subclasses.
+
A successful response will be a JSON-LD document providing the new class
+definition (but not any of the other entities in the ontology).
+
Creating a Class With Cardinalities
+
This can work if the new class will have cardinalities for properties
+that have no knora-api:subjectType, or if the new class will be a
+subclass of their knora-api:subjectType.
OWL_CARDINALITY_PREDICATE and OWL_CARDINALITY_VALUE must correspond
+to the supported combinations given in
+OWL Cardinalities. (The placeholder
+OWL_CARDINALITY_VALUE is shown here in quotes, but it should be an
+unquoted integer.)
+
Values for rdfs:label must be submitted in at least
+one language, either as an object or as an array of objects.
+
Values for rdfs:comment are optional, but if they are provided, they must include a language code.
+
At least one base class must be provided.
+
When a cardinality on a link property is submitted, an identical cardinality
+on the corresponding link value property is automatically added (see
+Links Between Resources).
+
A successful response will be a JSON-LD document providing the new class
+definition (but not any of the other entities in the ontology).
+
Changing the Labels of a Class
+
This operation is permitted even if the class is used in data.
Values for rdfs:label must be submitted in at least one language,
+either as an object or as an array of objects. The submitted labels will
+replace the existing ones.
Values for rdfs:comment must be submitted in at least one language,
+either as an object or as an array of objects. The submitted comments
+will replace the existing ones.
Values for rdfs:label must be submitted in at least
+one language, either as an object or as an array of objects.
+
Values for rdfs:comment are optional, but if they are provided, they must include a language code.
+
At least one base property must be provided, which can be
+knora-api:hasValue, knora-api:hasLinkTo, or any of their
+subproperties, with the exception of file properties (subproperties of
+knora-api:hasFileValue) and link value properties (subproperties of
+knora-api:hasLinkToValue).
+
If the property is a link property, the corresponding link value property
+(see Links Between Resources)
+will automatically be created.
+
The property definition must specify its knora-api:objectType. If the
+new property is a subproperty of knora-api:hasValue, its
+knora-api:objectType must be one of the built-in subclasses of
+knora-api:Value, which are defined in the knora-api ontology in the
+complex schema. If the new property is a subproperty of
+knora-base:hasLinkTo, its knora-api:objectType must be a subclass of
+knora-api:Resource.
+
To improve consistency checking, it is recommended, but not required, to
+provide knora-api:subjectType, which must be a subclass of
+knora-api:Resource.
+
The predicates salsah-gui:guiElement and salsah-gui:guiAttribute are
+optional. If provided, the object of guiElement must be one of the OWL
+named individuals defined in
+The SALSAH GUI Ontology. Some GUI elements
+take required or optional attributes, which are provided as objects of
+salsah-gui:guiAttribute; see The SALSAH GUI Ontology
+for details.
+
A successful response will be a JSON-LD document providing the new
+property definition (but not any of the other entities in the ontology).
+
Changing the Labels of a Property
+
This operation is permitted even if the property is used in data.
+
HTTP PUT to http://host/v2/ontologies/properties
+
To remove the values of salsah-gui:guiElement and salsah-gui:guiAttribute from
+the property definition, submit the request without those predicates.
+
Adding Cardinalities to a Class
+
If the class (or any of its sub-classes) is used in data,
+it is not allowed to add cardinalities owl:minCardinality greater than 0 or owl:cardinality 1 to the class.
+
HTTP POST to http://host/v2/ontologies/cardinalities
+
OWL_CARDINALITY_PREDICATE and OWL_CARDINALITY_VALUE must correspond
+to the supported combinations given in
+OWL Cardinalities. (The placeholder
+OWL_CARDINALITY_VALUE is shown here in quotes, but it should be an
+unquoted integer.)
+
When a cardinality on a link property is submitted, an identical cardinality
+on the corresponding link value property is automatically added (see
+Links Between Resources).
+
A successful response will be a JSON-LD document providing the new class
+definition (but not any of the other entities in the ontology).
+
Replacing the Cardinalities of a Class
+
It is possible to replace all cardinalities on properties used by a class.
+If it succeeds the request will effectively replace all direct cardinalities of the class as specified.
+That is, it removes all the cardinalities from the class and replaces them with the submitted cardinalities.
+Meaning that, if no cardinalities are submitted (i.e. the request contains no rdfs:subClassOf),
+the class is left with no cardinalities.
+
The request will fail if any of the "Pre-Update Checks" fails.
+A partial update of the ontology will not be performed.
+
Pre-Update Checks
+
+
Ontology Check
+
Any given cardinality on a property must be included in any of the existing cardinalities
+ for the same property of the super-classes.
+
Any given cardinality on a property must include the effective cardinalities
+ for the same property of all subclasses,
+ taking into account the respective inherited cardinalities from the class hierarchy of the subclasses.
+
+
+
Consistency Check with existing data
+
Given that instances of the class or any of its subclasses exist,
+ then these instances are checked if they conform to the given cardinality.
+
+
+
+
+
Subproperty handling for cardinality pre-update checks
+
The Pre-Update check does not take into account any subproperty relations between the properties.
+Every cardinality is checked against only the given property and not its subproperties,
+neither in the ontology nor the consistency check with existing data.
+This means that currently it is necessary to maintain the cardinalities on all subproperties of a property
+in sync with the cardinalities on the superproperty.
+
+
HTTP PUT to http://host/v2/ontologies/cardinalities
+
OWL_CARDINALITY_PREDICATE and OWL_CARDINALITY_VALUE must correspond
+to the supported combinations given in
+OWL Cardinalities. (The placeholder
+OWL_CARDINALITY_VALUE is shown here in quotes, but it should be an
+unquoted integer.)
+
When a cardinality on a link property is submitted, an identical cardinality
+on the corresponding link value property is automatically added (see
+Links Between Resources).
+
A successful response will be a JSON-LD document providing the new class definition (but not any of the other entities in the ontology).
+If any of the "Pre-Update Checks" fail the endpoint will respond with a 400 Bad Request containing the reasons why the update failed.
+
The "Pre-Update Checks" are available on a dedicated endpoint.
+For a check whether a particular cardinality can be set on a class/property combination, use the following request:
+
HTTP GET to http://host/v2/ontologies/canreplacecardinalities/CLASS_IRI?propertyIri=PROPERTY_IRI&newCardinality=[0-1|1|1-n|0-n]
+
The ontologies/canreplacecardinalities/CLASS_IRI request is only checking if the class is in use.
+
Delete a single cardinality from a class
+
If a class is used in data, it is only allowed to delete a cardinality, if the
+property a cardinality refers to, is not used inside the data. Also, the property
+isn't allowed to be used inside the data in any subclasses of this class.
+
HTTP PATCH to http://host/v2/ontologies/cardinalities
+
OWL_CARDINALITY_PREDICATE and OWL_CARDINALITY_VALUE must correspond
+to the supported combinations given in
+OWL Cardinalities. (The placeholder
+OWL_CARDINALITY_VALUE is shown here in quotes, but it should be an
+unquoted integer.)
+
When a cardinality on a link property is submitted, an identical cardinality
+on the corresponding link value property is automatically added (see
+Links Between Resources).
+
A successful response will be a JSON-LD document providing the new class
+definition (but not any of the other entities in the ontology).
+
To check whether a class's cardinality can be deleted:
+
HTTP POST to http://host/v2/ontologies/candeletecardinalities
+
Only the cardinalities whose GUI order is to be changed need to be included
+in the request. The OWL_CARDINALITY_PREDICATE and OWL_CARDINALITY_VALUE
+are ignored; only the GUI_ORDER_VALUE is changed.
+
Deleting a Property
+
A property can be deleted only if no other ontology entity refers to it,
+and if it is not used in data.
+
HTTP DELETE to http://host/v2/ontologies/properties/PROPERTY_IRI?lastModificationDate=ONTOLOGY_LAST_MODIFICATION_DATE
+
+
The property IRI and the ontology's last modification date must be
+URL-encoded.
+
If the property is a link property, the corresponding link value property
+(see Links Between Resources)
+will automatically be deleted.
+
A successful response will be a JSON-LD document providing only the
+ontology's metadata.
+
To check whether a property can be deleted:
+
HTTP GET to http://host/v2/ontologies/candeleteproperty/PROPERTY_IRI
+
Knora provides a permanent, citable URL for each resource and value.
+These URLs use Archival Resource Key (ARK) Identifiers,
+and are designed to remain valid even if the resource itself is moved
+from one Knora repository to another.
+
Obtaining ARK URLs
+
In the complex schema, a resource or value
+is always returned with two ARK URLs: one that will always refer
+to the latest version of the resource or value (knora-api:arkUrl), and one that refers
+specifically to the version being returned (knora-api:versionArkUrl).
+For example:
The format of a Knora project ARK URL is as follows:
+
http://HOST/ark:/NAAN/VERSION/PROJECT
+
+
NAAN is a
+Name Assigning Authority Number,
+VERSION is the version number of the Knora ARK URL format (currently always 1),
+and PROJECT is the project's short-code.
+
For example, given a project with ID 0001, and using the DaSCH's ARK resolver
+hostname and NAAN, the ARK URL for the project itself is:
+
http://ark.dasch.swiss/ark:/72163/1/0001
+
+
This could redirect to a page describing the project.
+
ARK URLs for Resources
+
The format of a Knora resource ARK URL is as follows:
NAAN is a
+Name Assigning Authority Number,
+VERSION is the version number of the Knora ARK URL format (currently always 1),
+PROJECT is the project's short-code,
+and RESOURCE_UUID is the resource's UUID.
+
For example, given the Knora resource IRI http://rdfh.ch/0001/0C-0L1kORryKzJAJxxRyRQ,
+and using the DaSCH's ARK resolver hostname and NAAN, the corresponding
+ARK URL without a timestamp is:
NAAN is a
+Name Assigning Authority Number,
+VERSION is the version number of the Knora ARK URL format (currently always 1),
+PROJECT is the project's short-code,
+RESOURCE_UUID is the resource's UUID, and VALUE_UUID
+is the value's knora-api:valueHasUUID.
+
For example, given a value with knora-api:valueHasUUID "4OOf3qJUTnCDXlPNnygSzQ" in the resource
+http://rdfh.ch/0001/0C-0L1kORryKzJAJxxRyRQ, and using the DaSCH's ARK resolver
+hostname and NAAN, the corresponding ARK URL without a timestamp is:
Gravsearch is intended to offer the advantages of SPARQL endpoints
+(particularly the ability to perform queries using complex search
+criteria) while avoiding their drawbacks in terms of performance and
+security (see The Enduring Myth of the SPARQL
+Endpoint).
+It also has the benefit of enabling clients to work with a simpler RDF
+data model than the one the API actually uses to store data in the
+triplestore and makes it possible to provide better error-checking.
+
Rather than being processed directly by the triplestore, a Gravsearch query
+is interpreted by the API, which enforces certain
+restrictions on the query, and implements paging and permission
+checking. The API server generates SPARQL based on the Gravsearch query
+submitted, queries the triplestore, filters the results according to the
+user's permissions, and returns each page of query results as an
+API response. Thus, Gravsearch is a hybrid between a RESTful API and a
+SPARQL endpoint.
+
A Gravsearch query conforms to a subset of the syntax of a SPARQL
+CONSTRUCT query, with
+some additional restrictions and functionality. In particular, the
+variable representing the top-level (or 'main') resource that will
+appear in each search result must be identified, statements must be
+included to specify the types of the entities being queried, OFFSET is
+used to control paging, and ORDER BY is used to sort the results.
+
It is certainly possible to write Gravsearch queries by hand, but we expect
+that in general, they will be automatically generated by client
+software, e.g. by a client user interface.
It is also possible to submit a Gravsearch query using HTTP GET. The entire
+query must be URL-encoded and included as the last element of the URL path:
+
HTTP GET to http://host/v2/searchextended/QUERY
+
+
The response to a Gravsearch query is an RDF graph, which can be requested in various
+formats (see Responses Describing Resources).
+
To request the number of results rather than the results themselves, you can
+do a count query:
+
HTTP POST to http://host/v2/searchextended/count
+
+
The response to a count query request is an object with one predicate,
+http://schema.org/numberOfItems, with an integer value.
+
If a gravsearch query times out, a 504 Gateway Timeout will be returned.
+
Gravsearch and API Schemas
+
A Gravsearch query can be written in either of the two
+DSP-API v2 schemas. The simple schema
+is easier to work with, and is sufficient if you don't need to query
+anything below the level of a DSP-API value. If your query needs to refer to
+standoff markup, you must use the complex schema. Each query must use a single
+schema, with one exception (see Date Comparisons).
+
Gravsearch query results can be requested in the simple or complex schema;
+see API Schema.
+
All examples hereafter run with the DSP stack started locally. If you access another stack, you can check
+the IRI of the ontology you are targeting by requesting the ontologies metadata.
+
Using the Simple Schema
+
To write a query in the simple schema, use the knora-api ontology in
+the simple schema, and use the simple schema for any other DSP ontologies
+the query refers to, e.g.:
To write a query in the complex schema, use the knora-api ontology in
+the complex schema, and use the complex schema for any other DSP ontologies
+the query refers to, e.g.:
In the complex schema, DSP-API values are represented as objects belonging
+to subclasses of knora-api:Value, e.g. knora-api:TextValue, and have
+predicates of their own, which can be used in FILTER expressions
+(see Filtering on Values in the Complex Schema).
+
Main and Dependent Resources
+
The main resource is the top-level resource in a search result. Other
+resources that are in some way connected to the main resource are
+referred to as dependent resources. If the client asks for a resource A
+relating to a resource B, then all matches for A will be presented as
+main resources and those for B as dependent resources. The main resource
+must be represented by a variable, marked with knora-api:isMainResource,
+as explained under CONSTRUCT Clause.
+
Virtual incoming Links
+
Depending on the ontology design, a resource A points to B or vice versa.
+For example, a page A is part of a book B using the property incunabula:partOf.
+If A is marked as the main resource, then B is nested as a dependent resource
+in its link value incunabula:partOfValue. But in case B is marked as the main resource,
+B does not have a link value pointing to A because in fact B is pointed to by A.
+Instead, B has a virtual property knora-api:hasIncomingLink containing A's link value:
Note that the virtually inserted link value inverts the relation by using knora-api:linkValueHasSource.
+The source of the link is A and its target B is only represented by an IRI (knora-api:linkValueHasTargetIri)
+since B is the main resource.
+
Graph Patterns and Result Graphs
+
The WHERE clause of a Gravsearch query specifies a graph pattern. Each query
+result will match this graph pattern, and will have the form of a graph
+whose starting point is a main resource. The query's graph pattern, and
+hence each query result graph, can span zero more levels of relations
+between resources. For example, a query could request regions
+in images on pages of books written by a certain author, articles by
+authors who were students of a particular professor, or authors of texts
+that refer to events that took place within a certain date range.
+
Permission Checking
+
Each matching resource is returned with the values that the user has
+permission to see. If the user does not have permission to see a matching
+main resource, it is hidden in the results. If a user does not have
+permission to see a matching dependent resource, the link value is hidden.
+
Paging
+
Gravsearch results are returned in pages. The maximum number of main
+resources per page is determined by the API (and can be configured
+in application.conf via the setting app/v2/resources-sequence/results-per-page).
+If some resources have been filtered out because the user does not have
+permission to see them, a page could contain fewer results, or no results.
+If it is possible that more results are available in subsequent pages,
+the Gravsearch response will contain the predicate knora-api:mayHaveMoreResults
+with the boolean value true, otherwise it will not contain this predicate.
+Therefore, to retrieve all available results, the client must request each page
+one at a time, until the response does not contain knora-api:mayHaveMoreResults.
+
Inference
+
Gravsearch queries are understood to imply a subset of
+RDFS reasoning. This is done by the API by expanding the incoming query.
+
Specifically, if a statement pattern specifies a property, the pattern will
+also match subproperties of that property, and if a statement specifies that
+a subject has a particular rdf:type, the statement will also match subjects
+belonging to subclasses of that type.
+
If you know that reasoning will not return any additional results for
+your query, you can disable it by adding this line to the WHERE clause, which may improve query performance:
Every Gravsearch query is a valid SPARQL 1.1
+CONSTRUCT query.
+However, Gravsearch only supports a subset of the elements that can be used
+in a SPARQL Construct query, and a Gravsearch
+CONSTRUCT Clause has to indicate which variable
+is to be used for the main resource in each search result.
+
Supported SPARQL Syntax
+
The current version of Gravsearch accepts CONSTRUCT queries whose WHERE
+clauses use the following patterns, with the specified restrictions:
+
+
OPTIONAL: cannot be nested in a UNION.
+
UNION: cannot be nested in a UNION.
+
FILTER: may contain a complex expression using the Boolean
+ operators AND and OR, as well as comparison operators. The left
+ argument of a comparison operator must be a query variable.
+ A Knora ontology entity IRI used in a FILTER must be a property IRI.
+
FILTER NOT EXISTS
+
MINUS
+
OFFSET: the OFFSET is needed for paging. It does not actually
+ refer to the number of triples to be returned, but to the
+ requested page of results. The default value is 0, which refers
+ to the first page of results.
+
ORDER BY: In SPARQL, the result of a CONSTRUCT query is an
+ unordered set of triples. However, a Gravsearch query returns an
+ ordered list of resources, which can be ordered by the values of
+ specified properties. If the query is written in the complex schema,
+ items below the level of DSP-API values may not be used in ORDER BY.
+
BIND: The value assigned must be a DSP resource IRI.
+
+
Resources, Properties, and Values
+
Resources can be represented either by an IRI or by a variable, except for the
+main resource, which must be represented by a variable.
+
It is possible to do a Gravsearch query in which the IRI of the main resource
+is already known, e.g. to request specific information about that resource and
+perhaps about linked resources. In this case, the IRI of the main resource must
+be assigned to a variable using BIND. Note that BIND statements slow the query down,
+therefore we recommend that you do not use them unless you have to.
+
Properties can be represented by an IRI or a query variable. If a
+property is represented by a query variable, it can be restricted to
+certain property IRIs using a FILTER.
+
A Knora value (i.e. a value attached to a knora-api:Resource)
+must be represented as a query variable.
+
Filtering on Values
+
Filtering on Values in the Simple Schema
+
In the simple schema, a variable representing a DSP-API value can be used
+directly in a FILTER expression. For example:
+
?book incunabula:title ?title .
+FILTER(?title = "Zeitglöcklein des Lebens und Leidens Christi")
+
+
Here the type of ?title is xsd:string.
+
The following value types can be compared with literals in FILTER
+expressions in the simple schema:
+
+
Text values (xsd:string)
+
URI values (xsd:anyURI)
+
Integer values (xsd:integer)
+
Decimal values (xsd:decimal)
+
Boolean values (xsd:boolean)
+
Date values (knora-api:Date)
+
List values (knora-api:ListNode)
+
+
List values can only be searched for using the equal operator (=),
+performing an exact match on a list node's label. Labels can be given in different languages for a specific list node.
+If one of the given list node labels matches, it is considered a match.
+Note that in the simple schema, uniqueness is not guaranteed (as opposed to the complex schema).
+
A DSP-API value may not be represented as the literal object of a predicate;
+for example, this is not allowed:
+
?book incunabula:title "Zeitglöcklein des Lebens und Leidens Christi" .
+
+
Filtering on Values in the Complex Schema
+
In the complex schema, variables representing DSP-API values are not literals.
+You must add something to the query (generally a statement) to get a literal
+from a DSP-API value. For example:
+
?book incunabula:title ?title .
+?title knora-api:valueAsString "Zeitglöcklein des Lebens und Leidens Christi" .
+
+
Here the type of ?title is knora-api:TextValue. Note that no FILTER is needed
+in this example. But if you want to use a different comparison operator,
+you need a FILTER:
To match a date value in the complex schema, you must use the
+knora-api:toSimpleDate function in a FILTER
+(see Date Comparisons). The predicates of
+knora-api:DateValue (knora-api:dateValueHasStartYear, etc.) are not
+available in Gravsearch.
+
Date Comparisons
+
In the simple schema, you can compare a date value directly with a knora-api:Date
+in a FILTER:
In the complex schema, you must use the function knora-api:toSimpleDate,
+passing it the variable representing the date value. The date literal used
+in the comparison must still be a knora-api:Date in the simple schema.
+This is the only case in which you can use both schemas in a single query:
E.g. an exact date like GREGORIAN:2015-12-03 or a period like GREGORIAN:2015-12-03:2015-12-04.
+Dates may also have month or year precision, e.g. ISLAMIC:1407-02 (the whole month of december) or JULIAN:1330
+(the whole year 1330). An optional ERA indicator term (BCE, CE, or BC, AD) can be added to the date, when no
+era is provided the default era AD will be considered. Era can be given as GREGORIAN:1220 BC or in range as
+GREGORIAN:600 BC:480 BC.
+
Searching for Matching Words
+
The function knora-api:matchText searches for matching words anywhere in a
+text value and is implemented using a full-text search index if available.
+The first argument must represent a text value (a knore-api:TextValue in
+the complex schema, or an xsd:string in the simple schema). The second
+argument is a string literal containing the words to be matched, separated by spaces.
+The function supports the
+Lucene Query Parser syntax.
+Note that Lucene's default operator is a logical OR when submitting several search terms.
+
This function can only be used as the top-level expression in a FILTER.
+
For example, to search for titles that contain the words 'Zeitglöcklein' and
+'Lebens':
To refer to standoff markup in text values, you must write your query in the complex
+schema.
+
A knora-api:TextValue can have the property
+knora-api:textValueHasStandoff, whose objects are the standoff markup
+tags in the text. You can match the tags you're interested in using
+rdf:type or other properties of each tag.
+
Matching Text in a Standoff Tag
+
The function knora-api:matchTextInStandoff searches for standoff tags containing certain terms.
+The implementation is optimised using the full-text search index if available. The
+function takes three arguments:
+
+
A variable representing a text value.
+
A variable representing a standoff tag.
+
A string literal containing space-separated search terms.
+
+
This function can only be used as the top-level expression in a FILTER.
+For example:
Here we are looking for letters containing the words "Grund" and "Richtigkeit"
+within a single paragraph.
+
Matching Standoff Links
+
If you are only interested in specifying that a resource has some text
+value containing a standoff link to another resource, the most efficient
+way is to use the property knora-api:hasStandoffLinkTo, whose subjects and objects
+are resources. This property is automatically maintained by the API. For example:
Here we are looking for letters containing a link to the historian
+Claude Jordan, who is identified by his Integrated Authority File
+identifier, (VIAF)271899510.
+
However, if you need to specify the context in which the link tag occurs, you must
+use the function knora-api:standoffLink. It takes three arguments:
+
+
A variable or IRI representing the resource that is the source of the link.
+
A variable representing the standoff link tag.
+
A variable or IRI representing the resource that is the target of the link.
+
+
This function can only be used as the top-level expression in a FILTER.
+For example:
This has the same effect as the previous example, except that because we are matching
+the link tag itself, we can specify that its immediate parent is a
+StandoffItalicTag.
+
If you actually want to get the target of the link (in this example, ?person)
+in the search results, you need to add a statement like
+?letter knora-api:hasStandoffLinkTo ?person . to the WHERE clause and to the
+CONSTRUCT clause:
You can use the knora-api:toSimpleDate function (see @refDate Comparisons)
+to match dates in standoff date tags, i.e. instances of knora-api:StandoffDateTag or
+of one of its subclasses. For example, here we are looking for a text containing
+an anything:StandoffEventTag (which is a project-specific subclass of knora-api:StandoffDateTag)
+representing an event that occurred sometime during the month of December 2016:
Suppose we want to search for a standoff date in a paragraph, but we know
+that the paragraph tag might not be the immediate parent of the date tag.
+For example, the date tag might be in an italics tag, which is in a paragraph
+tag. In that case, we can use the inferred property
+knora-api:standoffTagHasStartAncestor. We can modify the previous example to
+do this:
The rdfs:label of a resource is not a DSP-API value, but you can still search for it.
+This can be done in the same ways in the simple or complex schema:
+
Using a string literal object:
+
?book rdfs:label "Zeitglöcklein des Lebens und Leidens Christi" .
+
+
Using a variable and a FILTER:
+
?book rdfs:label ?label .
+FILTER(?label = "Zeitglöcklein des Lebens und Leidens Christi")
+
To match words in an rdfs:label using the full-text search index, use the
+knora-api:matchLabel function, which works like knora-api:matchText,
+except that the first argument is a variable representing a resource:
A FILTER can compare a variable with another variable or IRI
+representing a resource. For example, to find a letter whose
+author and recipient are different persons:
In the CONSTRUCT clause of a Gravsearch query, the variable representing the
+main resource must be indicated with knora-api:isMainResource true. Exactly
+one variable representing a resource must be marked in this way.
+
Any other statements in the CONSTRUCT clause must also be present in the WHERE
+clause. If a variable representing a resource or value is used in the WHERE
+clause but not in the CONSTRUCT clause, the matching resources or values
+will not be included in the results.
+
If the query is written in the complex schema, all variables in the CONSTRUCT
+clause must refer to DSP-API resources, DSP-API values, or properties. Data below
+the level of values may not be mentioned in the CONSTRUCT clause.
+
Predicates from the rdf, rdfs, and owl ontologies may not be used
+in the CONSTRUCT clause. The rdfs:label of each matching resource is always
+returned, so there is no need to mention it in the query.
+
Gravsearch by Example
+
In this section, we provide some sample queries of different complexity
+to illustrate the usage of Gravsearch.
+
Getting All the Components of a Compound Resource
+
In order to get all the components of a compound resource, the following
+Gravsearch query can be sent to the API.
+
In this case, the compound resource is an incunabula:book identified
+by the IRI http://rdfh.ch/0803/c5058f3a and the components are of
+type incunabula:page (test data for the Incunabula project). Since
+inference is assumed, we can use knora-api:StillImageRepresentation
+(incunabula:page is one of its subclasses). This makes the query more
+generic and allows for reuse (for instance, a client would like to query
+different types of compound resources defined in different ontologies).
+
ORDER BY is used to sort the components by their sequence number.
+
OFFSET is set to 0 to get the first page of results.
+
PREFIX knora-api: <http://api.knora.org/ontology/knora-api/simple/v2#>
+
+CONSTRUCT {
+ ?component knora-api:isMainResource true . # marking of the component searched for as the main resource, required
+ ?component knora-api:seqnum ?seqnum . # return the sequence number in the response
+ ?component knora-api:hasStillImageFileValue ?file . # return the StillImageFile in the response
+} WHERE {
+ ?component a knora-api:StillImageRepresentation . # restriction of the type of component
+ ?component knora-api:isPartOf <http://rdfh.ch/0803/c5058f3a> . # component relates to a compound resource via this property
+ ?component knora-api:seqnum ?seqnum . # component must have a sequence number
+ ?component knora-api:hasStillImageFileValue ?file . # component must have a StillImageFile
+}
+ORDER BY ASC(?seqnum) # order by sequence number, ascending
+OFFSET 0 # get first page of results
+
+
The incunabula:book with the IRI http://rdfh.ch/0803/c5058f3a has
+402 pages. (This result can be obtained by doing a count query; see
+Submitting Gravsearch Queries.)
+However, with OFFSET 0, only the first page of results is returned.
+The same query can be sent again with OFFSET 1 to get the next page of
+results, and so forth. When a page of results is not full (see settings
+in app/v2 in application.conf) or is empty, no more results are
+available.
+
By design, it is not possible for the client to get more than one page
+of results at a time; this is intended to prevent performance problems
+that would be caused by huge responses. A client that wants to download
+all the results of a query must request each page sequentially.
+
Let's assume the client is not interested in all of the book's pages,
+but just in first ten of them. In that case, the sequence number can be
+restricted using a FILTER that is added to the query's WHERE clause:
+
FILTER (?seqnum <= 10)
+
+
The first page starts with sequence number 1, so with this FILTER only
+the first ten pages are returned.
+
This query would be exactly the same in the complex schema, except for
+the expansion of the knora-api prefix:
If we remove the line ?book incunabula:title ?title . from the CONSTRUCT
+clause, so that the CONSTRUCT clause no longer mentions ?title, the response
+will contain the same matching resources, but the titles of those resources
+will not be included in the response.
+
Requesting a Graph Starting with a Known Resource
+
Here the IRI of the main resource is already known and we want specific information
+about it, as well as about related resources. In this case, the IRI of the main
+resource must be assigned to a variable using BIND:
Searching for a List Value Referring to a Particular List Node
+
Since list nodes are represented by their IRI in the complex schema,
+uniqueness is guranteed (as opposed to the simple schema).
+Also all the subnodes of the given list node are considered a match.
Gravsearch needs to be able to determine the types of the entities that
+query variables and IRIs refer to in the WHERE clause. In most cases, it can
+infer these from context and from the ontologies used. In particular, it needs to
+know:
+
+
The type of the subject and object of each statement.
+
The type that is expected as the object of each predicate.
+
+
Type Annotations
+
When one or more types cannot be inferred, Gravsearch will return an error message
+indicating the entities for which it could not determine types. The missing
+information must then be given by adding type annotations to the query. This can always done by
+adding statements with the predicate rdf:type. The subject must be a resource or value,
+and the object must either be knora-api:Resource (if the subject is a resource)
+or the subject's specific type (if it is a value).
+
For example, consider this query that uses a non-DSP property:
The types of one or more entities could not be determined:
+ ?book, <http://purl.org/dc/terms/title>, ?title
+
+
To solve this problem, it is enough to specify the types of ?book and
+?title; the type of the expected object of dcterms:title can then be inferred
+from the type of ?title.
One or more entities have inconsistent types:
+
+<http://0.0.0.0:3333/ontology/0803/incunabula/simple/v2#pubdate>
+ knora-api:objectType <http://api.knora.org/ontology/knora-api/simple/v2#Date> ;
+ knora-api:objectType <http://www.w3.org/2001/XMLSchema#string> .
+
+?pubdate rdf:type <http://api.knora.org/ontology/knora-api/simple/v2#Date> ;
+ rdf:type <http://www.w3.org/2001/XMLSchema#string> .
+
+
This is because the incunabula ontology says that the object of incunabula:pubdate must be a knora-api:Date,
+but the FILTER expression compares ?pubdate with an xsd:string. The solution is to specify the
+type of the literal in the FILTER:
SPARQL is evaluated from the bottom up.
+A UNION block therefore opens a new scope, in which variables bound at
+higher levels are not necessarily in scope. This can cause unexpected results if queries
+are not carefully designed. Gravsearch tries to prevent this by rejecting queries in the
+following cases.
+
FILTER in UNION
+
A FILTER in a UNION block can only use variables that are bound in the same block, otherwise the query will be rejected. This query is invalid because ?text is not bound in the UNION block containing the FILTER where the variable is used:
A variable used in ORDER BY must be bound at the top level of the WHERE clause. This query is invalid, because ?int is not bound at the top level of the WHERE clause:
The query performance of triplestores, such as Fuseki, is highly dependent on the order of query
+patterns. To improve performance, Gravsearch automatically reorders the
+statement patterns in the WHERE clause according to their dependencies on each other, to minimise
+the number of possible matches for each pattern.
To retrieve an existing resource, the HTTP method GET has to be used.
+Reading resources may require authentication, since some resources may
+have restricted viewing permissions.
Operations for reading and searching resources can return responses in either the
+simple or the complex ontology schema. The complex schema is used by default.
+To receive a response in the simple schema, use the HTTP request header or URL
+parameter described in API Schema.
+
Each DSP-API v2 response describing one or more resources returns a
+single RDF graph. For example, a request for a single resource returns that
+resource and all its values. In a full-text search, the resource is returned with the
+values that matched the search criteria. A response to an extended search
+may represent a whole graph of interconnected resources.
+
In JSON-LD, if only one resource is returned, it is the top-level object;
+if more than one resource is returned, they are represented as an array
+of objects of the @graph member of the top-level object (see
+Named Graphs in the
+JSON-LD specification).
+
In the complex schema, dependent resources, i.e. resources that are referred
+to by other resources on the top level, are nested in link value objects.
+If resources on the top level are referred to by other resources and
+these links are part of the response, virtual incoming links are generated;
+see Gravsearch: Virtual Graph Search).
+
See the interfaces Resource and ResourcesSequence in module
+ResourcesResponse (exists for both API schemas: ApiV2Simple and
+ApiV2WithValueObjects).
+
Requesting Text Markup as XML
+
When requesting a text value with standoff markup, there are three possibilities:
+
+
The text value uses standard mapping.
+
The text value uses a custom mapping which does not specify an XSL transformation.
+
The text value uses a custom mapping which specifies an XSL transformation.
+
+
In the first case, the mapping will be defined as:
where the content of <text> is a limited set of HTML tags that can be handled by CKEditor in DSP-APP.
+This allows for both displaying and editing the text value.
+
In the second and third case, kb:textValueHasMapping will point to the custom mapping
+that may or may not specify an XSL transformation.
+
If no transformation is specified (second case), the text value will be returned only as kb:textValueAsXml.
+This property will be a string containing the contents of the initially uploaded XML.
+
Note: The returned XML document is equivalent to the uploaded document but it is not necessarily identical -
+the order of the attributes in one element may vary from the original.
+
In the third case, when a transformation is specified, both kb:textValueAsXml and kb:textValueAsHtml will be returned.
+kb:textValueAsHtml is the result of the XSL transformation applied to kb:textValueAsXml.
+The HTML representation is intended to display the text value in a human readable and properly styled way,
+while the XML representation can be used to update the text value.
+
Get the Representation of a Resource by IRI
+
Get a Full Representation of a Resource by IRI
+
A full representation of resource can be obtained by making a GET
+request to the API providing its IRI. Because a DSP IRI has the format
+of a URL, its IRI has to be URL-encoded.
+
To get the resource with the IRI http://rdfh.ch/c5058f3a (a
+book from the sample Incunabula project, which is included in the DSP-API
+server's test data), make a HTTP GET request to the resources
+route (path segment resources in the API call) and append the
+URL-encoded IRI:
+
HTTP GET to http://host/v2/resources/http%3A%2F%2Frdfh.ch%2Fc5058f3a
+
+
If necessary, several resources can be queried at the same time, their
+IRIs separated by slashes. Please note that the amount of resources that
+can be queried in one requested is limited. See the settings for
+app/v2 in application.conf.
+
More formally, the URL looks like this:
+
HTTP GET to http://host/v2/resources/resourceIRI(/anotherResourceIri)*
+
+
Get a Full Representation of a Version of a Resource by IRI
+
To get a specific past version of a resource, use the route described in
+Get a Full Representation of a Resource by IRI,
+and add the URL parameter ?version=TIMESTAMP, where TIMESTAMP is an
+xsd:dateTimeStamp in the
+UTC timezone. The timestamp can either be URL-encoded, or submitted with all
+punctuation (-, :, and .) removed (this is to accept timestamps
+from DSP's ARK URLs).
+
The resource will be returned with the values that it had at the specified
+time. Since DSP only versions values, not resource metadata (e.g.
+rdfs:label), the current metadata will be returned.
+
Each value will be returned with the permissions that are attached to
+the current version of the value
+(see Permissions).
+
The returned resource will include the predicate knora-api:versionDate,
+containing the timestamp that was submitted, and its knora-api:versionArkUrl
+(see Resource Permalinks) will contain the
+same timestamp.
+
Get a Value in a Resource
+
To get a specific value of a resource, use this route:
+
HTTP GET to http://host/v2/values/resourceIRI/valueUUID
+
+
The resource IRI must be URL-encoded. The path element valueUUID is the
+string object of the value's knora-api:valueHasUUID.
+
The value will be returned within its containing resource, in the same format
+as for Responses Describing Resources,
+but without any of the resource's other values.
+
Get a Version of a Value in a Resource
+
To get a particular version of a specific value of a resource, use the route
+described in Get a Value in a Resource,
+and add the URL parameter ?version=TIMESTAMP, where TIMESTAMP is an
+xsd:dateTimeStamp in the
+UTC timezone. The timestamp can either be URL-encoded, or submitted with all
+punctuation (-, :, and .) removed (this is to accept timestamps
+from DSP's ARK URLs).
+
The value will be returned within its containing resource, in the same format
+as for Responses Describing Resources,
+but without any of the resource's other values.
+
Since DSP only versions values, not resource metadata (e.g.
+rdfs:label), the current resource metadata will be returned.
+
The value will be returned with the permissions that are attached to
+its current version
+(see Permissions).
+
Get the Version History of a Resource
+
To get a list of the changes that have been made to a resource since its creation,
+use this route:
+
HTTP GET to http://host/v2/resources/history/resourceIRI[?startDate=START_DATE&endDate=END_DATE]
+
+
The resource IRI must be URL-encoded. The start and end dates are optional, and
+are URL-encoded timestamps in
+xsd:dateTimeStamp format.
+The start date is inclusive, and the end date is exclusive.
+If the start date is not provided, the resource's history since its creation is returned.
+If the end date is not provided, the resource's history up to the present is returned.
+
The response is a list of changes made to the resource, in reverse chronological order.
+Each entry has the properties knora-api:author (the IRI of the user who made the change) and
+knora-api:versionDate (the date when the change was made). For example:
The entries include all the dates when the resource's values were created or modified (within
+the requested date range), as well as the date when the resource was created (if the requested
+date range allows it). Each date is included only once. Since DSP only versions values, not
+resource metadata (e.g. rdfs:label), changes to a resource's metadata are not included in its
+version history.
In some cases, the client may only want to request the preview of a
+resource, which just provides its metadata (e.g. its IRI, rdfs:label,
+and type), without its values.
+
This works exactly like making a conventional resource request, using
+the path segment resourcespreview:
+
HTTP GET to http://host/v2/resourcespreview/resourceIRI(/anotherResourceIri)*
+
+
Get a Graph of Resources
+
DSP can return a graph of connections between resources, e.g. for generating a network diagram.
+
HTTP GET to http://host/v2/graph/resourceIRI[depth=Integer]
+[direction=outbound|inbound|both][excludeProperty=propertyIri]
+
+
The first parameter must be preceded by a question mark ?, any
+following parameter by an ampersand &.
+
+
depth must be at least 1. The maximum depth is a DSP configuration setting.
+ The default is 4.
+
direction specifies the direction of the links to be queried, i.e. links to
+ and/or from the given resource. The default is outbound.
+
excludeProperty is an optional link property to be excluded from the
+ results.
+
+
To accommodate large graphs, the graph response format is very concise, and is therefore
+simpler than the usual resources response format. Each resource represented only by its IRI,
+class, and label. Direct links are shown instead of link values. For example:
DSP offers the possibility to search for resources by their
+rdfs:label. The use case for this search is to find a specific
+resource as you type. E.g., the user wants to get a list of resources
+whose rdfs:label contain some search terms separated by a whitespace
+character:
+
+
Zeit
+
Zeitg
+
...
+
Zeitglöcklein d
+
...
+
Zeitglöcklein des Lebens
+
+
With each character added to the last term, the selection gets more
+specific. The first term should at least contain three characters. To
+make this kind of "search as you type" possible, a wildcard character is
+automatically added to the last search term.
+
Characters provided by the user that have a special meaning in the Lucene Query Parser
+syntax need to be escaped. If a user wants to search for the string "Zeit-Glöcklein", she
+needs to type "Zeit-Glöcklein". The special characters that need escaping are:
++, -, &, |, !, (, ), [, ], {, }, ^, ", ~, *, ?, :, \, /
+
HTTP GET to http://host/v2/searchbylabel/searchValue[limitToResourceClass=resourceClassIRI]
+[limitToProject=projectIRI][offset=Integer]
+
+
The first parameter must be preceded by a question mark ?, any
+following parameter by an ampersand &.
+
The default value for the parameter offset is 0, which returns the
+first page of search results. Subsequent pages of results can be fetched
+by increasing offset by one. The amount of results per page is defined
+in app/v2 in application.conf.
+
For performance reasons, standoff markup is not queried for this route.
+
To request the number of results rather than the results themselves, you can
+do a count query:
+
HTTP GET to http://host/v2/searchbylabel/count/searchValue[limitToResourceClass=resourceClassIRI][limitToProject=projectIRI][offset=Integer]
+
+
The response to a count query request is an object with one predicate,
+http://schema.org/numberOfItems, with an integer value.
+
Full-text Search
+
DSP offers a full-text search that searches through all textual
+representations of values and rdfs:label of resources.
+Full-text search supports the
+Lucene Query Parser syntax.
+Note that Lucene's default operator is a logical OR when submitting several search terms.
+
The search index used by DSP transforms all text into lower case characters and splits text into tokens by whitespace.
+For example, if a text value is: The cake needs flour, sugar, and butter.,
+the tokens are the, cake, needs, flour,, sugar,, and, butter..
+Note that punctuation marks like , and . are left with the word where they occurred.
+Therefore, if you search for sugar you would have to use sugar* or sugar?
+to get results that contain sugar, or sugar. as well.
+The reason for this kind of tokenization is
+that some users need to be able to search explicitly for special characters including punctuation marks.
+
Alphabetic, numeric, symbolic, and diacritical Unicode characters
+which are not in the first 127 ASCII characters (the "Basic Latin" Unicode block)
+are converted into their ASCII equivalents, if one exists, e.g. é or ä are converted into e and a.
+
Please note that the search terms have to be URL-encoded.
+
HTTP GET to http://host/v2/search/searchValue[limitToResourceClass=resourceClassIRI]
+[limitToStandoffClass=standoffClassIri][limitToProject=projectIRI][offset=Integer]
+
+
The first parameter has to be preceded by a question mark ?, any following parameter by an ampersand &.
+
A search value must have a minimal length of three characters (default value)
+as defined in search-value-min-length in application.conf.
+
A search term may contain wildcards. A ? represents a single character.
+It has to be URL-encoded as %3F since it has a special meaning in the URL syntax.
+For example, the term Uniform can be search for like this:
+
HTTP GET to http://host/v2/search/Unif%3Frm
+
+
A * represents zero, one or multiple characters. For example, the term Uniform can be searched for like this:
+
HTTP GET to http://host/v2/search/Uni*m
+
+
The default value for the parameter offset is 0 which returns the
+first page of search results. Subsequent pages of results can be fetched
+by increasing offset by one. The amount of results per page is defined
+in results-per-page in application.conf.
+
If the parameter limitToStandoffClass is provided, DSP will look for search terms
+that are marked up with the indicated standoff class.
+
If the parameter returnFiles=true is provided, DSP will return any
+file value attached to each matching resource.
+
To request the number of results rather than the results themselves, you can
+do a count query:
+
HTTP GET to http://host/v2/search/count/searchValue[limitToResourceClass=resourceClassIRI][limitToStandoffClass=standoffClassIri][limitToProject=projectIRI][offset=Integer]
+
+
The first parameter has to be preceded by a question
+mark ?, any following parameter by an ampersand &.
+
The response to a count query request is an object with one predicate,
+http://schema.org/numberOfItems, with an integer value.
To convert standoff markup to TEI/XML, see TEI/XML.
+
IIIF Manifests
+
This is an experimental feature and may change.
+
To generate a IIIF manifest for a resource, containing
+the still image representations that have knora-api:isPartOf (or a subproperty)
+pointing to that resource:
+
HTTP GET to http://host/v2/resources//iiifmanifest/RESOURCE_IRI
+
+
Reading Resources by Class from a Project
+
To facilitate the development of tabular user interfaces for data entry, it is
+possible to get a paged list of all the resources belonging to a particular
+class in a given project, sorted by the value of a property:
+
HTTP GET to http://host/v2/resources?resourceClass=RESOURCE_CLASS_IRI&page=PAGE[&orderByProperty=PROPERTY_IRI]
+
+
This is useful only if the project does not contain a large amount of data;
+otherwise, you should use Gravsearch to search
+using more specific criteria.
+
The specified class and property are used without inference; they will not
+match subclasses or subproperties.
+
The HTTP header X-Knora-Accept-Project must be submitted; its value is
+a DSP project IRI. In the request URL, the values of resourceClass and orderByProperty
+are URL-encoded IRIs in the complex schema.
+The orderByProperty parameter is optional; if it is not supplied, resources will
+be sorted alphabetically by resource IRI (an arbitrary but consistent order).
+The value of page is a 0-based integer page number. Paging works as it does
+in Gravsearch).
+
Get the Full History of a Resource and its Values as Events
+
To get a list of the changes that have been made to a resource and its values since its creation as events ordered by
+date:
+
HTTP GET to http://host/v2/resources/resourceHistoryEvents/<resourceIRI>
+
+
The resource IRI must be URL-encoded. The response is a list of events describing changes made to the resource and its values,
+ in chronological order. Each entry has the properties:
+ knora-api:eventType (the type of the operation performed on a specific date. The operation can be either
+ createdResource, updatedResourceMetadata, deletedResource, createdValue, updatedValueContent,
+ updatedValuePermissions, or deletedValue.),
+knora-api:versionDate (the date when the change was made),
+knora-api:author (the IRI of the user who made the change),
+knora-api:eventBody (the information necessary to make the same request).
+
For example, the following response contains the list of events describing the version history of the resource
+http://rdfh.ch/0001/thing-with-history ordered by date:
Since the history of changes made to the metadata of a resource is not part of resouce's version history, there are no
+events describing the changes on metadata elements like its rdfs:label or rdfs:comment.
+The only record depicting a change in a resource's metadata is the knora-api:lastModificationDate of the resource. Thus
+the event updatedResourceMetadata indicates a change in a resource's metadata, its knora-api:eventBody contains the
+payload needed to update the value of the resource's lastModificationDate, see
+modifying metadata of a resource.
+
Get the Full History of all Resources of a Project as Events
+
To get a list of the changes that have been made to the resources and their values of a project as events ordered by
+date:
+
HTTP GET to http://host/v2/resources/projectHistoryEvents/<projectIRI>
+
+
The project IRI must be URL-encoded. The response contains the resource history events of all resources that belong to
+the specified project.
Reading the User's Permissions on Resources and Values
+
In the complex API schema, each
+resource and value is returned with the predicate knora-api:userHasPermission.
+The object of this predicate is a string containing a permission code, which
+indicates the requesting user's maximum permission on the resource or value.
+These are the possible permission codes, in ascending order:
+
+
RV: restricted view permission (least privileged)
+
V: view permission
+
M modify permission
+
D: delete permission
+
CR: change rights permission (most privileged)
+
+
Each permission implies all lesser permissions. For more details, see
+Permissions.
The DSP-API's standard standoff mapping only supports a few HTML tags. In order to
+submit more complex XML markup, a custom mapping has to be
+created first. A mapping expresses the relations between XML
+elements and attributes, and their corresponding standoff classes and
+properties. The relations expressed in a mapping are one-to-one
+relations, so the XML can be recreated from the data in RDF. However,
+since HTML offers a very limited set of elements, custom mappings support
+the combination of element names and classes. In this way, the same
+element can be used several times in combination with another classname
+(please note that <a> without a class is a hyperlink whereas <a class="salsah-link"> is an internal link/standoff link).
+
With a mapping, a default XSL transformation may be provided to
+transform the XML to HTML before sending it back to the client. This is
+useful when the client is a web-browser expecting HTML (instead of XML).
+
Basic Structure of a Mapping
+
The mapping is written in XML itself (for a formal description, see
+webapi/src/resources/mappingXMLToStandoff.xsd). It has the following
+structure (the indentation corresponds to the nesting in XML):
+
+
<mapping>: the root element
+
<defaultXSLTransformation> (optional): the IRI of the
+ default XSL transformation to be applied to the XML when
+ reading it back from DSP-API. The XSL transformation is
+ expected to produce HTML. If given, the IRI has to refer to
+ a resource of type knora-base:XSLTransformation.
+
<mappingElement>: an element of the mapping (at least one)
+
<tag>: information about the XML element that is mapped to a standoff class
+
<name>: name of the XML element
+
<class>: value of the class attribute of
+ the XML element, if any. If the element has
+ no class attribute, the keyword noClass
+ has to be used.
+
<namespace>: the namespace the XML element
+ belongs to, if any. If the element does not
+ belong to a namespace, the keyword
+ noNamespace has to be used.
+
<separatesWords>: a Boolean value
+ indicating whether this tag separates words
+ in the text. Once an XML document is
+ converted to RDF-standoff the markup is
+ stripped from the text, possibly leading to
+ continuous text that has been separated by
+ tags before. For structural tags like
+ paragraphs etc., <separatesWords> can be
+ set to true in which case a special
+ separator is inserted in the text in the
+ RDF representation. In this way, words stay
+ separated and are represented in the
+ fulltext index as such.
+
+
+
<standoffClass>: information about the standoff class the XML element is mapped to
+
<classIri>: IRI of the standoff class the XML element is mapped to
+
<attributes>: XML attributes to be mapped to standoff properties (other than id or class), if any
+
<attribute>: an XML attribute to be mapped to a standoff property, may be repeated
+
<attributeName>: the name of the XML attribute
+
<namespace>: the namespace the attribute belongs to, if any.
+ If the attribute does not belong to a namespace, the keyword noNamespace has to be used.
+
<propertyIri>: the IRI of the standoff property the XML attribute is mapped to.
+
+
+
+
+
<datatype>: the data type of the standoff class, if any.
+
<type>: the IRI of the data type standoff class
+
<attributeName>: the name of the attribute holding the typed value in the expected standard format
Please note that the absence of an XML namespace and/or a class have to
+be explicitly stated using the keywords noNamespace and
+noClass. This is because we use XML Schema validation to ensure the one-to-one
+relations between XML elements and standoff classes. XML Schema validation's unique checks
+do not support optional values.
+
id and class Attributes
+
The id and class attributes are supported by default and do not have
+to be included in the mapping like other attributes. The id attribute
+identifies an element and must be unique in the document. id is an
+optional attribute. The class attribute allows for the reuse of an
+element in the mapping, i.e. the same element can be combined with
+different class names and mapped to different standoff classes (mapping
+element <class> in <tag>).
+
Respecting Cardinalities
+
A mapping from XML elements and attributes to standoff classes and
+standoff properties must respect the cardinalities defined in the
+ontology for those very standoff classes. If an XML element is mapped to
+a certain standoff class and this class requires a standoff property, an
+attribute must be defined for the XML element mapping to that very
+standoff property. Equally, all mappings for attributes of an XML
+element must have corresponding cardinalities for standoff properties
+defined for the standoff class the XML element maps to.
+
However, since an XML attribute may occur once at maximum, it makes
+sense to make the corresponding standoff property required
+(owl:cardinality of one) in the ontology or optional
+(owl:maxCardinality of one), but not allowing it more than once.
+
Standoff Data Types
+
DSP-API allows the use of all its value types as standoff data types
+(defined in knora-base.ttl):
+
+
knora-base:StandoffLinkTag: Represents a reference to a
+ resource (the IRI of the target resource must be submitted in the
+ data type attribute).
+
knora-base:StandoffInternalReferenceTag: Represents an internal
+ reference inside a document (the id of the target element inside the
+ same document must be indicated in the data type attribute); see
+ Internal References in an XML Document.
+
knora-base:StandoffUriTag: Represents a reference to a URI (the
+ URI of the target resource must be submitted in the data type
+ attribute).
+
knora-base:StandoffDateTag: Represents a date (a date
+ string must be submitted in the data type attribute, e.g.
+ GREGORIAN:2017-01-27).
+
knora-base:StandoffColorTag: Represents a color (a hexadecimal
+ RGB color string must be submitted in the data type attribute, e.g.
+ #0000FF).
+
knora-base:StandoffIntegerTag: Represents an integer (the integer
+ must be submitted in the data type attribute).
+
knora-base:StandoffDecimalTag: Represents a number with fractions
+ (the decimal number must be submitted in the data type attribute,
+ e.g. 1.1).
+
knora-base:StandoffIntervalTag: Represents an interval (two
+ decimal numbers separated with a comma must be submitted in the data
+ type attribute, e.g. 1.1,2.2).
+
knora-base:StandoffBooleanTag: Represents a Boolean value (true
+ or false must be submitted in the data type attribute).
+
knora-base:StandoffTimeTag: Represents a timestamp value (an xsd:dateTimeStamp
+ must be submitted in the data type attribute).
+
+
The basic idea is that parts of a text can be marked up in a way that
+allows using DSP-API's built-in data types. In order to do so, the typed
+values have to be provided in a standardized way in an attribute that
+has to be defined in the mapping.
+
Data type standoff classes are standoff classes with predefined
+properties (e.g., a knora-base:StandoffLinkTag has a
+knora-base:standoffTagHasLink and a knora-base:StandoffIntegerTag
+has a knora-base:valueHasInteger). Please note the data type standoff
+classes can not be combined, i.e. a standoff class can only be the
+subclass of one data type standoff class. However, standoff data
+type classes can be subclassed and extended further by assigning
+properties to them (see below).
+
The following simple mapping illustrates this principle:
<datatype>must hold the IRI of a standoff data type class (see
+list above). The <classIri> must be a subclass of this type or this
+type itself (the latter is probably not recommendable since semantics
+are missing: what is the meaning of the date?). In the example above,
+the standoff class is anything:StandoffEventTag which has the
+following definition in the ontology anything-onto.ttl:
+
anything:StandoffEventTag rdf:type owl:Class ;
+
+ rdfs:subClassOf knora-base:StandoffDateTag,
+ [
+ rdf:type owl:Restriction ;
+ owl:onProperty :standoffEventTagHasDescription ;
+ owl:cardinality "1"^^xsd:nonNegativeInteger
+ ] ;
+
+ rdfs:label "Represents an event in a TextValue"@en ;
+
+ rdfs:comment """Represents an event in a TextValue"""@en .
+
+
anything:StandoffEventTag is a subclass of
+knora-base:StandoffDateTag and therefore has the data type date. It
+also requires the standoff property
+anything:standoffEventTagHasDescription which is defined as an
+attribute in the mapping.
+
Once the mapping has been created, an XML like the following could be
+sent to DSP-API and converted to standoff:
The attribute holds the date in the format of a DSP-API date string (the
+format is also documented in the typescript type alias dateString in
+module basicMessageComponents. There you will also find documentation
+about the other types like color etc.). DSP-API date strings have this
+format: GREGORIAN|JULIAN):YYYY[-MM[-DD]][:YYYY[-MM[-DD]]]. This allows
+for different formats as well as for imprecision and periods. Intervals
+are submitted as one attribute in the following format:
+interval-attribute="1.0,2.0" (two decimal numbers separated with a
+comma).
+
You will find a sample mapping with all the data types and a sample XML
+file in the the test data:
+test_data/test_route/texts/mappingForHTML.xml and
+test_data/test_route/texts/HTML.xml.
+
Internal References in an XML Document
+
Internal references inside an XML document can be represented using the
+data type standoff class knora-base:StandoffInternalReferenceTag or a
+subclass of it. This class has a standoff property that points to a
+standoff node representing the target XML element when converted to RDF.
+
The following example shows the definition of a mapping element for an
+internal reference (for reasons of simplicity, only the mapping element
+for the element is question is depicted):
Predefined standoff classes may be used by various projects, each
+providing a custom mapping to be able to recreate the original XML from
+RDF. Predefined standoff classes may also be inherited and extended in
+project specific ontologies.
When mapping XML attributes to standoff properties, attention has to be
+paid to the properties' object constraints.
+
In the ontology, standoff property literals may have one of the
+following knora-base:objectDatatypeConstraint:
+
+
xsd:string
+
xsd:integer
+
xsd:boolean
+
xsd:decimal
+
xsd:anyURI
+
+
In XML, all attribute values are submitted as strings. However, these
+string representations need to be convertible to the types defined in
+the ontology. If they are not, the request will be rejected. It is
+recommended to enforce types on attributes by applying XML Schema
+validations (restrictions).
+
Links (object property) to a knora-base:Resource can be represented
+using the data type standoff class knora-base:StandoffLinkTag,
+internal links using the data type standoff class
+knora-base:StandoffInternalReferenceTag.
+
Validating a Mapping and sending it to DSP-API
+
A mapping can be validated before sending it to DSP-API with the following
+XML Schema file: webapi/src/resources/mappingXMLToStandoff.xsd. Any
+mapping that does not conform to this XML Schema file will be rejected
+by DSP-API.
+
The mapping has to be sent as a multipart request to the standoff route
+using the path segment mapping:
+
HTTP POST http://host/v2/mapping
+
+
The multipart request consists of two named parts:
A successful response returns the IRI of the mapping. However, the IRI
+of a mapping is predictable: it consists of the project Iri followed by
+/mappings/ and the knora-api:mappingHasName submitted in the JSON-LD (if the name
+already exists, the request will be rejected). Once created, a mapping
+can be used to create TextValues in Knora. The formats are documented in
+the v2 typescript interfaces AddMappingRequest and AddMappingResponse
+in module MappingFormats
DSP-API supports various ways of handling textual data:
+
Text in RDF
+
Textual data can be included directly in the data stored in DSP-API.
+This is the default way of handling text in the DSP.
+There are three ways of representing textual data in DSP-API,
+two of which are fully supported by DSP-APP and DSP-TOOLS.
+
Texts stored in RDF can be searched using both full-text search and structured queries.
+
Simple Text
+
If a text requires no formatting, it can simply be stored as a string in a knora-base:TextValue.
+This is sufficient in many cases, especially for shorter texts like names, titles, identifiers, etc.
+
Text with Formatting
+
For text requiring regular markup, knora-base:TextValue can be used
+in combination with the DSP's standard standoff markup.
+
This allows for the following markup:
+
+
structural markup
+
paragraphs
+
headings levels 1-6
+
ordered lists
+
unordered lists
+
tables
+
line breaks
+
horizontal rules
+
code blocks
+
block quotes
+
+
+
typographical markup
+
italics
+
bold
+
underline
+
strikethrough
+
subscript
+
superscript
+
+
+
semantic markup
+
links
+
DSP internal links
+
+
+
+
DSP-APP provides a text editor for conveniently editing text with standard standoff markup.
It is possible to create custom XML-to-Schema mappings,
+which allows for creating project specific custom markup for text values.
+Details can be found here.
+
+
Info
+
Custom markup is not supported by DSP-TOOLS and is view-only in DSP-APP.
+Creating custom markup is relatively involved,
+so that it should only be used by projects working with complex textual data.
+
+
File Based
+
Text files of various formats (Word, PDF, XML, etc.) can be uploaded to the media file server.
+For more details, see here
+
This allows for easy upload and retrieval of the file.
+However, it does not allow for searching within the file content.
+
TEI XML
+
All text values in DSP-API using standoff markup can be converted to TEI XML as described here.
A mapping allows for the conversion of XML to standoff representation in RDF and back.
+In order to create a TextValue with markup,
+the text has to be provided in XML format,
+along with the IRI of the mapping that will be used to convert the markup to standoff.
+
DSP-API offers a standard mapping with the IRI http://rdfh.ch/standoff/mappings/StandardMapping.
+The standard mapping covers the HTML elements and attributes
+supported by the GUI's text editor, CKEditor.
+(Please note that the HTML has to be encoded in strict XML syntax.
+CKeditor offers the possibility to define filter rules.
+They should reflect the elements supported by the mapping.)
+The standard mapping contains the following elements and attributes
+that are mapped to standoff classes and properties defined in the ontology:
<h1> to <h6> → standoff:StandoffHeader1Tag to standoff:StandoffHeader6Tag
+
<ol> → standoff:StandoffOrderedListTag
+
<ul> → standoff:StandoffUnrderedListTag
+
<li> → standoff:StandoffListElementTag
+
<tbody> → standoff:StandoffTableBodyTag
+
<thead> → standoff:StandoffTableHeaderTag
+
<table> → standoff:StandoffTableTag
+
<tr> → standoff:StandoffTableRowTag
+
<th> → standoff:StandoffTableHeaderCellTag
+
<td> → standoff:StandoffTableCellTag
+
<br> → standoff:StandoffBrTag
+
<hr> → standoff:StandoffLineTag
+
<pre> → standoff:StandoffPreTag
+
<cite> → standoff:StandoffCiteTag
+
<blockquote> → standoff:StandoffBlockquoteTag
+
<code> → standoff:StandoffCodeTag
+
+
The HTML produced by CKEditor is wrapped in an XML doctype and a pair of root tags <text>...</text>
+and then sent to the DSP-API.
+The XML sent to the GUI by the DSP-API is unwrapped accordingly.
+Although the GUI supports HTML5, it is treated as if it was XHTML in strict XML notation.
+
Text with standard standoff markup can be transformed to TEI XML as described here.
DSP-API offers a way to convert standoff markup to TEI/XML.
+The conversion is based on the assumption that a whole resource is to be turned into a TEI document.
+There is a basic distinction between the body and the header of a TEI document.
+The resource's property that contains the text with standoff markup is mapped to the TEI document's body.
+Other of the resource's property may be mapped to the TEI header.
+
Standard Standoff to TEI Conversion
+
DSP-API offers a built-in conversion form standard standoff entities (defined in the standoff ontology) tags to TEI.
+
+
Note
+
As TEI provides a wide range of Elements and Attributes
+which can have different meaning depending on the markup practices of a project,
+whereas DSP standard standoff has a very limited tagset,
+this conversion is oppinionated by necessity
+and may not be appropriate for all projects.
+
+
In order to obtain a resource as a TEI document, the following request has to be performed.
+Please note that the URL parameters have to be URL-encoded.
+
HTTP GET to http://host/v2/tei/resourceIri?textProperty=textPropertyIri
+
+
In addition to the resource's Iri, the Iri of the property containing the text with standoff has to be submitted.
+This will be converted to the TEI body.
+Please note that the resource can only have one instance of this property and the text must have standoff markup.
+
The test data contain the resource http://rdfh.ch/0001/thing_with_richtext_with_markup
+with the text property http://0.0.0.0:3333/ontology/0001/anything/v2#hasRichtext
+that can be converted to TEI as follows:
+
HTTP GET to http://host/v2/tei/http%3A%2F%2Frdfh.ch%2F0001%2Fthing_with_richtext_with_markup?textProperty=http%3A%2F%2F0.0.0.0%3A3333%2Fontology%2F0001%2Fanything%2Fv2%23hasRichtext
+
+
The response to this request is a TEI XML document:
The body of the TEI document contains the standoff markup as XML.
+The header contains contains some basic metadata about the resource such as the rdfs:label an its IRI.
+However, this might not be sufficient for more advanced use cases like digital edition projects.
+In that case, a custom conversion has to be performed (see below).
+
Custom Conversion
+
If a project defines its own standoff entities, a custom conversion can be provided (body of the TEI document).
+Also for the TEI header, a custom conversion can be provided.
+
For the custom conversion, additional configuration is required.
+
TEI body:
+
+
additional mapping from standoff to XML (URL parameter mappingIri)
+
XSL transformation to turn the XML into a valid TEI body (referred to by the mapping).
+
+
The mapping has to refer to a defaultXSLTransformation that transforms the XML that was created from standoff markup
+(see XML To Standoff Mapping).
+This step is necessary because the mapping assumes a one to one relation
+between standoff classes and properties and XML elements and attributes.
+For example, we may want to convert a standoff:StandoffItalicTag into TEI/XML.
+TEI expresses this as <hi rend="italic">...</hi>.
+In the mapping, the standoff:StandoffItalicTag may be mapped to a temporary XML element
+that is going to be converted to <hi rend="italic">...</hi> in a further step by the XSLT.
+
For sample data, see webapi/_test_data/test_route/texts/beol/BEOLTEIMapping.xml (mapping)
+and webapi/_test_data/test_route/texts/beol/standoffToTEI.xsl.
+The standoff entities are defined in beol-onto.ttl.
+
TEI header:
+
+
Gravsearch template to query the resources metadata, results are serialized to RDF/XML (URL parameter gravsearchTemplateIri)
+
XSL transformation to turn that RDF/XML into a valid TEI header (URL parameter teiHeaderXSLTIri)
+
+
The Gravsearch template is expected to be of type knora-base:TextRepresentation
+and to contain a placeholder $resourceIri that is to be replaced by the actual resource Iri.
+The Gravsearch template is expected to contain a query involving the text property (URL parameter textProperty)
+and more properties that are going to be mapped to the TEI header.
+The Gravsearch template is a simple text file with the files extension .txt.
+
A Gravsearch template may look like this (see test_data/test_route/texts/beol/gravsearch.txt):
Note the placeholder BIND(<$resourceIri> as ?letter) that is going to be replaced
+by the Iri of the resource the request is performed for.
+The query asks for information about the letter's text beol:hasText and information about its author and recipient.
+This information is converted to the TEI header in the format required by correspSearch.
+
To write the XSLT, do the Gravsearch query and request the data as RDF/XML using content negotiation
+(see Introduction).
+
The Gravsearch query's result may look like this (RDF/XML):
In order to convert the metadata (not the actual standoff markup),
+a knora-base:knora-base:XSLTransformation has to be provided.
+For our example, it looks like this (see test_data/test_route/texts/beol/header.xsl):
You can use the functions knora-api:iaf and knora-api:dateformat in your own XSLT in case you want to support correspSearch.
+
The complete request looks like this:
+
HTTP GET request to http://host/v2/tei/resourceIri&textProperty=textPropertyIri&mappingIri=mappingIri&gravsearchTemplateIri=gravsearchTemplateIri&teiHeaderXSLTIri=teiHeaderXSLTIri
+
The instrumentation endpoints are running on a separate port (default 3339)
+defined in application.conf under the key: app.instrumentaion-server-config.port
+and can also be set through the environment variable: KNORA_INSTRUMENTATION_SERVER_PORT.
+
The exposed endpoints are:
+
+
/metrics - a metrics endpoint, backed by the ZIO metrics backend exposing metrics in the prometheus format
+
/health - provides information about the health state, see Health Endpoint
The metrics endpoint exposes metrics gathered through the ZIO metrics frontend in the Prometheus
+format. Additionally, ZIO runtime, JVM and ZIO-HTTP metrics are also exposed.
+
Configuration
+
The refresh interval is configured in application.conf under the key: app.instrumentaion-server-config.interval
+which es per default set to 5 seconds.
+
Example request
+
GET /metrics
+
Example response
+
# TYPE jvm_memory_pool_allocated_bytes_total counter
+# HELP jvm_memory_pool_allocated_bytes_total Some help
+jvm_memory_pool_allocated_bytes_total{pool="G1 Survivor Space"} 4828024.0 1671021037947
+# TYPE jvm_memory_pool_allocated_bytes_total counter
+# HELP jvm_memory_pool_allocated_bytes_total Some help
+jvm_memory_pool_allocated_bytes_total{pool="G1 Eden Space"} 3.3554432E7 1671021037947
+# TYPE zio_fiber_successes counter
+# HELP zio_fiber_successes Some help
+zio_fiber_successes 17.0 1671021037947
+# TYPE zio_fiber_lifetimes histogram
+# HELP zio_fiber_lifetimes Some help
+zio_fiber_lifetimes_bucket{le="1.0"} 17.0 1671021037947
+zio_fiber_lifetimes_bucket{le="2.0"} 17.0 1671021037947
+...
+
+
ZIO-HTTP metrics
+
Metrics of all routes served by ZIO-HTTP (default: port 5555) are exposed through a default metrics middleware.
+However, instead of http_concurrent_requests_total etc. they are labeled zio_http_concurrent_requests_total etc.
+with zio prepended, so that they are clearly distinguishable while we still run ZIO-HTTP and Pekko-HTTP in parallel.
+
To prevent excessive amounts of labels, it is considered good practice,
+to replace dynamic path segments with slugs (e.g. /projects/shortcode/0000 with /projects/shortcode/:shortcode).
+Like this, requesting different projects by identifier will add multiple values to the histogram of a single route,
+instead of creating a histogram for each project:
This is achieved by providing the middleware a pathLabelMapper;
+when adding new routes, it is advisable to assert that this replacement works correctly for the newly added route.
All configuration for Knora is done in application.conf. Besides the Knora application
+specific configuration, there we can also find configuration for the underlying Pekko library.
+
For optimal performance it is important to tune the configuration to the hardware used, mainly
+to the number of CPUs and cores per CPU.
+
The relevant sections for tuning are:
+
+
pekko.actor.deployment
+
knora-actor-dispatcher
+
knora-blocking-dispatcher
+
+
System Environment Variables
+
A number of core settings is additionally configurable through system environment variables. These are:
DSP's Docker images are published automatically through Github CI each time a
+pull-request is merged into the main branch.
+
Each image is tagged with a version number, which is derived by
+using the result of git describe. The describe version is built from the
+last tag + number of commits since tag + short hash, e.g., 8.0.0-7-ga7827e9.
ADR-0002 Change Cache Service Manager from Akka-Actor to ZLayer
+
Date: 2022-04-06
+
Status
+
Accepted
+
Context
+
The org.knora.webapi.store.cacheservice.CacheServiceManager was implemented as an Akka-Actor.
+
Decision
+
As part of the move from Akka to ZIO,
+it was decided that the CacheServiceManager
+and the whole implementation of the in-memory and Redis backed cache
+is refactored using ZIO.
+
Consequences
+
The usage from other actors stays the same. The actor messages and responses don't change.
ADR-0004 Change Triplestore Service Manager and Fuseki implementation to ZLayer
+
Date: 2022-05-23
+
Status
+
Accepted
+
Context
+
Both org.knora.webapi.store.triplestore.TriplestoreServiceManager
+and org.knora.webapi.store.triplestore.impl.TriplestoreServiceHttpConnectorImpl
+where implemented as Akka-Actors.
+
Decision
+
As part of the move from Akka to ZIO,
+it was decided that the TriplestoreServiceManager
+and the TriplestoreServiceHttpConnectorImpl
+is refactored using ZIO.
+
Consequences
+
The usage from other actors stays the same. The actor messages and responses don't change.
ADR-0005 Change ResponderManager to a simple case class
+
Date: 2022-06-06
+
Status
+
Accepted
+
Context
+
The org.knora.webapi.responders.ResponderManager was implemented as an Akka-Actor.
+
Decision
+
In preparation of the move from Akka to ZIO, it was decided that the ResponderManager is refactored using plain case classes.
+
Consequences
+
The actor messages and responses don't change.
+All calls made previously to the ResponderManager and the StorageManager
+are now changed to the ApplicationActor
+which will route the calls to either the ResponderManager
+or the StorageManager, based on the message type.
+The ApplicationActor is the only actor that is allowed to make calls
+to either the ResponderManager or the StorageManager.
+All requests from routes are now routed to the ApplicationActor.
The current routes use the Akka Http library.
+Because of changes to the licensing of the Akka framework,
+we want to move away from using Akka Http.
+This also fits the general strategic decision to use ZIO for the backend.
+
Decision
+
In preparation of the move from Akka to ZIO,
+it was decided that the routes should be ported to use the ZIO HTTP server / library instead of Akka Http.
+
Consequences
+
In a first step only the routes are going to be ported, one by one,
+to use ZIO HTTP instead of being routed through Akka Http.
+The Akka Actor System still remains and will be dealt with later.
In order to remove all Akka dependencies, we have to migrate the existing Responders to a ZIO based
+implementation.
+This migration should be possible to do on a per Responder basis so that we do not do a single "big-bang" release with
+too much code changed at once.
+
Status Quo
+
The central and only Actor is the RoutingActor which contains instances of each Responder as a field.
+Each of the Responders needs an ActorRef to the RoutingActor and used the Akka "ask pattern" for communication
+with the other Responders.
+This means a Responder can only be created inside the RoutingActor because the RoutingActor must know
+every Responder in order to route the message but the Responder needs the ActorRef in order to communicate with
+the other Responders.
+This leads to a circular dependency between the RoutingActor and all Akka based Responders.
+
Goal
+
In the long term all Responders do not contain any Akka dependency anymore and all implementations currently
+returning a Future will return a zio.Task.
+
The zio.Task is a very suitable replacement for the Future because:
+
+
a Future[A] will complete with either a value A or with a failure Throwable.
+
a zio.Task[A] will succeed with either a value A or fail with an error of type Throwable.
+
+
Ideally all Responders will directly call the necessary components directly through invoking methods.
+However, this will not be possible in the beginning as there are Responders who call on each other creating yet another
+circular dependency which we cannot simply recreate with ZLayer dependency injection.
+Hence, a message like communication pattern through a central component the MessageRelay will be introduced which
+can replace the existing Akka "ask pattern" one to one in the ziofied component.
+
Solution
+
The MessageRelay is capable of relaying message to subscribed MessageHandlers and replaces the existing Akka "ask
+pattern" with the RoutingActor.
+Messages which will have a MessageHandler implementation must extend the RelayedMessage trait so that these are
+routed to the MessageRelay from the RoutingActor.
+All other messages will be handled as before.
+
In ziofied Responders we can use the MessageRelay for communication with all other Responders in a similar fashion
+as the Akka "ask pattern" by invoking the method MessageRelay#ask(ResponderRequest): Task[Any].
+A special MessageHandler will route all messages which do not implement the RelayedMessage trait back to
+the RoutingActor, this is the AppRouterRelayingMessageHandler.
+
In the long run we will prefer to invoke methods on the respective ziofied services directly.
+This is now already possible for example with the TriplestoreServive, i.e. instead of
+calling MessageRelay#ask[SparqlSelectResul](SparqlSelectRequest) it is much easier and more importantly typesafe to
+call TriplestoreService#sparqlHttpSelect(String): UIO[SparqlSelectResult].
+
Communication between Akka based Responder and another Akka based Responder
+
Nothing changes with regard to existing communication patterns:
Communication between Akka based Responder and ziofied Responder
+
The AkkaResponder code remains unchanged and will still ask the ActorRef to the RoutingActor.
+The RoutingActor will forward the message to the MessageRelay and return its response to the AkkaResponder.
In preparation of the move from Akka to ZIO,
+it was decided that the Responders should be ported to use return ZIOs and the MessageRelay
+instead of Futures and the ActorRef to the RoutingActor.
+
Consequences
+
In a first step only the Responders are going to be ported, one by one, to use the above pattern.
+The Akka Actor System still remains, will be used in the test and will be removed in a later step.
+Due to the added indirections and the blocking nature of Unsafe.unsafe(implicit u => r.unsafe.run(effect))
+it is necessary to spin up more RoutingActor instances as otherwise deadlocks will occur.
+This should not be a problem as any shared state, e.g. caches,
+is not held within the RoutingActor or one of its contained Responder instances.
On 7. September 2022 Lightbend announced a
+license change for the Akka project,
+the TL;DR being that you will need a commercial license to use future versions of Akka (2.7+) in production
+if you exceed a certain revenue threshold.
+
For now, we have staid on Akka 2.6, the current latest version that is still available under the original license.
+Historically Akka has been incredibly stable, and combined with our limited use of features,
+we did not expect this to be a problem.
Will critical vulnerabilities and bugs be patched in 2.6.x?
+Yes, critical security updates and critical bugs will be patched in Akka v2.6.x
+ under the current Apache 2 license until September of 2023.
+
+
As a result, we will not receive further updates and we will never get support for Scala 3 for Akka.
Our current migration to another http server implementation is currently on hold,
+but we might want to switch to Pekko so that we could receive security updates and bugfixes.
+
The proof of concept implementation has been shared in the pull request
+here,
+allowing for further testing and validation of the proposed switch to Pekko.
+
Decision
+
We replace Akka and Akka/Http with Apache Pekko.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/05-internals/design/api-admin/administration-fig1.dot b/05-internals/design/api-admin/administration-fig1.dot
new file mode 100644
index 0000000000..5c52b261f7
--- /dev/null
+++ b/05-internals/design/api-admin/administration-fig1.dot
@@ -0,0 +1,30 @@
+digraph G {
+ a [label="Start"];
+
+ b [label="Get all groups for user"];
+
+ c1 [label="Get all Resource Creation Permissions"];
+ c2 [label="Decide if user is allowed to create the resource type"];
+
+ d1 [label="Get all Default Object Access Permissions"];
+ d2 [label="Get Default Object Access Permissions attached to Groups"];
+ d3 [label="Get Default Object Access Permissions attached to Resources/Values"];
+ d4 [label="Calculate maximum Default Object Access Permissions"];
+
+ e [label="Create Resource/Values with maximum Default Object Access Permissions"];
+
+ z [label="End"];
+
+ a -> b;
+ b -> c1;
+ c1 -> c2;
+ c2 -> e;
+
+ b -> d1;
+ d1 -> d2;
+ d2 -> d3;
+ d3 -> d4;
+ d4 -> e;
+
+ e -> z;
+}
diff --git a/05-internals/design/api-admin/administration-fig1.dot.png b/05-internals/design/api-admin/administration-fig1.dot.png
new file mode 100644
index 0000000000..a7bdfdf3ef
Binary files /dev/null and b/05-internals/design/api-admin/administration-fig1.dot.png differ
diff --git a/05-internals/design/api-admin/administration-fig2.dot b/05-internals/design/api-admin/administration-fig2.dot
new file mode 100644
index 0000000000..02375f7efe
--- /dev/null
+++ b/05-internals/design/api-admin/administration-fig2.dot
@@ -0,0 +1,18 @@
+digraph G {
+ a [label="Start"];
+
+ b [label="Get all groups for user"];
+ c [label="Get all permissions attached to Resource/Value"];
+ d [label="Calculate max permission user has on Resource/Value through group membership"];
+ e [label="Decide if user is allowed to perform operation"];
+
+ z [label="End"];
+
+ a -> b;
+ a -> c;
+ b -> d;
+ c -> d;
+ d -> e;
+
+ e -> z;
+}
diff --git a/05-internals/design/api-admin/administration-fig2.dot.png b/05-internals/design/api-admin/administration-fig2.dot.png
new file mode 100644
index 0000000000..29167f662c
Binary files /dev/null and b/05-internals/design/api-admin/administration-fig2.dot.png differ
diff --git a/05-internals/design/api-admin/administration-fig3.dot b/05-internals/design/api-admin/administration-fig3.dot
new file mode 100644
index 0000000000..1f9f94a6f0
--- /dev/null
+++ b/05-internals/design/api-admin/administration-fig3.dot
@@ -0,0 +1,14 @@
+digraph G {
+ a [label="Start"];
+
+ b [label="Get all groups for user"];
+ c [label="Get all Project Administration Permissions received through group membership"];
+ d [label="Decide if user is allowed to perform operation"];
+
+ z [label="End"];
+
+ a -> b;
+ b -> c;
+ c -> d;
+ d -> z;
+}
diff --git a/05-internals/design/api-admin/administration-fig3.dot.png b/05-internals/design/api-admin/administration-fig3.dot.png
new file mode 100644
index 0000000000..1949abad12
Binary files /dev/null and b/05-internals/design/api-admin/administration-fig3.dot.png differ
diff --git a/05-internals/design/api-admin/administration-fig4.dot b/05-internals/design/api-admin/administration-fig4.dot
new file mode 100644
index 0000000000..263377acac
--- /dev/null
+++ b/05-internals/design/api-admin/administration-fig4.dot
@@ -0,0 +1,12 @@
+digraph G {
+ rankdir="BT"
+
+ oc [label="owl:Class"]
+ p [label="knora-base:Permission"]
+ ap [label ="knora-base:AdministrativePermission"]
+ doap [label ="knora-base:DefaultObjectAccessPermission"]
+
+ p -> oc [label="rdf:type"]
+ ap -> p [label="rdf:subClassOf"]
+ doap -> p [label="rdf:subClassOf"]
+}
diff --git a/05-internals/design/api-admin/administration-fig4.dot.png b/05-internals/design/api-admin/administration-fig4.dot.png
new file mode 100644
index 0000000000..668e7a5854
Binary files /dev/null and b/05-internals/design/api-admin/administration-fig4.dot.png differ
diff --git a/05-internals/design/api-admin/administration-fig5.dot b/05-internals/design/api-admin/administration-fig5.dot
new file mode 100644
index 0000000000..01cb297d35
--- /dev/null
+++ b/05-internals/design/api-admin/administration-fig5.dot
@@ -0,0 +1,12 @@
+digraph AdministrativePermissions {
+ rankdir="LR"
+
+ ap [label="knora-base:AdministrativePermission"]
+ kp [label="knora-base:knoraProject"]
+ ug [label="knora-base:UserGroup"]
+
+ ap -> kp [ label="knora-base:forProject" ]
+ ap -> ug [ label="knora-base:forGroup" ]
+
+ ap -> "Administrative permissions compact format string" [ label="knora-base:hasPermissions" ]
+}
diff --git a/05-internals/design/api-admin/administration-fig5.dot.png b/05-internals/design/api-admin/administration-fig5.dot.png
new file mode 100644
index 0000000000..823a271b81
Binary files /dev/null and b/05-internals/design/api-admin/administration-fig5.dot.png differ
diff --git a/05-internals/design/api-admin/administration-fig6.dot b/05-internals/design/api-admin/administration-fig6.dot
new file mode 100644
index 0000000000..6163784bee
--- /dev/null
+++ b/05-internals/design/api-admin/administration-fig6.dot
@@ -0,0 +1,16 @@
+digraph DefaultObjectAccessPermissions {
+ rankdir="LR"
+
+ doap [label="knora-base:DefaultObjectAccessPermission"]
+ kp [label="knora-base:knoraProject"]
+ ug [label="knora-base:UserGroup"]
+ rc [label="Resource Class Name"]
+ pr [label="Resource Property Name"]
+
+ doap -> kp [ label="knora-base:forProject" ]
+ doap -> ug [ label="knora-base:forGroup" ]
+ doap -> rc [ label="knora-base:forResourceClass" ]
+ doap -> pr [ label="knora-base:forProperty" ]
+
+ doap -> "Default object access permission compact format string" [ label="knora-base:hasPermissions"]
+}
diff --git a/05-internals/design/api-admin/administration-fig6.dot.png b/05-internals/design/api-admin/administration-fig6.dot.png
new file mode 100644
index 0000000000..fd1e4f23e4
Binary files /dev/null and b/05-internals/design/api-admin/administration-fig6.dot.png differ
diff --git a/05-internals/design/api-admin/administration/index.html b/05-internals/design/api-admin/administration/index.html
new file mode 100644
index 0000000000..a889020dbb
--- /dev/null
+++ b/05-internals/design/api-admin/administration/index.html
@@ -0,0 +1,3769 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Admin API Design - DSP-API
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The default permissions when a project is created are described
+here.
+
DSP's concept of access control is that permissions
+can only be granted to groups and not to individual users.
+There are two distinct ways of granting permission.
+
+
An object (a resource or value) can grant permissions to groups of users.
+
Permissions can be granted directly to a group of users (not bound to a specific object).
+
+
There are six built-in groups:
+UnknownUser, KnownUser, Creator, ProjectMember, ProjectAdmin, and SystemAdmin.
+These groups can be used in the same way as normal user created groups for permission
+management, i.e. can be used to give certain groups of users, certain
+permissions, without the need to explicitly create them.
+
A user becomes implicitly a member of such a group by satisfying certain conditions:
+
+
+
knora-admin:UnknownUser:
+ Any user who has not logged into the DSP is automatically assigned to this group.
+ Group IRI: http://www.knora.org/ontology/knora-admin#UnknownUser
+
+
+
knora-admin:KnownUser:
+ Any user who has logged into the DSP is automatically assigned to this group.
+ Group IRI: http://www.knora.org/ontology/knora-admin#KnownUser
+
+
+
knora-admin:Creator:
+ When checking a user’s permissions on an object, the user is automatically assigned to this group
+ if they are the creator of the object.
+ Group IRI: http://www.knora.org/ontology/knora-admin#Creator
+
+
+
knora-admin:ProjectMember:
+ When checking a user’s permissions, the user is automatically assigned to this group
+ by being a member of a project designated by the knora-admin:isInProject property.
+ Group IRI: http://www.knora.org/ontology/knora-admin#ProjectMember
+
+
+
knora-admin:ProjectAdmin:
+ When checking a user's permission, the user is automatically assigned to this group
+ through the knora-admin:isInProjectAdminGroup property, which points to the project in question.
+ Group IRI: http://www.knora.org/ontology/knora-admin#ProjectAdmin
+
+
+
knora-admin:SystemAdmin:
+ Membership is received by setting the property knora-admin:isInSystemAdminGroup to true on a knora-admin:User.
+ Group IRI: http://www.knora.org/ontology/knora-admin#SystemAdmin
+
+
+
There are three kinds of permissions:
+
+
object access permissions, which contain permissions
+ that point from explicit objects (resources/values) to groups.
+
administrative permissions, which contain permissions
+ that are put on instances of knora-admin:Permission objects directly affecting groups.
+
default object access permissions which are also put on instances of knora-admin:Permission,
+ and which also directly affect groups.
+
+
Object Access Permissions
+
An object (resource / value) can grant the following permissions, which
+are stored in a compact format in a single string, which is the object
+of the predicate knora-base:hasPermissions:
+
+
Restricted view permission (RV): Allows a restricted view of
+ the object, e.g. a view of an image with a watermark.
+
View permission (V): Allows an unrestricted view of the
+ object. Having view permission on a resource only affects the
+ user's ability to view information about the resource other than
+ its values. To view a value, she must have view permission on the
+ value itself.
+
Modify permission (M): For values, this permission allows a
+ new version of a value to be created. For resources, this allows
+ the user to create a new value (as opposed to a new version of an
+ existing value), or to change information about the resource other
+ than its values. When he wants to make a new version of a value,
+ his permissions on the containing resource are not relevant.
+ However, when he wants to change the target of a link, the old
+ link must be deleted and a new one created, so he needs modify
+ permission on the resource.
+
Delete permission (D): Allows the item to be marked as deleted.
+
Change rights permission (CR): Allows the permissions granted by the object to be changed.
+
+
Each permission in the above list implies all lower-numbered
+permissions.
+
A user's permission level on a particular object is calculated in
+the following way:
+
+
Make a list of the groups that the user belongs to, including
+ Creator and/or ProjectMember and/or ProjectAdmin if applicable.
+
Make a list of the permissions that she can obtain on the
+ object, by iterating over the permissions that the object
+ grants. For each permission, if she is in the specified group,
+ add the specified permission to the list of permissions she can
+ obtain.
+
From the resulting list, select the highest-level permission.
+
If the result is that she would have no permissions, give her
+ whatever permission UnknownUser would have.
+
+
The format of the object of knora-base:hasPermissions is as
+follows:
+
+
Each permission is represented by the one-letter or two-letter
+ abbreviation given above.
+
Each permission abbreviation is followed by a space, then a
+ comma-separated list of groups that the permission is granted
+ to.
+
The IRIs of built-in groups are shortened using the knora-admin
+ prefix.
+
Multiple permissions are separated by a vertical bar (|).
+
+
For example, if an object grants view permission to unknown and known
+users, and modify permission to project members, the resulting
+permission literal would be: V knora-admin:UnknownUser,knora-admin:KnownUser|M knora-admin:ProjectMember.
+
Administrative Permissions
+
The following permissions can be set via instances of
+knora-admin:AdministrativePermission on any group belonging to a
+project. For users that are members of a number of groups with
+administrative permissions attached, the final set of permissions is
+additive and most permissive. The administrative permissions are stored
+in a compact format in a single string, which is the object of the
+predicate knora-base:hasPermissions attached to an instance of the
+knora-admin:AdministrativePermission class. The following permission
+values can be used:
+
+
Resource / Value Creation Permissions:
+ 1) ProjectResourceCreateAllPermission:
+ - description: gives the permission to create resources inside the project.
+ - usage: used as a value for knora-base:hasPermissions.
+ 2) ProjectResourceCreateRestrictedPermission:
+ - description: gives restricted resource creation permission inside the project.
+ - usage: used as a value for knora-base:hasPermissions.
+ - value: RestrictedProjectResourceCreatePermission
+ followed by a comma-separated list of ResourceClasses
+ the user should only be able to create instances of.
+
Project Administration Permissions:
+ 1) ProjectAdminAllPermission:
+ - description: gives the user the permission to do anything
+ on project level, i.e. create new groups, modify all
+ existing groups (group info, group membership,
+ resource creation permissions, project administration
+ permissions, and default permissions).
+ - usage: used as a value for knora-base:hasPermissions.
+ 2) ProjectAdminGroupAllPermission:
+ - description: gives the user the permission to modify
+ group info and group membership on all groups
+ belonging to the project.
+ - usage: used as a value for the knora-base:hasPermissions property.
+ 3) ProjectAdminGroupRestrictedPermission:
+ - description: gives the user the permission to modify
+ group info and group membership on certain groups
+ belonging to the project.
+ - usage: used as a value for knora-base:hasPermissions
+ - value: ProjectGroupAdminRestrictedPermission followed by
+ a comma-separated list of knora-admin:UserGroup.
+ 4) ProjectAdminRightsAllPermission:
+ - description: gives the user the permission to change the
+ permissions on all objects belonging to the project
+ (e.g., default permissions attached to groups and
+ permissions on objects).
+ - usage: used as a value for the knora-base:hasPermissions property.
+
+
The administrative permissions are stored in a compact format in a
+single string, which is the object of the predicate
+knora-base:hasPermissions attached to an instance of the
+knora-admin:AdministrativePermission class.
+
+
The format of the object of knora-base:hasPermissions is as follows:
+
Each permission is represented by the name given above.
+
Each permission is followed by a space, then if applicable, by comma separated list of IRIs, as defined above.
+
The IRIs of built-in values (e.g., built-in groups, resource
+ classes, etc.) are shortened using the knora-admin prefix knora-admin:.
+
Multiple permissions are separated by a vertical bar (|).
+
+
+
+
For example, if an administrative permission grants the
+knora-admin:ProjectMember group the permission to create all resources
+(ProjectResourceCreateAllPermission), the resulting administrative
+permission object with the compact form literal would be: :
Default Object Access Permissions are used when new objects (resources
+and/or values) are created. They represent object access permissions
+with which the new object will be initially outfitted. As with
+administrative permissions, these default object access permissions can
+be defined for any number of groups. Additionally, they can be also
+defined for resource classes and properties.
+
The following default object access permissions can be attached to
+groups, resource classes and/or properties via instances of
+knora-admin:DefaultObjectAccessPermission (described further bellow).
+The default object access permissions correspond to the earlier
+described object access permission:
+
+
Default Restricted View Permission (RV):
+
description: any object, created by a user inside a group
+ holding this permission, is restricted to carry this permission
+
value: RV followed by a comma-separated list of knora-admin:UserGroup
+
+
+
Default View Permission (V):
+
description: any object, created by a user inside a group
+ holding this permission, is restricted to carry this permission
+
value: V followed by a comma-separated list of knora-admin:UserGroup
+
+
+
Default Modify Permission (M) accompanied by a list of groups.
+
description: any object, created by a user inside a group
+ holding this permission, is restricted to carry this permission
+
value: M followed by a comma-separated list of knora-admin:UserGroup
+
+
+
Default Delete Permission (D) accompanied by a list of groups.
+
description: any object, created by a user inside a group
+ holding this permission, is restricted to carry this permission
+
value: D followed by a comma-separated list of knora-admin:UserGroup
+
+
+
Default Change Rights Permission (CR) accompanied by a list of groups.
+
description: any object, created by a user inside a group
+ holding this permission, is restricted to carry this permission
+
value: CR followed by a comma-separated list of knora-admin:UserGroup
+
+
+
+
A single instance of knora-admin:DefaultObjectAccessPermission must
+always reference a project, but can only reference either a group
+(knora-admin:forGroup property), a resource class
+(knora-admin:forResourceClass), a property (knora-admin:forProperty),
+or a combination of resource class and property.
+
Example default object access permission instance:
This instance is setting default object access permissions to the
+project member group of a project, giving change right permission to the
+creator, modify permission to all project members, and view permission
+to known users. Further, this implicitly applies to all resource
+classes and all their properties inside the project.
+
Permission Precedence Rules
+
For both administrative permissions and default object access
+permissions, the resulting permissions are derived by applying
+precedence rules, for the case that the user is member of more than one
+group.
+
The following list is sorted by the permission precedence level in
+descending order:
+
+
permissions on knora-admin:ProjectAdmin (highest level)
+
permissions on resource classes and property combination (own project)
+
permissions on properties (own project, when creating a Value)
+
permissions on resource classes (own project, when creating a Resource)
+
permissions on custom groups
+
permissions on knora-admin:ProjectMember
+
+
The permissions on resource classes / properties are only relevant for
+default object access permissions.
+
Administrative Permissions: When a user performs an operation
+requiring administrative permissions, then only the permissions from
+the highest level are taken into account. If a user is a member of
+more than one group on the same level (only possible for custom groups)
+then the defined permissions are summed up and all are taken into
+account.
+
Default Object Access Permissions: When a user creates a resource or
+value, then only the default object permissions from the highest
+level are applied. If a user is a member of more than one group on the
+same level (only possible for custom groups) then the defined
+permissions are summed up and the most permissive are applied.
+
In the case of the user belonging to the SystemAdmin group, but which
+is not member of a project and thus not member of any group belonging
+to the project, the default object access permissions from the
+ProjectAdmin, or ProjectMember group will be
+applied in the order of precedence. If no permissions are defined on
+either of these groups, then the resulting permission will be CR knora-admin:Creator.
+
Implicit Permissions
+
The knora-admin:SystemAdmin group receives implicitly the following
+permissions:
+
+
receives implicitly ProjectAdminAllPermission for all projects.
+
receives implicitly ProjectResourceCreateAllPermission for all projects.
+
receives implicitly CR on all objects from all projects.
+
+
These permissions are baked into the system, and cannot be changed.
+
Default Permissions Matrix for new Projects
+
The access control matrix defines what are the default operations a
+subject (i.e. User), being a member of a built-in group (represented
+by row headers), is permitted to perform on an object (represented by
+column headers). The different operation abbreviations used are defined
+as follows:
+
+
+
C: Create - the subject inside the group is allowed to create the object.
+
+
+
U: Update - the subject inside the group is allowed to update the object.
+
+
+
R: Read - the subject inside the group is allowed to readall information about the object.
+
+
+
D: Delete - the subject inside the group is allowed to delete the object.
+
+
+
P: Permission - the subject inside the group is allowed to change the permissions on the object.
+
+
+
-: none - none or not applicable
+
+
+
+
+
+
Built-In Group
+
Project
+
Group
+
User
+
Resource
+
Value
+
+
+
+
+
SystemAdmin
+
CRUD
+
CRUDP
+
CRUDP all
+
CRUDP all
+
CRUDP all
+
+
+
ProjectAdmin
+
-RUD
+
CRUDP
+
CRUDP +/- project
+
CRUDP (in project)
+
CRUDP (in project)
+
+
+
ProjectMember
+
----
+
-----
+
-----
+
CRU-- (in project)
+
----- (in project)
+
+
+
Creator
+
----
+
-----
+
-----
+
----- (his resource)
+
----- (his value)
+
+
+
KnownUser
+
C---
+
C----
+
CRUD- himself
+
----- (in project)
+
----- (in project)
+
+
+
+
Default Permissions Matrix for new Projects
+
The explicitly defined default permissions for a new project are as follows:
+
+
+
knora-admin:ProjectAdmin group:
+
+
Administrative Permissions:
+
ProjectResourceCreateAllPermission.
+
ProjectAdminAllPermission.
+
+
+
Default Object Access Permissions:
+
CR for the knora-admin:ProjectAdmin group
+
D for the knora-admin:ProjectAdmin group
+
M for the knora-admin:ProjectAdmin group
+
V for the knora-admin:ProjectAdmin group
+
RV for the knora-admin:ProjectAdmin group
+
+
+
+
+
+
The knora-admin:ProjectMember group:
+
+
Administrative Permissions:
+
ProjectResourceCreateAllPermission.
+
+
+
Default Object Access Permissions:
+
M for the knora-admin:ProjectMember group
+
V for the knora-admin:ProjectMember group
+
RV for the knora-admin:ProjectMember group
+
+
+
+
+
+
Basic Workflows involving Permissions
+
Creating a new Resource
+
+
Accessing a Resource/Value
+
+
Project / Group Administration
+
+
Implementation
+
The requirements for defining default permissions imposed by all the
+different use cases are very broad. Potentially, we need to be able to
+define default permissions per project, per group, per resource class,
+per resource property, and all their possible combinations.
+
For this reason, we introduce the knora-admin:Permission class with two
+sub-classes, namely knora-admin:AdministrativePermission and
+knora-admin:DefaultObjectAccessPermission, which instances will carry
+all the necessary information.
+
Permission Class Hierarchy and Structure
+
The following graphs show the class hierarchy and the structure of each
+permission class.
The properties forProject and either of forGroup,
+forResourceClass, and forProperty form together a compound
+key, allowing finding existing permission instances, that address the
+same set of Project / Group / ResourceClass / Property combination, thus
+making it possible to extend or change the attached permissions.
+
Administrative Permission Instances: For each group inside the
+project, there can be zero or one instance holding
+administrative permission information. Querying is straitforward by
+using the knora-admin:forProject and knora-admin:forGroup properties
+as the compound key.
+
Default Object Access Permission Instances: For each group, resource
+class, or property inside the project, there can be zero or one
+instances holding default object access permission informations.
+Querying is straitforward by using the knora-admin:forProject and
+either knora-admin:forGroup, knora-admin:forResourceClass, or
+knora-admin:forProperty properties as part of the compound key.
+
Example Data stored in the permissions graph
+
Administrative permissions on a 'ProjectAdmin' group:
When the user's UserProfile is queried, all permissions for all
+projects and groups the user is a member of are also queried. This
+information is then stored as an easy accessible object inside the
+UserProfile, being readily available wherever needed. As this is a
+somewhat expensive operation, built-in caching mechanism at different
+levels (e.g., UsersResponder, PermissionsResponder), will be applied.
Knora must produce an ARK URL for each resource and each value. The ARK identifiers used
+by Knora must respect
+the draft ARK specification.
+The format of Knora’s ARK URLs must be able to change over
+time, while ensuring that previously generated ARK URLs still work.
VALUE_UUID: optionally, the knora-base:valueHasUUID of one of the
+ resource's values, normally a
+ base64url-encoded UUID, as described in
+ IRIs for Data.
+
+
+
TIMESTAMP: an optional timestamp indicating that the ARK URL represents
+ the state of the resource at a specific time in the past. The format
+ of the timestamp is an ISO 8601
+ date in Coordinated universal time (UTC), including date, time, and an optional
+ nano-of-second field (of at most 9 digits), without the characters -, :, and . (because
+ - and . are reserved characters in ARK, and : would have to be URL-encoded).
+ Example: 20180528T155203897Z.
+
+
+
Following the ARK ID spec, /
+represents object hierarchy
+and .represents an object variant.
+A value is thus contained in a resource, which is contained in its project,
+which is contained in a repository (represented by the URL version number).
+A timestamp is a type of variant.
+
Since sub-objects are optional, there is also implicitly an ARK URL
+for each project, as well as for the repository as a whole.
+
The RESOURCE_UUID and VALUE_UUID are processed as follows:
+
+
+
A check digit is calculated, using the algorithm in
+ the Scala class org.knora.webapi.util.Base64UrlCheckDigit, and appended
+ to the UUID.
+
+
+
Any - characters in the resulting string are replaced with =, because
+ base64url encoding uses -, which is a reserved character in ARK URLs.
+
+
+
For example, given a project with ID 0001, and using the DaSCH's ARK resolver
+hostname and NAAN, the ARK URL for the project itself is:
+
http://ark.dasch.swiss/ark:/72163/1/0001
+
+
Given the Knora resource IRI http://rdfh.ch/0001/0C-0L1kORryKzJAJxxRyRQ,
+the corresponding ARK URL without a timestamp is:
Given a value with knora-api:valueHasUUID "4OOf3qJUTnCDXlPNnygSzQ" in the resource
+http://rdfh.ch/0001/0C-0L1kORryKzJAJxxRyRQ, and using the DaSCH's ARK resolver
+hostname and NAAN, the corresponding ARK URL without a timestamp is:
SmartIri converts Knora resource IRIs to ARK URLs. This conversion is invoked in ReadResourceV2.toJsonLD,
+when returning a resource's metadata in JSON-LD format.
Whenever possible, the same data structures are used to represent the same
+types of data, regardless of the API operation (reading, creating, or
+modifying). However, often more data is available in output than in input. For
+example, when a value is read from the triplestore, its IRI is
+available, but when it is being created, it does not yet have an IRI.
+
The implementation of API v2 therefore uses content wrappers. For each type,
+there is a case class that represents the lowest common denominator of the
+type, the data that will be present regardless of the API operation. For
+example, the trait ValueContentV2 represents a Knora value, regardless
+of whether it is received as input or returned as output. Case classes
+such as DateValueContentV2 and TextValueContentV2 implement this trait.
+
An instance of this lowest-common-denominator class, or "content class", can then
+be wrapped in an instance of an operation-specific class that carries additional
+data. For example, when a Knora value is returned from the triplestore, a
+ValueContentV2 is wrapped in a ReadValueV2, which additionally contains the
+value's IRI. When a value is created, it is wrapped in a CreateValueV2, which
+has the resource IRI and the property IRI, but not the value IRI.
+
A read wrapper can be wrapped in another read wrapper; for
+example, a ReadResourceV2 contains ReadValueV2 objects.
+
In general, DSP-API v2 responders deal only with the internal schema.
+(The exception is OntologyResponderV2, which can return ontology information
+that exists only in an external schema.) Therefore, a content class needs
+to be able to convert itself from the internal schema to an external schema
+(when it is being used for output) and vice versa (when it is being used for
+input). Each content class class should therefore extend KnoraContentV2, and
+thus have a toOntologySchema method or converting itself between internal and
+external schemas, in either direction:
+
/**
+ * A trait for content classes that can convert themselves between internal and internal schemas.
+ *
+ * @tparam C the type of the content class that extends this trait.
+ */
+trait KnoraContentV2[C <: KnoraContentV2[C]] {
+ this: C =>
+ def toOntologySchema(targetSchema: OntologySchema): C
+}
+
+
Since read wrappers are used only for output, they need to be able convert
+themselves only from the internal schema to an external schema. Each read wrapper class
+should extend KnoraReadV2, and thus have a method for doing this:
+
/**
+ * A trait for read wrappers that can convert themselves to external schemas.
+ *
+ * @tparam C the type of the read wrapper that extends this trait.
+ */
+trait KnoraReadV2[C <: KnoraReadV2[C]] {
+ this: C =>
+ def toOntologySchema(targetSchema: ApiV2Schema): C
+}
+
The code that converts Gravsearch queries into SPARQL queries, and processes the query results, needs to know the
+types of the entities that are used in the input query. As explained in
+Type Inference, these types can be inferred,
+or they can be specified in the query using type annotations.
+
Type inspection is implemented in the package org.knora.webapi.messages.util.search.gravsearch.types.
+The entry point to this package is GravsearchTypeInspectionRunner, which is instantiated by SearchResponderV2.
+The result of type inspection is a GravsearchTypeInspectionResult, in which each typeable entity in the input query is
+associated with a GravsearchEntityTypeInfo, which can be either:
+
+
A PropertyTypeInfo, which specifies the type of object that a property is expected to have.
+
A NonPropertyTypeInfo, which specifies the type of a variable, or the type of an IRI representing a resource or value.
+
+
Identifying Typeable Entities
+
After parsing a Gravsearch query, SearchResponderV2 calls GravsearchTypeInspectionRunner.inspectTypes, passing
+the WHERE clause of the input query. This method first identifies the entities whose types need to be determined. Each
+of these entities is represented as a TypeableEntity. To do this, GravsearchTypeInspectionRunner uses QueryTraverser
+to traverse the WHERE clause, collecting typeable entities in a visitor called TypeableEntityCollectingWhereVisitor.
+The entities that are considered to need type information are:
+
+
All variables.
+
All IRIs except for those that represent type annotations or types.
+
+
The Type Inspection Pipeline
+
GravsearchTypeInspectionRunner contains a pipeline of type inspectors, each of which extends GravsearchTypeInspector.
+There are two type inspectors in the pipeline:
+
+
AnnotationReadingGravsearchTypeInspector: reads
+ type annotations included in a Gravsearch query.
+
InferringGravsearchTypeInspector: infers the types of entities from the context in which they are used, as well
+ as from ontology information that it requests from OntologyResponderV2.
+
+
Each type inspector takes as input, and returns as output, an IntermediateTypeInspectionResult, which
+associates each TypeableEntity with zero or more types. Initially, each TypeableEntity has no types.
+Each type inspector adds whatever types it finds for each entity.
+
At the end of the pipeline, each entity should
+have exactly one type. Therefore, to only keep the most specific type for an entity,
+the method refineDeterminedTypes refines the determined types by removing those that are base classes of others. However,
+it can be that inconsistent types are determined for entities. For example, in cases where multiple resource class types
+are determined, but one is not a base class of the others. From the following statement
+
{ ?document a beol:manuscript . } UNION { ?document a beol:letter .}
+
+
two inconsistent types can be inferred for ?document: beol:letter and beol:manuscript.
+In these cases, a sanitizer sanitizeInconsistentResourceTypes replaces the inconsistent resource types by
+their common base resource class (in the above example, it would be beol:writtenSource).
+
Lastly, an error is returned if
+
+
An entity's type could not be determined. The client must add a type annotation to make the query work.
+
Inconsistent types could not be sanitized (an entity appears to have more than one type). The client must correct the query.
+
+
If there are no errors, GravsearchTypeInspectionRunner converts the pipeline's output to a
+GravsearchTypeInspectionResult, in which each entity is associated with exactly one type.
+
AnnotationReadingGravsearchTypeInspector
+
This inspector uses QueryTraverser to traverse the WHERE clause, collecting type annotations in a visitor called
+AnnotationCollectingWhereVisitor. It then converts each annotation to a GravsearchEntityTypeInfo.
+
InferringGravsearchTypeInspector
+
This inspector first uses QueryTraverser to traverse the WHERE clause, assembling an index of
+usage information about typeable entities in a visitor called UsageIndexCollectingWhereVisitor. The UsageIndex contains,
+for example, an index of all the entities that are used as subjects, predicates, or objects, along with the
+statements in which they are used. It also contains sets of all the Knora class and property IRIs
+that are used in the WHERE clause. InferringGravsearchTypeInspector then asks OntologyResponderV2 for information
+about those classes and properties, as well as about the classes that are subject types or object types of those properties.
+
Next, the inspector runs inference rules (which extend InferenceRule) on each TypeableEntity. Each rule
+takes as input a TypeableEntity, the usage index, the ontology information, and the IntermediateTypeInspectionResult,
+and returns a new IntermediateTypeInspectionResult. For example, TypeOfObjectFromPropertyRule infers an entity's type
+if the entity is used as the object of a statement and the predicate's knora-api:objectType is known. For each TypeableEntity,
+if a type is inferred from a property, the entity and the inferred type are added to
+IntermediateTypeInspectionResult.entitiesInferredFromProperty.
+
The inference rules are run repeatedly, because the output of one rule may allow another rule to infer additional
+information. There are two pipelines of rules: a pipeline for the first iteration of type inference, and a
+pipeline for subsequent iterations. This is because some rules can return additional information if they are run
+more than once on the same entity, while others cannot.
+
The number of iterations is limited to InferringGravsearchTypeInspector.MAX_ITERATIONS, but in practice
+two iterations are sufficient for most realistic queries, and it is difficult to design a query that requires more than
+six iterations.
+
Transformation of a Gravsearch Query
+
A Gravsearch query submitted by the client is parsed by GravsearchParser and preprocessed by GravsearchTypeInspector
+to get type information about the elements used in the query (resources, values, properties etc.)
+and do some basic sanity checks.
+
In SearchResponderV2, two queries are generated from a given Gravsearch query: a prequery and a main query.
+
Query Transformers
+
The Gravsearch query is passed to QueryTraverser along with a query transformer. Query transformers are classes
+that implement traits supported by QueryTraverser:
+
+
WhereTransformer: instructions how to convert statements in the WHERE clause of a SPARQL query
+ (to generate the prequery's Where clause).
+
+
To improve query performance, this trait defines the method optimiseQueryPatterns whose implementation can call
+private methods to optimise the generated SPARQL. For example, before transformation of statements in WHERE clause, query
+pattern orders must be optimised by moving LuceneQueryPatterns to the beginning and isDeleted statement patterns to the end of the WHERE clause.
+
+
AbstractPrequeryGenerator (extends WhereTransformer): converts a Gravsearch query into a prequery;
+ this one has two implementations for regular search queries and for count queries.
+
SelectTransformer (extends WhereTransformer): transforms a Select query into a Select query with simulated RDF inference.
+
ConstructTransformer: transforms a Construct query into a Construct query with simulated RDF inference.
+
+
Prequery
+
The purpose of the prequery is to get an ordered collection of results representing only the IRIs of one page of matching resources and values.
+Sort criteria can be submitted by the user, but the result is always deterministic also without sort criteria.
+This is necessary to support paging.
+A prequery is a SPARQL SELECT query.
+
The classes involved in generating prequeries can be found in org.knora.webapi.messages.util.search.gravsearch.prequery.
+
If the client submits a count query, the prequery returns the overall number of hits, but not the results themselves.
+
In a first step, before transforming the WHERE clause, query patterns must be further optimised by removing
+the rdfs:type statement for entities whose type could be inferred from their use with a property IRI, since there would be no need
+for explicit rdfs:type statements for them (unless the property IRI from which the type of an entity must be inferred from
+is wrapped in an OPTIONAL block). This optimisation takes the Gravsearch query as input (rather than the generated SPARQL),
+because it uses type information that refers to entities in the Gravsearch query, and the generated SPARQL might
+have different entities.
+
Next, the Gravsearch query's WHERE clause is transformed and the prequery (SELECT and WHERE clause) is generated from this result.
+The transformation of the Gravsearch query's WHERE clause relies on the implementation of the abstract class AbstractPrequeryGenerator.
+
AbstractPrequeryGenerator contains members whose state is changed during the iteration over the statements of the input query.
+They can then be used to create the converted query.
+
+
mainResourceVariable: Option[QueryVariable]:
+ SPARQL variable representing the main resource of the input query.
+ Present in the prequery's SELECT clause.
+
dependentResourceVariables: mutable.Set[QueryVariable]:
+ a set of SPARQL variables representing dependent resources in the input query.
+ Used in an aggregation function in the prequery's SELECT clause (see below).
+
dependentResourceVariablesGroupConcat: Set[QueryVariable]:
+ a set of SPARQL variables representing an aggregation of dependent resources.
+ Present in the prequery's SELECT clause.
+
valueObjectVariables: mutable.Set[QueryVariable]:
+ a set of SPARQL variables representing value objects.
+ Used in an aggregation function in the prequery's SELECT clause (see below).
+
valueObjectVarsGroupConcat: Set[QueryVariable]:
+ a set of SPARQL variables representing an aggregation of value objects.
+ Present in the prequery's SELECT clause.
+
+
The variables mentioned above are present in the prequery's result rows because they are part of the prequery's SELECT clause.
+
The following example illustrates the handling of variables.
+The following Gravsearch query looks for pages with a sequence number of 10 that are part of a book:
The prequery's SELECT clause is built by
+NonTriplestoreSpecificGravsearchToPrequeryTransformer.getSelectColumns,
+based on the variables used in the input query's CONSTRUCT clause.
+The resulting SELECT clause looks as follows:
+
SELECTDISTINCT
+ ?page
+ (GROUP_CONCAT(DISTINCT(IF(BOUND(?book),STR(?book),""));SEPARATOR='')AS?book__Concat)
+ (GROUP_CONCAT(DISTINCT(IF(BOUND(?seqnum),STR(?seqnum),""));SEPARATOR='')AS?seqnum__Concat)
+ (GROUP_CONCAT(DISTINCT(IF(BOUND(?book__LinkValue),STR(?book__LinkValue),""));SEPARATOR='')AS?book__LinkValue__Concat)
+ WHERE{...}
+ GROUP BY?page
+ ORDER BYASC(?page)
+ LIMIT25
+
+
?page represents the main resource. When accessing the prequery's result rows, ?page contains the IRI of the main resource.
+The prequery's results are grouped by the main resource so that there is exactly one result row per matching main resource.
+?page is also used as a sort criterion although none has been defined in the input query.
+This is necessary to make paging work: results always have to be returned in the same order (the prequery is always deterministic).
+Like this, results can be fetched page by page using LIMIT and OFFSET.
+
Grouping by main resource requires other results to be aggregated using the function GROUP_CONCAT.
+?book is used as an argument of the aggregation function.
+The aggregation's result is accessible in the prequery's result rows as ?book__Concat.
+The variable ?book is bound to an IRI.
+Since more than one IRI could be bound to a variable representing a dependent resource, the results have to be aggregated.
+GROUP_CONCAT takes two arguments: a collection of strings (IRIs in our use case) and a separator
+(we use the non-printing Unicode character INFORMATION SEPARATOR ONE).
+When accessing ?book__Concat in the prequery's results containing the IRIs of dependent resources,
+the string has to be split with the separator used in the aggregation function.
+The result is a collection of IRIs representing dependent resources.
+The same logic applies to value objects.
+
Each GROUP_CONCAT checks whether the concatenated variable is bound in each result in the group; if a variable
+is unbound, we concatenate an empty string. This is necessary because, in Apache Jena (and perhaps other
+triplestores), "If GROUP_CONCAT has an unbound value in the list of values to concat, the overall result is 'error'"
+(see this Jena issue).
+
If the input query contains a UNION, and a variable is bound in one branch
+of the UNION and not in another branch, it is possible that the prequery
+will return more than one row per main resource. To deal with this situation,
+SearchResponderV2 merges rows that contain the same main resource IRI.
+
Main Query
+
The purpose of the main query is to get all requested information
+about the main resource, dependent resources, and value objects.
+The IRIs of those resources and value objects were returned by the prequery.
+Since the prequery only returns resources and value objects matching the input query's criteria,
+the main query can specifically ask for more detailed information on these resources and values
+without having to reconsider these criteria.
+
Generating the Main Query
+
The main query is a SPARQL CONSTRUCT query. Its generation is handled by the
+method GravsearchMainQueryGenerator.createMainQuery.
+It takes three arguments:
+mainResourceIris: Set[IriRef], dependentResourceIris: Set[IriRef], valueObjectIris: Set[IRI].
+
These sets are constructed based on information about variables representing
+dependent resources and value objects in the prequery, which is provided by
+NonTriplestoreSpecificGravsearchToPrequeryTransformer:
From the given Iris, statements are
+generated that ask for complete information on exactly these resources and
+values. For any given resource Iri, only the values present in
+valueObjectIris are to be queried. This is achieved by using SPARQL's
+VALUES expression for the main resource and dependent resources as well as
+for values.
+
Processing the Main Query's results
+
To do the permission checking, the results of the main query are passed to
+ConstructResponseUtilV2.splitMainResourcesAndValueRdfData,
+which transforms a SparqlConstructResponse (a set of RDF triples)
+into a structure organized by main resource Iris. In this structure, dependent
+resources and values are nested and can be accessed via their main resource,
+and resources and values that the user does not have permission to see are
+filtered out. As a result, a page of results may contain fewer than the maximum
+allowed number of results per page, even if more pages of results are available.
+
MainQueryResultProcessor.getRequestedValuesFromResultsWithFullGraphPattern
+then filters out values that the user did not explicitly ask for in the input
+query.
+
Finally, ConstructResponseUtilV2.createApiResponse transforms the query
+results into an API response (a ReadResourcesSequenceV2). If the number
+of main resources found (even if filtered out because of permissions) is equal
+to the maximum allowed page size, the predicate
+knora-api:mayHaveMoreResults: true is included in the response.
+
Inference
+
Gravsearch queries support a subset of RDFS reasoning
+(see Inference in the API documentation on Gravsearch).
+This is implemented as follows:
+
To simulate RDF inference, the API expands all rdfs:subClassOf and rdfs:subPropertyOf statements
+using UNION statements for all subclasses and subproperties from the ontologies
+(equivalent to rdfs:subClassOf* and rdfs:subPropertyOf*).
+Similarly, the API replaces knora-api:standoffTagHasStartAncestor with knora-base:standoffTagHasStartParent*.
+
Optimisation of generated SPARQL
+
The triplestore-specific transformers in SparqlTransformer.scala can run optimisations on the generated SPARQL, in
+the method optimiseQueryPatterns inherited from WhereTransformer. For example, moveLuceneToBeginning moves
+Lucene queries to the beginning of the block in which they occur.
+
Query Optimization by Topological Sorting of Statements
+
In Jena Fuseki, the performance of a query highly depends on the order of the query statements.
+For example, a query such as the one below:
takes a very long time with Fuseki. The performance of this query can be improved
+by moving up the statements with literal objects that are not dependent on any other statement:
Since users cannot be expected to know about performance of triplestores in order to write efficient queries,
+an optimization method to automatically rearrange the statements of the given queries has been implemented.
+Upon receiving the Gravsearch query, the algorithm converts the query to a graph. For each statement pattern,
+the subject of the statement is the origin node, the predicate is a directed edge, and the object
+is the target node. For the query above, this conversion would result in the following graph:
The algorithm returns the nodes of the graph ordered in several layers, where the
+root element ?letter is in layer 0, [?date, ?person1, ?person2] are in layer 1, [?gnd1, ?gnd2] in layer 2, and the
+leaf nodes [(DE-588)118531379, (DE-588)118696149] are given in the last layer (i.e. layer 3).
+According to Kahn's algorithm, there are multiple valid permutations of the topological order. The graph in the example
+above has 24 valid permutations of topological order. Here are two of them (nodes are ordered from left to right with the
+highest order to the lowest):
From all valid topological orders, one is chosen based on certain criteria; for example, the leaf node should not
+belong to a statement that has predicate rdf:type, since that could match all resources of the specified type.
+Once the best order is chosen, it is used to re-arrange the query statements. Starting from the last leaf node, i.e.
+(DE-588)118696149, the method finds the statement pattern which has this node as its object, and brings this statement
+to the top of the query. This rearrangement continues so that the statements with the fewest dependencies on other
+statements are all brought to the top of the query. The resulting query is as follows:
Note that position of the FILTER statements does not play a significant role in the optimization.
+
If a Gravsearch query contains statements in UNION, OPTIONAL, MINUS, or FILTER NOT EXISTS, they are reordered
+by defining a graph per block. For example, consider the following query with UNION:
This would result in one graph per block of the UNION. Each graph is then sorted, and the statements of its
+block are rearranged according to the topological order of graph. This is the result:
The topological sorting algorithm can only be used for DAGs (directed acyclic graphs). However,
+a Gravsearch query can contains statements that result in a cyclic graph, e.g.:
Add any SPARQL templates you need to src/main/twirl/queries/sparql/v2,
+using the Twirl template
+engine.
+
Write Responder Request and Response Messages
+
Add a file to the org.knora.webapi.messages.v2.responder
+package, containing case classes for your responder's request and
+response messages. Add a trait that the responder's request messages
+extend. Each request message type should contain a UserADM.
+
Request and response messages should be designed following the patterns described
+in JSON-LD Parsing and Formatting. Each responder's
+request messages should extend a responder-specific trait, so that
+ResponderManager will know which responder to route those messages to.
+
Write a Responder
+
Write a Pekko actor class that extends org.knora.webapi.responders.Responder,
+and add it to the org.knora.webapi.responders.v2 package.
+
Give your responder a receive(msg: YourCustomType) method that handles each of your
+request message types by generating a Future containing a response message.
+
Add the path of your responder to the org.knora.webapi.responders package object,
+and add code to ResponderManager to instantiate the new responder. Then add a case to
+the receive method in ResponderManager, to match messages that extend your request
+message trait, and pass them to that responder's receive method.
+The responder's resulting Future must be passed to the ActorUtil.future2Message.
+See Error Handling for details.
+
Write a Route
+
Add a class to the org.knora.webapi.routing.v2 package for your
+route, using the Pekko HTTP Routing DSL.
+See the routes in that package for examples. Typically, each route
+route will construct a responder request message and pass it to
+RouteUtilV2.runRdfRouteWithFuture to handle the request.
+
Finally, add your route's knoraApiPath function to the apiRoutes member
+variable in KnoraService. Any exception thrown inside the route will
+be handled by the KnoraExceptionHandler, so that the correct client
+response (including the HTTP status code) will be returned.
Knora provides a utility object called JsonLDUtil, which wraps the
+titanium-json-ld Java library, and parses JSON-LD text to a
+Knora data structure called JsonLDDocument. These classes provide commonly needed
+functionality for extracting and validating data from JSON-LD documents, as well
+as for constructing new documents.
+
Parsing JSON-LD
+
A route that expects a JSON-LD request must first parse the JSON-LD using
+JsonLDUtil . For example, this is how ValuesRouteV2 parses a JSON-LD request to create a value:
This is done in a Future, because the processing of JSON-LD input
+could in itself involve sending messages to responders.
+
Each request message case class (in this case CreateValueRequestV2) has a companion object
+that implements the KnoraJsonLDRequestReaderV2 trait:
+
/**
+ * A trait for objects that can generate case class instances based on JSON-LD input.
+ *
+ * @tparam C the type of the case class that can be generated.
+ */
+traitKnoraJsonLDRequestReaderV2[C]{
+/**
+ * Converts JSON-LD input into a case class instance.
+ *
+ * @param jsonLDDocument the JSON-LD input.
+ * @param apiRequestID the UUID of the API request.
+ * @param requestingUser the user making the request.
+ * @param responderManager a reference to the responder manager.
+ * @param storeManager a reference to the store manager.
+ * @param settings the application settings.
+ * @param log a logging adapter.
+ * @param timeout a timeout for `ask` messages.
+ * @param executionContext an execution context for futures.
+ * @return a case class instance representing the input.
+ */
+deffromJsonLD(jsonLDDocument:JsonLDDocument,
+apiRequestID:UUID,
+requestingUser:UserADM,
+responderManager:ActorRef,
+storeManager:ActorRef,
+settings:KnoraSettingsImpl,
+log:LoggingAdapter)(implicittimeout:Timeout,executionContext:ExecutionContext):Future[C]
+}
+
+
This means that the companion object has a method fromJsonLD that takes a
+JsonLDDocument and returns an instance of the case class. The fromJsonLD method
+can use the functionality of the JsonLDDocument data structure for extracting
+and validating the content of the request. For example, JsonLDObject.requireStringWithValidation
+gets a required member of a JSON-LD object, and validates it using a function
+that is passed as an argument. Here is an example of getting and validating
+a SmartIri:
The validation function (in this case stringFormatter.toSmartIriWithErr) has to take
+two arguments: a string to be validated, and a function that that throws an exception
+if the string is invalid. The return value of requireStringWithValidation is the
+return value of the validation function, which in this case is a SmartIri. If
+the string is invalid, requireStringWithValidation throws BadRequestException.
+
It is also possible to get and validate an optional JSON-LD object member:
Here JsonLDObject.maybeStringWithValidation returns an Option that contains
+the return value of the validation function (DateEraV2.parse) if it was given,
+otherwise None.
+
Returning a JSON-LD Response
+
Each API response is represented by a message class that extends
+KnoraJsonLDResponseV2, which has a method toJsonLDDocument that specifies
+the target ontology schema. The implementation of this method constructs a JsonLDDocument,
+in which all object keys are full IRIs (no prefixes are used), but in which
+the JSON-LD context also specifies the prefixes that will be used when the
+document is returned to the client. The function JsonLDUtil.makeContext
+is a convenient way to construct the JSON-LD context.
+
Since toJsonLDDocument has to return an object that uses the specified
+ontology schema, the recommended design is to separate schema conversion as much
+as possible from JSON-LD generation. As a first step, schema conversion (or at the very
+least, the conversion of Knora type IRIs to the target schema) can be done via an
+implementation of KnoraReadV2:
+
/**
+ * A trait for read wrappers that can convert themselves to external schemas.
+ *
+ * @tparam C the type of the read wrapper that extends this trait.
+ */
+traitKnoraReadV2[C<:KnoraReadV2[C]]{
+this:C=>
+deftoOntologySchema(targetSchema:ApiV2Schema):C
+}
+
+
This means that the response message class has the method toOntologySchema, which returns
+a copy of the same message, with Knora type IRIs (and perhaps other content) adjusted
+for the target schema. (See Smart IRIs on how to convert Knora
+type IRIs to the target schema.)
+
The response message class could then have a private method called generateJsonLD, which
+generates a JsonLDDocument that has the correct structure for the target schema, like
+this:
Most routes complete by calling RouteUtilV2.runRdfRouteWithFuture, which calls
+the response message's toJsonLDDocument method. The runRdfRouteWithFuture function
+has a parameter that enables the route to select the schema that should be used in
+the response. It is up to each route to determine what the appropriate response schema
+should be. Some routes support only one response schema. Others allow the client
+to choose. To use the schema requested by the client, the route can call
+RouteUtilV2.getOntologySchema:
RouteUtilV2.runRdfRouteWithFuture implements
+HTTP content negotiation. After
+determining the client's preferred format, it asks the KnoraResponseV2 to convert
+itself into that format. KnoraResponseV2 has an abstract format method, whose implementations
+select the most efficient conversion between the response message's internal
+representation (which could be JSON-LD or Turtle) and the requested format.
The core of Knora's ontology management logic is OntologyResponderV2.
+It is responsible for:
+
+
Loading ontologies from the triplestore when Knora starts.
+
Maintaining an ontology cache to improve performance.
+
Returning requested ontology entities from the cache. Requests for ontology
+ information never access the triplestore.
+
Creating and updating ontologies in response to API requests.
+
Ensuring that all user-created ontologies are consistent and conform to knora-base.
+
+
When Knora starts it will load all ontologies from the triplestore into the ontology cache:
+
+
Loads all ontologies found in the triplestore into suitable Scala data structures,
+ which include indexes of relations between entities (e.g. rdfs:subClassOf relations),
+ to facilitate validity checks.
The ontology responder assumes that nothing except itself modifies ontologies
+in the triplestore while Knora is running. Therefore, the ontology cache is updated
+only when the ontology responder processes a request to update an ontology.
+
By design, the ontology responder can update only one ontology entity per request,
+to simplify the necessary validity checks. This requires the client to
+construct an ontology by submitting a sequence of requests in a certain order,
+as explained in
+Ontology Updates.
+
The ontology responder mainly works with ontologies in the internal schema.
+However, it knows that some entities in built-in ontologies have hard-coded
+definitions in external schemas, and it checks the relevant
+transformation rules and returns those entities directly when they are requested
+(see Generation of Ontologies in External Schemas).
As explained in API Schema,
+Knora can represent the same RDF data in different forms: an "internal schema"
+for use in the triplestore, and different "external schemas" for use in Knora
+API v2. Different schemas use different IRIs, as explained in
+Knora IRIs. Internally,
+Knora uses a SmartIri class to convert IRIs between
+schemas.
+
The data type representing a schema itself is OntologySchema, which
+uses the sealed trait
+pattern:
+
packageorg.knora.webapi
+
+/**
+ * Indicates the schema that a Knora ontology or ontology entity conforms to.
+ */
+sealedtraitOntologySchema
+
+/**
+ * The schema of DSP ontologies and entities that are used in the triplestore.
+ */
+caseobjectInternalSchemaextendsOntologySchema
+
+/**
+ * The schema of DSP ontologies and entities that are used in API v2.
+ */
+sealedtraitApiV2SchemaextendsOntologySchema
+
+/**
+ * The simple schema for representing DSP ontologies and entities. This schema represents values as literals
+ * when possible.
+ */
+caseobjectApiV2SimpleextendsApiV2Schema
+
+/**
+ * The default (or complex) schema for representing DSP ontologies and entities. This
+ * schema always represents values as objects.
+ */
+caseobjectApiV2ComplexextendsApiV2Schema
+
+/**
+ * A trait representing options that can be submitted to configure an ontology schema.
+ */
+sealedtraitSchemaOption
+
+/**
+ * A trait representing options that affect the rendering of markup when text values are returned.
+ */
+sealedtraitMarkupRenderingextendsSchemaOption
+
+/**
+ * Indicates that markup should be rendered as XML when text values are returned.
+ */
+caseobjectMarkupAsXmlextendsMarkupRendering
+
+/**
+ * Indicates that markup should not be returned with text values, because it will be requested
+ * separately as standoff.
+ */
+caseobjectMarkupAsStandoffextendsMarkupRendering
+
+/**
+ * Indicates that no markup should be returned with text values. Used only internally.
+ */
+caseobjectNoMarkupextendsMarkupRendering
+
+/**
+ * Utility functions for working with schema options.
+ */
+objectSchemaOptions{
+/**
+ * A set of schema options for querying all standoff markup along with text values.
+ */
+valForStandoffWithTextValues:Set[SchemaOption]=Set(MarkupAsXml)
+
+/**
+ * A set of schema options for querying standoff markup separately from text values.
+ */
+valForStandoffSeparateFromTextValues:Set[SchemaOption]=Set(MarkupAsStandoff)
+
+/**
+ * Determines whether standoff should be queried when a text value is queried.
+ *
+ * @param targetSchema the target API schema.
+ * @param schemaOptions the schema options submitted with the request.
+ * @return `true` if standoff should be queried.
+ */
+defqueryStandoffWithTextValues(targetSchema:ApiV2Schema,schemaOptions:Set[SchemaOption]):Boolean={
+targetSchema==ApiV2Complex&&!schemaOptions.contains(MarkupAsStandoff)
+}
+
+/**
+ * Determines whether markup should be rendered as XML.
+ *
+ * @param targetSchema the target API schema.
+ * @param schemaOptions the schema options submitted with the request.
+ * @return `true` if markup should be rendered as XML.
+ */
+defrenderMarkupAsXml(targetSchema:ApiV2Schema,schemaOptions:Set[SchemaOption]):Boolean={
+targetSchema==ApiV2Complex&&!schemaOptions.contains(MarkupAsStandoff)
+}
+
+/**
+ * Determines whether markup should be rendered as standoff, separately from text values.
+ *
+ * @param targetSchema the target API schema.
+ * @param schemaOptions the schema options submitted with the request.
+ * @return `true` if markup should be rendered as standoff.
+ */
+defrenderMarkupAsStandoff(targetSchema:ApiV2Schema,schemaOptions:Set[SchemaOption]):Boolean={
+targetSchema==ApiV2Complex&&schemaOptions.contains(MarkupAsStandoff)
+}
+}
+
+
This class hierarchy allows method declarations to restrict the schemas
+they accept. A method that can accept any schema can take a parameter of type
+OntologySchema, while a method that accepts only external schemas can take
+a parameter of type ApiV2Schema. For examples, see Content Wrappers.
+
Generation of Ontologies in External Schemas
+
Ontologies are stored only in the internal schema, and are converted on the fly
+to external schemas. For each external schema, there is a Scala object in
+org.knora.webapi.messages.v2.responder.ontologymessages that provides rules
+for this conversion:
+
+
KnoraApiV2SimpleTransformationRules for the API v2 simple schema
+
KnoraApiV2WithValueObjectsTransformationRules for the API v2 complex schema
+
+
Since these are Scala objects rather than classes, they are initialised before
+the Akka ActorSystem starts, and therefore need a special instance of
+Knora's StringFormatter class (see Smart IRIs).
+
Each of these rule objects implements this trait:
+
/**
+ * A trait for objects that provide rules for converting an ontology from the internal schema to an external schema.
+ * * See also [[OntologyConstants.CorrespondingIris]].
+ */
+traitOntologyTransformationRules{
+/**
+ * The metadata to be used for the transformed ontology.
+ */
+valontologyMetadata:OntologyMetadataV2
+
+/**
+ * Properties to remove from the ontology before converting it to the target schema.
+ * See also [[OntologyConstants.CorrespondingIris]].
+ */
+valinternalPropertiesToRemove:Set[SmartIri]
+
+/**
+ * Classes to remove from the ontology before converting it to the target schema.
+ */
+valinternalClassesToRemove:Set[SmartIri]
+
+/**
+ * After the ontology has been converted to the target schema, these cardinalities must be
+ * added to the specified classes.
+ */
+valexternalCardinalitiesToAdd:Map[SmartIri,Map[SmartIri,KnoraCardinalityInfo]]
+
+/**
+ * Classes that need to be added to the ontology after converting it to the target schema.
+ */
+valexternalClassesToAdd:Map[SmartIri,ReadClassInfoV2]
+
+/**
+ * Properties that need to be added to the ontology after converting it to the target schema.
+ * See also [[OntologyConstants.CorrespondingIris]].
+ */
+valexternalPropertiesToAdd:Map[SmartIri,ReadPropertyInfoV2]
+}
+
+
These rules are applied to knora-base as well as to user-created ontologies.
+For example, knora-base:Resource has different cardinalities depending on its
+schema (knora-api:Resource has an additional cardinality on knora-api:hasIncomingLink),
+and this is therefore also true of its user-created subclasses. The transformation
+is implemented:
+
+
In the implementations of the toOntologySchema method in classes defined in
+ OntologyMessagesV2.scala: ReadOntologyV2, ReadClassInfoV2, ClassInfoContentV2,
+ PropertyInfoContentV2, and OntologyMetadataV2.
+
In OntologyResponderV2.getEntityInfoResponseV2, which handles requests for
+ specific ontology entities. If the requested entity is hard-coded in a transformation
+ rule, this method returns the hard-coded external entity, otherwise it returns the relevant
+ internal entity.
DSP-API v2 requests and responses are RDF documents. Any API v2
+ response can be returned as JSON-LD,
+ Turtle,
+ or RDF/XML.
+
Each class or property used in a request or response has a definition in an ontology, which Knora can serve.
+
Response formats are reused for different requests whenever
+ possible, to minimise the number of different response formats a
+ client has to handle. For example, any request for one or more
+ resources (such as a search result, or a request for one specific
+ resource) returns a response in the same format.
+
Response size is limited by design. Large amounts of data must be
+ retrieved by requesting small pages of data, one after the other.
+
Responses that provide data are distinct from responses that provide
+ definitions (i.e. ontology entities). Data responses indicate which
+ types are used, and the client can request information about these
+ types separately.
+
+
API Schemas
+
The types used in the triplestore are not exposed directly in the API.
+Instead, they are mapped onto API 'schemas'. Two schemas are currently
+provided.
+
+
A complex schema, which is suitable both for reading and for editing
+ data. The complex schema represents values primarily as complex objects.
+
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.
+
+
Each schema has its own type IRIs, which are derived from the ones used
+in the triplestore. For details of these different IRI formats, see
+Knora IRIs.
+
Implementation
+
JSON-LD Parsing and Formatting
+
Each API response is represented by a class that extends
+KnoraResponseV2, which has a method toJsonLDDocument that specifies
+the target schema. It is currently up to each route to determine what
+the appropriate response schema should be. Some routes will support only
+one response schema. Others will allow the client to choose, and there
+will be one or more standard ways for the client to specify the desired
+response schema.
+
A route calls RouteUtilV2.runRdfRoute, passing a request message and
+a response schema. When RouteUtilV2 gets the response message from the
+responder, it calls toJsonLDDocument on it, specifying that schema.
+The response message returns a JsonLDDocument, which is a simple data
+structure that is then converted to Java objects and passed to the
+JSON-LD Java library for formatting. In general, toJsonLDDocument is
+implemented in two stages: first the object converts itself to the
+target schema, and then the resulting object is converted to a
+JsonLDDocument.
+
A route that receives JSON-LD requests should use
+JsonLDUtil.parseJsonLD to convert each request to a JsonLDDocument.
Whenever possible, the same data structures are used for input and
+output. Often more data is available in output than in input. For
+example, when a value is read from the triplestore, its IRI is
+available, but when it is being created, it does not yet have an IRI. In
+such cases, there is a class like ValueContentV2, which represents the
+data that is used both for input and for output. When a value is read, a
+ValueContentV2 is wrapped in a ReadValueV2, which additionally
+contains the value's IRI. When a value is created, it is wrapped in a
+CreateValueV2, which has the resource IRI and the property IRI, but
+not the value IRI.
+
A Read* wrapper can be wrapped in another Read* wrapper; for
+example, a ReadResourceV2 contains ReadValueV2 objects.
+
Each *Content* class should extend KnoraContentV2 and thus have a
+toOntologySchema method or converting itself between internal and
+external schemas, in either direction.
+
Each Read* wrapper class should have a method for converting itself to
+JSON-LD in a particular external schema. If the Read* wrapper is a
+KnoraResponseV2, this method is toJsonLDDocument.
+
Smart IRIs
+
Usage
+
The SmartIri trait can be used to parse and validate IRIs, and in
+particular for converting Knora type IRIs between internal and external
+schemas. It validates each IRI it parses. To use it, import the
+following:
You can then use methods such as SmartIri.isKnoraApiV2EntityIri and
+SmartIri.getProjectCode to obtain information about the IRI. To
+convert it to another schema, call SmartIri.toOntologySchema.
+Converting a non-Knora IRI returns the same IRI.
+
If the IRI represents a Knora internal value class such as
+knora-base:TextValue, converting it to the ApiV2Simple schema will
+return the corresponding simplified type, such as xsd:string. But this
+conversion is not performed in the other direction (external to
+internal), since this would require knowledge of the context in which
+the IRI is being used.
+
The performance penalty for using a SmartIri instead of a string is
+very small. Instances are automatically cached once they are
+constructed. Parsing and caching a SmartIri instance takes about 10-20
+µs, and retrieving a cached SmartIri takes about 1 µs.
+
There is no advantage to using SmartIri for data IRIs, since they are
+not schema-specific (and are not cached). If a data IRI has been
+received from a client request, it is better just to validate it using
+StringFormatter.validateAndEscapeIri.
+
Smart IRI Implementation
+
The smart IRI implementation, SmartIriImpl, is nested in the
+StringFormatter class, because it uses Knora's
+hostname, which isn't available until the Akka ActorSystem has started.
+However, this means that the type of a SmartIriImpl instance is
+dependent on the instance of StringFormatter that constructed it.
+Therefore, instances of SmartIriImpl created by different instances of
+StringFormatter can't be compared directly.
+
There are in fact two instances of StringFormatter:
+
+
one returned by StringFormatter.getGeneralInstance which is
+ available after Akka has started and has the API server's hostname
+ (and can therefore provide SmartIri instances capable of parsing
+ IRIs containing that hostname). This instance is used throughout the
+ DSP-API server.
+
one returned by StringFormatter.getInstanceForConstantOntologies,
+ which is available before Akka has started, and is used only by the
+ hard-coded constant knora-api ontologies.
+
+
This is the reason for the existence of the SmartIri trait, which is a
+top-level definition and has its own equals and hashCode methods.
+Instances of SmartIri can thus be compared (e.g. to use them as unique
+keys in collections), regardless of which instance of StringFormatter
+created them.
DSP-API does not require the triplestore to perform inference,
+as different triplestores implement inference quite differently,
+so that taking advantage of inference would require triplestore specific code, which is not well maintainable.
+Instead, the API simulates inference for each Gravsearch query, so that the expected results are returned.
+
Gravsearch queries currently need to do the following:
+
+
Given a base property, find triples using a subproperty as predicate, and
+ return the subproperty used in each case.
+
Given a base class, find triples using an instance of subclass as subject or
+ object, and return the subclass used in each case.
+
+
Without inference, this can be done using property path syntax.
Checks that the queried resource belongs to a subclass of knora-base:Resource.
+
+
+
Returns the class that the resource explicitly belongs to.
+
+
+
Finds the Knora values attached to the resource, and returns each value along with
+ the property that explicitly attaches it to the resource.
+
+
+
However, such a query is very inefficient.
+Instead, the API does inference on the query, so that the relevant information can be found in a timely manner.
+
For this, the query is analyzed to check which project ontologies are relevant to the query.
+If an ontology is not relevant to a query,
+then all class and property definitions of this ontology are disregarded for inference.
+
Then, each statement that requires inference (i.e. that could be phrased with property path syntax, as described above)
+is cross-referenced with the relevant ontologies,
+to see which property/class definitions would fit the statement according to the rules of RDF inference.
+And each of those definitions is added to the query as a separate UNION statement.
+
E.g.: Given the resource class B is a subclass of A and the property hasY is a subproperty of hasX,
+then the following query
Value versions are a linked list, starting with the current version. Each value points to
+the previous version via knora-base:previousValue. The resource points only to the current
+version.
+
Past value versions are queried in getResourcePropertiesAndValues.scala.txt, which can
+take a timestamp argument. Given the current value version, we must find the most recent
+past version that existed at the target date.
+
First, we get the set of previous values that were created on or before the target
+date:
The resulting versions are now possible values of ?valueObject. Next, out of this set
+of versions, we exclude all versions except for the most recent one. We do this by checking,
+for each ?valueObject, whether there is another version, ?otherValueObject, that is more
+recent and was also created before the target date. If such a version exists, we exclude
+the one we are looking at.
The DSP-API specific configuration and scripts for Sipi are in the
+sipi subdirectory of the DSP-API source tree. See the README.md for
+instructions on how to start Sipi with DSP-API.
+
Lua Scripts
+
DSP-API v2 uses custom Lua scripts to control Sipi. These scripts can be
+found in sipi/scripts in the DSP-API source tree.
+
Each of these scripts expects a JSON Web Token in the
+URL parameter token. In all cases, the token must be signed by DSP-API,
+it must have an expiration date and not have expired, its issuer must equal
+the hostname and port of the API, and its audience must include Sipi.
+The other contents of the expected tokens are described below.
+
upload.lua
+
The upload.lua script is available at Sipi's upload route. It processes one
+or more file uploads submitted to Sipi. It converts uploaded images to JPEG 2000
+format, and stores them in Sipi's tmp directory. The usage of this script is described in
+Upload Files to Sipi.
+
upload_without_processing.lua
+
The upload_without_processing.lua script is available at Sipi's upload_without_processing route.
+It receives files submitted to Sipi but does not process them.
+Instead, it stores them as is in Sipi's tmp directory.
+
store.lua
+
The store.lua script is available at Sipi's store route. It moves a file
+from temporary to permanent storage. It expects an HTTP POST request containing
+application/x-www-form-urlencoded data with the parameters prefix (the
+project shortcode) and filename (the internal Sipi-generated filename of the file
+to be moved).
+
The JWT sent to this script must contain the key knora-data, whose value
+must be a JSON object containing:
+
+
permission: must be StoreFile
+
prefix: the project shortcode submitted in the form data
+
filename: the filename submitted in the form data
+
+
delete_temp_file.lua
+
The delete_temp_file.lua script is available at Sipi's delete_temp_file route.
+It is used only if DSP-API rejects a file value update request. It expects an
+HTTP DELETE request, with a filename as the last component of the URL.
+
The JWT sent to this script must contain the key knora-data, whose value
+must be a JSON object containing:
+
+
permission: must be DeleteTempFile
+
filename: must be the same as the filename submitted in the URL
+
+
clean_temp_dir.lua
+
The clean_temp_dir.lua script is available at Sipi's clean_temp_dir route.
+When called, it deletes old temporary files from tmp and (recursively) from any subdirectories.
+The maximum allowed age of temporary files can be set in Sipi's configuration file,
+using the parameter max_temp_file_age, which takes a value in seconds.
+
The clean_temp_dir route requires basic authentication.
+
SipiConnector
+
In DSP-API, the org.knora.webapi.iiif.SipiConnector handles all communication
+with Sipi. It blocks while processing each request, to ensure that the number of
+concurrent requests to Sipi is not greater than
+akka.actor.deployment./storeManager/iiifManager/sipiConnector.nr-of-instances.
+If it encounters an error, it returns SipiException.
+
The Image File Upload Workflow
+
+
The client uploads an image file to the upload route, which runs
+ upload.lua. The image is converted to JPEG 2000 and stored in Sipi's tmp
+ directory. In the response, the client receives the JPEG 2000's unique,
+ randomly generated filename.
+
The client submits a JSON-LD request to a DSP-API route (/v2/values or /v2/resources)
+ to create or change a file value. The request includes Sipi's internal filename.
+
During parsing of this JSON-LD request, a StillImageFileValueContentV2
+ is constructed to represent the file value. During the construction of this
+ object, a GetFileMetadataRequestV2 is sent to SipiConnector, which
+ uses Sipi's built-in knora.json route to get the rest of the file's
+ metadata.
+
A responder (ResourcesResponderV2 or ValuesResponderV2) validates
+ the request and updates the triplestore. (If it is ResourcesResponderV2,
+ it asks ValuesResponderV2 to generate SPARQL for the values.)
+
The responder that did the update calls ValueUtilV2.doSipiPostUpdate.
+ If the triplestore update was successful, this method sends
+ MoveTemporaryFileToPermanentStorageRequestV2 to SipiConnector, which
+ makes a request to Sipi's store route. Otherwise, the same method sends
+ DeleteTemporaryFileRequestV2 to SipiConnector, which makes a request
+ to Sipi's delete_temp_file route.
+
+
If the request to DSP-API cannot be parsed, the temporary file is not deleted
+immediately, but it will be deleted during the processing of a subsequent
+request by Sipi's upload route.
+
If Sipi's store route fails, DSP-API returns the SipiException to the client.
+In this case, manual intervention may be necessary to restore consistency
+between DSP-API and Sipi.
+
If Sipi's delete_temp_file route fails, the error is not returned to the client,
+because there is already a DSP-API error that needs to be returned to the client.
+In this case, the Sipi error is simply logged.
The SmartIri trait can be used to parse and validate IRIs, and in
+particular for converting Knora type IRIs
+between internal and external schemas. It validates each IRI it parses. To use it,
+import the following:
Then, if you have a string representing an IRI, you can can convert
+it to a SmartIri like this:
+
valpropertyIri:SmartIri="http://0.0.0.0:3333/ontology/0001/anything/v2#hasInteger".toSmartIri
+````
+
+If the IRI came from a request, use this method to throw a specific
+exception if the IRI is invalid:
+
+```scala
+valpropertyIri:SmartIri=propertyIriStr.toSmartIriWithErr(throwBadRequestException(s"Invalid property IRI: <$propertyIriStr>"))
+
+
You can then use methods such as SmartIri.isKnoraApiV2EntityIri and
+SmartIri.getProjectCode to obtain information about the IRI. To
+convert it to another schema, call SmartIri.toOntologySchema.
+Converting a non-Knora IRI returns the same IRI.
+
If the IRI represents a Knora internal value class such as
+knora-base:TextValue, converting it to the ApiV2Simple schema will
+return the corresponding simplified type, such as xsd:string. But this
+conversion is not performed in the other direction (external to
+internal), since this would require knowledge of the context in which
+the IRI is being used.
+
The performance penalty for using a SmartIri instead of a string is
+very small. Instances are automatically cached once they are
+constructed.
+
There is no advantage to using SmartIri for data IRIs, since they are
+not schema-specific (and are not cached). If a data IRI has been
+received from a client request, it is better just to validate it using
+StringFormatter.validateAndEscapeIri, and represent it as an
+org.knora.webapi.IRI (an alias for String).
+
Implementation
+
The smart IRI implementation, SmartIriImpl, is nested in the
+StringFormatter class, because it uses Knora's
+hostname, which isn't available until the Akka ActorSystem has started.
+However, this means that the Scala type of a SmartIriImpl instance is
+dependent on the instance of StringFormatter that constructed it.
+Therefore, instances of SmartIriImpl created by different instances of
+StringFormatter can't be compared directly.
+
There are in fact two instances of StringFormatter:
+
+
one returned by StringFormatter.getGeneralInstance, which is
+ available after Akka has started and has the API server's hostname
+ (and can therefore provide SmartIri instances capable of parsing
+ IRIs containing that hostname). This instance is used throughout the
+ DSP-API server.
+
one returned by StringFormatter.getInstanceForConstantOntologies,
+ which is available before Akka has started, and is used only by the
+ hard-coded constant knora-api ontologies (see
+ Generation of Ontologies in External Schemas).
+
+
This is the reason for the existence of the SmartIri trait, which is a
+top-level definition and has its own equals and hashCode methods.
+Instances of SmartIri can thus be compared (e.g. to use them as unique
+keys in collections), regardless of which instance of StringFormatter
+created them.
Markup should be stored as RDF, so it can be searched and analysed using the same tools that are used
+ with other data managed by Knora.
+
+
+
In particular, Gravsearch queries should be able
+ to specify search criteria that refer to the markup tags attached to a text, together with
+ any other search criteria relating to the resource that contains the text.
+
+
+
It should be possible to import any XML document into Knora, store the markup as standoff, and
+ at any time export the document as an equivalent XML document.
Since the number of standoff tags that can be attached to a text value is unlimited, standoff is queried
+in pages of a limited size, to avoid requesting huge SPARQL query results from the triplestore.
+
When ResourcesResponderV2 or SearchResponderV2 need to return a text value with all its markup,
+they first query the text value with at most one page of standoff. If the text value has more than one page of
+standoff, ConstructResponseUtilV2.makeTextValueContentV2 then sends a GetRemainingStandoffFromTextValueRequestV2
+message to StandoffResponderV2, which queries the rest of the standoff in the text value, one page at a time.
+The resulting standoff is concatenated together and returned.
+
To optimise query performance:
+
+
+
Each text value with standoff has the predicate knora-base:valueHasMaxStandoffStartIndex, so that when Knora
+ queries a page of standoff, it knows whether it has reached the last page.
+
+
+
The last path component of the IRI of a standoff tag is the integer object of its
+ knora-base:standoffTagHasStartIndex predicate. When querying standoff, it is necessary to convert
+ the IRI objects of knora-base:standoffTagHasStartParent and knora-base:standoffTagHasEndParent to
+ integer indexes (the start indexes of those tags). Including each tag's start index in its IRI makes it
+ unnecessary to query the parent tags to determine their start indexes.
+
+
+
Conversion Between Standoff and XML
+
XMLToStandoffUtil does the low-level conversion of documents between standoff and XML, using a simple
+data structure to represent standoff. This data structure knows nothing about RDF, and each standoff tag
+contains its XML element name and namespace and those of its attributes.
+
In DSP-API, it is possible to define mappings to
+control how standoff/RDF is converted to XML and vice versa. Different mappings can be used to convert the same
+standoff/RDF to different sorts of XML documents. StandoffTagUtilV2 converts between standoff/RDF and XML using
+mappings, delegating the lower-level work to XMLToStandoffUtil.
While knora-admin and salsah-gui have relatively flat class hierarchies,
+in knora-base there are very complicated - yet highly relevant - inheritance structures.
+The following class diagrams try to model these structures.
+For the sake of comprehensibility, it was necessary to split the ontology into multiple diagrams,
+even though this obliterates the evident connections between those diagrams.
+
+
Legend
+
dotted lines: the boxes are copies from another diagram.
In the context of DEV-1415: Domain Model
+we attempted to gain a clear overview over the DSP's domain,
+as implicitly modelled by the ontologies, code, validations and documentation of the DSP-API.
+
The following document aims to give a higher level overview of said domain.
+
+
Note
+
+
As a high level overview, this document does not aim for exhaustivity.
+
Naming is tried to be kept as simple as possible,
+ while trying to consolidate different naming schemes
+ (ontologies, code, API),
+ which in result means that no naming scheme is strictly followed.
+
The split between V2 and Admin is arbitrary as those are intertwined within the system.
+ It merely serves the purpose of organizing the presented entities.
+
+
+
Domain Entities
+
The following Diagrams visualize the top level entities present in the DSP.
+The attributes of these entities should be exhaustive.
+Cardinalities or validation constraints are normally not depicted.
+The indicated relationships are of conceptual nature and are more complicated in the actual system.
+
Admin
+
erDiagram
+ %% entities
+ User {
+ IRI id
+ string userName "unique"
+ string email "unique"
+ string givenName
+ string familyName
+ string password
+ string language "2 character ISO language code"
+ boolean status
+ boolean systemAdmin
+ }
+ Project {
+ IRI id
+ string shortcode "4 character hex"
+ string shortname "xsd:NCNAME"
+ string longname "optional"
+ langstring description
+ string keywords
+ boolean status
+ boolean selfjoin
+ string logo "optional"
+ string restrictedViewSize
+ string restrictedViewWatermark
+ }
+ Group {
+ IRI id
+ string name
+ langstring description
+ boolean status
+ boolean selfjoin
+ }
+ ListNode {
+ IRI id
+ IRI projectIri "only for root node"
+ langstring labels
+ langstring comments
+ string name
+ boolean isRootNode
+ integer listNodePosition
+ }
+ DefaultObjectAccessPermission {
+ IRI id
+ string hasPermission "the 'RV, V, M, D, CR' string"
+ }
+ AdministrativePermission {
+ IRI id
+ string hasPermission "a different string representation"
+ }
+ Property {}
+ ResourceClass {}
+
+ %% relations
+ User }|--|{ Project: "is member/admin of"
+ User }o--|{ Group: "is member of"
+ Group }o--|| Project: "belongs to"
+ ListNode }o--|| Project: "belongs to"
+ ListNode }o--o{ ListNode: "hasSubListNode"
+ ListNode |o--o| ListNode: "hasRootNode"
+ AdministrativePermission |{--o| Project: "points to"
+ AdministrativePermission |{--|{ Group: "points to"
+
+ DefaultObjectAccessPermission |{--o{ Group: "points to"
+ DefaultObjectAccessPermission |{--|| Project: "points to"
+ DefaultObjectAccessPermission |{--o{ Property: "points to"
+ DefaultObjectAccessPermission |{--o{ ResourceClass: "points to"
+
Apart from class and property definitions,
+knora-base and knora-admin provide a small number of class instances
+that should be present in any running DSP stack:
Authentication is the process of making sure that if someone is
+accessing something then this someone is actually also the person they
+pretend to be. The process of making sure that someone is authorized,
+(i.e. has the permission to access something, is handled as described
+in Authorisation).
+
Implementation
+
The authentication in Knora is based on Basic Auth HTTP basic
+authentication,
+URL parameters, JSON Web Token, and cookies. This means
+that on every request (to any of the routes), credentials need to be
+sent either via authorization header, URL parameters or cookie header.
+
All routes are always accessible and if there are no credentials
+provided, a default user is assumed. If credentials are sent and they
+are not correct (e.g., wrong username, password incorrect, token
+expired), then the request will end in an error message.
+
Skipping Authentication
+
There is the possibility to turn skipping authentication on and use a
+hardcoded user (Test User). In application.conf set the
+skip-authentication = true and Test User will be always assumed.
Attention! GraphDB is not supported anymore, therefore parts related
+to it in this document are redundant.
+
Requirements
+
Knora is designed to prevent inconsistencies in RDF data,
+as far as is practical, in a triplestore-independent way (see
+Triplestore Updates). However, it is also
+useful to enforce consistency constraints in the triplestore itself, for
+two reasons:
+
+
To prevent inconsistencies resulting from bugs in the DSP-API server.
+
To prevent users from inserting inconsistent data directly into the triplestore, bypassing Knora.
+
+
The design of the knora-base ontology supports two ways of specifying
+constraints on data (see knora-base: Consistency Checking
+for details):
+
+
A property definition should specify the types that are allowed as
+ subjects and objects of the property, using
+ knora-base:subjectClassConstraint and (if it is an object
+ property) knora-base:objectClassConstraint. Every subproperty of
+ knora-base:hasValue or a knora-base:hasLinkTo (i.e. every
+ property of a resource that points to a knora-base:Value or to
+ another resource) is required have this constraint, because the
+ DSP-API server relies on it to know what type of object to expect
+ for the property. Use of knora-base:subjectClassConstraint is
+ recommended but not required.
+
A class definition should use OWL cardinalities
+ (see OWL 2 Quick Reference Guide)
+ to indicate the properties that instances of the class are allowed to
+ have, and to constrain the number of objects that each property can
+ have. Subclasses of knora-base:Resource are required to have a
+ cardinality for each subproperty of knora-base:hasValue or a
+ knora-base:hasLinkTo that resources of that class can have.
+
+
Specifically, consistency checking should prevent the following:
+
+
An object property or datatype property has a subject of the wrong
+ class, or an object property has an object of the wrong class
+ (GraphDB's consistency checke cannot check the types of literals).
+
An object property has an object that does not exist (i.e. the
+ object is an IRI that is not used as the subject of any statements
+ in the repository). This can be treated as if the object is of the
+ wrong type (i.e. it can cause a violation of
+ knora-base:objectClassConstraint, because there is no compatible
+ rdf:type statement for the object).
+
A class has owl:cardinality 1 or owl:minCardinality 1 on an
+ object property or datatype property, and an instance of the class
+ does not have that property.
+
A class has owl:cardinality 1 or owl:maxCardinality 1 on an
+ object property or datatype property, and an instance of the class
+ has more than one object for that property.
+
An instance of knora-base:Resource has an object property pointing
+ to a knora-base:Value or to another Resource, and its class has
+ no cardinality for that property.
+
An instance of knora-base:Value has a subproperty of
+ knora-base:valueHas, and its class has no cardinality for that
+ property.
+
A datatype property has an empty string as an object.
+
+
Cardinalities in base classes are inherited by derived classes. Derived
+classes can override inherited cardinalities by making them more
+restrictive, i.e. by specifying a subproperty of the one specified in
+the original cardinality.
+
Instances of Resource and Value can be marked as deleted, using the
+property isDeleted. This must be taken into account as follows:
+
+
With owl:cardinality 1 or owl:maxCardinality 1, if the object of
+ the property can be marked as deleted, the property must not have
+ more than one object that has not been marked as deleted. In other
+ words, it's OK if there is more than one object, as long only one of
+ them has knora-base:isDeleted false.
+
With owl:cardinality 1 or owl:minCardinality 1, the property
+ must have an object, but it's OK if the property's only object is
+ marked as deleted. We allow this because the subject and object may
+ have different owners, and it may not be feasible for them to
+ coordinate their work. The owner of the object should always be able
+ to mark it as deleted. (It could be useful to notify the owner of
+ the subject when this happens, but that is beyond the scope of
+ consistency checking.)
+
+
Design
+
Ontotext GraphDB provides a
+mechanism for checking the consistency of data in a repository each time
+an update transaction is committed. Knora provides GraphDB-specific
+consistency rules that take advantage of this feature to provide an
+extra layer of consistency checks, in addition to the checks that are
+implemented in Knora.
+
When a repository is created in GraphDB, a set of consistency rules can
+be provided, and GraphDB's consistency checker can be turned on to
+ensure that each update transaction respects these rules, as described
+in the section
+Reasoning
+of the GraphDB documentation. Like custom inference rules, consistency
+rules are defined in files with the .pie filename extension, in a
+GraphDB-specific syntax.
+
We have added rules to the standard RDFS inference rules file
+builtin_RdfsRules.pie, to create the file KnoraRules.pie. The .ttl
+configuration file that is used to create the repository must contain
+these settings:
The path to KnoraRules.pie must be an absolute path. The scripts
+provided with Knora to create test repositories set this path
+automatically.
+
Consistency checking in GraphDB relies on reasoning. GraphDB's reasoning
+is
+Forward-chaining,
+which means that reasoning is applied to the contents of each update,
+before the update transaction is committed, and the inferred statements
+are added to the repository.
+
A GraphDB rules file can contain two types of rules: inference rules and
+consistency rules. Before committing an update transaction, GraphDB
+applies inference rules, then consistency rules. If any of the
+consistency rules are violated, the transaction is rolled back.
The premises are a pattern that tries to match statements found in the
+data. Optional constraints, which are enclosed in square brackets, make
+it possible to specify the premises more precisely, or to specify a
+named graph (see examples below). Consequences are the statements that
+will be inferred if the premises match. A line of hyphens separates
+premises from consequences.
The differences between inference rules and consistency rules are:
+
+
A consistency rule begins with Consistency instead of Id.
+
In a consistency rule, the consequences are optional. Instead of
+ representing statements to be inferred, they represent statements
+ that must exist if the premises are satisfied. In other words, if
+ the premises are satisfied and the consequences are not found, the
+ rule is violated.
+
If a consistency rule doesn't specify any consequences, and the
+ premises are satisfied, the rule is violated.
+
+
Rules use variable names for subjects, predicates, and objects, and they
+can use actual property names.
+
Empty string as object
+
If subject i has a predicate p whose object is an empty string, the
+constraint is violated:
+
Consistency: empty_string
+ i p ""
+ ------------------------------------
+
+
Subject and object class constraints
+
If subject i has a predicate p that requires a subject of type t,
+and i is not a t, the constraint is violated:
+
Consistency: subject_class_constraint
+ p <knora-base:subjectClassConstraint> t
+ i p j
+ ------------------------------------
+ i <rdf:type> t
+
+
If subject i has a predicate p that requires an object of type t,
+and the object of p is not a t, the constraint is violated:
+
Consistency: object_class_constraint
+ p <knora-base:objectClassConstraint> t
+ i p j
+ ------------------------------------
+ j <rdf:type> t
+
+
Cardinality constraints
+
A simple implementation of a consistency rule to check
+owl:maxCardinality 1, for objects that can be marked as deleted, could
+look like this:
+
Consistency: max_cardinality_1_with_deletion_flag
+ i <rdf:type> r
+ r <owl:maxCardinality> "1"^^xsd:nonNegativeInteger
+ r <owl:onProperty> p
+ i p j
+ i p k [Constraint j != k]
+ j <knora-base:isDeleted> "false"^^xsd:boolean
+ k <knora-base:isDeleted> "false"^^xsd:boolean
+ ------------------------------------
+
+
This means: if resource i is a subclass of an owl:Restrictionr
+with owl:maxCardinality 1 on property p, and the resource has two
+different objects for that property, neither of which is marked as
+deleted, the rule is violated. Note that this takes advantage of the
+fact that Resource and Value have owl:cardinality 1 on isDeleted
+(isDeleted must be present even if false), so we do not need to check
+whether i is actually something that can be marked as deleted.
+
However, this implementation would be much too slow. We therefore use
+two optimisations suggested by Ontotext:
+
+
Add custom inference rules to make tables (i.e. named graphs) of
+ pre-calculated information about the cardinalities on properties of
+ subjects, and use those tables to simplify the consistency rules.
+
Use the [Cut] constraint to avoid generating certain redundant
+ compiled rules (see Entailment
+ rules).
+
+
For example, to construct a table of subjects belonging to classes that
+have owl:maxCardinality 1 on some property p, we use the following
+custom inference rule:
+
Id: maxCardinality_1_table
+ i <rdf:type> r
+ r <owl:maxCardinality> "1"^^xsd:nonNegativeInteger
+ r <owl:onProperty> p
+ ------------------------------------
+ i p r [Context <onto:_maxCardinality_1_table>]
+
+
The constraint [Context <onto:_maxCardinality_1_table>] means that the
+inferred triples are added to the context (i.e. the named graph)
+http://www.ontotext.com/_maxCardinality_1_table. (Note that we have
+defined the prefix onto as http://www.ontotext.com/ in the
+Prefices section of the rules file.) As the GraphDB documentation on
+Rules
+explains:
+
+
If the context is provided, the statements produced as rule
+consequences are not ‘visible’ during normal query answering. Instead,
+they can only be used as input to this or other rules and only when
+the rule premise explicitly uses the given context.
+
+
Now, to find out whether a subject belongs to a class with that
+cardinality on a given property, we only need to match one triple. The
+revised implementation of the rule
+max_cardinality_1_with_deletion_flag is as follows:
+
Consistency: max_cardinality_1_with_deletion_flag
+ i p r [Context <onto:_maxCardinality_1_table>]
+ i p j [Constraint j != k]
+ i p k [Cut]
+ j <knora-base:isDeleted> "false"^^xsd:boolean
+ k <knora-base:isDeleted> "false"^^xsd:boolean
+ ------------------------------------
+
+
The constraint [Constraint j != k] means that the premises will be
+satisfied only if the variables j and k do not refer to the same
+thing.
+
With these optimisations, the rule is faster by several orders of
+magnitude.
+
Since properties whose objects can be marked as deleted must be handled
+differently to properties whose objects cannot be marked as deleted, the
+knora-base ontology provides a property called
+objectCannotBeMarkedAsDeleted. All properties in knora-base whose
+objects cannot take the isDeleted flag (including datatype properties)
+should be derived from this property. This is how it is used to check
+owl:maxCardinality 1 for objects that cannot be marked as deleted:
+
Consistency: max_cardinality_1_without_deletion_flag
+ i p r [Context <onto:_maxCardinality_1_table>]
+ p <rdfs:subPropertyOf> <knora-base:objectCannotBeMarkedAsDeleted>
+ i p j [Constraint j != k]
+ i p k [Cut]
+ ------------------------------------
+
+
To check owl:minCardinality 1, we do not care whether the object can
+be marked as deleted, so we can use this simple rule:
+
Consistency: min_cardinality_1_any_object
+ i p r [Context <onto:_minCardinality_1_table>]
+ ------------------------------------
+ i p j
+
+
This means: if a subject i belongs to a class that has
+owl:minCardinality 1 on property p, and i has no object for p,
+the rule is violated.
+
To check owl:cardinality 1, we need two rules: one that checks whether
+there are too few objects, and one that checks whether there are too
+many. To check whether there are too few objects, we don't care whether
+the objects can be marked as deleted, so the rule is the same as
+min_cardinality_1_any_object, except for the cardinality:
+
Consistency: cardinality_1_not_less_any_object
+ i p r [Context <onto:_cardinality_1_table>]
+ ------------------------------------
+ i p j
+
+
To check whether there are too many objects, we need to know whether the
+objects can be marked as deleted or not. In the case where the objects
+can be marked as deleted, the rule is the same as
+max_cardinality_1_with_deletion_flag, except for the cardinality:
+
Consistency: cardinality_1_not_greater_with_deletion_flag
+ i p r [Context <onto:_cardinality_1_table>]
+ i p j [Constraint j != k]
+ i p k [Cut]
+ j <knora-base:isDeleted> "false"^^xsd:boolean
+ k <knora-base:isDeleted> "false"^^xsd:boolean
+ ------------------------------------
+
+
In the case where the objects cannot be marked as deleted, the rule is
+the same as max_cardinality_1_without_deletion_flag, except for the
+cardinality:
+
Consistency: cardinality_1_not_less_any_object
+ i p r [Context <onto:_cardinality_1_table>]
+ ------------------------------------
+ i p j
+
+
Knora allows a subproperty of knora-base:hasValue or
+knora-base:hasLinkTo to be a predicate of a resource only if the
+resource's class has some cardinality for the property. For convenience,
+knora-base:hasValue and knora-base:hasLinkTo are subproperties of
+knora-base:resourceProperty, which is used to check this constraint in
+the following rule:
+
Consistency: resource_prop_cardinality_any
+ i <knora-base:resourceProperty> j
+ ------------------------------------
+ i p j
+ i <rdf:type> r
+ r <owl:onProperty> p
+
+
If resource i has a subproperty of knora-base:resourceProperty, and
+i is not a member of a subclass of an owl:Restrictionr with a
+cardinality on that property (or on one of its base properties), the
+rule is violated.
+
A similar rule, value_prop_cardinality_any, ensures that if a value
+has a subproperty of knora-base:valueHas, the value's class has some
+cardinality for that property.
Creating, updating and deleting data models (ontologies)
+
Managing projects and users
+
Authentication of clients
+
Authorisation of clients' requests
+
+
DSP-API is developed with Scala and uses the
+Akka framework for message-based concurrency. It is
+designed to work with the Apache Jena Fuseki triplestore
+which is compliant to the SPARQL 1.1 Protocol.
+For file storage, it uses Sipi.
+
DSP-API Versions
+
+
DSP-API v2: the latest DSP-API that should be used.
+
DSP-API v1: has been removed after a long period of deprecation.
+
+
There is also an Admin API for administrating DSP projects.
+
Error Handling
+
The error-handling design has these aims:
+
+
Simplify the error-handling code in actors as much as possible.
+
Produce error messages that clearly indicate the context in which
+ the error occurred (i.e. what the application was trying to do).
+
Ensure that clients receive an appropriate error message when an
+ error occurs.
+
Ensure that ask requests are properly terminated with an
+ akka.actor.Status.Failure message in the event of an error,
+ without which they will simply time out (see
+ Ask: Send and Receive Future).
+
When a actor encounters an error that isn't the client's fault (e.g.
+ a triplestore failure), log it, but don't do this with errors caused
+ by bad input.
+
When logging errors, include the full JVM stack trace.
+
+
A hierarchy of exception classes is defined in Exceptions.scala,
+representing different sorts of errors that could occur. The hierarchy
+has two main branches:
+
+
RequestRejectedException, an abstract class for errors that are
+ the client's fault. These errors are not logged.
+
InternalServerException, an abstract class for errors that are not
+ the client's fault. These errors are logged.
+
+
Exception classes in this hierarchy can be defined to include a wrapped
+cause exception. When an exception is logged, its stack trace will be
+logged along with the stack trace of its cause. It is therefore
+recommended that low-level code should catch low-level exceptions, and
+wrap them in one of our higher-level exceptions, in order to clarify the
+context in which the error occurred.
+
To simplify error-handling in responders, a utility method called
+future2Message is provided in ActorUtils. It is intended to be used
+in an actor's receive method to respond to messages in the ask
+pattern. If the responder's computation is successful, it is sent to the
+requesting actor as a response to the ask. If the computation fails,
+the exception representing the failure is wrapped in a Status.Failure,
+which is sent as a response to the ask. If the error is a subclass of
+RequestRejectedException, only the sender is notified of the error;
+otherwise, the error is also logged and rethrown (so that the
+KnoraExceptionHandler can handle the exception).
+
In many cases, we transform data from the triplestore into a Map
+object. To simplify checking for required values in these collections,
+the class ErrorHandlingMap is provided. You can wrap any Map in an
+ErrorHandlingMap. You must provide a function that will generate an
+error message when a required value is missing, and optionally a
+function that throws a particular exception. Rows of SPARQL query
+results are already returned in ErrorHandlingMap objects.
+
If you want to add a new exception class, see the comments in
+Exceptions.scala for instructions.
+
Transformation of Exception to Client Responses
+
The org.knora.webapi.KnoraExceptionHandler is brought implicitly into
+scope of pekko-http, and by doing so registered and used to handle the
+transformation of all KnoraExceptions into HttpResponses. This
+handler handles only exceptions thrown inside the route and not the
+actors. However, the design of reply message passing from actors (by
+using future2Message), makes sure that any exceptions thrown inside
+actors, will reach the route, where they will be handled.
+
API Routing
+
The API routes in the routing package are defined using the DSL
+provided by the
+pekko-http
+library. A routing function has to do the following:
+
+
Authenticate the client.
+
Figure out what the client is asking for.
+
Construct an appropriate request message and send it to the appropriate responder.
+
Return a result to the client.
+
+
To simplify the coding of routing functions, they are contained in
+objects that extend org.knora.webapi.routing.Authenticator. Each
+routing function performs the following operations:
+
+
Authenticator.getUserADM is called to authenticate the user.
+
The request parameters are interpreted and validated, and a request
+ message is constructed to send to the responder. If the request is
+ invalid, BadRequestException is thrown. If the request message is
+ requesting an update operation, it must include a UUID generated by
+ UUID.randomUUID, so the responder can obtain a write lock on the
+ resource being updated.
+
+
The routing function then passes the message to a function in an API-specific
+routing utility: RouteUtilV2 or RouteUtilADM.
+This utility function sends the message to ResponderManager (which
+forwards it to the relevant responder), returns a response to the client
+in the appropriate format, and handles any errors.
+
Logging
+
Logging in DSP-API is configurable through logback.xml, allowing fine
+grain configuration of what classes / objects should be logged from which level.
+
The Akka Actors use Akka Logging
+while logging inside plain Scala Objects and Classes is done through
+Scala Logging.
DSP provides an API for parsing and formatting RDF data and
+for working with RDF graphs. This allows DSP developers to use a single,
+idiomatic Scala API as a façade for a Java RDF library.
+
Overview
+
The API is in the package org.knora.webapi.messages.util.rdf. It includes:
+
+
+
RdfModel, which represents a set of RDF graphs (a default graph and/or one or more named graphs).
+ A model can be constructed from scratch, modified, and searched.
+
+
+
RdfNode and its subclasses, which represent RDF nodes (IRIs, blank nodes, and literals).
+
+
+
Statement, which represents a triple or quad.
+
+
+
RdfNodeFactory, which creates nodes and statements.
+
+
+
RdfModelFactory, which creates empty RDF models.
+
+
+
RdfFormatUtil, which parses and formats RDF models.
+
+
+
JsonLDUtil, which provides specialised functionality for working
+ with RDF in JSON-LD format, and for converting between RDF models
+ and JSON-LD documents. RdfFormatUtil uses JsonLDUtil when appropriate.
+
+
+
ShaclValidator, which validates RDF models using SHACL shapes.
+
+
+
To work with RDF models, start with RdfFeatureFactory, which returns instances
+of RdfNodeFactory, RdfModelFactory, RdfFormatUtil, and ShaclValidator.
+JsonLDUtil does not need a feature factory.
+
To iterate efficiently over the statements in an RdfModel, use its iterator method.
+An RdfModel cannot be modified while you are iterating over it.
+If you are iterating to look for statements to modify, you can
+collect a Set of statements to remove and a Set of statements
+to add, and perform these update operations after you have finished
+the iteration.
+
RDF stream processing
+
To read or write a large amount of RDF data without generating a large string
+object, you can use the stream processing methods in RdfFormatUtil.
+
To parse an InputStream to an RdfModel, use inputStreamToRdfModel.
+To format an RdfModel to an OutputStream, use rdfModelToOutputStream.
+
To parse RDF data from an InputStream and process it one statement at a time,
+you can write a class that implements the RdfStreamProcessor trait, and
+use it with the RdfFormatUtil.parseWithStreamProcessor method.
+Your RdfStreamProcessor can also send one statement at a time to a
+formatting stream processor, which knows how to write RDF to an OutputStream
+in a particular format. Use RdfFormatUtil.makeFormattingStreamProcessor to
+construct one of these.
+
SPARQL queries
+
In tests, it can be useful to run SPARQL queries to check the content of
+an RdfModel. To do this, use the RdfModel.asRepository method, which
+returns an RdfRepository that can run SELECT queries.
+
The configuration of the default graph depends on which underlying
+RDF library is used. If you are querying data in named graphs, use FROM
+or quad patterns rather than the default graph.
+
SHACL validation
+
On startup, graphs of SHACL shapes are loaded from Turtle files in a directory specified
+by app.shacl.shapes-dir in application.conf, and in subdirectories of
+that directory. To validate the default graph of an RdfModel using a graph of
+SHACL shapes, call ShaclValidator.validate, specifying the relative path of the
+Turtle file containing the graph of shapes.
+
Implementations
+
+
+
The Jena-based implementation, in package org.knora.webapi.messages.util.rdf.jenaimpl.
+
+
+
The RDF4J-based implementation, in package org.knora.webapi.messages.util.rdf.rdf4jimpl.
GraphDB and embedded Jena TDB triplestores support is deprecated since
+v20.1.1 of DSP-API.
+
The store module houses the different types of data stores supported by
+Knora. At the moment, only triplestores and IIIF servers (Sipi) are supported.
+The triplestore support is implemented in the
+org.knora.webapi.store.triplestore package and the IIIF server support in
+org.knora.webapi.store.iiif package.
+
Lifecycle
+
At the top level, the store package houses the StoreManager-Actor
+which is started when Knora starts. The StoreManager then starts the
+TriplestoreManager and IIIFManager, which each in turn starts their
+correct actor implementation.
+
Triplestores
+
Currently, the only supported triplestore is Apache Jena Fuseki, a HTTP-based triplestore.
+
HTTP-based triplestore support is implemented in the org.knora.webapi.triplestore.http package.
+
An HTTP-based triplestore is one that is accessed remotely over the HTTP
+protocol. HttpTriplestoreConnector supports the open source triplestore Apache Jena Fuseki.
+
IIIF Servers
+
Currently, only support for SIPI is implemented in org.knora.webapi.store.iiifSipiConnector.
Users must be able to edit the same data concurrently.
+
Each update must be atomic and leave the database in a consistent,
+meaningful state, respecting ontology constraints and permissions.
+
The application must not use any sort of long-lived locks, because they
+tend to hinder concurrent edits, and it is difficult to ensure that they
+are released when they are no longer needed. Instead, if a user requests
+an update based on outdated information (because another user has just
+changed something, and the first user has not found out yet), the update
+must be not performed, and the application must notify the user who
+requested it, suggesting that the user should check the relevant data
+and try again if necessary. (We may eventually provide functionality to
+help users merge edits in such a situation. The application can also
+encourage users to coordinate with one another when they are working on
+the same data, and may eventually provide functionality to facilitate
+this coordination.)
+
We can assume that each SPARQL update operation will run in its own
+database transaction with an isolation level of 'read committed'.
+We cannot assume that it is possible to run more than one SPARQL update
+in a single database transaction. The SPARQL 1.1 Protocol does not provide a
+way to do this, and currently it
+can be done only by embedding the triplestore in the application and
+using a vendor-specific API, but we cannot require this in Knora.)
+
Permissions
+
To create a new value (as opposed to a new version of an existing
+value), the user must have permission to modify the containing resource.
+
To create a new version of an existing value, the user needs only to
+have permission to modify the current version of the
+value; no permissions on the resource are needed.
+
Since changing a link requires deleting the old link and creating a new
+one (as described in Linking), a user wishing
+to change a link must have modify permission on both the containing
+resource and the knora-base:LinkValue for the existing link.
+
When a new resource or value is created, it can be given default permissions
+specified the project's admin data, or (only in API v2) custom permissions
+can be specified.
+
Ontology Constraints
+
Knora must not allow an update that would violate an ontology
+constraint.
+
When creating a new value (as opposed to adding a new version of an
+existing value), Knora must not allow the update if the containing
+resource's OWL class does not contain a cardinality restriction for the
+submitted property, or if the new value would violate the cardinality
+restriction.
+
It must also not allow the update if the type of the submitted value
+does not match the knora-base:objectClassConstraint of the property,
+or if the property has no knora-base:objectClassConstraint. In the
+case of a property that points to a resource, Knora must ensure that the
+target resource belongs to the OWL class specified in the property's
+knora-base:objectClassConstraint, or to a subclass of that class.
+
Duplicate and Redundant Values
+
When creating a new value, or changing an existing value, Knora checks
+whether the submitted value would duplicate an existing value for the
+same property in the resource. The definition of 'duplicate' depends on
+the type of value; it does not necessarily mean that the two values are
+strictly equal. For example, if two text values contain the same Unicode
+string, they are considered duplicates, even if they have different
+Standoff markup. If resource R has property P with value V1, and
+V1 is a duplicate of V2, the API server must not add another
+instance of property P with value V2. However, if the requesting
+user does not have permission to see V2, the duplicate is allowed,
+because forbidding it would reveal the contents of V2 to the user.
+
When creating a new version of a value, Knora also checks whether the
+new version is redundant, given the existing value. It is possible for
+the definition of 'redundant' can depend on the type of value, but in
+practice, it means that the values are strictly equal: any change,
+however trivial, is allowed.
+
Versioning
+
Each Knora value (i.e. something belonging to an OWL class derived from
+knora-base:Value) is versioned. This means that once created, a value
+is never modified. Instead, 'changing' a value means creating a new
+version of the value --- actually a new value --- that points to the
+previous version using knora-base:previousValue. The versions of a
+value are a singly-linked list, pointing backwards into the past. When a
+new version of a value is made, the triple that points from the resource
+to the old version (using a subproperty of knora-base:hasValue) is
+removed, and a triple is added to point from the resource to the new
+version. Thus the resource always points only to the current version of
+the value, and the older versions are available only via the current
+version's knora-base:previousValue predicate.
+
Unlike values, resources (members of OWL classes derived from
+knora-base:Resource) are not versioned. The data that is attached to a
+resource, other than its values, can be modified.
+
Deleting
+
Knora does not actually delete resources or values; it only marks them
+as deleted. Deleted data is normally hidden. All resources and values
+must have the predicate knora- base:isDeleted, whose object is a
+boolean. If a resource or value has been marked as deleted, it has
+knora-base:isDeleted true and has a knora-base:deleteDate. An
+optional knora-base:deleteComment may be added to explain why the
+resource or value has been marked as deleted.
+
Normally, a value is marked as deleted without creating a new version of
+it. However, link values must be treated as a special case. Before a
+LinkValue can be marked as deleted, its reference count must be
+decremented to 0. Therefore, a new version of the LinkValue is made,
+with a reference count of 0, and it is this new version that is marked
+as deleted.
+
Since it is necessary to be able to find out when a resource was
+deleted, it is not possible to undelete a resource. Moreover, to
+simplify the checking of cardinality constraints, and for consistency
+with resources, it is not possible to undelete a value, and no new
+versions of a deleted value can be made. Instead, if desired, a new
+resource or value can be created by copying data from a deleted resource
+or value.
+
Linking
+
Links must be treated differently to other types of values. Knora needs
+to maintain information about the link, including permissions and a
+version history. Since the link does not have a unique IRI of its own,
+Knora uses RDF
+reifications for
+this purpose. Each link between two resources has exactly one
+(non-deleted) knora-base:LinkValue. The resource itself has a
+predicate that points to the LinkValue, using a naming convention in
+which the word Value is appended to the name of the link predicate to
+produce the link value predicate. For example, if a resource
+representing a book has a predicate called hasAuthor that points to
+another resource, it must also have a predicate called hasAuthorValue
+that points to the LinkValue in which information about the link is
+stored. To find a particular LinkValue, one can query it either by
+using its IRI (if known), or by using its rdf:subject,
+rdf:predicate, and rdf:object (and excluding link values that are
+marked as deleted).
+
Like other values, link values are versioned. The link value predicate
+always points from the resource to the current version of the link
+value, and previous versions are available only via the current
+version's knora-base:previousValue predicate. Deleting a link means
+deleting the triple that links the two resources, and making a new
+version of the link value, marked with knora-base:isDeleted. A triple
+then points from the resource to this new, deleted version (using the
+link value property).
+
The API allows a link to be 'changed' so that it points to a different
+target resource. This is implemented as follows: the existing triple
+connecting the two resources is removed, and a new triple is added using
+the same link property and pointing to the new target resource. A new
+version of the old link's LinkValue is made, marked with
+knora-base:isDeleted. A new LinkValue is made for the new link. The
+new LinkValue has no connection to the old one.
+
When a resource contains knora-base:TextValue with Standoff markup
+that includes a reference to another resource, this reference is
+materialised as a direct link between the two resources, to make it
+easier to query. A special link property,
+knora-base:hasStandoffLinkTo, is used for this purpose. The
+corresponding link value property, knora-base:hasStandoffLinkToValue,
+points to a LinkValue. This LinkValue contains a reference count,
+indicated by knora-base:valueHasRefCount, that represents the number
+of text values in the containing resource that include one or more
+Standoff references to the specified target resource. Each time this
+number changes, a new version of this LinkValue is made. When the
+reference count reaches zero, the triple with
+knora-base:hasStandoffLinkTo is removed, and a new version of the
+LinkValue is made and marked with knora-base:isDeleted. If the same
+resource reference later appears again in a text value, a new triple is
+added using knora-base:hasStandoffLinkTo, and a new LinkValue is
+made, with no connection to the old one.
+
For consistency, every LinkValue contains a reference count. If the
+link property is not knora-base:hasStandoffLinkTo, the reference count
+will always be either 1 (if the link exists) or 0 (if it has been
+deleted, in which case the link value will also be marked with
+knora-base:isDeleted).
+
When a LinkValue is created for a standoff resource reference, it is
+given the same permissions as the text value containing the reference.
+
Design
+
Responsibilities of Responders
+
The resources responder (ResourcesResponderV2) has sole responsibility for generating SPARQL to
+create and updating resources, and the values responder (ValuesResponderV2) has sole responsibility for generating
+SPARQL to create and update values. When a new resource is created with its values, the values responder
+generates SPARQL statements that can be included in the INSERT
+clause of a SPARQL update to create the values, and
+the resources responder adds these statements to the SPARQL update that
+creates the resource. This ensures that the resource and its values are
+created in a single SPARQL update operation, and hence in a single
+triplestore transaction.
+
Application-level Locking
+
The 'read committed' isolation level cannot prevent a scenario where two
+users want to add the same data at the same time. It is possible that
+both requests would do pre-update checks and simultaneously find that it
+is OK to add the data, and that both updates would then succeed,
+inserting redundant data and possibly violating ontology constraints.
+Therefore, Knora uses short-lived, application-level write locks on
+resources, to ensure that only one request at a time can update a given
+resource. Before each update, the application acquires a lock on a resource.
+To prevent deadlocks, Knora locks only one resource per API operation.
+It then does the pre-update checks and the update, then releases the
+lock. The lock implementation (in IriLocker) requires each API
+request message to include a random UUID, which is generated in the
+API Routing package. Using
+application-level locks allows us to do pre-update checks in their own
+transactions, and finally to do the SPARQL update in its own
+transaction.
+
Ensuring Data Consistency
+
Knora enforces consistency constraints using three redundant mechanisms:
+
+
By doing pre-update checks using SPARQL SELECT queries and cached
+ ontology data.
+
By doing checks in the WHERE clauses of SPARQL updates.
+
Deprecated: By using GraphDB's built-in consistency checker (see
+ Consistency Checking).
+
+
We take the view that redundant consistency checks are a good thing.
+
Pre-update checks are SPARQL SELECT queries that are executed while
+holding an application-level lock on the resource to be updated. These
+checks should work with any triplestore, and can return helpful,
+Knora-specific error messages to the client if the request would violate
+a consistency constraint.
+
However, the SPARQL update itself is our only chance to do pre-update
+checks in the same transaction that will perform the update. The design
+of the SPARQL 1.1 Update
+standard makes it possible to ensure that if certain conditions are not
+met, the update will not be performed. In our SPARQL update code, each
+update contains a WHERE clause, possibly a DELETE clause, and an
+INSERT clause. The WHERE clause is executed first. It performs
+consistency checks and provides values for variables that are used in
+the DELETE and/or INSERT clauses. In our updates, if the
+expectations of the WHERE clause are not met (e.g. because the data to
+be updated does not exist), the WHERE clause should return no results;
+as a result, the update will not be performed.
+
Regardless of whether the update changes the contents of the
+triplestore, it returns nothing. If the update did nothing because the
+conditions of the WHERE clause were not met, the only way to find out is
+to do a SELECT afterwards. Moreover, in this case, there is no
+straightforward way to find out which conditions was not met. This is
+one reason why Knora does pre-update checks using separate SELECT
+queries and/or cached ontology data, before performing the update.
+This makes it possible to return specific error messages to the user to
+indicate why an update cannot be performed.
+
Moreover, while some checks are easy to do in a SPARQL update, others
+are difficult, impractical, or impossible. Easy checks include checking
+whether a resource or value exists or is deleted, and checking that the
+knora-base:objectClassConstraint of a predicate matches the rdf:type
+of its intended object. Cardinality checks are not very difficult, but
+they perform poorly on Jena. Knora does not do permission checks in
+SPARQL, because its permission-checking algorithm is too complex to be
+implemented in SPARQL. For this reason, Knora's check for duplicate
+values cannot be done in SPARQL update code, because it relies on
+permission checks.
+
In a bulk import operation, which can create a large number of resources
+in a single SPARQL update, a WHERE clause can become very expensive
+for the triplestore, in terms of memory as well as execution time.
+Moreover, RDF4J (and hence GraphDB) uses a recursive algorithm to parse
+SPARQL queries with WHERE clauses, so the size of a WHERE clause is
+limited by the stack space available to the Java Virtual Machine.
+Therefore, in bulk import operations, Knora uses INSERT DATA, which
+does not involve a WHERE clause. Bulk imports thus rely on checks (1)
+and (3) above.
+
SPARQL Update Examples
+
The following sample SPARQL update code is simpler than what Knora
+actually does. It is included here to illustrate the way Knora's SPARQL
+updates are structured and how concurrent updates are handled.
+
Finding a value IRI in a value's version history
+
We will need this query below. If a value is present in a resource
+property's version history, the query returns everything known about the
+value, or nothing otherwise:
The update request must contain the IRI of the most recent version of
+the value (http://rdfh.ch/c5058f3a/values/c3295339). If this is
+not in fact the most recent version (because someone else has done an
+update), this operation will do nothing (because the WHERE clause will
+return no rows). To find out whether the update succeeded, the
+application will then need to do a SELECT query using the query in
+Finding a value IRI in a value's version history.
+In the case of concurrent updates, there are two possibilities:
+
+
Users A and B are looking at version 1. User A submits an update and
+ it succeeds, creating version 2, which user A verifies using a
+ SELECT. User B then submits an update to version 1 but it fails,
+ because version 1 is no longer the latest version. User B's SELECT
+ will find that user B's new value IRI is absent from the value's
+ version history.
+
Users A and B are looking at version 1. User A submits an update and
+ it succeeds, creating version 2. Before User A has time to do a
+ SELECT, user B reads the new value and updates it again. Both users
+ then do a SELECT, and find that both their new value IRIs are
+ present in the value's version history.
This assumes that we know the current version of the value. If the
+version we have is not actually the current version, this query will
+return no rows.
Go to Docker preferences and increase the memory allocation.
+
+ The stack's memory usage is limited to ~20GB, though it should only use that much during heavy workloads. You should
+ be good to go in any case if you allocate 22GB or more.
+
+
Running the stack
+
With Docker installed and configured,
+
+
Run the following:
+
+
makeinit-db-test
+
+
to create the knora-test repository and initialize it with loading some test data into the triplestore (Fuseki).
+
+
Start the entire knora-stack (fuseki (db), sipi, api, salsah1) with the following command:
+
+
makestack-up
+
+
Note: To delete the existing containers and for a clean start, before creating the knora-test repository explained
+in the first step above, run the following:
+
makestack-down-delete-volumes
+
+
This stops the knora-stack and deletes any created volumes (deletes the database!).
+
To only shut down the Knora-Stack without deleting the containers:
+
makestack-down
+
+
To restart the knora-api use the following command:
+
makestack-restart-api
+
+
If a change is made to knora-api code, only its image needs to be rebuilt. In that case, use
+
makestack-up-fast
+
+
which starts the knora-stack by skipping rebuilding most of the images (only api image is rebuilt).
+
To work on Metadata, use
+
makestack-up-with-metadata
+
+
which will put three example metadata sets to the projects anything, images and dokubib.
+This data can then be consumed
+from localhost:3333/v2/metadata/http%3A%2F%2Frdfh.ch%2Fprojects%2F0001, localhost:3333/v2/metadata/http%3A%2F%2Frdfh.ch%2Fprojects%2F00FF
+and localhost:3333/v2/metadata/http%3A%2F%2Frdfh.ch%2Fprojects%2F0804.
+
Managing Containers in Docker Dashboard
+
The Docker Desktop is installed on your computer during the installation of docker, it enables easy management of docker
+containers and access to Docker Hub. To manage your docker containers, docker desktop provides a dashbord.
+
+
In docker dashboard, you can see all the running containers, stop, start, restart, or completely delete them. For
+example, when
+you start the knora-stack as explained above, in the docker dashboard you will see following:
+
+
Access the logs
+
To read information logged out of any container (db, api, etc.), click on the container in the dashboard and choose
+logs. The example, below shows the logs of the database (db) container that includes the last SPARQL query sent to the
+triplestore.
+
+
Note that, you can also print out the log information directly from the command line. For example, the same logs of the
+database container can be printed out using the following command:
+
makestack-logs-db
+
+
Similarly, the logs of the other containers can be printed out by running make with stack-logs-api
+or stack-logs-sipi.
+These commands print out and follow the logs, to only print the logs out without following, use
+-no-follow version of the commands for example:
+
makestack-logs-db-no-follow
+
+
Lastly, to print out the entire logs of the running knora-stack, use
+
makestack-logs
+
+
With the Docker plugin installed, you can attach a terminal to the docker container within VS Code. This will stream the
+docker logs to the terminal window of the editor.
+
+
The docker plugin also allows for a number of other useful features, like inspecting the container's file system or
+attaching a shell to the container.
+
Running the automated tests
+
To run all test targets, use the following in the command line:
+
maketest-all
+
+
To run a single test from the command line, for example SearchV2R2RSpec,
+run the following:
+
sbt" webapi / testOnly *SearchV2R2RSpec* "
+
+
Note: to run tests, the api container must be stopped first!
+
Build and Publish Documentation
+
First, you need to install the requirements through:
+
makedocs-install-requirements
+
+
Then, to build docs into the local site folder, run the following command:
+
makedocs-build
+
+
At this point, you can serve the docs to view them locally using
+
makedocs-serve
+
+
Lastly, to build and publish docs to Github Pages, use
+
makedocs-publish
+
+
Build and Publish Docker Images
+
To build and publish all Docker images locally
+
makedocker-build
+
+
To publish all Docker images to Dockerhub
+
makedocker-publish
+
+
Continuous Integration
+
For continuous integration testing, we use Github CI Actions. Every commit
+pushed to the git repository or every pull request, triggers the build.
+Additionally, in Github there is a small checkmark beside every commit,
+signaling the status of the build (successful, unsuccessful, ongoing).
+
The build that is executed on Github CI Actions is defined in the .github/workflows/*.yml files.
+
Webapi Server Startup-Flags
+
The Webapi-Server can be started with a number of flags.
+
loadDemoData - Flag
+
When the webapi-server is started with the loadDemoData flag, then at
+startup, the data which is configured in application.conf under the
+app.triplestore.rdf-data key is loaded into the triplestore, and any
+data in the triplestore is removed beforehand.
Fuseki - supplied triplestore in the DSP-API Github repository.
+
Sipi by building from
+ source or using the docker
+ image
+
+
Knora Github Repository
+
gitclonehttps://github.com/dasch-swiss/dsp-api
+
+
Triplestore
+
A number of triplestore implementations are available, including free
+software as well as
+proprietary options. DSP-API is designed to work with any
+standards-compliant triplestore. It is primarily tested with Apache Jena Fuseki.
+
Sipi
+
Build Sipi Docker Image
+
The Sipi docker image needs to be build by hand, as it requires the
+Kakadu distribution.
+
To build the image, and push it to the docker hub, follow the following
+steps:
Pushing the image to the docker hub requires prior authentication with
+$ docker login. The user needs to be registered on hub.docker.com.
+Also, the user needs to be allowed to push to the dblabbasel
+organisation.
+
Running Sipi
+
To use the docker image stored locally or on the docker hub repository
+type:
+
dockerrun--namesipi-d-p1024:1024daschswiss/sipi
+
+
This will create and start a docker container with the daschswiss/sipi
+image in the background. The default behaviour is to start Sipi by
+calling the following command:
Within the build.sbt file, the Dependencies package is referenced, which is located in project/Dependencies.scala.
+All third party dependencies need to be declared there.
+
Referencing a third party library
+
There is an object Dependencies where each library should be declared in a val.
The first string corresponds to the group/organization in the library's maven artefact,
+the second string corresponds to the artefact ID and the third string defines the version.
+
The strings are combined with % or %% operators, the latter fixing the dependency to the specified scala-version.
+
It is also possible to use variables in these definitions, e.g. if multiple dependencies share a version number:
Assigning the dependencies to a specific subproject
+
For each SBT project, there is one Seq in the Dependencies object.
+In order to make use of the declared dependencies, they must be referred to in the Seq of the respective subproject.
When a new version of Knora requires an existing repository to be updated,
+ do this automatically when Knora starts, if possible.
+
+
+
Make the update process as fast as possible, with some indication of progress
+ as it runs.
+
+
+
Design
+
As explained in
+Knora Ontology Versions,
+the knora-base ontology contains a version string to ensure compatibility
+between a repository and a given version of Knora. The same version string
+is therefore hard-coded in the Knora source code, in the string constant
+org.knora.webapi.KnoraBaseVersion. For new pull requests, the format of this string
+is knora-base vN, where N is an integer that is incremented for
+each version.
+
During Knora's startup process, ApplicationActor sends an UpdateRepositoryRequest
+message to the StoreManager, which forwards it to TriplestoreManager, which delegates
+it to org.knora.webapi.store.triplestore.upgrade.RepositoryUpdater.
+
RepositoryUpdater does the following procedure:
+
+
+
Check the knora-base version string in the repository.
+
+
+
Consult org.knora.webapi.store.triplestore.upgrade.RepositoryUpdatePlan to see which
+ transformations are needed.
+
+
+
Download the entire repository from the triplestore into an N-Quads file.
+
+
+
Read the N-Quads file into an RdfModel.
+
+
+
Update the RdfModel by running the necessary transformations, and replacing the
+ built-in DSP ontologies with the current ones.
+
+
+
Save the RdfModel to a new N-Quads file.
+
+
+
Empty the repository in the triplestore.
+
+
+
Upload the transformed repository file to the triplestore.
+
+
+
To update the RdfModel, RepositoryUpdater runs a sequence of upgrade plugins, each of which
+is a class in org.knora.webapi.store.triplestore.upgrade.plugins and is registered
+in RepositoryUpdatePlan.
+
Design Rationale
+
We tried and rejected several other designs:
+
+
+
Running SPARQL updates in the triplestore: too slow, and no way to report
+ progress during the update.
+
+
+
Downloading the repository and transforming it in Python using
+ rdflib: too slow.
+
+
+
Downloading the repository and transforming it in C++ using
+ Redland: also too slow.
+
+
+
The Scala implementation is the fastest by far.
+
The whole repository is uploaded in a single transaction, rather than uploading one named
+graph at a time, because GraphDB's consistency checker can enforce dependencies between
+named graphs.
+
Adding an Upgrade Plugin
+
Each time a pull request introduces changes that are not compatible
+with existing data, the following must happen:
+
+
+
The knora-base version number must be incremented in knora-base.ttl and
+ in the string constant org.knora.webapi.KnoraBaseVersion.
+
+
+
A plugin must be added in the package org.knora.webapi.store.triplestore.upgrade.plugins,
+ to transform existing repositories so that they are compatible with the code changes
+ introduced in the pull request. Each new plugin must be registered
+ by adding it to the sequence returned by RepositoryUpdatePlan.makePluginsForVersions.
+
+
+
The order of version numbers (and the plugins) must correspond to the order in which the
+pull requests are merged.
+
An upgrade plugin is a Scala class that extends UpgradePlugin. The name of the plugin
+class should refer to the pull request that made the transformation necessary,
+using the format UpgradePluginPRNNNN, where NNNN is the number of the pull request.
+
A plugin's transform method takes an RdfModel (a mutable object representing
+the repository) and modifies it as needed.
+
Before transforming the data, a plugin can check whether a required manual transformation
+has been carried out. If the requirement is not met, the plugin can throw
+InconsistentRepositoryDataException to abort the upgrade process.
+
Testing Update Plugins
+
Each plugin should have a unit test that extends UpgradePluginSpec. A typical
+test loads a file containing RDF test data into a RdfModel, runs the plugin,
+makes an RdfRepository containing the transformed RdfModel, and uses
+SPARQL to check the result.
Setup Visual Studio Code for development of DSP-API
+
To have full functionality, the Scala Metals plugin should be installed.
+
Additionally, a number of plugins can be installed for convenience, but are not required.
+Those include but are by no means limited to:
+
+
Docker - to attach to running docker containers
+
Stardog RDF grammar - TTL syntax highlighting
+
Lua
+
REST client
+
...
+
+
Formatter
+
As a formatter, we use Scalafmt.
+Metals automatically recognizes the formatting configuration in the .scalafmt.conf file in the root directory.
+VSCode should be configured so that it austomatically formats (e.g. on file saved).
+
Running Tests
+
The tests can be run through make commands or through SBT.
+The most convenient way to run the tests is through VSCode.
+Metals recognizes scalatest suits and lets you run them in the text explorer:
+
+
Or with the setting "metals.testUserInterface": "Code Lenses" directly in the text:
+
+
Debugger
+
It is currently not possible to start the stack in debug mode.
+
Tests can be run in debug mode by running them as described above but choosing debug test instead of test.
Sipi is a high-performance media server written in C++,
+for serving and converting binary media files such as images and video. Sipi can
+efficiently convert between many different formats on demand, preserving
+embedded metadata, and implements the International Image
+Interoperability Framework (IIIF). DSP-API is designed
+to use Sipi for converting and serving media files.
DSP-API and Sipi (Simple Image Presentation Interface) are two
+complementary software projects. Whereas DSP-API deals with data that
+is written to and read from a triplestore (metadata and annotations),
+Sipi takes care of storing, converting and serving image files as well
+as other types of files such as audio, video, or documents (binary files
+it just stores and serves).
+
DSP-API and Sipi stick to a clear division of responsibility regarding
+files: DSP-API knows about the names of files that are attached to
+resources as well as some metadata and is capable of creating the URLs
+for the client to request them from Sipi, but the whole handling of
+files (storing, naming, organization of the internal directory
+structure, format conversions, and serving) is taken care of by Sipi.
+
Adding Files to DSP
+
A file is first uploaded to Sipi, then its metadata is submitted to
+DSP. The implementation of this procedure is described in
+DSP-API and Sipi. Instructions for the client are given in
+Creating File Values.
+
Retrieving Files from Sipi
+
File URLs in API v2
+
In DSP-API v2, image file URLs are provided in IIIF format. In the simple
+ontology schema, a file value is simply
+a IIIF URL that can be used to retrieve the file from Sipi. In the complex schema,
+it is a StillImageFileValue with additional properties that the client can use to construct
+different IIIF URLs, e.g. at different resolutions. See the knora-api ontology for details.
+
Authentication of Users with Sipi
+
File access is restricted to users who have the permission to view the resource that the file is attached to.
+In order to check whether a user has the permission to view a resource, Sipi needs to know the user's identity.
+The identity is provided by DSP-API in the form of a JWT token.
+This jwt token can be provided to Sipi in the following ways:
+
+
recommended - The Authorization header of the request as a Bearer type token.
+
deprecated - The value for a token query parameter of the request. This is unsafe a the token is visible in the
+ URL.
+
deprecated - As a session cookie as set by the dsp-api. For the session cookie to be sent to Sipi, both the DSP-API
+ and Sipi endpoints need to
+ be under the same domain, e.g., api.example.com and iiif.example.com.
The Lucene full-text index provided by the triplestore is used to perform full-text searches in DSP.
+
Lucene Query Parser Syntax
+
Full-text searches in DSP are based on Lucene.
+Therefore, full-text searches support the
+Lucene Query Parser Syntax.
+
A full-text search consists of a single word in the simplest case, but could also be composed of several words combined with
+Boolean operators.
+By default, Lucene combines two or more terms separated by space with a logical OR.
XML files do not lend themselves to searching and linking. Knora's RDF storage
+is better suited to its goal of facilitating data reuse.
+
If your XML files represent text with markup (e.g. TEI/XML),
+the recommended approach is to allow Knora to store it as
+Standoff/RDF. This will allow both text and
+markup to be searched using Gravsearch. Knora
+can also regenerate, at any time, an XML document that is equivalent to the original one.
+
If you have XML that simply represents structured data (rather than text documents),
+we recommend converting it to Knora resources, which are stored as RDF.
Can a project use classes or properties defined in another project's ontology?
+
DSP-API does not allow this to be done with project-specific ontologies.
+Each project must be free to change its own ontologies, but this is not possible
+if they have been used in ontologies or data created by other projects.
+
However, an ontology can be defined as shared, meaning that it can be used by multiple
+projects, and that its creators promise not to change it in ways that could
+affect other ontologies or data that are based on it. See
+Shared Ontologies for details.
+
Why doesn't DSP-API use rdfs:domain and rdfs:range for consistency checking?
+
DSP-API's consistency checking uses specific properties, which are called
+knora-base:subjectClassConstraint and knora-base:objectClassConstraint in
+the knora-base ontology, and knora-api:subjectType and knora-api:objectType
+in the knora-api ontologies. These properties express restrictions on the
+possible subjects and objects of a property. If a property's subject or object
+does not conform to the specified restrictions, DSP-API considers it an error.
+
In contrast,
+the RDF Schema specification says
+that rdfs:domain and rdfs:range can be used to "infer additional information"
+about the subjects and objects of properties, rather than to enforce restrictions.
+This is, in fact, what RDFS reasoners do in practice. For example, consider these
+statements:
To an RDFS reasoner, the first statement means: if something is used as
+the object of example:hasAuthor, we can infer that it's an
+example:Person.
+
The second statement is a mistake; oxygen is not a person. But
+an RDFS reasoner would infer that data:oxygen is actually an
+example:Person, since it is used as the object of
+example:hasAuthor. Queries looking for persons would then get
+data:oxygen in their results, which would be incorrect.
+
Therefore, rdfs:domain and rdfs:range are not suitable for consistency
+checking.
+
DSP-API therefore uses its own properties, along with
+OWL cardinalities, which it interprets according to a "closed world"
+assumption. DSP-API performs its own consistency checks to enforce
+these restrictions. DSP-API repositories can also take advantage of
+triplestore-specific consistency checking mechanisms.
+
The constraint language SHACL may someday
+provide a standard, triplestore-independent way to implement consistency
+checks, if the obstacles to its adoption can be overcome
+(see Diverging views of SHACL).
+For further discussion of these issues, see
+SHACL and OWL Compared.
+
Can a user-created property be an owl:TransitiveProperty?
+
No, because in DSP-API, a resource controls its properties. This basic
+assumption is what allows DSP-API to enforce permissions and transaction
+integrity. The concept of a transitive property would break this assumption.
+
Consider a link property hasLinkToFoo that is defined as an owl:TransitiveProperty,
+and is used to link resource Foo1 to resource Foo2:
+
+
Suppose that Foo1 and Foo2 are owned by different users, and that
+the owner of Foo2 does not have permission to change Foo1.
+Now suppose that the owner of Foo2 adds a link from Foo2 to Foo3,
+using the transitive property:
+
+
Since the property is transitive, a link from Foo1 to Foo3 is now
+inferred. But this should not be allowed, because the owner of Foo2
+does not have permission to add a link to Foo1.
+
Moreover, even if the owner of Foo2 did have that permission, the inferred
+link would not have a knora-base:LinkValue (a reification), which every
+link must have. The LinkValue is what stores metadata about the creator
+of the link, its creation date, its permissions, and so on
+(see LinkValue).
+
Finally, if an update to a resource could modify another
+resource, this would violate DSP-API's model of transaction integrity, in which
+each transaction can modify only one resource
+(see Application-level Locking).
+DSP-API would then be unable to ensure that concurrent transactions do not
+interfere with each other.
+
General
+
Why should I use 0.0.0.0 instead of localhost when running the DSP stack locally?
+
When running locally with the default configuration, if you want authorization cookies
+to be shared between webapi and sipi, then both webapi and sipi must be accessed
+over 0.0.0.0, or otherwise, the cookie will not be sent to sipi.
+
If no authorization cookie sharing is necessary, then both 0.0.0.0 and localhostwill
+work.
Generally, DSP-API is designed to be backward compatible.
+Whenever a new major version of DSP-API is released,
+the existing data is migrated to the new version automatically.
+The public Rest API is also stable and should remain backward compatible.
+
However, when a feature appears not to be used,
+or if there are urgent technical reasons to change the API,
+we may decide to release breaking changes.
+In these instances, we try to provide a migration guide,
+in case some project or application is affected by the change.
+
If you experience any issues with the migration,
+please contact us via the DaSCH Help Center.
+
Migration Guides
+
+
+
Planned: Removal of knora-base:isSequenceOf and knora-base:hasSequenceBounds
+
If you have used knora-base:isSequenceOf and knora-base:hasSequenceBounds in your data,
+this should be replaced by knora-base:isAudioSegmentOf or knora-base:isVideoSegmentOf respectively,
+and knora-base:hasSegmentBounds.
+
The issue with that is that these properties are only allowed
+on resources of type knora-base:AudioSegment and knora-base:VideoSegment,
+whereas previously knora-base:isSequenceOf could be added to any knora-base:Resource.
+This means that you will have to change the type of the resources that you have been using
+to be of type knora-base:AudioSegment or knora-base:VideoSegment.
+
Deprecation Warnings
+
+
+
isSequenceOf and hasSequenceBounds
+
With the introduction of the new Segment concept in DSP-API v30.11.0,
+the previously existing properties knora-base:isSequenceOf and knora-base:hasSequenceBounds
+have been deprecated and will be removed in a future version.
+
If you are creating a new ontology,
+please do not use these properties anymore.
+Instead, use the newly introduced Segment type.
+ The stack's memory usage is limited to ~20GB, though it should only use that much during heavy workloads. You should
+ be good to go in any case if you allocate 22GB or more.
