feat(api-v2): Make values citable

docs/src/paradox/01-introduction/what-is-knora.md

@@ -114,7 +114,7 @@ versions of each item of data. Ordinary searches return only the latest version,
 but you can
 @ref:[obtain](../03-apis/api-v2/reading-and-searching-resources.md#get-a-full-representation-of-a-version-of-a-resource-by-iri)
 and
-@ref:[cite](../03-apis/api-v2/resource-permalinks.md)
+@ref:[cite](../03-apis/api-v2/permalinks.md)
 an item as it was at any point in the past.
 
 ## Data Consistency

docs/src/paradox/02-knora-ontologies/knora-base.md

@@ -286,6 +286,14 @@ 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.
@@ -338,6 +346,11 @@ created by copying data from a deleted value.
 
 :   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.

docs/src/paradox/03-apis/api-v2/index.md

@@ -35,6 +35,6 @@ License along with Knora.  If not, see <http://www.gnu.org/licenses/>.
 - [Editing Values](editing-values.md)
 - [Querying, Creating, and Updating Ontologies](ontology-information.md)
 - [TEI/XML](tei-xml.md)
-- [Resource Permalinks](resource-permalinks.md)
+- [Permalinks](permalinks.md)
 
 @@@

docs/src/paradox/03-apis/api-v2/knora-iris.md

@@ -207,7 +207,7 @@ identifiers to make it unique. To keep data IRIs relatively short, each UUID is
 thus each UUID is a 22-character string.
 
 Data IRIs are not currently intended to be dereferenced as URLs.
-Instead, each Knora resource has a separate @ref:[permalink](resource-permalinks.md).
+Instead, each Knora resource has a separate @ref:[permalink](permalinks.md).
 
 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.

docs/src/paradox/03-apis/api-v2/permalinks.md

@@ -0,0 +1,161 @@
+<!---
+Copyright © 2015-2019 the contributors (see Contributors.md).
+
+This file is part of Knora.
+
+Knora is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+Knora is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public
+License along with Knora.  If not, see <http://www.gnu.org/licenses/>.
+-->
+
+# Permalinks
+
+@@toc
+
+Knora provides a permanent, citable URL for each resource and value.
+These URLs use [Archival Resource Key (ARK) Identifiers](http://n2t.net/e/ark_ids.html),
+and are designed to remain valid even if the resource itself is moved
+from one Knora repository to another.
+
+## Obtaining ARK URLs
+
+In the @ref:[complex schema](introduction.md#api-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:
+
+```jsonld
+{
+  "@id" : "http://rdfh.ch/0803/2a6221216701",
+  "@type" : "incunabula:book",
+  "incunabula:book_comment" : {
+    "@id" : "http://rdfh.ch/0803/2a6221216701/values/56c287fc9505",
+    "@type" : "knora-api:TextValue",
+    "knora-api:arkUrl" : {
+      "@type" : "xsd:anyURI",
+      "@value" : "http://ark.dasch.swiss/ark:/72163/1/0803/2a6221216701W/dhaRsvZATjmOxhCOOzHqewB"
+    },
+    "knora-api:versionArkUrl" : {
+      "@type" : "xsd:anyURI",
+      "@value" : "http://ark.dasch.swiss/ark:/72163/1/0803/2a6221216701W/dhaRsvZATjmOxhCOOzHqewB.20160302T150521Z"
+    },
+    "knora-api:attachedToUser" : {
+      "@id" : "http://rdfh.ch/users/91e19f1e01"
+    },
+    "knora-api:hasPermissions" : "CR knora-admin:Creator|M knora-admin:ProjectMember|V knora-admin:UnknownUser",
+    "knora-api:userHasPermission" : "V",
+    "knora-api:valueAsString" : "Katalogaufnahme anhand ISTC und v.d.Haegen",
+    "knora-api:valueCreationDate" : {
+      "@type" : "xsd:dateTimeStamp",
+      "@value" : "2016-03-02T15:05:21Z"
+    },
+    "knora-api:valueHasUUID" : "dhaRsvZATjmOxhCOOzHqew"
+  },
+  "knora-api:arkUrl" : {
+    "@type" : "xsd:anyURI",
+    "@value" : "http://ark.dasch.swiss/ark:/72163/1/0803/2a6221216701W"
+  },
+  "knora-api:versionArkUrl" : {
+    "@type" : "xsd:anyURI",
+    "@value" : "http://ark.dasch.swiss/ark:/72163/1/0803/2a6221216701W.20160302T150521Z"
+  },
+  "knora-api:attachedToProject" : {
+    "@id" : "http://rdfh.ch/projects/0803"
+  },
+  "knora-api:attachedToUser" : {
+    "@id" : "http://rdfh.ch/users/91e19f1e01"
+  },
+  "knora-api:creationDate" : {
+    "@type" : "xsd:dateTimeStamp",
+    "@value" : "2016-03-02T15:05:21Z"
+  },
+  "knora-api:hasPermissions" : "CR knora-admin:Creator|M knora-admin:ProjectMember|V knora-admin:UnknownUser",
+  "knora-api:userHasPermission" : "V",
+  "rdfs:label" : "Reise ins Heilige Land",
+  "@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#",
+    "incunabula" : "http://0.0.0.0:3333/ontology/0803/incunabula/v2#",
+    "xsd" : "http://www.w3.org/2001/XMLSchema#"
+  }
+}
+```
+
+In the @ref:[simple schema](introduction.md#api-schema), resources are returned
+with ARK URLs, but values are returned as literals, so ARK URLs are not provided
+for values.
+
+For more information on getting past versions of resources and values, see:
+
+- @ref:[Get a Full Representation of a Version of a Resource by IRI](reading-and-searching-resources.md#get-a-full-representation-of-a-version-of-a-resource-by-iri)
+- @ref:[Get a Version of a Value in a Resource](reading-and-searching-resources.md#get-a-version-of-a-value-in-a-resource)
+- @ref:[Get the Version History of a Resource](reading-and-searching-resources.md#get-the-version-history-of-a-resource)
+
+## Resolving Knora ARK URLs
+
+A Knora ARK URL is intended to be resolved by the [Knora ARK resolver](https://github.com/dhlab-basel/ark-resolver).
+
+## Knora ARK URL Format
+
+For details, see @ref:[Archival Resource Key (ARK) Identifiers](../../05-internals/design/api-v2/ark.md).
+
+### ARK URLs for Resources
+
+The format of a Knora resource ARK URL is as follows:
+
+```
+http://HOST/ark:/NAAN/VERSION/PROJECT/RESOURCE_UUID[.TIMESTAMP]
+```
+
+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:
+
+```
+http://ark.dasch.swiss/ark:/72163/1/0001/0C=0L1kORryKzJAJxxRyRQY
+```
+
+The same ARK URL with an optional timestamp is:
+
+```
+http://ark.dasch.swiss/ark:/72163/1/0001/0C=0L1kORryKzJAJxxRyRQY.20180604T085622513Z
+```
+
+Without a timestamp, a Knora resource ARK URL refers to the latest version of the
+resource at the time when the URL is resolved.
+
+### ARK URLs for Values
+
+The format of a Knora value ARK URL is as follows:
+
+```
+http://HOST/ark:/NAAN/VERSION/PROJECT/RESOURCE_UUID/VALUE_UUID[.TIMESTAMP]
+```
+
+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:
+
+```
+http://ark.dasch.swiss/ark:/72163/1/0001/0C=0L1kORryKzJAJxxRyRQY/4OOf3qJUTnCDXlPNnygSzQX
+```
+
+The same ARK URL with an optional timestamp is:
+
+```
+http://ark.dasch.swiss/ark:/72163/1/0001/0C=0L1kORryKzJAJxxRyRQY/4OOf3qJUTnCDXlPNnygSzQX.20180604T085622513Z
+```
+
+Without a timestamp, a Knora value ARK URL refers to the latest version of the
+value at the time when the URL is resolved.

docs/src/paradox/03-apis/api-v2/reading-and-searching-resources.md

@@ -216,17 +216,49 @@ and add the URL parameter `?version=TIMESTAMP`, where `TIMESTAMP` is an
 [xsd:dateTimeStamp](https://www.w3.org/TR/xmlschema11-2/#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 Knora's @ref:[ARK URLs](resource-permalinks.md)).
+from Knora's @ref:[ARK URLs](permalinks.md)).
 
 The resource will be returned with the values that it had at the specified
 time. Since Knora only versions values, not resource metadata (e.g.
 `rdfs:label`), the current metadata will be returned.
 
 The returned resource will include the predicate `knora-api:versionDate`,
 containing the timestamp that was submitted, and its `knora-api:versionArkUrl`
-(see @ref:[Resource Permalinks](resource-permalinks.md)) will contain the
+(see @ref:[Resource Permalinks](permalinks.md)) 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 @ref:[Responses Describing Resources](#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 @ref:[Get a Value in a Resource](#get-a-value-in-a-resource),
+and add the URL parameter `?version=TIMESTAMP`, where `TIMESTAMP` is an
+[xsd:dateTimeStamp](https://www.w3.org/TR/xmlschema11-2/#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 Knora's @ref:[ARK URLs](permalinks.md)).
+
+The value will be returned within its containing resource, in the same format
+as for @ref:[Responses Describing Resources](#responses-describing-resources),
+but without any of the resource's other values.
+
+Since Knora only versions values, not resource metadata (e.g.
+`rdfs:label`), the current resource metadata will be returned.
+
 ### Get the Version History of a Resource
 
 To get a list of the changes that have been made to a resource since its creation,
@@ -498,7 +530,7 @@ HTTP GET to http://host/v2/resources?resourceClass=RESOURCE_CLASS_IRI&page=PAGE[
 ```
 
 This is useful only if the project does not contain a large amount of data;
-otherwise, you should use @ref:[Gravsearch](query-language.md)) to search
+otherwise, you should use @ref:[Gravsearch](query-language.md) to search
 using more specific criteria.
 
 The HTTP header `X-Knora-Accept-Project` must be submitted; its value is