docs: publish architectural decision records (#2301)

CHANGELOG.md

@@ -1524,7 +1524,7 @@
 * MAJOR: Fix property names for incoming links (#1144))
 * MAJOR: Generate and resolve ARK URLs for resources (#1161). Projects
   that have resource IRIs that do not conform to the format specified in
-  <https://docs.knora.org/paradox/03-apis/api-v2/knora-iris.html#iris-for-data>
+  <https://docs.knora.org/paradox/03-endpoints/api-v2/knora-iris.html#iris-for-data>
   must update them.
 * MAJOR: Use project shortcode in IIIF URLs (#1191). If you have file value IRIs containing the substring `/reps/`, you must replace `/reps/` with `/values/`.
 

README.md

@@ -111,4 +111,4 @@ The DSP-API release versioning follows the [Semantic Versioning](https://semver.
 > * PATCH version when you make backwards-compatible bug fixes.
 
 Additionally, we will also increment the MAJOR version in the case when any kind of changes to existing
-data would be necessary, e.g., any changes to the [knora-base ontology](https://docs.dasch.swiss/latest/DSP-API/02-knora-ontologies/knora-base/) which are not backwards compatible.
+data would be necessary, e.g., any changes to the [knora-base ontology](https://docs.dasch.swiss/latest/DSP-API/02-dsp-ontologies/knora-base/) which are not backwards compatible.

docs/01-introduction/example-project.md

@@ -316,7 +316,7 @@ least one title and at most one publication date. In the DSP-API
 version 1, the word 'occurrence' is used instead of 'cardinality'.
 
 The OWL cardinalities supported by Knora are described in
-[OWL Cardinalities](../02-knora-ontologies/knora-base.md#owl-cardinalities).
+[OWL Cardinalities](../02-dsp-ontologies/knora-base.md#owl-cardinalities).
 
 Note that `incunabula:book` specifies a cardinality of
 `owl:minCardinality 0` on the property `incunabula:hasAuthor`. At first

docs/01-introduction/standoff-rdf.md

@@ -30,24 +30,24 @@ person who lived in the same city as another person who is the author of a text
 event that occurred during a certain time period.
 
 In DSP-API's Standoff/RDF, a tag is an RDF entity that is linked to a
-[text value](../02-knora-ontologies/knora-base.md#textvalue). Each tag points to a substring
+[text value](../02-dsp-ontologies/knora-base.md#textvalue). Each tag points to a substring
 of the text, and has semantic properties of its own. You can define your own tag classes
 in your ontology by making subclasses of `knora-base:StandoffTag`, and attach your own
 properties to them. You can then search for those properties using DSP-API's search language,
-[Gravsearch](../03-apis/api-v2/query-language.md).
+[Gravsearch](../03-endpoints/api-v2/query-language.md).
 
-The built-in [knora-base](../02-knora-ontologies/knora-base.md) and `standoff` ontologies
+The built-in [knora-base](../02-dsp-ontologies/knora-base.md) and `standoff` ontologies
 provide some basic tags that can be reused or extended. These include tags that represent
 DSP-API data types. For example, `knora-base:StandoffDateTag` represents a date in exactly the
-same way as a [date value](../02-knora-ontologies/knora-base.md#datevalue), i.e. as a
+same way as a [date value](../02-dsp-ontologies/knora-base.md#datevalue), i.e. as a
 calendar-independent astronomical date. You can use this tag as-is, or extend it by making
 a subclass, to represent dates in texts. Gravsearch includes built-in functionality for
 searching for these data type tags. For example, you can search for text containing a date that
-falls within a certain [date range](../03-apis/api-v2/query-language.md#matching-standoff-dates).
+falls within a certain [date range](../03-endpoints/api-v2/query-language.md#matching-standoff-dates).
 
 DSP-API supports automatic conversion between XML and Standoff/RDF. To make this work,
 Standoff/RDF stores the order of tags and their hierarchical relationships. You must define an
-[XML-to-Standoff Mapping](../03-apis/api-v2/xml-to-standoff-mapping.md) for your standoff tag classes and properties.
+[XML-to-Standoff Mapping](../03-endpoints/api-v2/xml-to-standoff-mapping.md) for your standoff tag classes and properties.
 Then you can import an XML document into DSP-API, which will store it as Standoff/RDF. The text and markup
 can then be searched using Gravsearch. When you retrieve the document, DSP-API converts it back to the
 original XML.

docs/01-introduction/what-is-knora.md → docs/01-introduction/what-is-dsp.md

@@ -3,9 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
 -->
 
-# What Is DSP and DSP-API (previous Knora)?
+# What is DSP and DSP-API?
 
-The DaSCH Service Platform (DSP) is a
+The DaSCH Service Platform (DSP) is 
 a content management system for the long-term preservation and reuse of
 humanities data. It is designed to accommodate data with a complex internal
 structure, including data that could be stored in relational databases.
@@ -37,16 +37,16 @@ certain number of [file formats](file-formats.md).
   archival file formats and stored by [Sipi](https://github.com/dhlab-basel/Sipi),
   with metadata stored in the triplestore.
 
-DSP then makes this data available for reuse via its generic, standards-based
-application programming interfaces (APIs = DSP-API). A virtual research environment
-(VRE) can then use these APIs to search, link together, and add to data
+DSP makes this data available for reuse via its generic, standards-based
+application programming interface DSP-API. A virtual research environment
+(VRE) can use DSP-API to query, link, and add to data
 from different research projects in a unified way.
 
 ## Humanities-Focused Data Storage
 
 Each project creates its own data model (or *ontology*), describing the types of
 items it wishes to store, using basic data types defined in Knora's
-[base ontology](../02-knora-ontologies/knora-base.md).
+[base ontology](../02-dsp-ontologies/knora-base.md).
 This gives projects the freedom to describe their data in a way that makes
 sense to them, while allowing DSP to support searching and linking across projects.
 
@@ -72,7 +72,7 @@ and can regenerate the original XML document at any time.
 
 ## Powerful Searches
 
-DSP-API provides a search language, [Gravsearch](../03-apis/api-v2/query-language.md),
+DSP-API provides a search language, [Gravsearch](../03-endpoints/api-v2/query-language.md),
 that is designed to meet the needs of humanities researchers. Gravsearch supports DSP-API's
 humanities-focused data structures, including calendar-independent dates and standoff markup, as well
 as fast full-text searches. This allows searches to combine text-related criteria with any other
@@ -92,9 +92,9 @@ user's permissions.
 RDF does not have a concept of data history. DSP-API maintains all previous
 versions of each item of data. Ordinary searches return only the latest version,
 but you can
-[obtain](../03-apis/api-v2/reading-and-searching-resources.md#get-a-full-representation-of-a-version-of-a-resource-by-iri)
+[obtain](../03-endpoints/api-v2/reading-and-searching-resources.md#get-a-full-representation-of-a-version-of-a-resource-by-iri)
 and
-[cite](../03-apis/api-v2/permalinks.md)
+[cite](../03-endpoints/api-v2/permalinks.md)
 an item as it was at any point in the past.
 
 ## Data Consistency

docs/02-knora-ontologies/introduction.md → docs/02-dsp-ontologies/introduction.md

@@ -5,6 +5,10 @@
 
 # Introduction
 
+The DSP ontologies provide a generic framework for describing humanities
+research data, allowing data from different projects to be combined, augmented,
+and reused.
+
 ## Resource Description Framework (RDF)
 
 DSP-API uses a hierarchy of ontologies based on the Resource Description
@@ -67,4 +71,4 @@ see [Restrictions on Classes](knora-base.md#restrictions-on-classes).)
 A standardisation process for shared ontologies is planned (issue @github[#523](#523)).
 
 For more details about shared ontologies, see
-[Shared Ontology IRIs](../03-apis/api-v2/knora-iris.md#shared-ontology-iris).
+[Shared Ontology IRIs](../03-endpoints/api-v2/knora-iris.md#shared-ontology-iris).

docs/02-knora-ontologies/knora-base.md → docs/02-dsp-ontologies/knora-base.md

@@ -116,7 +116,7 @@ It is not practical to store all data in RDF. In particular, RDF is not a good s
 images. Therefore, Knora stores such data outside the triplestore, in ordinary files. A resource can have metadata about
 a file attached to it. The technical term for such a resource in Knora is a **Representation**. For each file, there is
 a `kb:FileValue` in the triplestore containing metadata about the file (see [FileValue](#filevalue)). Knora
-uses [Sipi](https://github.com/dhlab-basel/Sipi) to store files. The [Knora APIs](../03-apis/index.md) provide ways to
+uses [Sipi](https://github.com/dhlab-basel/Sipi) to store files. The Knora APIs provide ways to
 create file values using Knora and Sipi.
 
 A resource that has a file value must belong to one of the subclasses of
@@ -148,9 +148,9 @@ There are two ways for a project to design classes for representations. The simp
 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](../03-apis/api-v1/index.md).
+DSP-API v1.
 
-The more flexible approach, which is supported by [DSP-API v2](../03-apis/api-v2/index.md), is for each `ex:Painting` to
+The more flexible approach, which is supported by DSP-API v2, is for each `ex:Painting` to
 link (using `kb:hasRepresentation` or a subproperty) to other resources containing files that represent the painting.
 Each of these other resources can extend a different subclass of `Representation`. For example, a painting could have a
 `StillImageRepresentation` as well as a `DDDrepresentation`.
@@ -759,7 +759,7 @@ For links to a `kb:Resource`, see [StandoffLinkTag](#standofflinktag).
 
 A mapping allows for the conversion of an XML document to RDF-standoff and back. A mapping defines one-to-one relations
 between XML elements (with or without a class) and attributes and standoff classes and properties (see 
-[XML to Standoff Mapping](../03-apis/api-v2/xml-to-standoff-mapping.md)).
+[XML to Standoff Mapping](../03-endpoints/api-v2/xml-to-standoff-mapping.md)).
 
 A mapping is represented by a `kb:XMLToStandoffMapping` which contains one or more `kb:MappingElement`.
 A `kb:MappingElement` maps an XML element (including attributes) to a standoff class and standoff properties. It has the
@@ -1065,7 +1065,7 @@ subject or object class that is a subclass of the one specified in the base prop
 the subproperty to make the base property's constraint less restrictive.
 
 See
-also [Why doesn’t Knora use rdfs:domain and rdfs:range for consistency checking?](../faq/index.md#why-doesnt-knora-use-rdfs-domain-and-rdfs-range-for-consistency-checking-)
+also [Why doesn’t Knora use rdfs:domain and rdfs:range for consistency checking?](../08-faq/index.md#why-doesnt-knora-use-rdfs-domain-and-rdfs-range-for-consistency-checking-)
 
 ### Consistency Constraint Example
 
@@ -1093,7 +1093,7 @@ A user-created ontology could define consistency constraints as in this simplifi
 ## Summary of Restrictions on User-Created Ontologies
 
 An ontology can refer to a Knora ontology in another project only if the other ontology is built-in or shared
-(see [Shared Ontologies](../03-apis/api-v2/knora-iris.md#shared-ontologies)).
+(see [Shared Ontologies](../03-endpoints/api-v2/knora-iris.md#shared-ontologies)).
 
 ### Restrictions on Classes
 
@@ -1133,7 +1133,7 @@ The [DaSCH](http://dasch.swiss/) intends to coordinate the standardisation of ge
 user-created ontologies. We envisage a process in which two or more projects would initiate the process by starting a
 public discussion on proposed entities to be shared. Once a consensus was reached, the
 [DaSCH](http://dasch.swiss/) would publish these entities in a
-[shared ontology](../03-apis/api-v2/knora-iris.md#shared-ontologies)).
+[shared ontology](../03-endpoints/api-v2/knora-iris.md#shared-ontologies)).
 
 ## Knora Ontology Versions
 

docs/03-apis/api-admin/introduction.md → docs/03-endpoints/api-admin/introduction.md

@@ -5,6 +5,8 @@
 
 # Introduction: Using the Admin API
 
+The DSP Admin API makes it possible to administrate projects, users, user groups, permissions, and hierarchical lists.
+
 ## RESTful API
 
 The Knora Admin API is a RESTful API that allows for reading and adding of

docs/03-endpoints/api-util/health.md

@@ -0,0 +1,25 @@
+<!---
+ * Copyright © 2021 - 2022 Swiss National Data and Service Center for the Humanities and/or DaSCH Service Platform contributors.
+ * SPDX-License-Identifier: Apache-2.0
+-->
+
+# Health
+
+The health endpoint provides information about the health state of the dsp-stack.
+
+
+## Example request
+
+`GET /health`
+
+
+## Example response
+
+```json
+{
+    "name":"AppState",
+    "message" : "Application is healthy",
+    "severity":"non fatal",
+    "status":"healthy"
+}
+```

docs/03-apis/api-util/version.md → docs/03-endpoints/api-util/version.md

@@ -21,11 +21,13 @@ The response has the type `application/json` and contains the following informat
 
 
 ## Example request
+
 `GET /version`
 
 
 ## Example response
-```
+
+```json
 {
     "akkaHttp": "10.1.7",
     "gdbFree": "8.10.0-free",

docs/03-apis/api-v1/reading-and-searching-resources.md → docs/03-endpoints/api-v1/reading-and-searching-resources.md

@@ -189,7 +189,7 @@ interface `vocabularyResponse` in module `resourceResponseFormats`.
 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/index.md).
+[Lucene Query Parser syntax](../../07-lucene/lucene-query-parser-syntax.md).
 
 It is a simple string-based method:
 
@@ -219,9 +219,9 @@ TypeScript interface `resourceLabelSearchResponse` in module
 
 ### Fulltext Search
 
-Knora offers a fulltext search that searches through all textual
+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/index.md).
+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.
 
 ```

docs/03-apis/api-v2/editing-resources.md → docs/03-endpoints/api-v2/editing-resources.md

@@ -155,7 +155,7 @@ by adding `knora-api:attachedToUser`. For example:
 ```
 
 The format of the object of `knora-api:hasPermissions` is described in
-[Permissions](../../02-knora-ontologies/knora-base.md#permissions).
+[Permissions](../../02-dsp-ontologies/knora-base.md#permissions).
 
 If permissions are not given, configurable default permissions are used (see
 [Default Object Access Permissions](../../05-internals/design/api-admin/administration.md#default-object-access-permissions)
@@ -251,7 +251,7 @@ want to change:
 
 - `rdfs:label`: a string
 - `knora-api:hasPermissions`, in the format described
-  in [Permissions](../../02-knora-ontologies/knora-base.md#permissions)
+  in [Permissions](../../02-dsp-ontologies/knora-base.md#permissions)
 - `knora-api:newModificationDate`: an [xsd:dateTimeStamp](https://www.w3.org/TR/xmlschema11-2/#dateTimeStamp).
 
 Here is an example: