diff --git a/docs/02-dsp-ontologies/knora-base.md b/docs/02-dsp-ontologies/knora-base.md index e072535d9c..f271a350ff 100644 --- a/docs/02-dsp-ontologies/knora-base.md +++ b/docs/02-dsp-ontologies/knora-base.md @@ -49,8 +49,10 @@ the `kb:isInProject` property, as described in ### Ontologies -Each user-created ontology must be defined as an `owl:Ontology` with the properties `rdfs:label` and `kb:attachedToProject`. -Since [DSP-API v20](https://github.com/dasch-swiss/dsp-api/releases/tag/v20.0.0) `kb:lastModificationDate` property is also required. +Each user-created ontology must be defined as an `owl:Ontology` with the properties `rdfs:label` +and `kb:attachedToProject`. +Since [DSP-API v20](https://github.com/dasch-swiss/dsp-api/releases/tag/v20.0.0) `kb:lastModificationDate` property is +also required. ### Resources @@ -147,8 +149,7 @@ property, which its subclasses override: 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`. This is the only approach supported in -DSP-API v1. +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. @@ -576,31 +577,31 @@ as the `kb:LinkValue`. #### 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 +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 +`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 +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](../01-introduction/example-project.md#resource-classes) example). #### isSequenceOf Similar to `kb:isPartOf` for `kb:StillImageRepresentations`, part-whole-relations can be defined for resources that have -a time dimension by using `kb:isSequenceOf`. You can use it for video or audio resources that are subtypes of +a time dimension by using `kb:isSequenceOf`. You can use it for video or audio resources that are subtypes of `kb:MovingImageRepresentation` and `kb:AudioRepresentation`. -`kb:isSequenceOf` is intended to be used in combination with the property `kb:hasSequenceBounds` which points to a -`kb:IntervalValue`. This defines the start and end point of the subseqence in relation to the entire audio/video +`kb:isSequenceOf` is intended to be used in combination with the property `kb:hasSequenceBounds` which points to a +`kb:IntervalValue`. This defines the start and end point of the subseqence in relation to the entire audio/video resource as an [interval](#intervalvalue). When the properties are used in this combination, a dedicated behavior in the frontend allows to display the sequences alongside the main resource. -There is an important difference between `kb:isSequenceOf` and `kb:isPartOf`: For `kb:isPartOf`, each part *is a* +There is an important difference between `kb:isSequenceOf` and `kb:isPartOf`: For `kb:isPartOf`, each part *is a* `kb:StillImageRepresentation` and the whole consists of multiple such parts. In `kb:isSequenceOf` on the other hand, the whole is one `kb:MovingImageRepresentation` or `kb:AudioRepresentation`. The parts only define which sub-sequence of this representation they are. @@ -609,14 +610,16 @@ this representation they are. 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](http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html)) +humanities is to encode it in XML using the Text Encoding +Initiative ([TEI](http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html)) 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](https://doi.org/10.1515/itit-2015-0030)). +( +see [Using Standoff Properties for Marking-up Historical Documents in the Humanities](https://doi.org/10.1515/itit-2015-0030)). 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. @@ -644,22 +647,29 @@ end positions of a substring in the text that has a particular attribute. The OW - `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. +- `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. +- `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. + 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. +- `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. +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`). @@ -667,7 +677,8 @@ or one of the standoff data type classes or subclasses of one of the standoff cl ##### 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. +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](#standofflinktag). - `StandoffInternalReferenceTag` Indicates that a substring refers to another standoff tag in the same text value. @@ -705,7 +716,8 @@ discussed in [Links Between Resources](#links-between-resources). In this case, 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. +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](#linkvalue)) describing the direct link. Each time this number changes, it makes a new version of @@ -716,24 +728,32 @@ For example, if `data:R1` is a resource with a text value in which the resource could contain the following triples: ```turtle -data:R1 ex:hasComment data:V1 . -data:V1 rdf:type kb:TextValue ; - kb:valueHasString "This link is internal." ; +data:R1 + ex:hasComment data:V1 . + +data:V1 + rdf:type kb:TextValue ; + kb:valueHasString "This link is internal." ; kb:valueHasStandoff data:SO1 . -data:SO1 rdf:type kb:StandoffLinkTag ; +data:SO1 + rdf:type kb:StandoffLinkTag ; kb:standoffTagHasStart: 5 ; - kb:standoffTagHasEnd: 9 ; - kb:standoffTagHasLink data:R2 . + kb:standoffTagHasEnd: 9 ; + kb:standoffTagHasLink data:R2 . + +data:R1 + kb:hasStandoffLinkTo data:R2 . -data:R1 kb:hasStandoffLinkTo data:R2 . -data:R1 kb:hasStandoffLinkToValue data:LV1 . +data:R1 + kb:hasStandoffLinkToValue data:LV1 . -data:LV1 rdf:type kb:LinkValue ; - rdf:subject data:R1 ; - rdf:predicate kb:hasStandoffLinkTo ; - rdf:object data:R2 ; +data:LV1 + rdf:type kb:LinkValue ; + rdf:subject data:R1 ; + rdf:predicate kb:hasStandoffLinkTo ; + rdf:object data:R2 ; kb:valueHasRefCount 1 . ``` @@ -751,14 +771,15 @@ the user has permission to see the source and target resources. 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`. +`standoffTagHasInternalReference` (1): Points to a `StandoffTag` that belongs to the same `TextValue`. It has +an `objectClassConstraint` of `StandoffTag`. For links to a `kb:Resource`, see [StandoffLinkTag](#standofflinktag). #### Mapping to Create Standoff From XML 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 +between XML elements (with or without a class) and attributes and standoff classes and properties (see [XML to Standoff Mapping](../03-endpoints/api-v2/text/custom-standoff.md)). A mapping is represented by a `kb:XMLToStandoffMapping` which contains one or more `kb:MappingElement`. @@ -766,24 +787,32 @@ A `kb:MappingElement` maps an XML element (including attributes) to a standoff c 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. +- `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. +- `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. +- `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. +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 +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. @@ -803,11 +832,14 @@ markup to be represented in XML. When non-hierarchical markup is converted to st 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, +- `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 diff --git a/docs/02-dsp-ontologies/salsah-gui.md b/docs/02-dsp-ontologies/salsah-gui.md index 66d7766cec..f4a6af1734 100644 --- a/docs/02-dsp-ontologies/salsah-gui.md +++ b/docs/02-dsp-ontologies/salsah-gui.md @@ -19,7 +19,7 @@ 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 @@ -112,7 +112,7 @@ recording. `List` is a GUI element for selecting an item in a hierarchical list (see [ListValue](knora-base.md#listvalue)). A property definition that -uses this element must also contain this `guiAttribute` predicate: +uses this element must also contain this `guiAttribute` predicate: `"hlist="`, where `LIST_IRI` is the IRI of a `knora-base:ListNode` that is the root node of a hierarchical list. @@ -122,7 +122,7 @@ uses this element must also contain this `guiAttribute` predicate: `Pulldown` is a GUI element for selecting an item in a flat list (see [ListValue](knora-base.md#listvalue)) using a pull-down menu. A property definition that uses this element must also contain this -`guiAttribute` predicate: +`guiAttribute` predicate: `"hlist="`, where `LIST_IRI` is the IRI of a `knora-base:ListNode` that is the root node of a hierarchical list. @@ -143,14 +143,7 @@ definition that uses this element must also contain this ### Searchbox -`Searchbox` is a GUI element for searching for a resource by matching text in its -`rdfs:label`. For DSP-API v1, a property definition that uses this -element may also contain this `guiAttribute` predicate: - -`"numprops=N"`, where `N` is an integer specifying the number of -describing properties to be returned for each found resource. - -For DSP-API v2, the `guiAttribute` has no effect. +`Searchbox` is a GUI element for searching for a resource by matching text in its `rdfs:label`. ### SimpleText @@ -158,10 +151,10 @@ For DSP-API v2, the `guiAttribute` has no effect. 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. +- `"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 @@ -169,10 +162,10 @@ length of the string to be input. 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. +- `"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 @@ -180,10 +173,10 @@ of the input. 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. +- `"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 @@ -191,14 +184,14 @@ of the input. 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. -- `"wrap=W"`, where `W` is `soft` or `hard` (see -[wrap](https://www.w3.org/TR/html5/sec-forms.html#element-attrdef-textarea-wrap)). +- `"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. +- `"wrap=W"`, where `W` is `soft` or `hard` (see + [wrap](https://www.w3.org/TR/html5/sec-forms.html#element-attrdef-textarea-wrap)). ### Checkbox diff --git a/docs/03-endpoints/api-admin/groups.md b/docs/03-endpoints/api-admin/groups.md index c2a1a6d1e7..2af205dd94 100644 --- a/docs/03-endpoints/api-admin/groups.md +++ b/docs/03-endpoints/api-admin/groups.md @@ -20,52 +20,62 @@ - `GET: /admin/groups//members` : return all group members - ## Group Operations ### Create Group - Required permission: SystemAdmin / hasProjectAllAdminPermission -/ hasProjectAllGroupAdminPermission + / hasProjectAllGroupAdminPermission - Required information: name (unique inside project), project IRI - Optional information: group descriptions - Returns information about the newly created group -- TypeScript Docs: groupFormats - CreateGroupApiRequestV1 - POST: `/admin/groups` - BODY: ```json { - "name": "NewGroup", - "descriptions": [ - {"value": "NewGroupDescription", "language": "en"}, - {"value": "NeueGruppenBeschreibung", "language": "de"} - ], - "project": "http://rdfh.ch/projects/00FF", - "status": true, - "selfjoin": false + "name": "NewGroup", + "descriptions": [ + { + "value": "NewGroupDescription", + "language": "en" + }, + { + "value": "NeueGruppenBeschreibung", + "language": "de" } + ], + "project": "http://rdfh.ch/projects/00FF", + "status": true, + "selfjoin": false +} ``` -Additionally, each group can have an optional custom IRI (of @ref:[Knora IRI](../api-v2/knora-iris.md#iris-for-data) form) +Additionally, each group can have an optional custom IRI (of @ref:[Knora IRI](../api-v2/knora-iris.md#iris-for-data) +form) specified by the `id` in the request body as below: ```json - { - "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 + { + "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 +} ``` ### Update group information - Required permission: SystemAdmin / hasProjectAllAdminPermission -/ hasProjectAllGroupAdminPermission / -hasProjectRestrictedGroupAdminPermission (for this group) + / hasProjectAllGroupAdminPermission / + hasProjectRestrictedGroupAdminPermission (for this group) - Changeable information: `name`, `descriptions`, `selfjoin` - TypeScript Docs: groupFormats - ChangeGroupApiRequestADM - PUT: `/admin/groups/` @@ -74,7 +84,12 @@ hasProjectRestrictedGroupAdminPermission (for this group) ```json { "name": "UpdatedGroupName", - "descriptions": [{"value": "UpdatedGroupDescription", "language": "en"}], + "descriptions": [ + { + "value": "UpdatedGroupDescription", + "language": "en" + } + ], "selfjoin": false } ``` @@ -97,7 +112,7 @@ hasProjectRestrictedGroupAdminPermission (for this group) - Required permission: SystemAdmin / hasProjectAllAdminPermission - Remark: The same as changing the groups `status` to -`false`. To un-delete, set `status` to `true`. + `false`. To un-delete, set `status` to `true`. - DELETE: `/admin/groups/` Example Group Information stored in admin named graph: : diff --git a/docs/03-endpoints/api-admin/users.md b/docs/03-endpoints/api-admin/users.md index 488d36cb9c..5e489283bc 100644 --- a/docs/03-endpoints/api-admin/users.md +++ b/docs/03-endpoints/api-admin/users.md @@ -21,7 +21,8 @@ - `GET: /admin/users/iri//project-memberships` : get user's project memberships - `POST: /admin/users/iri//project-memberships/` : add user to project (to ProjectMember group) -- `DELETE: /admin/users/iri//project-memberships/` : remove user from project (to ProjectMember group) +- `DELETE: /admin/users/iri//project-memberships/` : remove user from project (to ProjectMember + group) **User's group membership operations** @@ -39,101 +40,100 @@ ### Get users - - Required permission: SystemAdmin - - GET: `/admin/users` +- Required permission: SystemAdmin +- GET: `/admin/users` ### Get user - - Required permission: +- Required permission: - SystemAdmin / self: for getting all properties - All other users: for getting only the public properties (`givenName` and `familyName`) - - GET:`/admin/users/[iri | email | username ]/` +- GET:`/admin/users/[iri | email | username ]/` ### Create user - - Required permission: none, self-registration is allowed - - Required information: email (unique), given name, family name, - password, status, systemAdmin - - Username restrictions: +- Required permission: none, self-registration is allowed +- Required information: email (unique), given name, family name, + password, status, systemAdmin +- Username restrictions: - 4 - 50 characters long - Only contains alphanumeric characters, underscore and dot. - Underscore and dot can't be at the end or start of a username - Underscore or dot can't be used multiple times in a row - - Returns information about the newly created user - - TypeScript Docs: userFormats - `CreateUserApiRequestV1` - - POST: `/admin/users` - - BODY: - +- Returns information about the newly created user +- POST: `/admin/users` +- BODY: + ```json { - "email": "donald.duck@example.org", - "givenName": "Donald", - "familyName": "Duck", - "username": "donald.duck", - "password": "test", - "status": true, - "lang": "en", - "systemAdmin": false - } + "email": "donald.duck@example.org", + "givenName": "Donald", + "familyName": "Duck", + "username": "donald.duck", + "password": "test", + "status": true, + "lang": "en", + "systemAdmin": false +} ``` - -Additionally, each user can have an optional custom IRI (of [Knora IRI](../api-v2/knora-iris.md#iris-for-data) form) + +Additionally, each user can have an optional custom IRI (of [Knora IRI](../api-v2/knora-iris.md#iris-for-data) form) specified by the `id` in the request body as below: ```json - { - "id" : "http://rdfh.ch/users/FnjFfIQFVDvI7ex8zSyUyw", - "email": "donald.duck@example.org", - "givenName": "Donald", - "familyName": "Duck", - "username": "donald.duck", - "password": "test", - "status": true, - "lang": "en", - "systemAdmin": false - } + { + "id": "http://rdfh.ch/users/FnjFfIQFVDvI7ex8zSyUyw", + "email": "donald.duck@example.org", + "givenName": "Donald", + "familyName": "Duck", + "username": "donald.duck", + "password": "test", + "status": true, + "lang": "en", + "systemAdmin": false +} ``` - + ### Update basic user information** - - Required permission: SystemAdmin / self - - Changeable information: username, email, given name, family name, - password, status, SystemAdmin membership - - TypeScript Docs: userFormats - ChangeUserApiRequestADM - - PUT: `/admin/users/iri//BasicUserInformation` - - BODY: +- Required permission: SystemAdmin / self +- Changeable information: username, email, given name, family name, + password, status, SystemAdmin membership +- TypeScript Docs: userFormats - ChangeUserApiRequestADM +- PUT: `/admin/users/iri//BasicUserInformation` +- BODY: ```json { - "username": "donald.big.duck", - "email": "donald.big.duck@example.org", - "givenName": "Big Donald", - "familyName": "Duckmann", - "lang": "de" - } + "username": "donald.big.duck", + "email": "donald.big.duck@example.org", + "givenName": "Big Donald", + "familyName": "Duckmann", + "lang": "de" +} ``` ### Update user's password - - Required permission: SystemAdmin / self - - Changeable information: password - - PUT: `/admin/users/iri//Password` - - BODY: - +- Required permission: SystemAdmin / self +- Changeable information: password +- PUT: `/admin/users/iri//Password` +- BODY: + ```json { - "requesterPassword": "test", - "newPassword": "test1234" - } + "requesterPassword": "test", + "newPassword": "test1234" +} ``` ### Delete user - - Required permission: SystemAdmin / self - - Remark: The same as updating a user and changing `status` to `false`. To un-delete, set `status` to `true`. - - PUT: `/admin/users/iri//Status` - - BODY: - +- Required permission: SystemAdmin / self +- Remark: The same as updating a user and changing `status` to `false`. To un-delete, set `status` to `true`. +- PUT: `/admin/users/iri//Status` +- BODY: + ``` { "status": false // true or false @@ -142,25 +142,24 @@ specified by the `id` in the request body as below: ### Delete user (-\update user)** - - Required permission: SystemAdmin / self - - Remark: The same as updating a user and changing `status` to `false`. To un-delete, set `status` to `true`. - - DELETE: `/admin/users/iri/` - - BODY: empty - +- Required permission: SystemAdmin / self +- Remark: The same as updating a user and changing `status` to `false`. To un-delete, set `status` to `true`. +- DELETE: `/admin/users/iri/` +- BODY: empty ## User's project membership operations ### Get user's project memberships - - GET: `/admin/users/iri//project-memberships` +- GET: `/admin/users/iri//project-memberships` ### Add/remove user to/from project - - Required permission: SystemAdmin / ProjectAdmin / self (if project self-assignment is enabled) - - Required information: project IRI, user IRI - - Effects: `knora-base:isInProject` user property - - POST / DELETE: `/admin/users/iri//project-memberships/` - - BODY: empty +- Required permission: SystemAdmin / ProjectAdmin / self (if project self-assignment is enabled) +- Required information: project IRI, user IRI +- Effects: `knora-base:isInProject` user property +- POST / DELETE: `/admin/users/iri//project-memberships/` +- BODY: empty Note: When a user is project admin in the same project, his project admin membership will be removed as well. @@ -168,41 +167,41 @@ Note: When a user is project admin in the same project, his project admin member ### Get user's project admin memberships - - GET: `/admin/users/iri//project-admin-memberships` +- GET: `/admin/users/iri//project-admin-memberships` ### Add/remove user to/from project admin group - - Required permission: SystemAdmin / ProjectAdmin - - Required information: project IRI, user IRI - - Effects: `knora-base:isInProjectAdminGroup` user property - - POST / DELETE: `/admin/users/iri//project-admin-memberships/` - - BODY: empty +- Required permission: SystemAdmin / ProjectAdmin +- Required information: project IRI, user IRI +- Effects: `knora-base:isInProjectAdminGroup` user property +- POST / DELETE: `/admin/users/iri//project-admin-memberships/` +- BODY: empty Note: In order to add a user to a project admin group, the user needs to be member of that project. ### Get user's group memberships** - - GET: `/admin/users/iri//group-memberships` +- GET: `/admin/users/iri//group-memberships` ### Add/remove user to/from 'normal' group** (not *SystemAdmin* or *ProjectAdmin*) - - Required permission: SystemAdmin / hasProjectAllAdminPermission - / hasProjectAllGroupAdminPermission / - hasProjectRestrictedGroupAdminPermission (for this group) / User - (if group self-assignment is enabled) - - Required information: group IRI, user IRI - - Effects: `knora-base:isInGroup` - - POST / DELETE: `/admin/users/iri//group-memberships/` - - BODY: empty +- Required permission: SystemAdmin / hasProjectAllAdminPermission + / hasProjectAllGroupAdminPermission / + hasProjectRestrictedGroupAdminPermission (for this group) / User + (if group self-assignment is enabled) +- Required information: group IRI, user IRI +- Effects: `knora-base:isInGroup` +- POST / DELETE: `/admin/users/iri//group-memberships/` +- BODY: empty ### Add/remove user to/from system admin group - - Required permission: SystemAdmin / self - - Effects property: `knora-base:isInSystemAdminGroup` with value - `true` or `false` - - PUT: `/admin/users/iri//SystemAdmin` - - BODY: - +- Required permission: SystemAdmin / self +- Effects property: `knora-base:isInSystemAdminGroup` with value + `true` or `false` +- PUT: `/admin/users/iri//SystemAdmin` +- BODY: + ``` { "systemAdmin": false diff --git a/docs/03-endpoints/api-v1/adding-resources.md b/docs/03-endpoints/api-v1/adding-resources.md deleted file mode 100644 index 7ac249c6f1..0000000000 --- a/docs/03-endpoints/api-v1/adding-resources.md +++ /dev/null @@ -1,423 +0,0 @@ - - -# Adding Resources - -To create a resource, the HTTP method `POST` has to be used. -The request has to be sent to the Knora server using the `resources` -path segment: - -``` -HTTP POST to http://host/v1/resources -``` - -Unlike in the case of GET requests, the request body consists of JSON -describing the resource to be created. - -Creating resources requires authentication since only known users may -add resources. - -## Adding Resources Without Image Files - -The format of the JSON used to create a resource without an image file is -described in the TypeScript interface -`createResourceWithoutRepresentationRequest` in module -`createResourceFormats`. It requires the IRI of the resource class the -new resource belongs to, a label describing the new resource, the IRI of -the project the new resource belongs to, and the properties to be -assigned to the new resource. - -The request header's content type has to be set to `application/json`. - -## Adding Resources with Image Files - -The first step is to upload an image file 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` is the `sid` returned by Knora in response to the -client's login request (see [Authentication](authentication.md)). -The request must contain a body part providing the file as well as a parameter -`filename`, providing the file's original filename, which both Knora and Sipi will -store; these filenames can be descriptive and need not be unique. - -Sipi will then convert the uploaded image file to JPEG 2000 format and store -it in a temporary location. If this is successful, it will return a JSON -response that looks something like this: - -```json -{ - "uploadedFiles": [{ - "originalFilename": "manuscript-1234-page-1.tiff", - "internalFilename": "3UIsXH9bP0j-BV0D4sN51Xz.jp2", - "temporaryBaseIIIFUrl": "http://sipihost/tmp" - }] -} -``` - -This provides: - -- 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 - -The client may now wish to get a thumbnail of the uploaded image, to allow -the user to confirm that the correct files have been uploaded. This can be done -by adding the filename and IIIF parameters to `temporaryBaseIIIFUrl`. For example, to get -a JPG thumbnail image whose width and height are at most 128 pixels wide, you would request -`http://sipihost/tmp/3UIsXH9bP0j-BV0D4sN51Xz.jp2/full/!128,128/0/default.jpg`. - -The request to Knora works similarly to -[Adding Resources Without Image Files](#adding-resources-without-image-files), -with the addition of `file`, whose value is the `internalFilename` that Sipi returned. -See the TypeScript interface `createResourceWithRepresentationRequest` in -module `createResourceFormats` for details. The request header's content type must be -set to `application/json`. - -## Response to a Resource Creation - -When a resource has been successfully created, Knora sends back a JSON -containing the new resource's IRI (`res_id`) and its properties. The -resource IRI identifies the resource and can be used to perform future -DSP-API V1 operations. - -The JSON format of the response is described in the TypeScript interface -`createResourceResponse` in module `createResourceFormats`. - -## Changing a Resource's Label - -A resource's label can be changed by making a PUT request to the path -segments `resources/label`. The resource's IRI has to be provided in the -URL (as its last segment). The new label has to submitted as JSON in the -HTTP request's body. - -``` -HTTP PUT to http://host/v1/resources/label/resourceIRI -``` - -The JSON format of the request is described in the TypeScript interface -`changeResourceLabelRequest` in module `createResourceFormats`. The -response is described in the TypeScript interface -`changeResourceLabelResponse` in module `createResourceFormats`. - -## Bulk Import - -If you have a large amount of data to import into Knora, it can be more -convenient to use the bulk import feature than to create resources one -by one. In a bulk import operation, you submit an XML document to Knora, -describing multiple resources to be created. This is especially useful -if the resources to be created have links to one another. Knora checks -the entire request for consistency as as a whole, and performs the -update in a single database transaction. - -Only system or project administrators may use the bulk import. - -The procedure for using this feature is as follows -(see the [example below](#bulk-import-example)). - -1. Make an HTTP GET request to Knora to [get XML schemas](#1-get-xml-schemas) describing - the XML to be provided for the import. - -2. If you are importing image files, [upload files to Sipi](#2-upload-files-to-sipi). - -3. [Generate an XML import document](#3-generate-xml-import-document) representing the - data to be imported, following the Knora import schemas that were generated in step 1. - You will probably want to write a script to do this. Knora is not involved in this step. - If you are also importing image files, this XML document needs to - [contain the filenames](#bulk-import-with-image-files) that Sipi returned - for the files you uploaded in step 2. - -4. [Validate your XML import document](#4-validate-xml-import-document), using an XML schema validator such as - [Apache Xerces](http://xerces.apache.org) or [Saxon](http://www.saxonica.com), or an - XML development environment such as [Oxygen](https://www.oxygenxml.com). This will - help ensure that the data you submit to Knora is correct. Knora is not involved in this step. - -5. [Submit the XML import document to Knora](#5-submit-xml-import-document-to-knora). - -In this procedure, the person responsible for generating the XML import -data need not be familiar with RDF or with the ontologies involved. - -When Knora receives an XML import, it validates it first using the -relevant XML schemas, and then using the same internal checks that it -performs when creating any resource. - -The details of the XML import format are illustrated in the following -examples. - -### Bulk Import Example - -Suppose we have a project with existing data (but no image files), -which we want to import into Knora. We have created an -ontology called `http://www.knora.org/ontology/0801/biblio` for the -project, and this ontology also uses definitions from another ontology, -called `http://www.knora.org/ontology/0801/beol`. - -#### 1. Get XML Schemas - -To get XML schemas for an import, we use the following route, specifying -the (URL-encoded) IRI of our project's main ontology (in this case -`http://www.knora.org/ontology/0801/biblio`): - -``` -HTTP GET to http://host/v1/resources/xmlimportschemas/ontologyIRI -``` - -In our example, the URL could be: - -``` -http://localhost:3333/v1/resources/xmlimportschemas/http%3A%2F%2Fwww.knora.org%2Fontology%2F0801%2Fbiblio -``` - -This returns a Zip archive called `p0801-biblio-xml-schemas.zip`, -containing three files: - -- `p0801-biblio.xsd`: The schema for our main ontology. - -- `p0801-beol.xsd`: A schema for another ontology that our main ontology depends on. - -- `knoraXmlImport.xsd`: The standard Knora XML import schema, used by all XML imports. - -#### 2. Upload Files to Sipi - -See [Upload Files to Sipi](../api-v2/editing-values.md#upload-files-to-sipi) in -the DSP-API v2 documentation. - -#### 3. Generate XML Import Document - -We now convert our existing data to XML, probably by writing a custom -script. The resulting XML import document could look like this: - -```xml - - - - Niels Henrik Abel - Abel - Niels Henrik - Sir - - - Sherlock Holmes - Holmes - Sherlock - - - Math Intelligencer - Math Intelligencer - - - Strings in the 16th and 17th Centuries - - The most interesting article in Math Intelligencer. - - 73 - - - - 27 - - - - - - - GREGORIAN:1976 - Strings in the 16th and 17th Centuries - An alternate title - 48 - - -``` - -This illustrates several aspects of XML imports: - - - The root XML element must be `knoraXmlImport:resources`. - - - There is an XML namespace corresponding each ontology used in the - import. These namespaces can be found in the XML schema files - returned by Knora. - - - We have copied and pasted - `xmlns="http://api.knora.org/ontology/0801/biblio/xml-import/v1#"` - from the main XML schema, `p0801-biblio.xsd`. This enables the Knora - API server to identify the main ontology we are using. - - - We have used `xsi:schemaLocation` to indicate the main schema's - namespace and filename. If we put our XML document in the same - directory as the schemas, and we run an XML validator to check the - XML, it should load the schemas. - - - The child elements of `knoraXmlImport:resources` represent resources - to be created. The order of these elements is unimportant. - - - Each resource must have an ID, which must be an XML - [NCName](https://www.w3.org/TR/REC-xml-names/#NT-NCName), and must - be unique within the file. These IDs are used only during the - import, and will not be stored in the triplestore. - - - Each resource can optionally have a `creationDate` attribute, which - can be an [xsd:dateTime](https://www.w3.org/TR/xmlschema11-2/#dateTime) - or an [xsd:dateTimeStamp](https://www.w3.org/TR/xmlschema11-2/#dateTimeStamp). - If `creationDate` is not supplied, the current time is used. - - - The first child element of each resource must be a - `knoraXmlImport:label`, which will be stored as the resource's - `rdfs:label`. - - - Optionally, the second child element of a resource can provide - metadata about a file to be attached to the resource (see - bulk-import-with-digital-representations). - - - The remaining child elements of each resource represent its property - values. These must be sorted in alphabetical order by property name. - - - If a property has mutliple values, these are represented as multiple - adjacent property elements. - - - The type of each value must be specified using the attribute - `knoraType`. - - - A link to another resource described in the XML import is - represented as a child element of a property element, with - attributes `knoraType="link_value"` and `linkType="ref"`, and a - `target` attribute containing the ID of the target resource. - - - There is a specfic syntax for referring to properties from other - ontologies. In the example, `p0801-beol:comment` is defined in the - ontology `http://www.knora.org/ontology/0001/beol`. In the XML, we - refer to it as `p0801-biblio:p0801-beol__comment`. - - - A text value can contain XML markup. If it does: - - + The text value element must have the attribute `mapping_id`, - specifying a mapping from XML to standoff markup (see - XML-to-standoff-mapping). - + It is necessary to specify the appropriate XML namespace (in - this case the null namespace, `xmlns=""`) for the XML markup - in the text value. - + The XML markup in the text value will not be validated by - the schema. - + In an XML tag that is mapped to a standoff link tag, the - link target can refer either to the IRI of a resoruce that - already exists in the triplestore, or to the ID of a - resource described in the import. If a link points to a - resource described in the import, the ID of the target - resource must be prefixed with `ref:`. In the example above, - using the standard mapping, the standoff link to - `math_intelligencer` has the target - `ref:math_intelligencer`. - - - A text value can have a `lang` attribute, whose value is an ISO 639-1 - code specifying the language of the text. - -#### 4. Validate XML Import Document - -You can use an XML schema validator such as [Apache Xerces](http://xerces.apache.org) or -[Saxon](http://saxon.sourceforge.net/), or an XML development environment -such as [Oxygen](https://www.oxygenxml.com), to check that your XML import document -is valid according to the schemas you got from Knora. - -For example, using Saxon: - -``` -java -cp ./saxon9ee.jar com.saxonica.Validate -xsd:p0801-biblio.xsd -s:data.xml -``` - -#### 5. Submit XML Import Document to Knora - -To create these resources in Knora, make an HTTP post request with the XML import document -as the request body. The URL must specify the (URL-encoded) IRI of the project in which -the resources should be created: - -``` -HTTP POST to http://host/v1/resources/xmlimport/projectIRI -``` - -For example, using [curl](https://curl.haxx.se/): - -``` -curl -v -u root@example.com:test --data @data.xml --header "Content-Type: application/xml" http://localhost:3333/v1/resources/xmlimport/http%3A%2F%2Frdfh.ch%2Fprojects%2F0801 -``` - -### Bulk Import with Links to Existing Resources - -Having run the import in the previous example, we can import more data -with links to the data that is now in the triplestore: - -```xml - - - - Strings in the 18th Century - - The most boring article in Math Intelligencer. - - 76 - - - - 27 - - - - GREGORIAN:1977 - Strings in the 18th Century - 52 - - -``` - -Note that in the link elements referring to existing resources, the -`linkType` attribute has the value `iri`, and the `target` attribute -contains the IRI of the target resource. - -### Bulk Import with Image Files - -To attach an image file to a resource, we must provide the -element `knoraXmlImport:file` before the property elements. In this -element, we must provide a `filename` attribute, containing the `internalFilename` -that Sipi returned for the file in [2. Upload Files to Sipi](#2-upload-files-to-sipi). - -```xml - - - - a book with one page - the title of a book with one page - - - a page with an image - - Chlaus - 1a - - - - 1 - - -``` - -During the processing of the bulk import, Knora will ask Sipi for the rest of the -file's metadata, and store that metadata in a file value attached to the resource. diff --git a/docs/03-endpoints/api-v1/adding-values.md b/docs/03-endpoints/api-v1/adding-values.md deleted file mode 100644 index ccc34824f9..0000000000 --- a/docs/03-endpoints/api-v1/adding-values.md +++ /dev/null @@ -1,48 +0,0 @@ - - -# Adding a Value - -In order to add values to an existing resource, the HTTP method `POST` -has to be used. The request has to be sent to the Knora server using the -`values` path segment. Creating values requires authentication since -only known users may add values. - -## Adding a Property Value - -In order to add a value to a resource, its property type, value, and -project has to be indicated in the JSON. Also the IRI of the resource -the new value belongs has to be provided in the JSON. - -``` -HTTP POST to http://host/v1/values -``` - - - Depending on the type of the new value, one of the following formats - (all TypeScript interfaces defined in module `addValueFormats`) has - to be used in order to create a new value: - - - `addRichtextValueRequest` - - `addLinkValueRequest` - - `addIntegerValueRequest` - - `addDecimalValueRequest` - - `addBooleanValueRequest` - - `addUriValueRequest` - - `addDateValueRequest` (see `dateString` in - `basicMessageComponents` for the date format) - - `addColorValueRequest` - - `addGeometryValueRequest` - - `addHierarchicalListValueRequest` - - `addintervalValueRequest` - - `addGeonameValueRequest` - -## Response on Value Creation - -When a value has been successfully created, Knora sends back a JSON with -the new value's IRI. The value IRI identifies the value and can be used -to perform future DSP-API V1 operations. - -The JSON format of the response is described in the TypeScript interface -`addValueResponse` in module `addValueFormats`. diff --git a/docs/03-endpoints/api-v1/authentication.md b/docs/03-endpoints/api-v1/authentication.md deleted file mode 100644 index feda4ee573..0000000000 --- a/docs/03-endpoints/api-v1/authentication.md +++ /dev/null @@ -1,54 +0,0 @@ - - -# Authentication - -## Login and Logout - -When a client accesses the **/v1/session?login** route successfully, it -gets back headers requesting that a cookie is created, which will store -the session token. On all subsequent calls to any route, this session -token needs to be sent with each request. Normally, a web browser does -this automatically, i.e. sends the cookie on every request. The session -token is used by the server to retrieve the user profile. If successful, -the user is deemed authenticated. - -To **logout** the client can call the same route and provide the logout -parameter **/v1/session?logout**. This will invalidate the session token -and return headers for removing the cookie on the client. - -## Submitting Credentials - -For **login**, credentials in form of *email* and *password* need to be -sent with the request. - -There are two possibilities to do so: - - - in the URL submitting the parameters `email` and `password` - (e.g., - ) - - in the HTTP authorization header ([HTTP basic - authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)) - when doing a HTTP request to the API - -When using Python's module `requests`, the credentials (email / password) can simply be -submitted as a tuple with each request using the param `auth` -([python requests](https://requests.readthedocs.io/en/latest/user/authentication/#basic-authentication)). - -An alternative way for accessing all routes is to simply supply the -*email* and *password* credentials on each request either as URL -parameters or in the HTTP authorization header. - -## Checking Credentials - -To check the credentials, there is a special route called -**/v1/authenticate**, which can be used to check if the credentials are -valid. - -## Usage Scenarios - -1. Create session by logging-in, send session token on each subsequent - request, and logout when finished. -2. Send email/password credentials on every request. diff --git a/docs/03-endpoints/api-v1/changing-values.md b/docs/03-endpoints/api-v1/changing-values.md deleted file mode 100644 index c3be309551..0000000000 --- a/docs/03-endpoints/api-v1/changing-values.md +++ /dev/null @@ -1,68 +0,0 @@ - - -# Changing a Value - -To add values to an existing resource, the HTTP method `PUT` -has to be used. Changing values requires authentication since only known -users may change values. - -## Modifying a Property Value - -The request has to be sent to the Knora server using the `values` path -segment followed by the value's IRI: - -``` -HTTP PUT to http://host/values/valueIRI -``` - -The value IRI has to be URL-encoded. - -To change an existing value (creating a new version of it), the -value's current IRI and its new value have to be submitted as JSON in -the HTTP body. - -Depending on the type of the new value, one of the following formats -has to be used in order to create a new value (all these TypeScript interfaces are defined in module `changeValueFormats`): - -* `changeRichtextValueRequest` -* `changeLinkValueRequest` -* `changeIntegerValueRequest` -* `changeDecimalValueRequest` -* `changeBooleanValueRequest` -* `changeUriValueRequest` -* `changeDateValueRequest` -* `changeColorValueRequest` -* `changeGeometryValueRequest` -* `changeHierarchicalListValueRequest` -* `changeIntervalValueRequest` -* `changeGeonameValueRequest` - -## Modifying a File Value - -To change a file value, the client first uploads the new file to -Sipi, following the procedure described in -[Adding Resources with Image Files](adding-resources.md#adding-resources-with-image-files). - -Then the client sends a request to Knora, using this following route: - -``` -HTTP PUT to http://host/filevalue/resourceIRI -``` - -Here, `resourceIRI` is the URL-encoded IRI of the resource whose file value is -to be changed. The body of the request is a JSON object described in the TypeScript -interface `changeFileValueRequest` in module `changeValueFormats`, and contains -`file`, whose value is the `internalFilename` that Sipi returned. The request header's -content type must be set to `application/json`. - -## Response on Value Change - -When a value has been successfully changed, Knora sends back a JSON with -the new value's IRI. The value IRI identifies the value and can be used -to perform future DSP-API V1 operations. - -The JSON format of the response is described in the TypeScript interface -`changeValueResponse` in module `changeValueFormats`. diff --git a/docs/03-endpoints/api-v1/delete-resources-and-values.md b/docs/03-endpoints/api-v1/delete-resources-and-values.md deleted file mode 100644 index 9461ead40a..0000000000 --- a/docs/03-endpoints/api-v1/delete-resources-and-values.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Deleting Resources and Values - -Knora does not actually delete resources or values; it just marks them -as deleted. To mark a resource or value as deleted, you must use the -HTTP method `DELETE` has to be used. This requires authentication. - -## Mark a Resource as Deleted - -The delete request has to be sent to the Knora server using the -`resources` path - segment. - -``` -HTTP DELETE to http://host/resources/resourceIRI?deleteComment=String -``` - -The resource IRI must be URL-encoded. The `deleteComment` is an optional -comment explaining why the resource is being marked as deleted. - -## Mark a Value as Deleted - -The delete request has to be sent to the Knora server using the `values` -path segment, providing the valueIRI: - -``` -HTTP DELETE to http://host/values/valueIRI?deleteComment=String -``` - -The value IRI must be URL-encoded. The `deleteComment` is an optional -comment explaining why the value is being marked as deleted. - -Once a value has been marked as deleted, no new versions of it can be -made. diff --git a/docs/03-endpoints/api-v1/introduction.md b/docs/03-endpoints/api-v1/introduction.md deleted file mode 100644 index 4efa2b80f6..0000000000 --- a/docs/03-endpoints/api-v1/introduction.md +++ /dev/null @@ -1,69 +0,0 @@ - - -# Introduction: Using API V1 - -## RESTful API - -DSP-API V1 is a RESTful API that allows for reading and adding of -resources from and to Knora and changing their values using HTTP -requests. The actual data is submitted as JSON (request and response -format). The diverse 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](http://www.restapitutorial.com/lessons/httpmethods.html)). - -## Knora IRIs - -Every resource that is created or hosted by Knora is identified by a -unique id, a so called 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 DSP-API v2, DSP-API v1 uses internal IRIs, i.e. the actual IRIs -that are stored in the triplestore (see [Knora IRIs](../api-v2/knora-iris.md)). - -## V1 Path Segment - -Every request to API V1 includes `v1` as a path segment, e.g. -`http://host/v1/resources/http%3A%2F%2Frdfh.ch%2Fc5058f3a`. -Accordingly, requests to another version of the API will require another -path segment. - -## DSP-API Response Format - -In case an API request could be 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 (using -UTF-8). In this JSON, an API specific status code is sent (member -`status`). - -The JSON formats are formally defined as TypeScript interfaces (located -in `salsah/src/typescript_interfaces`). Build the HTML documentation of -these interfaces by executing `make jsonformat` (see `docs/Readme.md` -for further instructions). - -## 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. When using the -SALSAH web interface, after logging in a session is established (cookie -based). When using the API with another client application, credentials -can be sent as a part of the HTTP header or as parts of the URL (see -[Authentication in Knora](../../05-internals/design/principles/authentication.md)). - -Also when reading resources authentication my be needed as resources and -their values may have restricted view permissions. diff --git a/docs/03-endpoints/api-v1/reading-and-searching-resources.md b/docs/03-endpoints/api-v1/reading-and-searching-resources.md deleted file mode 100644 index 49a4bec88e..0000000000 --- a/docs/03-endpoints/api-v1/reading-and-searching-resources.md +++ /dev/null @@ -1,430 +0,0 @@ - - -# Reading and Searching Resources - -In order to get an existing resource, the HTTP method `GET` has to be -used. The request has to be sent to the Knora server using the -`resources` path segment (depending on the type of request, this segment -has to be exchanged, see below). Reading resources may require -authentication since some resources may have restricted viewing -permissions. - -## Get the Representation of a Resource by its IRI - -### Simple Request of a Resource (full Resource Request) - -A resource can be obtained by making a GET request to the API providing -its IRI. Because a Knora IRI has the format of a URL, its IRI has to be -URL encoded. - -In order to get the resource with the IRI -`http://rdfh.ch/c5058f3a` (an incunabula book contained in the -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/v1/resources/http%3A%2F%2Frdfh.ch%2Fc5058f3a -```` - -More formalized, the URL looks like this: - -``` -HTTP GET to http://host/v1/resources/resourceIRI -``` - -As an answer, the client receives a JSON that represents the -requested resource. It has the following members: - -* `status`: The Knora status code, `0` if everything went well -* `userdata`: Data about the user that made the request -* `resinfo`: Data describing the requested resource and its class -* `resdata`: Short information about the resource and its class - (including information about the given user's permissions on the - resource) -* `incoming`: Resources pointing to the requested resource -* `props`: Properties of the requested resource. - -For a complete and more formalized description of a full resource -request, look at the TypeScript interface `resourceFullResponse` in the -module `resourceResponseFormats`. - -#### Provide Request Parameters - -To make a request more specific, the following parameters can be -appended to the URL (`http://www.knora.org/resources/resourceIRI?param1=value1¶m2=value2`): - -- `reqtype=info|context|rights`: Specifies the type of - request. - - - Setting the parameter's to value `info` returns short - information about the requested resource (contains only - `resinfo` and no properties, see TypeScript interface - `resourceInfoResponse` in module - `resourceResponseFormats`). - - - Setting the parameter's value to `context` returns - context information (`resource_context`) about the - requested resource: Either the dependent parts of a - compound resource (e.g. pages of a book) or the parent - resource of a dependent resource (e.g. the book a pages - belongs to). By default, a context query does not return - information about the requested resource itself, but - only about its context (see TypeScript interface - `resourceContextResponse` in module - `resourceResponseFormats`). See below how to get - additional information about the resource. - - - The parameter `rights` returns only the given user's - permissions on the requested resource (see TypeScript - interface `resourceRightsResponse` in module - `resourceResponseFormats`). - -- `resinfo=true`: Can be used in combination with - `reqtype=context`: If set, `resinfo` is added to the response - representing information about the requested resource - (complementary to its context), see TypeScript interface - `resourceContextResponse` in module `resourceResponseFormats`. - -### Obtain an HTML Representation of a Resource - -In order to get an HTML representation of a resource (not a JSON), the -path segment `resources.html` can be - used: - -``` -HTTP GET to http://host/v1/resources.html/resourceIRI?reqtype=properties -``` - -The request returns the properties of the requested resource as an HTML -document. - -### Get only the Properties belonging to a Resource - -In order to get only the properties of a resource without any other -information, the path segment `properties` can be used: - -``` -HTTP GET to http://host/v1/properties/resourceIRI -``` - -The JSON contains just the member `properties` representing the -requested resource's properties (see TypeScript interface -`resourcePropertiesResponse` in module `resourceResponseFormats`). - -## Get Information about a Resource Class - -### Get a Resource Class by its IRI - -In order to get information about a resource class, the path segment -`resourcetypes` can be used. Append the IRI of the resource class to the -URL (e.g. `http://www.knora.org/ontology/0803/incunabula#book`). - -``` -HTTP GET to http://host/v1/resourcetypes/resourceClassIRI -``` - -In the JSON, the information about the resource class and all the -property types that it may have are returned. None of -these are actual instances of a property, but only types (see TypeScript -interface `resourceTypeResponse` in module `resourceResponseFormats`). - -### Get all the Property Types of a Resource Class or a Vocabulary - -To get a list of all the available property types, the path segment -`propertylists` can be used. It can be restricted to a certain vocbulary -using the parameter `vocabulary` or to a certain resource class using -the parameter `restype`. - -``` -# returns all the property types for incunabula:page -HTTP GET to http://host/v1/propertylists?restype=resourceClassIRI - -# returns all the property types for the incunabula vocabulary -HTTP GET to http://host/v1/propertylists?vocabulary=vocabularyIRI -``` - -Both of these queries return a list of property types. The default value -for the parameter `vocabulary` is `0` and means that the resource -classes from all the available vocabularies are returned. See TypeScript -interface `propertyTypesInResourceClassResponse` in module -`resourceResponseFormats`. - -### Get the Resource Classes of a Vocabulary - -Resource classes and property types are organized in (project specific) -name spaces, so called vocabularies. In order to get all the resource -classes defined for a specific vocabulary (e.g. `incunabula`), the -parameter `vocabulary` has to be used and assigned the vocabulary's IRI: - -``` -HTTP GET to http://host/v1/resourcetypes?vocabulary=vocabularyIRI -``` - -This returns all the resource classes defined for the specified -vocabulary and their property types. The default value for the parameter -`vocabulary` is `0` and means that the resource classes from all the -available vocabularies are returned. See TypeScript interface -`resourceTypesInVocabularyResponse` in module `resourceResponseFormats`. - -## Get all the Vocabularies - -To get a list of all available vocabularies, the path segment -`vocabularies` can be used: - -``` -HTTP GET to http://host/v1/vocabularies -``` - -The response will list all the available vocabularies. See TypeScript -interface `vocabularyResponse` in module `resourceResponseFormats`. - -## Search for Resources - -### Search for Resources by their Label - -This is a simplified way for searching for resources just by their label. -Search by label automatically adds Lucene operators, -search strings are expected not to contain any characters with a special meaning in -[Lucene Query Parser syntax](../../07-lucene/lucene-query-parser-syntax.md). - -It is a simple string-based method: - -``` -HTTP GET to http://host/v1/resources?searchstr=searchValue -``` - -Additionally, the following parameters can be appended to the URL (search value is `Zeitglöcklein`): - -- `restype_id=resourceClassIRI`: This restricts the search to - resources of the specified class (subclasses of that class will - also match). `-1` is the default value and means no restriction - to a specific class. If a resource class IRI is specified, it - has to be URL encoded (e.g. - `http://www.knora.org/v1/resources?searchstr=Zeitgl%C3%B6cklein&restype_id=http%3A%2F%2Fwww.knora.org%2Fontology%2Fincunabula%23book`). - -- `numprops=Integer`: Specifies the number of properties returned - for each resource that was found (sorted by GUI order), e.g. - `http://www.knora.org/v1/resources?searchstr=Zeitgl%C3%B6cklein&numprops=4`. - -- `limit=Integer`: Limits the amount of results returned (e.g. - `http://www.knora.org/v1/resources?searchstr=Zeitgl%C3%B6cklein&limit=1`). - -The response lists the resources that matched the search criteria (see -TypeScript interface `resourceLabelSearchResponse` in module -`resourceResponseFormats`). - -### Fulltext Search - -DSP-API offers a fulltext search that searches through all textual -representations of values. The search terms have to be URL encoded. -Fulltext search supports the [Lucene Query Parser syntax](../../07-lucene/lucene-query-parser-syntax.md). -Note that Lucene's default operator is a logical OR when submitting several search terms. - -``` -HTTP GET to http://host/v1/search/searchValue?searchtype=fulltext[&filter_by_restype=resourceClassIRI] -[&filter_by_project=projectIRI][&show_nrows=Integer]{[&start_at=Integer] -``` - -The parameter `searchtype` is required and has to be set to -`fulltext`. Additionally, these parameters can be set: - -- `filter_by_restype=resourceClassIRI`: restricts the search to - resources of the specified resource class (subclasses of that - class will also match). -- `filter_by_project=projectIRI`: restricts the search to - resources of the specified project. -- `show_nrows=Integer`: Indicates how many reults should be - presented on one page. If omitted, the default value `25` is - used. -- `start_at=Integer`: Used to enable paging and go through all the - results request by request. - -The response presents the retrieved resources (according to `show_nrows` -and `start_at`) and information about paging. If not all resources could -be presented on one page (`nhits` is greater than `shown_nrows`), the -next page can be requested (by increasing `start_at` by the number of -`show_nrows`). You can simply go through the elements of `paging` to -request the single pages one by one. See TypeScript interface -`searchResponse` in module `searchResponseFormats`. - -### Extended Search for Resources - -``` -HTTP GET to http://host/v1/search/?searchtype=extended -[&filter_by_restype=resourceClassIRI][&filter_by_project=projectIRI][&filter_by_owner=userIRI] -(&property_id=propertyTypeIRI&compop=comparisonOperator&searchval=searchValue)+ -[&show_nrows=Integer][&start_at=Integer] -``` - -The parameter `searchtype` is required and has to be set to -`extended`. An extended search requires at least one set of -parameters consisting of: - -- `property_id=propertyTypeIRI`: the property the resource has to - have (subproperties of that property will also match). - -- `compop=comparisonOperator`: the comparison operator to be used - to match between the resource's property value and the search - term. - -- `searchval=searchTerm`: the search value to look for. - -You can also provide several of these sets to make your query more -specific. - -The following table indicates the possible combinations of value types -and comparison -operators: - -| Value Type | Comparison Operator | -| ---------------- | -------------------------------------------------- | -| Date Value | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS | -| Integer Value | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS | -| Float Value | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS | -| Text Value | MATCH_BOOLEAN, MATCH, EQ, !EQ, LIKE, !LIKE, EXISTS | -| Geometry Value | EXISTS | -| Geoname Value | EQ, EXISTS | -| URI Value | EQ, EXISTS | -| Resource Pointer | EQ, EXISTS | -| Color Value | EQ, EXISTS | -| List Value | EQ, EXISTS | -| Boolean Value | EQ, !EQ, EXISTS | - -Explanation of the comparison operators: - -* `EQ` (equal): checks if a resource's value *equals* the search value. In - case of a text value type, it checks for identity of the strings - compared. In case of a date value type, equality is given if the - dates overlap in any way. Since dates are internally always - treated as periods, equality is given if a date value's period - ends after or equals the start of the defined period and a date - value's period starts before or equals the end of the defined - period. -* `!EQ` (not equal): checks if a resource's value *does not equal* the search - value. In case of a text value type, it checks if the compared - strings are different. In case of a date value type, inequality - is given if the dates do not overlap in any way, meaning that a - date starts after the end of the defined period or ends before - the beginning of the defined period (dates are internally always - treated as periods, see above). -* `GT` (greater than): checks if a resource's value is *greater than* the search - value. In case of a date value type, it assures that a period - begins after the indicated period's end. -* `GT_EQ` (greater than or equal): checks if a resource's value *equals or is greater - than* the search value. In case of a date value type, it assures - that the periods overlap in any way (see `EQ`) **or** that the - period starts after the indicated period's end (see `GT`). -* `LT` (less than): checks if a resource's value is *lower than* the search - value. In case of a date value type, it assures that a period - ends before the indicated period's start. -* `LT_EQ` (less than or equal): checks if a resource's value *equals or is lower than* - the search value. In case of a date value type, it assures that - the periods overlap in any way (see `EQ`) **or** that the period - ends before the indicated period's start (see `LT`). -* `EXISTS`: checks if an instance of the indicated property type - *exists* for a resource. **Please always provide an empty search - value when using EXISTS: "searchval="**. Otherwise, the query - syntax rules would be violated. -* `MATCH`: checks if a resource's text value *matches* the search - value, see [Lucene Query Parser Syntax](../../07-lucene/lucene-query-parser-syntax.md). -* `LIKE`: checks if the search value is contained in a resource's - text value using the SPARQL [REGEX](https://www.w3.org/TR/sparql11-query/#func-regex) function, - thus supporting regular expressions. -* `!LIKE` (not like): checks if the search value is not contained in a - resource's text value using the SPARQL [REGEX](https://www.w3.org/TR/sparql11-query/#func-regex) function, - thus supporting regular expressions. -* `MATCH_BOOLEAN`: checks if a resource's text value *matches* the - provided list of positive (exist) and negative (do not exist) - terms. The list takes this form: `([+-]term\s)+`. - -Additionally, these parameters can be set: - -* `filter_by_restype=resourceClassIRI`: restricts the search to - resources of the specified resource class (subclasses of that - class will also match). -* `filter_by_project=projectIRI`: restricts the search to - resources of the specified project. -* `filter_by_owner`: restricts the search to resources owned by - the specified user. -* `show_nrows=Integer`: Indicates how many reults should be - presented on one page. If omitted, the default value `25` is - used. -* `start_at=Integer`: Used to enable paging and go through all the - results request by request. - -Some sample searches: - -* `http://localhost:3333/v1/search/?searchtype=extended&filter_by_restype=http%3A%2F%2Fwww.knora.org%2Fontology%2Fincunabula%23book&property_id=http%3A%2F%2Fwww.knora.org%2Fontology%2Fincunabula%23title&compop=!EQ&searchval=Zeitgl%C3%B6cklein%20des%20Lebens%20und%20Leidens%20Christi`: - searches for books that have a title that does not equal - "Zeitglöcklein des Lebens und Leidens - Christi". -* `http://www.knora.org/v1/search/?searchtype=extended&filter_by_restype=http%3A%2F%2Fwww.knora.org%2Fontology%2Fincunabula%23book&property_id=http%3A%2F%2Fwww.knora.org%2Fontology%2Fincunabula%23title&compop=MATCH&searchval=Zeitgl%C3%B6cklein&property_id=http%3A%2F%2Fwww.knora.org%2Fontology%2Fincunabula%23pubdate&compop=EQ&searchval=JULIAN:1490`: - searches for resources of type `incunabula:book` whose titles - match "Zeitglöcklein" and were published in the year 1490 - (according to the Julian calendar). - -The response presents the retrieved resources (according to `show_nrows` -and `start_at`) and information about paging. If not all resources could -be presented on one page (`nhits` is greater than `shown_nrows`), the -next page can be requested (by increasing `start_at` by the number of -`show_nrows`). You can simply go through the elements of `paging` to -request the single pages one by one. See the TypeScript interface -`searchResponse` in module `searchResponseFormats`. - -## Get a Graph of Resources - -The path segment `graphdata` returns a graph of resources that are -reachable via links to or from an initial resource. - -``` -HTTP GET to http://host/v1/graphdata/resourceIRI?depth=Integer -``` - -The parameter `depth` specifies the maximum depth of the graph, and -defaults to 4. If `depth` is 1, the operation will return only the -initial resource and any resources that are directly linked to or from -it. - -The graph includes any link that is a subproperty of -`knora-base:hasLinkTo`, except for links that are subproperties of -`knora-base:isPartOf`. Specifically, if resource `R1` has a link that is -a subproperty of `knora-base:isPartOf` pointing to resource `R2`, no -link from `R1` to `R2` is included in the graph. - -The response represents the graph as a list of nodes (resources) and a -list of edges (links). For details, see the TypeScript interface -`graphDataResponse` in module `graphDataResponseFormats`. - -## Get Hierarchical Lists - -The knora-base ontology allows for the definition of hierarchical lists. -These can be queried by providing the IRI of the root node. Selections -are hierarchical list that are just one level deep. Internally, they are -represented as hierarchical lists. - -You can get a hierarchical by using the path segment `hlists` and -appending the hierarchical list's IRI (URL encoded): - -``` -HTTP GET to http://host/v1/hlists/rootNodeIRI -``` - -The response shows all of the list nodes that are element of the -requested hierarchical list as a tree structure. See TypeScript -interface `hierarchicalListResponse` in module -`hierarchicalListResponseFormats`. - -For each node, the full path leading to it from the top level can be -requested by making a query providing the node's IRI and setting the -param `reqtype=node`: - -``` -HTTP GET to http://host/v1/hlists/nodeIri?reqtype=node -``` - -The response presents the full path to the current node. See the TypeScript -interface `nodePathResponse` in module `hierarchicalListResponseFormats`. diff --git a/docs/03-endpoints/api-v1/reading-values.md b/docs/03-endpoints/api-v1/reading-values.md deleted file mode 100644 index 3b3e4d258e..0000000000 --- a/docs/03-endpoints/api-v1/reading-values.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Reading Values - -In order to get an existing value, the HTTP method GET has to be used. -The request has to be sent to the Knora server using the `values` path -segment. Reading values may require authentication since some resources -may have restricted viewing permissions. - -## Reading a Value - -The representation of a value can be obtained by making a GET request -providing the value's IRI: - -``` -HTTP GET to http://host/v1/values/valueIRI -``` - -In the response, the value's type and value are returned (see TypeScript -interface `valueResponse` in module `valueResponseFormats`). - -## Getting a Value's Version History - -In order to get the history of a value (its current and previous -versions), the IRI of the resource it belongs to, the IRI of the -property type that connects the resource to the value, and its -**current** value IRI have to be submitted. Each of these elements is -appended to the URL and separated by a slash. Please note that all of -these have to be URL encoded. - -Additionally to `values`, the path segment `history` has to be used: - -``` -HTTP GET to http://host/v1/values/history/resourceIRI/propertyTypeIRI/valueIRI -``` - -In the response, the value's versions returned (see TypeScript interface -`valueVersionsResponse` in module `valueResponseFormats`). - -## Getting a Linking Value - -In order to get information about a link between two resources, the path -segment `links` has to be used. The IRI of the source object, the IRI of -the property type linking the the two objects, and the IRI of the target -object have to be provided in the URL separated by slashes. Each of -these has to be URL - encoded. - -``` -HTTP GET to http://host/links/sourceObjectIRI/linkingPropertyIRI/targetObjectIRI -``` - -In the response, information about the link is returned such as a -reference count indicating how many links of the specified direction -(source to target) and type (property) between the two objects exist -(see TypeScript interface `linkResponse` in module -`valueResponseFormats`). diff --git a/docs/03-endpoints/api-v1/xml-to-standoff-mapping.md b/docs/03-endpoints/api-v1/xml-to-standoff-mapping.md deleted file mode 100644 index eb5d8977b7..0000000000 --- a/docs/03-endpoints/api-v1/xml-to-standoff-mapping.md +++ /dev/null @@ -1,553 +0,0 @@ - - -# XML to Standoff Mapping in API v1 - -## The Knora Standard Mapping - -### Description - -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. However, a mapping is -only needed if a TextValue with markup should be created. If a text has -no markup, it is submitted as a mere sequence of characters. - -The two cases are described in the TypeScript interfaces `simpletext` -and `richtext` in module `basicMessageComponents`. - -Knora 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](https://ckeditor.com/). (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; see `jquery.htmleditor.js`.) -The standard mapping contains the following elements and attributes that are mapped to standoff classes -and properties defined in the ontology: - -- `` → `standoff:StandoffRootTag` -- `

` → `standoff:StandoffParagraphTag` -- `` → `standoff:StandoffItalicTag` -- `` → `standoff:StandoffBoldTag` -- `` → `standoff:StandoffUnderlineTag` -- `` → `standoff:StandoffSubscriptTag` -- `` → `standoff:StandoffSuperscriptTag` -- `` → `standoff:StandoffStrikeTag` -- `` → `knora-base:StandoffUriTag` -- `` → `knora-base:StandoffLinkTag` -- `` → `knora-base:StandoffInternalReferenceTag` -- `

` to `
` → `standoff:StandoffHeader1Tag` to `standoff:StandoffHeader6Tag` -- `
    ` → `standoff:StandoffOrderedListTag` -- `