From be6bcd0b1b6b8d321e2105f25431a43d5814d5c6 Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Sat, 26 Nov 2022 10:59:38 +0100 Subject: [PATCH] docs: publish architectural decision records (#2301) --- CHANGELOG.md | 2 +- README.md | 2 +- docs/01-introduction/example-project.md | 2 +- docs/01-introduction/index.md | 11 -- docs/01-introduction/standoff-rdf.md | 12 +- .../{what-is-knora.md => what-is-dsp.md} | 18 +- .../introduction-fig1.dot | 0 .../introduction-fig2.dot | 0 .../introduction-fig3.dot | 0 .../introduction.md | 6 +- .../knora-base-fig1.dot | 0 .../knora-base-fig2.dot | 0 .../knora-base-fig3.dot | 0 .../knora-base.md | 14 +- .../salsah-gui.md | 0 docs/02-knora-ontologies/index.md | 14 -- docs/03-apis/api-admin/index.md | 17 -- docs/03-apis/api-util/health.md | 6 - docs/03-apis/api-util/index.md | 11 -- docs/03-apis/api-v1/index.md | 17 -- docs/03-apis/api-v2/index.md | 20 --- docs/03-apis/index.md | 17 -- .../api-admin/groups.md | 0 .../api-admin/introduction.md | 2 + .../api-admin/lists.md | 0 .../api-admin/overview.md | 0 .../api-admin/permissions.md | 0 .../api-admin/projects.md | 0 .../api-admin/stores.md | 0 .../api-admin/users.md | 0 docs/03-endpoints/api-util/health.md | 25 +++ .../api-util/version.md | 4 +- .../api-v1/adding-resources.md | 0 .../api-v1/adding-values.md | 0 .../api-v1/authentication.md | 0 .../api-v1/changing-values.md | 0 .../api-v1/delete-resources-and-values.md | 0 .../api-v1/introduction.md | 0 .../api-v1/reading-and-searching-resources.md | 6 +- .../api-v1/reading-values.md | 0 .../api-v1/xml-to-standoff-mapping.md | 0 .../api-v2/authentication.md | 0 .../api-v2/editing-resources.md | 4 +- .../api-v2/editing-values.md | 8 +- .../api-v2/getting-lists.md | 0 .../api-v2/introduction.md | 0 .../api-v2/knora-iris.md | 4 +- .../api-v2/ontology-information.md | 32 ++-- .../api-v2/permalinks.md | 0 .../api-v2/query-language.md | 5 +- .../api-v2/reading-and-searching-resources.md | 10 +- .../api-v2/reading-user-permissions.md | 2 +- .../api-v2/tei-xml.md | 0 .../api-v2/xml-to-standoff-mapping.md | 0 .../getting-started.md | 87 ---------- docs/04-publishing-deployment/index.md | 11 -- docs/04-publishing-deployment/publishing.md | 12 +- .../0001-record-architecture-decisions.md | 4 +- ...rvice-manager-from-akka-actor-to-zlayer.md | 0 ...nager-and-sipi-implementation-to-zlayer.md | 0 ...ger-and-fuseki-implementation-to-zlayer.md | 0 ...espondermanager-to-a-simple-case-class.md} | 2 +- .../design/api-admin/administration.md | 2 +- docs/05-internals/design/api-admin/index.md | 9 - docs/05-internals/design/api-v1/index.md | 9 - docs/05-internals/design/api-v2/ark.md | 6 +- docs/05-internals/design/api-v2/gravsearch.md | 6 +- docs/05-internals/design/api-v2/index.md | 20 --- .../design/api-v2/ontology-management.md | 6 +- .../design/api-v2/ontology-schemas.md | 4 +- docs/05-internals/design/api-v2/overview.md | 2 +- docs/05-internals/design/api-v2/sipi.md | 2 +- docs/05-internals/design/api-v2/smart-iris.md | 2 +- docs/05-internals/design/api-v2/standoff.md | 6 +- .../design/principles/authentication.md | 2 +- .../design/principles/consistency-checking.md | 2 +- .../design/principles/design-overview.md | 20 +-- docs/05-internals/design/principles/index.md | 15 -- docs/05-internals/development/index.md | 16 -- .../development/updating-repositories.md | 2 +- docs/06-sipi/sipi-and-dsp-api.md | 6 +- docs/07-lucene/index.md | 11 -- docs/07-lucene/lucene-query-parser-syntax.md | 7 +- docs/{faq => 08-faq}/faq-fig1.dot | 0 docs/{faq => 08-faq}/faq-fig2.dot | 0 docs/{faq => 08-faq}/index.md | 42 ++--- .../index.md | 0 docs/index.md | 14 -- mkdocs.yml | 163 ++++++++---------- 89 files changed, 240 insertions(+), 521 deletions(-) delete mode 100644 docs/01-introduction/index.md rename docs/01-introduction/{what-is-knora.md => what-is-dsp.md} (89%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/introduction-fig1.dot (100%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/introduction-fig2.dot (100%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/introduction-fig3.dot (100%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/introduction.md (92%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/knora-base-fig1.dot (100%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/knora-base-fig2.dot (100%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/knora-base-fig3.dot (100%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/knora-base.md (99%) rename docs/{02-knora-ontologies => 02-dsp-ontologies}/salsah-gui.md (100%) delete mode 100644 docs/02-knora-ontologies/index.md delete mode 100644 docs/03-apis/api-admin/index.md delete mode 100644 docs/03-apis/api-util/health.md delete mode 100644 docs/03-apis/api-util/index.md delete mode 100644 docs/03-apis/api-v1/index.md delete mode 100644 docs/03-apis/api-v2/index.md delete mode 100644 docs/03-apis/index.md rename docs/{03-apis => 03-endpoints}/api-admin/groups.md (100%) rename docs/{03-apis => 03-endpoints}/api-admin/introduction.md (95%) rename docs/{03-apis => 03-endpoints}/api-admin/lists.md (100%) rename docs/{03-apis => 03-endpoints}/api-admin/overview.md (100%) rename docs/{03-apis => 03-endpoints}/api-admin/permissions.md (100%) rename docs/{03-apis => 03-endpoints}/api-admin/projects.md (100%) rename docs/{03-apis => 03-endpoints}/api-admin/stores.md (100%) rename docs/{03-apis => 03-endpoints}/api-admin/users.md (100%) create mode 100644 docs/03-endpoints/api-util/health.md rename docs/{03-apis => 03-endpoints}/api-util/version.md (98%) rename docs/{03-apis => 03-endpoints}/api-v1/adding-resources.md (100%) rename docs/{03-apis => 03-endpoints}/api-v1/adding-values.md (100%) rename docs/{03-apis => 03-endpoints}/api-v1/authentication.md (100%) rename docs/{03-apis => 03-endpoints}/api-v1/changing-values.md (100%) rename docs/{03-apis => 03-endpoints}/api-v1/delete-resources-and-values.md (100%) rename docs/{03-apis => 03-endpoints}/api-v1/introduction.md (100%) rename docs/{03-apis => 03-endpoints}/api-v1/reading-and-searching-resources.md (99%) rename docs/{03-apis => 03-endpoints}/api-v1/reading-values.md (100%) rename docs/{03-apis => 03-endpoints}/api-v1/xml-to-standoff-mapping.md (100%) rename docs/{03-apis => 03-endpoints}/api-v2/authentication.md (100%) rename docs/{03-apis => 03-endpoints}/api-v2/editing-resources.md (99%) rename docs/{03-apis => 03-endpoints}/api-v2/editing-values.md (97%) rename docs/{03-apis => 03-endpoints}/api-v2/getting-lists.md (100%) rename docs/{03-apis => 03-endpoints}/api-v2/introduction.md (100%) rename docs/{03-apis => 03-endpoints}/api-v2/knora-iris.md (97%) rename docs/{03-apis => 03-endpoints}/api-v2/ontology-information.md (97%) rename docs/{03-apis => 03-endpoints}/api-v2/permalinks.md (100%) rename docs/{03-apis => 03-endpoints}/api-v2/query-language.md (99%) rename docs/{03-apis => 03-endpoints}/api-v2/reading-and-searching-resources.md (98%) rename docs/{03-apis => 03-endpoints}/api-v2/reading-user-permissions.md (92%) rename docs/{03-apis => 03-endpoints}/api-v2/tei-xml.md (100%) rename docs/{03-apis => 03-endpoints}/api-v2/xml-to-standoff-mapping.md (100%) delete mode 100644 docs/04-publishing-deployment/getting-started.md delete mode 100644 docs/04-publishing-deployment/index.md rename docs/{architecture/decisions => 05-internals/design/adr}/0001-record-architecture-decisions.md (60%) rename docs/{architecture/decisions => 05-internals/design/adr}/0002-change-cache-service-manager-from-akka-actor-to-zlayer.md (100%) rename docs/{architecture/decisions => 05-internals/design/adr}/0003-change-iiif-service-manager-and-sipi-implementation-to-zlayer.md (100%) rename docs/{architecture/decisions => 05-internals/design/adr}/0004-change-triplestore-service-manager-and-fuseki-implementation-to-zlayer.md (100%) rename docs/{architecture/decisions/0004-change-respondermanager-to-a-simple-case-class.md => 05-internals/design/adr/0005-change-respondermanager-to-a-simple-case-class.md} (93%) delete mode 100644 docs/05-internals/design/api-admin/index.md delete mode 100644 docs/05-internals/design/api-v1/index.md delete mode 100644 docs/05-internals/design/api-v2/index.md delete mode 100644 docs/05-internals/design/principles/index.md delete mode 100644 docs/05-internals/development/index.md delete mode 100644 docs/07-lucene/index.md rename docs/{faq => 08-faq}/faq-fig1.dot (100%) rename docs/{faq => 08-faq}/faq-fig2.dot (100%) rename docs/{faq => 08-faq}/index.md (78%) rename docs/{00-release-notes => 09-release-notes}/index.md (100%) delete mode 100644 docs/index.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c5c7141e26..203016f0a4 100644 --- a/CHANGELOG.md +++ b/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 - + 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/`. diff --git a/README.md b/README.md index 76e9de424d..24507ccd19 100644 --- a/README.md +++ b/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. diff --git a/docs/01-introduction/example-project.md b/docs/01-introduction/example-project.md index 8ba7575188..16094eaaea 100644 --- a/docs/01-introduction/example-project.md +++ b/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 diff --git a/docs/01-introduction/index.md b/docs/01-introduction/index.md deleted file mode 100644 index 7f6bcb15a6..0000000000 --- a/docs/01-introduction/index.md +++ /dev/null @@ -1,11 +0,0 @@ - - -# Introduction - -* [What Is DSP and DSP-API (previous Knora)?](what-is-knora.md) -* [File Formats in DSP-API](file-formats.md) -* [Standoff/RDF Text Markup](standoff-rdf.md) -* [An Example Project](example-project.md) diff --git a/docs/01-introduction/standoff-rdf.md b/docs/01-introduction/standoff-rdf.md index d18c45ab5f..8e7f512485 100644 --- a/docs/01-introduction/standoff-rdf.md +++ b/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. diff --git a/docs/01-introduction/what-is-knora.md b/docs/01-introduction/what-is-dsp.md similarity index 89% rename from docs/01-introduction/what-is-knora.md rename to docs/01-introduction/what-is-dsp.md index a2e3f9dc01..2e6ef5b0d0 100644 --- a/docs/01-introduction/what-is-knora.md +++ b/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 diff --git a/docs/02-knora-ontologies/introduction-fig1.dot b/docs/02-dsp-ontologies/introduction-fig1.dot similarity index 100% rename from docs/02-knora-ontologies/introduction-fig1.dot rename to docs/02-dsp-ontologies/introduction-fig1.dot diff --git a/docs/02-knora-ontologies/introduction-fig2.dot b/docs/02-dsp-ontologies/introduction-fig2.dot similarity index 100% rename from docs/02-knora-ontologies/introduction-fig2.dot rename to docs/02-dsp-ontologies/introduction-fig2.dot diff --git a/docs/02-knora-ontologies/introduction-fig3.dot b/docs/02-dsp-ontologies/introduction-fig3.dot similarity index 100% rename from docs/02-knora-ontologies/introduction-fig3.dot rename to docs/02-dsp-ontologies/introduction-fig3.dot diff --git a/docs/02-knora-ontologies/introduction.md b/docs/02-dsp-ontologies/introduction.md similarity index 92% rename from docs/02-knora-ontologies/introduction.md rename to docs/02-dsp-ontologies/introduction.md index 5aa15f3ece..98800c7278 100644 --- a/docs/02-knora-ontologies/introduction.md +++ b/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). diff --git a/docs/02-knora-ontologies/knora-base-fig1.dot b/docs/02-dsp-ontologies/knora-base-fig1.dot similarity index 100% rename from docs/02-knora-ontologies/knora-base-fig1.dot rename to docs/02-dsp-ontologies/knora-base-fig1.dot diff --git a/docs/02-knora-ontologies/knora-base-fig2.dot b/docs/02-dsp-ontologies/knora-base-fig2.dot similarity index 100% rename from docs/02-knora-ontologies/knora-base-fig2.dot rename to docs/02-dsp-ontologies/knora-base-fig2.dot diff --git a/docs/02-knora-ontologies/knora-base-fig3.dot b/docs/02-dsp-ontologies/knora-base-fig3.dot similarity index 100% rename from docs/02-knora-ontologies/knora-base-fig3.dot rename to docs/02-dsp-ontologies/knora-base-fig3.dot diff --git a/docs/02-knora-ontologies/knora-base.md b/docs/02-dsp-ontologies/knora-base.md similarity index 99% rename from docs/02-knora-ontologies/knora-base.md rename to docs/02-dsp-ontologies/knora-base.md index ff6550a227..28b5da854c 100644 --- a/docs/02-knora-ontologies/knora-base.md +++ b/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 diff --git a/docs/02-knora-ontologies/salsah-gui.md b/docs/02-dsp-ontologies/salsah-gui.md similarity index 100% rename from docs/02-knora-ontologies/salsah-gui.md rename to docs/02-dsp-ontologies/salsah-gui.md diff --git a/docs/02-knora-ontologies/index.md b/docs/02-knora-ontologies/index.md deleted file mode 100644 index dad59684e3..0000000000 --- a/docs/02-knora-ontologies/index.md +++ /dev/null @@ -1,14 +0,0 @@ - - -# Knora Ontologies - -* [Introduction](introduction.md) -* [The Knora Base Ontology](knora-base.md) -* [The SALSAH GUI Ontology](salsah-gui.md) - -The DSP ontologies provide a generic framework for describing humanities -research data, allowing data from different projects to be combined, augmented, -and reused. diff --git a/docs/03-apis/api-admin/index.md b/docs/03-apis/api-admin/index.md deleted file mode 100644 index 959009f2d4..0000000000 --- a/docs/03-apis/api-admin/index.md +++ /dev/null @@ -1,17 +0,0 @@ - - -# DSP Admin API - -The DSP Admin API makes it possible to administer projects, users, user groups, permissions, and hierarchical lists. - -- [Introduction](introduction.md) -- [Overview](overview.md) -- [Users Endpoint](users.md) -- [Projects Endpoint](projects.md) -- [Groups Endpoint](groups.md) -- [Lists Endpoint](lists.md) -- [Permissions Endpoint](permissions.md) -- [Stores Endpoint](stores.md) diff --git a/docs/03-apis/api-util/health.md b/docs/03-apis/api-util/health.md deleted file mode 100644 index a0927028ea..0000000000 --- a/docs/03-apis/api-util/health.md +++ /dev/null @@ -1,6 +0,0 @@ - - -# Health diff --git a/docs/03-apis/api-util/index.md b/docs/03-apis/api-util/index.md deleted file mode 100644 index 30845d7be1..0000000000 --- a/docs/03-apis/api-util/index.md +++ /dev/null @@ -1,11 +0,0 @@ - - -# Knora Util API - -The Knora Util API allows retrieving information about the Knora-stack itself. -It consists of the following elements: -* [Health](health.md): Knora health state -* [Version](version.md): Versions of used stack components diff --git a/docs/03-apis/api-v1/index.md b/docs/03-apis/api-v1/index.md deleted file mode 100644 index 42472ba919..0000000000 --- a/docs/03-apis/api-v1/index.md +++ /dev/null @@ -1,17 +0,0 @@ - - -# DSP-API v1 - -- [Introduction](introduction.md) -- [Authentication](authentication.md) -- [Reading and Searching Resources](reading-and-searching-resources.md) -- [XML to Standoff Mapping](xml-to-standoff-mapping.md) -- [Adding Resources](adding-resources.md) -- [Reading and Searching Resources](reading-and-searching-resources.md) -- [Reading Values](reading-values.md) -- [Adding a Value](adding-values.md) -- [Changing a Value](changing-values.md) -- [Deleting Resources and Values](delete-resources-and-values.md) diff --git a/docs/03-apis/api-v2/index.md b/docs/03-apis/api-v2/index.md deleted file mode 100644 index 88f5d3421c..0000000000 --- a/docs/03-apis/api-v2/index.md +++ /dev/null @@ -1,20 +0,0 @@ - - -# DSP-API v2 - -- [Introduction](introduction.md) -- [Authentication](authentication.md) -- [Knora IRIs](knora-iris.md) -- [Reading and Searching Resources](reading-and-searching-resources.md) -- [Reading the User's Permissions on Resources and Values](reading-user-permissions.md) -- [Getting Lists](getting-lists.md) -- [XML to Standoff Mapping](xml-to-standoff-mapping.md) -- [Gravsearch: Virtual Graph Search](query-language.md) -- [Creating and Editing Resources](editing-resources.md) -- [Creating and Editing Values](editing-values.md) -- [Querying, Creating, and Updating Ontologies](ontology-information.md) -- [TEI/XML](tei-xml.md) -- [Permalinks](permalinks.md) diff --git a/docs/03-apis/index.md b/docs/03-apis/index.md deleted file mode 100644 index ef282e2ea1..0000000000 --- a/docs/03-apis/index.md +++ /dev/null @@ -1,17 +0,0 @@ - - -# The DSP APIs - -The DSP APIs include: - -* The DSP API versions [1](api-v1/index.md) and [2](api-v2/index.md), which is intended to be used by - virtual research environments and other clients for querying and updating - data. -* The DSP [Admin API](api-admin/index.md), which is intended to be used only by the - [DSP-APP](https://github.com/dasch-swiss/dsp-app) user interface, for - administering projects that use Knora as well as Knora itself. -* The DSP [Util API](api-util/index.md), which is intended to be used for information retrieval - about the DSP-stack itself. diff --git a/docs/03-apis/api-admin/groups.md b/docs/03-endpoints/api-admin/groups.md similarity index 100% rename from docs/03-apis/api-admin/groups.md rename to docs/03-endpoints/api-admin/groups.md diff --git a/docs/03-apis/api-admin/introduction.md b/docs/03-endpoints/api-admin/introduction.md similarity index 95% rename from docs/03-apis/api-admin/introduction.md rename to docs/03-endpoints/api-admin/introduction.md index a7d68548dd..7adee6aa99 100644 --- a/docs/03-apis/api-admin/introduction.md +++ b/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 diff --git a/docs/03-apis/api-admin/lists.md b/docs/03-endpoints/api-admin/lists.md similarity index 100% rename from docs/03-apis/api-admin/lists.md rename to docs/03-endpoints/api-admin/lists.md diff --git a/docs/03-apis/api-admin/overview.md b/docs/03-endpoints/api-admin/overview.md similarity index 100% rename from docs/03-apis/api-admin/overview.md rename to docs/03-endpoints/api-admin/overview.md diff --git a/docs/03-apis/api-admin/permissions.md b/docs/03-endpoints/api-admin/permissions.md similarity index 100% rename from docs/03-apis/api-admin/permissions.md rename to docs/03-endpoints/api-admin/permissions.md diff --git a/docs/03-apis/api-admin/projects.md b/docs/03-endpoints/api-admin/projects.md similarity index 100% rename from docs/03-apis/api-admin/projects.md rename to docs/03-endpoints/api-admin/projects.md diff --git a/docs/03-apis/api-admin/stores.md b/docs/03-endpoints/api-admin/stores.md similarity index 100% rename from docs/03-apis/api-admin/stores.md rename to docs/03-endpoints/api-admin/stores.md diff --git a/docs/03-apis/api-admin/users.md b/docs/03-endpoints/api-admin/users.md similarity index 100% rename from docs/03-apis/api-admin/users.md rename to docs/03-endpoints/api-admin/users.md diff --git a/docs/03-endpoints/api-util/health.md b/docs/03-endpoints/api-util/health.md new file mode 100644 index 0000000000..4fd3a176fd --- /dev/null +++ b/docs/03-endpoints/api-util/health.md @@ -0,0 +1,25 @@ + + +# 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" +} +``` diff --git a/docs/03-apis/api-util/version.md b/docs/03-endpoints/api-util/version.md similarity index 98% rename from docs/03-apis/api-util/version.md rename to docs/03-endpoints/api-util/version.md index 0368ced8c6..670b19e1ad 100644 --- a/docs/03-apis/api-util/version.md +++ b/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", diff --git a/docs/03-apis/api-v1/adding-resources.md b/docs/03-endpoints/api-v1/adding-resources.md similarity index 100% rename from docs/03-apis/api-v1/adding-resources.md rename to docs/03-endpoints/api-v1/adding-resources.md diff --git a/docs/03-apis/api-v1/adding-values.md b/docs/03-endpoints/api-v1/adding-values.md similarity index 100% rename from docs/03-apis/api-v1/adding-values.md rename to docs/03-endpoints/api-v1/adding-values.md diff --git a/docs/03-apis/api-v1/authentication.md b/docs/03-endpoints/api-v1/authentication.md similarity index 100% rename from docs/03-apis/api-v1/authentication.md rename to docs/03-endpoints/api-v1/authentication.md diff --git a/docs/03-apis/api-v1/changing-values.md b/docs/03-endpoints/api-v1/changing-values.md similarity index 100% rename from docs/03-apis/api-v1/changing-values.md rename to docs/03-endpoints/api-v1/changing-values.md diff --git a/docs/03-apis/api-v1/delete-resources-and-values.md b/docs/03-endpoints/api-v1/delete-resources-and-values.md similarity index 100% rename from docs/03-apis/api-v1/delete-resources-and-values.md rename to docs/03-endpoints/api-v1/delete-resources-and-values.md diff --git a/docs/03-apis/api-v1/introduction.md b/docs/03-endpoints/api-v1/introduction.md similarity index 100% rename from docs/03-apis/api-v1/introduction.md rename to docs/03-endpoints/api-v1/introduction.md diff --git a/docs/03-apis/api-v1/reading-and-searching-resources.md b/docs/03-endpoints/api-v1/reading-and-searching-resources.md similarity index 99% rename from docs/03-apis/api-v1/reading-and-searching-resources.md rename to docs/03-endpoints/api-v1/reading-and-searching-resources.md index c06552c228..1f3438c459 100644 --- a/docs/03-apis/api-v1/reading-and-searching-resources.md +++ b/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. ``` diff --git a/docs/03-apis/api-v1/reading-values.md b/docs/03-endpoints/api-v1/reading-values.md similarity index 100% rename from docs/03-apis/api-v1/reading-values.md rename to docs/03-endpoints/api-v1/reading-values.md diff --git a/docs/03-apis/api-v1/xml-to-standoff-mapping.md b/docs/03-endpoints/api-v1/xml-to-standoff-mapping.md similarity index 100% rename from docs/03-apis/api-v1/xml-to-standoff-mapping.md rename to docs/03-endpoints/api-v1/xml-to-standoff-mapping.md diff --git a/docs/03-apis/api-v2/authentication.md b/docs/03-endpoints/api-v2/authentication.md similarity index 100% rename from docs/03-apis/api-v2/authentication.md rename to docs/03-endpoints/api-v2/authentication.md diff --git a/docs/03-apis/api-v2/editing-resources.md b/docs/03-endpoints/api-v2/editing-resources.md similarity index 99% rename from docs/03-apis/api-v2/editing-resources.md rename to docs/03-endpoints/api-v2/editing-resources.md index 5f8551f5e7..162a17ed37 100644 --- a/docs/03-apis/api-v2/editing-resources.md +++ b/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: diff --git a/docs/03-apis/api-v2/editing-values.md b/docs/03-endpoints/api-v2/editing-values.md similarity index 97% rename from docs/03-apis/api-v2/editing-values.md rename to docs/03-endpoints/api-v2/editing-values.md index 09d540844e..e2e06eae9e 100644 --- a/docs/03-apis/api-v2/editing-values.md +++ b/docs/03-endpoints/api-v2/editing-values.md @@ -101,7 +101,7 @@ a `/values/` and a custom ID string. 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) @@ -121,7 +121,7 @@ The response is a JSON-LD document containing: To create a link, you must create a `knora-api:LinkValue`, which represents metadata about the link. The property that connects the resource to the `LinkValue` is a link value property, whose name is constructed by adding `Value` to the name of the link property (see -[Links Between Resources](../../02-knora-ontologies/knora-base.md#links-between-resources)). The triple representing the +[Links Between Resources](../../02-dsp-ontologies/knora-base.md#links-between-resources)). The triple representing the direct link between the resources is created automatically. For example, if the link property that should connect the resources is `anything:hasOtherThing`, we can create a link like this: @@ -231,7 +231,7 @@ If no mapping has been defined, only `kb:textValueAsXml` can be returned. ## Creating File Values Knora supports the storage of certain types of data as files, using [Sipi](https://github.com/dhlab-basel/Sipi) -(see [FileValue](../../02-knora-ontologies/knora-base.md#filevalue)). DSP-API v2 currently supports using Sipi to store +(see [FileValue](../../02-dsp-ontologies/knora-base.md#filevalue)). DSP-API v2 currently supports using Sipi to store the following types of files: * Images: JPEG, JPEG2000, TIFF, or PNG which are stored internally as JPEG2000 @@ -294,7 +294,7 @@ For example, to get a JPG thumbnail image that is 150 pixels wide, you would add ### Submit A File Value to Knora A Knora `Representation` (i.e. a resource containing information about a file) must always have exactly one file value -attached to it. (see [Representations](../../02-knora-ontologies/knora-base.md#representations)). Therefore, a request +attached to it. (see [Representations](../../02-dsp-ontologies/knora-base.md#representations)). Therefore, a request to create a new file value must always be submitted as part of a request to create a new resource (see [Creating a Resource](editing-resources.md#creating-a-resource)). You can also update a file value in an existing `Representation`; see [Updating a Value](#updating-a-value). diff --git a/docs/03-apis/api-v2/getting-lists.md b/docs/03-endpoints/api-v2/getting-lists.md similarity index 100% rename from docs/03-apis/api-v2/getting-lists.md rename to docs/03-endpoints/api-v2/getting-lists.md diff --git a/docs/03-apis/api-v2/introduction.md b/docs/03-endpoints/api-v2/introduction.md similarity index 100% rename from docs/03-apis/api-v2/introduction.md rename to docs/03-endpoints/api-v2/introduction.md diff --git a/docs/03-apis/api-v2/knora-iris.md b/docs/03-endpoints/api-v2/knora-iris.md similarity index 97% rename from docs/03-apis/api-v2/knora-iris.md rename to docs/03-endpoints/api-v2/knora-iris.md index 35575c0022..e50f15fc00 100644 --- a/docs/03-apis/api-v2/knora-iris.md +++ b/docs/03-endpoints/api-v2/knora-iris.md @@ -17,7 +17,7 @@ are built into Knora do not contain shortcodes; these ontologies implicitly belong to the Knora system project. Project ID `0000` is reserved for shared ontologies -(see [Shared Ontologies](../../02-knora-ontologies/introduction.md#shared-ontologies)). +(see [Shared Ontologies](../../02-dsp-ontologies/introduction.md#shared-ontologies)). The range of project IDs from `0001` to `00FF` inclusive is reserved for local testing. Thus, the first useful project will be `0100`. @@ -157,7 +157,7 @@ has the following IRIs: ### Shared Ontology IRIs -As explained in [Shared Ontologies](../../02-knora-ontologies/introduction.md#shared-ontologies), +As explained in [Shared Ontologies](../../02-dsp-ontologies/introduction.md#shared-ontologies), a user-created ontology can be defined as shared, meaning that it can be used by multiple projects, and that its creators will not change it in ways that could affect other ontologies or data that are based on it. diff --git a/docs/03-apis/api-v2/ontology-information.md b/docs/03-endpoints/api-v2/ontology-information.md similarity index 97% rename from docs/03-apis/api-v2/ontology-information.md rename to docs/03-endpoints/api-v2/ontology-information.md index 53ac1af03c..c0455fa14d 100644 --- a/docs/03-apis/api-v2/ontology-information.md +++ b/docs/03-endpoints/api-v2/ontology-information.md @@ -271,7 +271,7 @@ in the examples in the next sections. The internal predicates `knora-base:subjectClassConstraint` and `knora-base:objectClassConstraint` (see -[Constraints on the Types of Property Subjects and Objects](../../02-knora-ontologies/knora-base.md#constraints-on-the-types-of-property-subjects-and-objects)) +[Constraints on the Types of Property Subjects and Objects](../../02-dsp-ontologies/knora-base.md#constraints-on-the-types-of-property-subjects-and-objects)) are represented as `knora-api:subjectType` and `knora-api:objectType` in external ontologies. @@ -496,7 +496,7 @@ ontology. In a class definition, cardinalities for properties of the class are represented as in OWL, using objects of type `owl:Restriction`. The supported cardinalities are the ones indicated in -[OWL Cardinalities](../../02-knora-ontologies/knora-base.md#owl-cardinalities). +[OWL Cardinalities](../../02-dsp-ontologies/knora-base.md#owl-cardinalities). The class definitions include cardinalities that are directly defined on each class, as well as cardinalities inherited from base classes. For @@ -964,7 +964,7 @@ updates links will need the IRIs of their link values. The predicate properties of a class, and the predicates `salsah-gui:guiElement` and `salsah-gui:guiAttribute` specify how to configure a GUI element for editing the value of a property. For more information on the -`salsah-gui` ontology, see [The SALSAH GUI Ontology](../../02-knora-ontologies/salsah-gui.md). +`salsah-gui` ontology, see [The SALSAH GUI Ontology](../../02-dsp-ontologies/salsah-gui.md). ## Ontology Updates @@ -1056,7 +1056,7 @@ and the request must have this additional boolean property: "knora-api:isShared" : true ``` -See [Shared Ontologies](../../02-knora-ontologies/introduction.md#shared-ontologies) for details about +See [Shared Ontologies](../../02-dsp-ontologies/introduction.md#shared-ontologies) for details about shared ontologies. A successful response will be a JSON-LD document providing only the @@ -1258,7 +1258,7 @@ HTTP POST to http://host/v2/ontologies/classes `OWL_CARDINALITY_PREDICATE` and `OWL_CARDINALITY_VALUE` must correspond to the supported combinations given in -[OWL Cardinalities](../../02-knora-ontologies/knora-base.md#owl-cardinalities). (The placeholder +[OWL Cardinalities](../../02-dsp-ontologies/knora-base.md#owl-cardinalities). (The placeholder `OWL_CARDINALITY_VALUE` is shown here in quotes, but it should be an unquoted integer.) @@ -1269,7 +1269,7 @@ At least one base class must be provided. When a cardinality on a link property is submitted, an identical cardinality on the corresponding link value property is automatically added (see -[Links Between Resources](../../02-knora-ontologies/knora-base.md#links-between-resources)). +[Links Between Resources](../../02-dsp-ontologies/knora-base.md#links-between-resources)). A successful response will be a JSON-LD document providing the new class definition (but not any of the other entities in the ontology). @@ -1428,7 +1428,7 @@ subproperties, with the exception of file properties (subproperties of `knora-api:hasLinkToValue`). If the property is a link property, the corresponding link value property -(see [Links Between Resources](../../02-knora-ontologies/knora-base.md#links-between-resources)) +(see [Links Between Resources](../../02-dsp-ontologies/knora-base.md#links-between-resources)) will automatically be created. The property definition must specify its `knora-api:objectType`. If the @@ -1446,9 +1446,9 @@ provide `knora-api:subjectType`, which must be a subclass of The predicates `salsah-gui:guiElement` and `salsah-gui:guiAttribute` are optional. If provided, the object of `guiElement` must be one of the OWL named individuals defined in -[The SALSAH GUI Ontology](../../02-knora-ontologies/salsah-gui.md#individuals). Some GUI elements +[The SALSAH GUI Ontology](../../02-dsp-ontologies/salsah-gui.md#individuals). Some GUI elements take required or optional attributes, which are provided as objects of -`salsah-gui:guiAttribute`; see [The SALSAH GUI Ontology](../../02-knora-ontologies/salsah-gui.md) +`salsah-gui:guiAttribute`; see [The SALSAH GUI Ontology](../../02-dsp-ontologies/salsah-gui.md) for details. A successful response will be a JSON-LD document providing the new @@ -1631,13 +1631,13 @@ At least one cardinality must be submitted. `OWL_CARDINALITY_PREDICATE` and `OWL_CARDINALITY_VALUE` must correspond to the supported combinations given in -[OWL Cardinalities](../../02-knora-ontologies/knora-base.md#owl-cardinalities). (The placeholder +[OWL Cardinalities](../../02-dsp-ontologies/knora-base.md#owl-cardinalities). (The placeholder `OWL_CARDINALITY_VALUE` is shown here in quotes, but it should be an unquoted integer.) When a cardinality on a link property is submitted, an identical cardinality on the corresponding link value property is automatically added (see -[Links Between Resources](../../02-knora-ontologies/knora-base.md#links-between-resources)). +[Links Between Resources](../../02-dsp-ontologies/knora-base.md#links-between-resources)). A successful response will be a JSON-LD document providing the new class definition (but not any of the other entities in the ontology). @@ -1686,13 +1686,13 @@ HTTP PUT to http://host/v2/ontologies/cardinalities `OWL_CARDINALITY_PREDICATE` and `OWL_CARDINALITY_VALUE` must correspond to the supported combinations given in -[OWL Cardinalities](../../02-knora-ontologies/knora-base.md#owl-cardinalities). (The placeholder +[OWL Cardinalities](../../02-dsp-ontologies/knora-base.md#owl-cardinalities). (The placeholder `OWL_CARDINALITY_VALUE` is shown here in quotes, but it should be an unquoted integer.) When a cardinality on a link property is submitted, an identical cardinality on the corresponding link value property is automatically added (see -[Links Between Resources](../../02-knora-ontologies/knora-base.md#links-between-resources)). +[Links Between Resources](../../02-dsp-ontologies/knora-base.md#links-between-resources)). A successful response will be a JSON-LD document providing the new class definition (but not any of the other entities in the ontology). @@ -1755,13 +1755,13 @@ HTTP PATCH to http://host/v2/ontologies/cardinalities `OWL_CARDINALITY_PREDICATE` and `OWL_CARDINALITY_VALUE` must correspond to the supported combinations given in -[OWL Cardinalities](../../02-knora-ontologies/knora-base.md#owl-cardinalities). (The placeholder +[OWL Cardinalities](../../02-dsp-ontologies/knora-base.md#owl-cardinalities). (The placeholder `OWL_CARDINALITY_VALUE` is shown here in quotes, but it should be an unquoted integer.) When a cardinality on a link property is submitted, an identical cardinality on the corresponding link value property is automatically added (see -[Links Between Resources](../../02-knora-ontologies/knora-base.md#links-between-resources)). +[Links Between Resources](../../02-dsp-ontologies/knora-base.md#links-between-resources)). A successful response will be a JSON-LD document providing the new class definition (but not any of the other entities in the ontology). @@ -1844,7 +1844,7 @@ The property IRI and the ontology's last modification date must be URL-encoded. If the property is a link property, the corresponding link value property -(see [Links Between Resources](../../02-knora-ontologies/knora-base.md#links-between-resources)) +(see [Links Between Resources](../../02-dsp-ontologies/knora-base.md#links-between-resources)) will automatically be deleted. A successful response will be a JSON-LD document providing only the diff --git a/docs/03-apis/api-v2/permalinks.md b/docs/03-endpoints/api-v2/permalinks.md similarity index 100% rename from docs/03-apis/api-v2/permalinks.md rename to docs/03-endpoints/api-v2/permalinks.md diff --git a/docs/03-apis/api-v2/query-language.md b/docs/03-endpoints/api-v2/query-language.md similarity index 99% rename from docs/03-apis/api-v2/query-language.md rename to docs/03-endpoints/api-v2/query-language.md index 420a980164..e20bd051c2 100644 --- a/docs/03-apis/api-v2/query-language.md +++ b/docs/03-endpoints/api-v2/query-language.md @@ -87,7 +87,8 @@ schema, with one exception (see [Date Comparisons](#date-comparisons)). Gravsearch query results can be requested in the simple or complex schema; see [API Schema](introduction.md#api-schema). -All examples hereafter run with the DSP stack started locally as documented in the section [Getting Started with DSP-API](../../04-publishing-deployment/getting-started.md). If you access another stack, you can check the IRI of the ontology you are targeting by requesting the [ontologies metadata](ontology-information.md#querying-ontology-metadata). +All examples hereafter run with the DSP stack started locally. If you access another stack, you can check +the IRI of the ontology you are targeting by requesting the [ontologies metadata](ontology-information.md#querying-ontology-metadata). ### Using the Simple Schema @@ -376,7 +377,7 @@ The first argument must represent a text value (a `knore-api:TextValue` in the complex schema, or an `xsd:string` in the simple schema). The second argument is a string literal containing the words to be matched, separated by spaces. The function supports the -[Lucene Query Parser syntax](../../07-lucene/index.md). +[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. This function can only be used as the top-level expression in a `FILTER`. diff --git a/docs/03-apis/api-v2/reading-and-searching-resources.md b/docs/03-endpoints/api-v2/reading-and-searching-resources.md similarity index 98% rename from docs/03-apis/api-v2/reading-and-searching-resources.md rename to docs/03-endpoints/api-v2/reading-and-searching-resources.md index ac621b045b..fda39aee7e 100644 --- a/docs/03-apis/api-v2/reading-and-searching-resources.md +++ b/docs/03-endpoints/api-v2/reading-and-searching-resources.md @@ -50,7 +50,7 @@ See the interfaces `Resource` and `ResourcesSequence` in module Text markup can be returned in one of two ways: - As XML embedded in the response, using an [XML to Standoff Mapping](xml-to-standoff-mapping.md). -- As [standoff/RDF](../../02-knora-ontologies/knora-base.md#text-with-standoff-markup), which is DSP-API's internal markup representation. +- As [standoff/RDF](../../02-dsp-ontologies/knora-base.md#text-with-standoff-markup), which is DSP-API's internal markup representation. Embedded XML is the default. @@ -196,7 +196,7 @@ initial value is 0. The response will look like this: } ``` -See [Text with Standoff Markup](../../02-knora-ontologies/knora-base.md#text-with-standoff-markup) +See [Text with Standoff Markup](../../02-dsp-ontologies/knora-base.md#text-with-standoff-markup) for details of the predicates in each standoff tag. If there are more pages of standoff to be requested, the response will contain `knora-api:nextStandoffStartIndex`, @@ -248,7 +248,7 @@ time. Since Knora only versions values, not resource metadata (e.g. Each value will be returned with the permissions that are attached to the **current** version of the value -(see [Permissions](../../02-knora-ontologies/knora-base.md#permissions)). +(see [Permissions](../../02-dsp-ontologies/knora-base.md#permissions)). The returned resource will include the predicate `knora-api:versionDate`, containing the timestamp that was submitted, and its `knora-api:versionArkUrl` @@ -289,7 +289,7 @@ Since Knora only versions values, not resource metadata (e.g. The value will be returned with the permissions that are attached to its **current** version -(see [Permissions](../../02-knora-ontologies/knora-base.md#permissions)). +(see [Permissions](../../02-dsp-ontologies/knora-base.md#permissions)). ### Get the Version History of a Resource @@ -504,7 +504,7 @@ The response to a count query request is an object with one predicate, Knora offers a full-text search that searches through all textual representations of values and `rdfs:label` of resources. Full-text search supports the -[Lucene Query Parser syntax](../../07-lucene/index.md). +[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. Please note that the search diff --git a/docs/03-apis/api-v2/reading-user-permissions.md b/docs/03-endpoints/api-v2/reading-user-permissions.md similarity index 92% rename from docs/03-apis/api-v2/reading-user-permissions.md rename to docs/03-endpoints/api-v2/reading-user-permissions.md index 2c9f47d206..01897e5bae 100644 --- a/docs/03-apis/api-v2/reading-user-permissions.md +++ b/docs/03-endpoints/api-v2/reading-user-permissions.md @@ -18,4 +18,4 @@ These are the possible permission codes, in ascending order: - `CR`: change rights permission (most privileged) Each permission implies all lesser permissions. For more details, see -[Permissions](../../02-knora-ontologies/knora-base.md#permissions). +[Permissions](../../02-dsp-ontologies/knora-base.md#permissions). diff --git a/docs/03-apis/api-v2/tei-xml.md b/docs/03-endpoints/api-v2/tei-xml.md similarity index 100% rename from docs/03-apis/api-v2/tei-xml.md rename to docs/03-endpoints/api-v2/tei-xml.md diff --git a/docs/03-apis/api-v2/xml-to-standoff-mapping.md b/docs/03-endpoints/api-v2/xml-to-standoff-mapping.md similarity index 100% rename from docs/03-apis/api-v2/xml-to-standoff-mapping.md rename to docs/03-endpoints/api-v2/xml-to-standoff-mapping.md diff --git a/docs/04-publishing-deployment/getting-started.md b/docs/04-publishing-deployment/getting-started.md deleted file mode 100644 index fc7a25f1ea..0000000000 --- a/docs/04-publishing-deployment/getting-started.md +++ /dev/null @@ -1,87 +0,0 @@ - - -# Getting Started with DSP-API - -Running DSP-API locally or on a server requires [Docker](https://www.docker.com), which -can be freely downloaded. Please follow the instructions for installing -[Docker Desktop](https://www.docker.com/products/docker-desktop). - -Additional software: - -- [Apple Xcode](https://itunes.apple.com/us/app/xcode/id497799835) -- git -- expect -- sbt -- java 11 - -These can be easily installed on macOS using [Homebrew](https://brew.sh): - -```bash -$ brew install git -$ brew install expect -$ brew install sbt -``` - -To install Adoptopenjdk Java 11 with [Homebrew](https://brew.sh): - -```bash -$ brew tap AdoptOpenJDK/openjdk -$ brew cask install AdoptOpenJDK/openjdk/adoptopenjdk11 -``` - -To pin the version of Java, please add this environment variable to you startup script (bashrc, etc.): - -``` -export JAVA_HOME=`/usr/libexec/java_home -v 11` -``` - -## Choosing a Triplestore - -DSP-API requires a standards-compliant -[RDF](https://www.w3.org/TR/rdf11-primer/) triplestore. A number of -triplestore implementations are available, including [free -software](http://www.gnu.org/philosophy/free-sw.en.html) as well as -proprietary options. - -DSP-API is designed to work with any standards-compliant -triplestore. It is primarily tested with -[Apache Jena Fuseki](https://jena.apache.org), an open source triplestore. - -Other triplestores are planned. - -## Running the DSP-Stack - -Use `git` to clone the DSP-API repository from [Github](https://github.com/dasch-swiss/dsp-api). - -Then from inside the cloned `DSP-API` repository folder, run: - -```bash -$ make stack-up -``` - -## Creating Repositories and Loading Test Data - -To create a test repository called `knora-test` and load test data, run: - -``` -$ make init-db-test -``` - -The scripts called by `make` can be found under `webapi/scripts`. You can -create your own scripts based on these scripts, to create new -repositories and optionally to load existing DSP-compliant RDF data -into them. - -If you need to reload the test data, you need to stop and **delete** the -running Apache Fuseki instance. **Make sure you don't delete important data.** -To stop the instance and delete the repository, run the following command: - -``` -$ make stack-down-delete-volumes -``` - -after which you can start the stack again with `make stack-up`, recreate -the repository and load the data with `make init-db-test`. diff --git a/docs/04-publishing-deployment/index.md b/docs/04-publishing-deployment/index.md deleted file mode 100644 index 36632c890f..0000000000 --- a/docs/04-publishing-deployment/index.md +++ /dev/null @@ -1,11 +0,0 @@ - - -# Deploying DSP-API - -- [Publishing](publishing.md) -- [Getting Started with DSP-API](getting-started.md) -- [Configuration](configuration.md) -- [Updating Repositories When Upgrading DSP-API](updates.md) diff --git a/docs/04-publishing-deployment/publishing.md b/docs/04-publishing-deployment/publishing.md index e99c45b61d..7141f5563e 100644 --- a/docs/04-publishing-deployment/publishing.md +++ b/docs/04-publishing-deployment/publishing.md @@ -10,19 +10,17 @@ DSP is published as a set of [Docker](https://www.docker.com) images under the The following Docker images are published: -- Knora-API: +- DSP-API: - https://hub.docker.com/r/daschswiss/knora-api - Sipi (includes DSP's specific Sipi scripts): - https://hub.docker.com/r/daschswiss/knora-sipi -- Salsah 1: - - https://hub.docker.com/r/daschswiss/knora-salsah1 -- Salsah 2: - - https://hub.docker.com/r/daschswiss/knora-app-web +- DSP-APP: + - https://hub.docker.com/r/daschswiss/dsp-app -Knora's Docker images are published automatically through Github CI each time a +DSP's Docker images are published automatically through Github CI each time a pull-request is merged into the `main` branch. -Each image is tagged with a version number, where the version is derived by +Each image is tagged with a version number, which is derived by using the result of `git describe`. The describe version is built from the `last tag + number of commits since tag + short hash`, e.g., `8.0.0-7-ga7827e9`. diff --git a/docs/architecture/decisions/0001-record-architecture-decisions.md b/docs/05-internals/design/adr/0001-record-architecture-decisions.md similarity index 60% rename from docs/architecture/decisions/0001-record-architecture-decisions.md rename to docs/05-internals/design/adr/0001-record-architecture-decisions.md index ed9d71ee40..bf750bb7ba 100644 --- a/docs/architecture/decisions/0001-record-architecture-decisions.md +++ b/docs/05-internals/design/adr/0001-record-architecture-decisions.md @@ -1,4 +1,4 @@ -# 1. Record architecture decisions +# 1. Record architectural decisions Date: 2022-03-14 @@ -12,7 +12,7 @@ We need to record the architectural decisions made on this project. ## Decision -We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). +We will use Architectural Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). ## Consequences diff --git a/docs/architecture/decisions/0002-change-cache-service-manager-from-akka-actor-to-zlayer.md b/docs/05-internals/design/adr/0002-change-cache-service-manager-from-akka-actor-to-zlayer.md similarity index 100% rename from docs/architecture/decisions/0002-change-cache-service-manager-from-akka-actor-to-zlayer.md rename to docs/05-internals/design/adr/0002-change-cache-service-manager-from-akka-actor-to-zlayer.md diff --git a/docs/architecture/decisions/0003-change-iiif-service-manager-and-sipi-implementation-to-zlayer.md b/docs/05-internals/design/adr/0003-change-iiif-service-manager-and-sipi-implementation-to-zlayer.md similarity index 100% rename from docs/architecture/decisions/0003-change-iiif-service-manager-and-sipi-implementation-to-zlayer.md rename to docs/05-internals/design/adr/0003-change-iiif-service-manager-and-sipi-implementation-to-zlayer.md diff --git a/docs/architecture/decisions/0004-change-triplestore-service-manager-and-fuseki-implementation-to-zlayer.md b/docs/05-internals/design/adr/0004-change-triplestore-service-manager-and-fuseki-implementation-to-zlayer.md similarity index 100% rename from docs/architecture/decisions/0004-change-triplestore-service-manager-and-fuseki-implementation-to-zlayer.md rename to docs/05-internals/design/adr/0004-change-triplestore-service-manager-and-fuseki-implementation-to-zlayer.md diff --git a/docs/architecture/decisions/0004-change-respondermanager-to-a-simple-case-class.md b/docs/05-internals/design/adr/0005-change-respondermanager-to-a-simple-case-class.md similarity index 93% rename from docs/architecture/decisions/0004-change-respondermanager-to-a-simple-case-class.md rename to docs/05-internals/design/adr/0005-change-respondermanager-to-a-simple-case-class.md index 56e57901c2..dd6a5c44be 100644 --- a/docs/architecture/decisions/0004-change-respondermanager-to-a-simple-case-class.md +++ b/docs/05-internals/design/adr/0005-change-respondermanager-to-a-simple-case-class.md @@ -1,4 +1,4 @@ -# 4. Change ResponderManager to a simple case class +# 5. Change ResponderManager to a simple case class Date: 2022-06-06 diff --git a/docs/05-internals/design/api-admin/administration.md b/docs/05-internals/design/api-admin/administration.md index 73116405ee..a733b88ffb 100644 --- a/docs/05-internals/design/api-admin/administration.md +++ b/docs/05-internals/design/api-admin/administration.md @@ -215,7 +215,7 @@ values can be used: 1) **ProjectAdminOntologyAllPermission**: - - description: gives the user the permission to administer + - description: gives the user the permission to administrate the project ontologies - usage: used as a value for the *knora-base:hasPermissions* property. diff --git a/docs/05-internals/design/api-admin/index.md b/docs/05-internals/design/api-admin/index.md deleted file mode 100644 index bac2a9ac35..0000000000 --- a/docs/05-internals/design/api-admin/index.md +++ /dev/null @@ -1,9 +0,0 @@ - - -# Admin API Design - -- [Administration](administration.md) - diff --git a/docs/05-internals/design/api-v1/index.md b/docs/05-internals/design/api-v1/index.md deleted file mode 100644 index e1daa41084..0000000000 --- a/docs/05-internals/design/api-v1/index.md +++ /dev/null @@ -1,9 +0,0 @@ - - -# DSP-API v1 Design - -- [JSON in API v1](json.md) -- [How to Add an API v1 Route](how-to-add-a-route.md) diff --git a/docs/05-internals/design/api-v2/ark.md b/docs/05-internals/design/api-v2/ark.md index 95656b7f82..31c123b711 100644 --- a/docs/05-internals/design/api-v2/ark.md +++ b/docs/05-internals/design/api-v2/ark.md @@ -29,17 +29,17 @@ http://HOST/ark:/NAAN/VERSION/PROJECT/RESOURCE_UUID[/VALUE_UUID][.TIMESTAMP] - `VERSION`: the version of the Knora ARK URL format being used (always 1 for now). -- `PROJECT`: the [short code](../../../03-apis/api-v2/knora-iris.md#project-short-codes) of the +- `PROJECT`: the [short code](../../../03-endpoints/api-v2/knora-iris.md#project-short-codes) of the project that the resource belongs to. - `RESOURCE_UUID`: the resource's unique ID, which is normally a [base64url-encoded](https://tools.ietf.org/html/rfc4648#section-5) UUID, as described in - [IRIs for Data](../../../03-apis/api-v2/knora-iris.md#iris-for-data). + [IRIs for Data](../../../03-endpoints/api-v2/knora-iris.md#iris-for-data). - `VALUE_UUID`: optionally, the `knora-base:valueHasUUID` of one of the resource's values, normally a [base64url-encoded](https://tools.ietf.org/html/rfc4648#section-5) UUID, as described in - [IRIs for Data](../../../03-apis/api-v2/knora-iris.md#iris-for-data). + [IRIs for Data](../../../03-endpoints/api-v2/knora-iris.md#iris-for-data). - `TIMESTAMP`: an optional timestamp indicating that the ARK URL represents the state of the resource at a specific time in the past. The format diff --git a/docs/05-internals/design/api-v2/gravsearch.md b/docs/05-internals/design/api-v2/gravsearch.md index dad4aca225..4fdd1af189 100644 --- a/docs/05-internals/design/api-v2/gravsearch.md +++ b/docs/05-internals/design/api-v2/gravsearch.md @@ -16,7 +16,7 @@ The classes that process Gravsearch queries and results can be found in `org.kno The code that converts Gravserch queries into SPARQL queries, and processes the query results, needs to know the types of the entities that are used in the input query. As explained in -[Type Inference](../../../03-apis/api-v2/query-language.md#type-inference), these types can be inferred, +[Type Inference](../../../03-endpoints/api-v2/query-language.md#type-inference), these types can be inferred, or they can be specified in the query using type annotations. Type inspection is implemented in the package `org.knora.webapi.messages.util.search.gravsearch.types`. @@ -44,7 +44,7 @@ The entities that are considered to need type information are: There are two type inspectors in the pipeline: - `AnnotationReadingGravsearchTypeInspector`: reads - [type annotations](../../../03-apis/api-v2/query-language.md#type-annotations) included in a Gravsearch query. + [type annotations](../../../03-endpoints/api-v2/query-language.md#type-annotations) included in a Gravsearch query. - `InferringGravsearchTypeInspector`: infers the types of entities from the context in which they are used, as well as from ontology information that it requests from `OntologyResponderV2`. @@ -288,7 +288,7 @@ to the maximum allowed page size, the predicate ## Inference -Gravsearch queries support a subset of RDFS reasoning (see [Inference](../../../03-apis/api-v2/query-language.md#inference) in the API documentation +Gravsearch queries support a subset of RDFS reasoning (see [Inference](../../../03-endpoints/api-v2/query-language.md#inference) in the API documentation on Gravsearch). This is implemented as follows: To simulate RDF inference, the API expands the prequery on basis of the available ontologies. For that reason, `SparqlTransformer.transformStatementInWhereForNoInference` expands all `rdfs:subClassOf` and `rdfs:subPropertyOf` statements using `UNION` statements for all subclasses and subproperties from the ontologies (equivalent to `rdfs:subClassOf*` and `rdfs:subPropertyOf*`). diff --git a/docs/05-internals/design/api-v2/index.md b/docs/05-internals/design/api-v2/index.md deleted file mode 100644 index 49aac42e93..0000000000 --- a/docs/05-internals/design/api-v2/index.md +++ /dev/null @@ -1,20 +0,0 @@ - - -# DSP-API v2 Design - -- [API v2 Design Overview](overview.md) -- [Ontology Schemas](ontology-schemas.md) -- [Smart IRIs](smart-iris.md) -- [Content Wrappers](content-wrappers.md) -- [How to Add an API v2 Route](how-to-add-a-route.md) -- [JSON-LD Parsing and Formatting](json-ld.md) -- [Ontology Management](ontology-management.md) -- [Knora and Sipi](sipi.md) -- [Gravsearch Design](gravsearch.md) -- [Standoff Markup](standoff.md) -- [Archival Resource Key (ARK) Identifiers](ark.md) -- [SPARQL Query Design](query-design.md) - diff --git a/docs/05-internals/design/api-v2/ontology-management.md b/docs/05-internals/design/api-v2/ontology-management.md index 9802010a80..69e3841cdf 100644 --- a/docs/05-internals/design/api-v2/ontology-management.md +++ b/docs/05-internals/design/api-v2/ontology-management.md @@ -13,7 +13,7 @@ It is responsible for: - Returning requested ontology entities from the cache. Requests for ontology information never access the triplestore. - Creating and updating ontologies in response to API requests. -- Ensuring that all user-created ontologies are consistent and conform to [knora-base](../../../02-knora-ontologies/knora-base.md). +- Ensuring that all user-created ontologies are consistent and conform to [knora-base](../../../02-dsp-ontologies/knora-base.md). When Knora starts, the ontology responder receives a `LoadOntologiesRequestV2` message. It then: @@ -23,7 +23,7 @@ message. It then: to facilitate validity checks. 2. Checks user-created ontologies for consistency and conformance to `knora-base`, according to the rules described in - [Summary of Restrictions on User-Created Ontologies](../../../02-knora-ontologies/knora-base.md#summary-of-restrictions-on-user-created-ontologies). + [Summary of Restrictions on User-Created Ontologies](../../../02-dsp-ontologies/knora-base.md#summary-of-restrictions-on-user-created-ontologies). 3. Caches all the loaded ontologies using `CacheUtil`. The ontology responder assumes that nothing except itself modifies ontologies @@ -34,7 +34,7 @@ By design, the ontology responder can update only one ontology entity per reques to simplify the necessary validity checks. This requires the client to construct an ontology by submitting a sequence of requests in a certain order, as explained in -[Ontology Updates](../../../03-apis/api-v2/ontology-information.md#ontology-updates). +[Ontology Updates](../../../03-endpoints/api-v2/ontology-information.md#ontology-updates). The ontology responder mainly works with ontologies in the internal schema. However, it knows that some entities in built-in ontologies have hard-coded diff --git a/docs/05-internals/design/api-v2/ontology-schemas.md b/docs/05-internals/design/api-v2/ontology-schemas.md index 5dd2b9d704..c595f86ccb 100644 --- a/docs/05-internals/design/api-v2/ontology-schemas.md +++ b/docs/05-internals/design/api-v2/ontology-schemas.md @@ -7,11 +7,11 @@ ## OntologySchema Type -As explained in [API Schema](../../../03-apis/api-v2/introduction.md#api-schema), +As explained in [API Schema](../../../03-endpoints/api-v2/introduction.md#api-schema), Knora can represent the same RDF data in different forms: an "internal schema" for use in the triplestore, and different "external schemas" for use in Knora API v2. Different schemas use different IRIs, as explained in -[Knora IRIs](../../../03-apis/api-v2/knora-iris.md). Internally, +[Knora IRIs](../../../03-endpoints/api-v2/knora-iris.md). Internally, Knora uses a [SmartIri](smart-iris.md) class to convert IRIs between schemas. diff --git a/docs/05-internals/design/api-v2/overview.md b/docs/05-internals/design/api-v2/overview.md index 21cf85e161..58524054a8 100644 --- a/docs/05-internals/design/api-v2/overview.md +++ b/docs/05-internals/design/api-v2/overview.md @@ -41,7 +41,7 @@ provided. Each schema has its own type IRIs, which are derived from the ones used in the triplestore. For details of these different IRI formats, see -[Knora IRIs](../../../03-apis/api-v2/knora-iris.md). +[Knora IRIs](../../../03-endpoints/api-v2/knora-iris.md). ## Implementation diff --git a/docs/05-internals/design/api-v2/sipi.md b/docs/05-internals/design/api-v2/sipi.md index 162fe3c1ee..fc271ee266 100644 --- a/docs/05-internals/design/api-v2/sipi.md +++ b/docs/05-internals/design/api-v2/sipi.md @@ -27,7 +27,7 @@ The other contents of the expected tokens are described below. The `upload.lua` script is available at Sipi's `upload` route. It processes one or more file uploads submitted to Sipi. It converts uploaded images to JPEG 2000 format, and stores them in Sipi's `tmp` directory. The usage of this script is described in -[Upload Files to Sipi](../../../03-apis/api-v2/editing-values.md#upload-files-to-sipi). +[Upload Files to Sipi](../../../03-endpoints/api-v2/editing-values.md#upload-files-to-sipi). Each time `upload.lua` processes a request, it also deletes old temporary files from `tmp` and (recursively) from any subdirectories. The maximum allowed age of diff --git a/docs/05-internals/design/api-v2/smart-iris.md b/docs/05-internals/design/api-v2/smart-iris.md index 7fa95fdc99..4edc2be064 100644 --- a/docs/05-internals/design/api-v2/smart-iris.md +++ b/docs/05-internals/design/api-v2/smart-iris.md @@ -8,7 +8,7 @@ ## Usage The `SmartIri` trait can be used to parse and validate IRIs, and in -particular for converting [Knora type IRIs](../../../03-apis/api-v2/knora-iris.md) +particular for converting [Knora type IRIs](../../../03-endpoints/api-v2/knora-iris.md) between internal and external schemas. It validates each IRI it parses. To use it, import the following: diff --git a/docs/05-internals/design/api-v2/standoff.md b/docs/05-internals/design/api-v2/standoff.md index ecffa10a09..f30428199f 100644 --- a/docs/05-internals/design/api-v2/standoff.md +++ b/docs/05-internals/design/api-v2/standoff.md @@ -18,7 +18,7 @@ Knora's standoff design is based on these requirements: - Markup should be stored as RDF, so it can be searched and analysed using the same tools that are used with other data managed by Knora. -- In particular, [Gravsearch](../../../03-apis/api-v2/query-language.md) queries should be able +- In particular, [Gravsearch](../../../03-endpoints/api-v2/query-language.md) queries should be able to specify search criteria that refer to the markup tags attached to a text, together with any other search criteria relating to the resource that contains the text. @@ -27,7 +27,7 @@ Knora's standoff design is based on these requirements: ## RDF Design -See [Text with Standoff Markup](../../../02-knora-ontologies/knora-base.md#text-with-standoff-markup). +See [Text with Standoff Markup](../../../02-dsp-ontologies/knora-base.md#text-with-standoff-markup). ## Querying Standoff @@ -57,7 +57,7 @@ To optimise query performance: data structure to represent standoff. This data structure knows nothing about RDF, and each standoff tag contains its XML element name and namespace and those of its attributes. -In Knora, it is possible to define [mappings](../../../03-apis/api-v2/xml-to-standoff-mapping.md) to +In Knora, it is possible to define [mappings](../../../03-endpoints/api-v2/xml-to-standoff-mapping.md) to control how standoff/RDF is converted to XML and vice versa. Different mappings can be used to convert the same standoff/RDF to different sorts of XML documents. `StandoffTagUtilV2` converts between standoff/RDF and XML using mappings, delegating the lower-level work to `XMLToStandoffUtil`. diff --git a/docs/05-internals/design/principles/authentication.md b/docs/05-internals/design/principles/authentication.md index be1cb8fbbd..5e4edc5373 100644 --- a/docs/05-internals/design/principles/authentication.md +++ b/docs/05-internals/design/principles/authentication.md @@ -11,7 +11,7 @@ Authentication is the process of making sure that if someone is accessing something then this someone is actually also the someone he pretends to be. The process of making sure that someone is authorized, i.e. has the permission to access something, is handled as described in -[Authorisation](../../../02-knora-ontologies/knora-base.md#authorisation)). +[Authorisation](../../../02-dsp-ontologies/knora-base.md#authorisation)). ## Implementation diff --git a/docs/05-internals/design/principles/consistency-checking.md b/docs/05-internals/design/principles/consistency-checking.md index 5d488839db..51f240fd7a 100644 --- a/docs/05-internals/design/principles/consistency-checking.md +++ b/docs/05-internals/design/principles/consistency-checking.md @@ -22,7 +22,7 @@ two reasons: triplestore, bypassing Knora. The design of the `knora-base` ontology supports two ways of specifying -constraints on data (see [knora-base: Consistency Checking](../../../02-knora-ontologies/knora-base.md#consistency-checking) +constraints on data (see [knora-base: Consistency Checking](../../../02-dsp-ontologies/knora-base.md#consistency-checking) for details): 1. A property definition should specify the types that are allowed as diff --git a/docs/05-internals/design/principles/design-overview.md b/docs/05-internals/design/principles/design-overview.md index f4c7bc8dbb..eb9a8cfe26 100644 --- a/docs/05-internals/design/principles/design-overview.md +++ b/docs/05-internals/design/principles/design-overview.md @@ -23,19 +23,15 @@ For file storage, it uses [Sipi](http://sipi.io). ## DSP-API Versions -DSP-API supports different versions of its API for working with humanities data: +There are two versions of DSP-API: -- [DSP-API v2](../../../03-apis/api-v2/index.md), the actual DSP-API that should be used -- [DSP-API v1](../../../03-apis/api-v1/index.md), legacy API compatibile with applications - that used the prototype software. +- DSP-API v2, the latest DSP-API that should be used +- DSP-API v1, legacy API compatibile with applications that used the prototype software. -There is also an [Admin API](../../../03-apis/api-admin/index.md) for -administering DSP projects. +There is also an Admin API for administrating DSP projects. -The DSP-API code base includes some functionality that is shared by these different -APIs, as well as separate packages for each API. Internally, Knora APIs v1 and v2 both -use functionality in the admin API. DSP-API v1 uses some functionality from -API v2, but API v2 does not depend on API v1. +Internally, DSP-API v1 and v2 both use functionality in the admin API. DSP-API v1 uses +some functionality from API v2, but API v2 does not depend on API v1. ## Error Handling @@ -103,7 +99,7 @@ actors. However, the design of reply message passing from actors (by using `future2Message`), makes sure that any exceptions thrown inside actors, will reach the route, where they will be handled. -See also [Fuures with Akka](futures-with-akka.md). +See also [Futures with Akka](futures-with-akka.md). ## API Routing @@ -138,7 +134,7 @@ in the appropriate format, and handles any errors. ## Logging -Logging in Knora is configurable through `logback.xml`, allowing fine +Logging in DSP-API is configurable through `logback.xml`, allowing fine grain configuration of what classes / objects should be logged from which level. The Akka Actors use [Akka Logging](https://doc.akka.io/docs/akka/current/logging.html) diff --git a/docs/05-internals/design/principles/index.md b/docs/05-internals/design/principles/index.md deleted file mode 100644 index 6c4c734d01..0000000000 --- a/docs/05-internals/design/principles/index.md +++ /dev/null @@ -1,15 +0,0 @@ - - -# DSP-API Design Principles - -- [Design Overview](design-overview.md) -- [Futures with Akka](futures-with-akka.md) -- [HTTP Module](http-module.md) -- [Store Module](store-module.md) -- [RDF Processing API](rdf-api.md) -- [Triplestore Updates](triplestore-updates.md) -- [Consistency Checking](consistency-checking.md) -- [Authentication](authentication.md) diff --git a/docs/05-internals/development/index.md b/docs/05-internals/development/index.md deleted file mode 100644 index c640e33c83..0000000000 --- a/docs/05-internals/development/index.md +++ /dev/null @@ -1,16 +0,0 @@ - - -# Development - -- [Overview](overview.md) -- [Build and Running](building-and-running.md) -- [Setup Visual Studio Code for development of Knora](vscode-config.md) -- [Testing](testing.md) -- [Docker Cheat Sheet](docker-cheat-sheet.md) -- [Monitoring Knora](monitoring.md) -- [Starting the Knora Stack inside Docker Container](docker-compose.md) -- [Updating Repositories](updating-repositories.md) -- [Generating Client Test Data](generating-client-test-data.md) diff --git a/docs/05-internals/development/updating-repositories.md b/docs/05-internals/development/updating-repositories.md index 976e54506a..9ecfc80e4c 100644 --- a/docs/05-internals/development/updating-repositories.md +++ b/docs/05-internals/development/updating-repositories.md @@ -16,7 +16,7 @@ ## Design As explained in -[Knora Ontology Versions](../../02-knora-ontologies/knora-base.md#knora-ontology-versions), +[Knora Ontology Versions](../../02-dsp-ontologies/knora-base.md#knora-ontology-versions), the `knora-base` ontology contains a version string to ensure compatibility between a repository and a given version of Knora. The same version string is therefore hard-coded in the Knora source code, in the string constant diff --git a/docs/06-sipi/sipi-and-dsp-api.md b/docs/06-sipi/sipi-and-dsp-api.md index 881a70beba..66640f73c8 100644 --- a/docs/06-sipi/sipi-and-dsp-api.md +++ b/docs/06-sipi/sipi-and-dsp-api.md @@ -27,9 +27,9 @@ A file is first uploaded to Sipi, then its metadata is submitted to DSP. The implementation of this procedure is described in [DSP-API and Sipi](../05-internals/design/api-v2/sipi.md). Instructions for the client are given in -[Creating File Values](../03-apis/api-v2/editing-values.md#creating-file-values) +[Creating File Values](../03-endpoints/api-v2/editing-values.md#creating-file-values) (for DSP-API v2) and in -[Adding Resources with Image Files](../03-apis/api-v1/adding-resources.md#adding-resources-with-image-files) +[Adding Resources with Image Files](../03-endpoints/api-v1/adding-resources.md#adding-resources-with-image-files) (for API v1). ## Retrieving Files from Sipi @@ -37,7 +37,7 @@ for the client are given in ### File URLs in API v2 In DSP-API v2, image file URLs are provided in [IIIF](https://iiif.io/) format. In the simple -[ontology schema](../03-apis/api-v2/introduction.md#api-schema), a file value is simply +[ontology schema](../03-endpoints/api-v2/introduction.md#api-schema), a file value is simply a IIIF URL that can be used to retrieve the file from Sipi. In the complex schema, it is a `StillImageFileValue` with additional properties that the client can use to construct different IIIF URLs, e.g. at different resolutions. See the `knora-api` ontology for details. diff --git a/docs/07-lucene/index.md b/docs/07-lucene/index.md deleted file mode 100644 index 6142c037f8..0000000000 --- a/docs/07-lucene/index.md +++ /dev/null @@ -1,11 +0,0 @@ - - -# Lucene - -The Lucene full-text index provided by the triplestore is used to perform full-text searches in Knora. -The exact behavior can be different depending on the triplestore. - -* [Lucene Query Parser Syntax](lucene-query-parser-syntax.md) diff --git a/docs/07-lucene/lucene-query-parser-syntax.md b/docs/07-lucene/lucene-query-parser-syntax.md index abdcb220b5..7ec3e2d32e 100644 --- a/docs/07-lucene/lucene-query-parser-syntax.md +++ b/docs/07-lucene/lucene-query-parser-syntax.md @@ -1,4 +1,9 @@ -# Lucene Query Parser Syntax +# Lucene + +The Lucene full-text index provided by the triplestore is used to perform full-text searches in Knora. +The exact behavior can be different depending on the triplestore. + +## Lucene Query Parser Syntax Full-text searches in Knora are based on Lucene. Therefore, full-text searches support the diff --git a/docs/faq/faq-fig1.dot b/docs/08-faq/faq-fig1.dot similarity index 100% rename from docs/faq/faq-fig1.dot rename to docs/08-faq/faq-fig1.dot diff --git a/docs/faq/faq-fig2.dot b/docs/08-faq/faq-fig2.dot similarity index 100% rename from docs/faq/faq-fig2.dot rename to docs/08-faq/faq-fig2.dot diff --git a/docs/faq/index.md b/docs/08-faq/index.md similarity index 78% rename from docs/faq/index.md rename to docs/08-faq/index.md index da18c24129..4fe3efd6c4 100644 --- a/docs/faq/index.md +++ b/docs/08-faq/index.md @@ -19,7 +19,7 @@ is better suited to its goal of facilitating data reuse. If your XML files represent text with markup (e.g. [TEI/XML](http://www.tei-c.org/)), the recommended approach is to allow Knora to store it as [Standoff/RDF](../01-introduction/standoff-rdf.md). This will allow both text and -markup to be searched using [Gravsearch](../03-apis/api-v2/query-language.md). Knora +markup to be searched using [Gravsearch](../03-endpoints/api-v2/query-language.md). Knora can also regenerate, at any time, an XML document that is equivalent to the original one. If you have XML that simply represents structured data (rather than text documents), @@ -27,34 +27,34 @@ we recommend converting it to Knora resources, which are stored as RDF. ## Triplestores -### Which triplestores can be used with Knora? +### Which triplestores can be used with DSP-API? -Knora is tested with [Apache Jena Fuseki](https://jena.apache.org/). +DSP-API is tested with [Apache Jena Fuseki](https://jena.apache.org/). -## Knora Ontologies +## DSP Ontologies ### Can a project use classes or properties defined in another project's ontology? -Knora does not allow this to be done with project-specific ontologies. +DSP-API does not allow this to be done with project-specific ontologies. Each project must be free to change its own ontologies, but this is not possible if they have been used in ontologies or data created by other projects. However, an ontology can be defined as shared, meaning that it can be used by multiple projects, and that its creators promise not to change it in ways that could affect other ontologies or data that are based on it. See -[Shared Ontologies](../02-knora-ontologies/introduction.md#shared-ontologies) for details. +[Shared Ontologies](../02-dsp-ontologies/introduction.md#shared-ontologies) for details. There will be a standardisation process for shared ontologies (issue [#523](https://github.com/dasch-swiss/dsp-api/issues/523)). -### Why doesn't Knora use `rdfs:domain` and `rdfs:range` for consistency checking? +### Why doesn't DSP-API use `rdfs:domain` and `rdfs:range` for consistency checking? -Knora's consistency checking uses Knora-specific properties, which are called +DSP-API's consistency checking uses specific properties, which are called `knora-base:subjectClassConstraint` and `knora-base:objectClassConstraint` in the `knora-base` ontology, and `knora-api:subjectType` and `knora-api:objectType` in the `knora-api` ontologies. These properties express *restrictions* on the possible subjects and objects of a property. If a property's subject or object -does not conform to the specified restrictions, Knora considers it an error. +does not conform to the specified restrictions, DSP-API considers it an error. In contrast, [the RDF Schema specification says](https://www.w3.org/TR/rdf-schema/#ch_domainrange) @@ -81,10 +81,10 @@ an RDFS reasoner would infer that `data:oxygen` is actually an Therefore, `rdfs:domain` and `rdfs:range` are not suitable for consistency checking. -Knora therefore uses its own properties, along with +DSP-API therefore uses its own properties, along with OWL cardinalities, which it interprets according to a "closed world" -assumption. Knora performs its own consistency checks to enforce -these restrictions. Knora repositories can also take advantage of +assumption. DSP-API performs its own consistency checks to enforce +these restrictions. DSP-API repositories can also take advantage of triplestore-specific consistency checking mechanisms. The constraint language [SHACL](https://www.w3.org/TR/shacl/) may someday @@ -96,8 +96,8 @@ For further discussion of these issues, see ### Can a user-created property be an `owl:TransitiveProperty`? -No, because in Knora, a resource controls its properties. This basic -assumption is what allows Knora to enforce permissions and transaction +No, because in DSP-API, a resource controls its properties. This basic +assumption is what allows DSP-API to enforce permissions and transaction integrity. The concept of a transitive property would break this assumption. Consider a link property `hasLinkToFoo` that is defined as an `owl:TransitiveProperty`, @@ -117,19 +117,21 @@ inferred. But this should not be allowed, because the owner of `Foo2` does not have permission to add a link to `Foo1`. Moreover, even if the owner of `Foo2` did have that permission, the inferred -link would not have a `knora-base:LinkValue` (a reification), which every Knora +link would not have a `knora-base:LinkValue` (a reification), which every link must have. The `LinkValue` is what stores metadata about the creator of the link, its creation date, its permissions, and so on -(see [LinkValue](../02-knora-ontologies/knora-base.md#linkvalue)). +(see [LinkValue](../02-dsp-ontologies/knora-base.md#linkvalue)). -Finally, if an update to one resource could modify another -resource, this would violate Knora's model of transaction integrity, in which +Finally, if an update to a resource could modify another +resource, this would violate DSP-API's model of transaction integrity, in which each transaction can modify only one resource (see [Application-level Locking](../05-internals/design/principles/triplestore-updates.md#application-level-locking)). -Knora would then be unable to ensure that concurrent transactions do not +DSP-API would then be unable to ensure that concurrent transactions do not interfere with each other. -### Should `0.0.0.0` or `localhost` be used to access Knora locally +## General + +### Why should I use `0.0.0.0` instead of `localhost` when running the DSP stack locally? When running locally with the default configuration, if you want authorization cookies to be shared between `webapi` and `sipi`, then both `webapi` and `sipi` must be accessed diff --git a/docs/00-release-notes/index.md b/docs/09-release-notes/index.md similarity index 100% rename from docs/00-release-notes/index.md rename to docs/09-release-notes/index.md diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index dbfc8dc5c9..0000000000 --- a/docs/index.md +++ /dev/null @@ -1,14 +0,0 @@ - - -* [Introduction](01-introduction/index.md) -* [DSP Ontologies](02-knora-ontologies/index.md) -* [DSP APIs](03-apis/index.md) -* [Publishing and Deployment](04-publishing-deployment/index.md) -* [DSP-API Internals](05-internals/design/principles/index.md) -* [Sipi](06-sipi/index.md) -* [Lucene](07-lucene/index.md) -* [Frequently Asked Questions](faq/index.md) -* [Release Notes](00-release-notes/index.md) diff --git a/mkdocs.yml b/mkdocs.yml index 92a0dfc56f..417d122fe9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,103 +6,93 @@ edit_uri: blob/main/docs/ copyright: "Copyright © 2021 - 2022 Swiss National Data and Service Center for the Humanities and/or DaSCH Service Platform contributors." nav: - - Home: index.md - Introduction: - - Index: 01-introduction/index.md - - What is DSP?: 01-introduction/what-is-knora.md + - What is DSP?: 01-introduction/what-is-dsp.md - File Formats in DSP-API: 01-introduction/file-formats.md - Standoff/RDF Text Markup: 01-introduction/standoff-rdf.md - An Example Project: 01-introduction/example-project.md - DSP Ontologies: - - Index: 02-knora-ontologies/index.md - - Introduction: 02-knora-ontologies/introduction.md - - The Knora Base Ontology: 02-knora-ontologies/knora-base.md - - The SALSAH GUI Ontology: 02-knora-ontologies/salsah-gui.md - - APIs: - - The DSP APIs: - - Index: 03-apis/index.md - - API V1: - - Index: 03-apis/api-v1/index.md - - Introduction: 03-apis/api-v1/introduction.md - - Authentication: 03-apis/api-v1/authentication.md - - Reading and Searching Resources: 03-apis/api-v1/reading-and-searching-resources.md - - XML to Standoff Mapping: 03-apis/api-v1/xml-to-standoff-mapping.md - - Adding Resources: 03-apis/api-v1/adding-resources.md - - Reading and Searching Resources: 03-apis/api-v1/reading-and-searching-resources.md - - Reading Values: 03-apis/api-v1/reading-values.md - - Adding Values: 03-apis/api-v1/adding-values.md - - Changing Values: 03-apis/api-v1/changing-values.md - - Deleting Resources and Values: 03-apis/api-v1/delete-resources-and-values.md - - API V2: - - Index: 03-apis/api-v2/index.md - - Introduction: 03-apis/api-v2/introduction.md - - Authentication: 03-apis/api-v2/authentication.md - - Knora IRIs: 03-apis/api-v2/knora-iris.md - - Reading and Searching Resources: 03-apis/api-v2/reading-and-searching-resources.md - - Reading the User's Permissions on Resources and Values: 03-apis/api-v2/reading-user-permissions.md - - Getting Lists: 03-apis/api-v2/getting-lists.md - - XML to Standoff Mapping: 03-apis/api-v2/xml-to-standoff-mapping.md - - Gravsearch - Virtual Graph Search: 03-apis/api-v2/query-language.md - - Creating and Editing Resources: 03-apis/api-v2/editing-resources.md - - Creating and Editing Values: 03-apis/api-v2/editing-values.md - - Querying, Creating, and Updating Ontologies: 03-apis/api-v2/ontology-information.md - - TEI/XML: 03-apis/api-v2/tei-xml.md - - Permalinks: 03-apis/api-v2/permalinks.md + - Introduction: 02-dsp-ontologies/introduction.md + - The Knora Base Ontology: 02-dsp-ontologies/knora-base.md + - The SALSAH GUI Ontology: 02-dsp-ontologies/salsah-gui.md + - DSP-API Endpoints: + - DSP-API V1: + - Introduction: 03-endpoints/api-v1/introduction.md + - Authentication: 03-endpoints/api-v1/authentication.md + - Reading and Searching Resources: 03-endpoints/api-v1/reading-and-searching-resources.md + - XML to Standoff Mapping: 03-endpoints/api-v1/xml-to-standoff-mapping.md + - Adding Resources: 03-endpoints/api-v1/adding-resources.md + - Reading and Searching Resources: 03-endpoints/api-v1/reading-and-searching-resources.md + - Reading Values: 03-endpoints/api-v1/reading-values.md + - Adding Values: 03-endpoints/api-v1/adding-values.md + - Changing Values: 03-endpoints/api-v1/changing-values.md + - Deleting Resources and Values: 03-endpoints/api-v1/delete-resources-and-values.md + - DSP-API V2: + - Introduction: 03-endpoints/api-v2/introduction.md + - Authentication: 03-endpoints/api-v2/authentication.md + - Knora IRIs: 03-endpoints/api-v2/knora-iris.md + - Reading and Searching Resources: 03-endpoints/api-v2/reading-and-searching-resources.md + - Reading the User's Permissions on Resources and Values: 03-endpoints/api-v2/reading-user-permissions.md + - Getting Lists: 03-endpoints/api-v2/getting-lists.md + - XML to Standoff Mapping: 03-endpoints/api-v2/xml-to-standoff-mapping.md + - Gravsearch - Virtual Graph Search: 03-endpoints/api-v2/query-language.md + - Creating and Editing Resources: 03-endpoints/api-v2/editing-resources.md + - Creating and Editing Values: 03-endpoints/api-v2/editing-values.md + - Querying, Creating, and Updating Ontologies: 03-endpoints/api-v2/ontology-information.md + - TEI/XML: 03-endpoints/api-v2/tei-xml.md + - Permalinks: 03-endpoints/api-v2/permalinks.md - Admin API: - - Index: 03-apis/api-admin/index.md - - Introduction: 03-apis/api-admin/introduction.md - - Overview: 03-apis/api-admin/overview.md - - Users Endpoint: 03-apis/api-admin/users.md - - Projects Endpoint: 03-apis/api-admin/projects.md - - Groups Endpoint: 03-apis/api-admin/groups.md - - Lists Endpoint: 03-apis/api-admin/lists.md - - Permissions Endpoint: 03-apis/api-admin/permissions.md - - Stores Endpoint: 03-apis/api-admin/stores.md + - Introduction: 03-endpoints/api-admin/introduction.md + - Overview: 03-endpoints/api-admin/overview.md + - Users Endpoint: 03-endpoints/api-admin/users.md + - Projects Endpoint: 03-endpoints/api-admin/projects.md + - Groups Endpoint: 03-endpoints/api-admin/groups.md + - Lists Endpoint: 03-endpoints/api-admin/lists.md + - Permissions Endpoint: 03-endpoints/api-admin/permissions.md + - Stores Endpoint: 03-endpoints/api-admin/stores.md - Util API: - - Index: 03-apis/api-util/index.md - - Health: 03-apis/api-util/health.md - - Version: 03-apis/api-util/version.md + - Health: 03-endpoints/api-util/health.md + - Version: 03-endpoints/api-util/version.md - Publishing and Deployment: - - Index: 04-publishing-deployment/index.md - Publishing: 04-publishing-deployment/publishing.md - - Getting Started with DSP-API: 04-publishing-deployment/getting-started.md - Configuration: 04-publishing-deployment/configuration.md - Updating Repositories when Upgrading DSP-API: 04-publishing-deployment/updates.md - DSP Internals: - Design: - - DSP-API Design Principles: - - Index: 05-internals/design/principles/index.md - - Design Overview: 05-internals/design/principles/design-overview.md - - Futures with Akka: 05-internals/design/principles/futures-with-akka.md - - HTTP Module: 05-internals/design/principles/http-module.md - - Store Module: 05-internals/design/principles/store-module.md - - Triplestore Updates: 05-internals/design/principles/triplestore-updates.md - - Consistency Checking: 05-internals/design/principles/consistency-checking.md - - Authentication: 05-internals/design/principles/authentication.md - - RDF Processing API: 05-internals/design/principles/rdf-api.md - - API V1 Design: - - Index: 05-internals/design/api-v1/index.md - - How to Add an API v1 Route: 05-internals/design/api-v1/how-to-add-a-route.md - - JSON in API v1: 05-internals/design/api-v1/json.md - - API V2 Design: - - Index: 05-internals/design/api-v2/index.md - - API v2 Design Overview: 05-internals/design/api-v2/overview.md - - Ontology Schemas: 05-internals/design/api-v2/ontology-schemas.md - - Smart IRIs: 05-internals/design/api-v2/smart-iris.md - - Content Wrappers: 05-internals/design/api-v2/content-wrappers.md - - How to Add an API v2 Route: 05-internals/design/api-v2/how-to-add-a-route.md - - JSON-LD Parsing and Formatting: 05-internals/design/api-v2/json-ld.md - - Ontology Management: 05-internals/design/api-v2/ontology-management.md - - DSP-API and Sipi: 05-internals/design/api-v2/sipi.md - - Gravsearch Design: 05-internals/design/api-v2/gravsearch.md - - Standoff Markup: 05-internals/design/api-v2/standoff.md - - Archival Resource Key (ARK) Identifiers: 05-internals/design/api-v2/ark.md - - SPARQL Query Design: 05-internals/design/api-v2/query-design.md - - Admin API Design: - - Index: 05-internals/design/api-admin/index.md - - Administration: 05-internals/design/api-admin/administration.md + - Architectural Decision Records (ADR): + - 0001 Record Architectural Decisions: 05-internals/design/adr/0001-record-architecture-decisions.md + - 0002 Change Cache Service Manager from Akka-Actor to ZLayer: 05-internals/design/adr/0002-change-cache-service-manager-from-akka-actor-to-zlayer.md + - 0003 Change IIIF Service Manager and Sipi implementation to zlayer: 05-internals/design/adr/0003-change-iiif-service-manager-and-sipi-implementation-to-zlayer.md + - 0004 Change Triplestore Service Manager and Fuseki implementation to ZLayer: 05-internals/design/adr/0004-change-triplestore-service-manager-and-fuseki-implementation-to-zlayer.md + - 0005 Change ResponderManager to a simple case class: 05-internals/design/adr/0005-change-respondermanager-to-a-simple-case-class.md + - DSP-API Design Principles: + - Design Overview: 05-internals/design/principles/design-overview.md + - Futures with Akka: 05-internals/design/principles/futures-with-akka.md + - HTTP Module: 05-internals/design/principles/http-module.md + - Store Module: 05-internals/design/principles/store-module.md + - Triplestore Updates: 05-internals/design/principles/triplestore-updates.md + - Consistency Checking: 05-internals/design/principles/consistency-checking.md + - Authentication: 05-internals/design/principles/authentication.md + - RDF Processing API: 05-internals/design/principles/rdf-api.md + - DSP-API V1 Design: + - How to Add an API v1 Route: 05-internals/design/api-v1/how-to-add-a-route.md + - JSON in API v1: 05-internals/design/api-v1/json.md + - DSP-API V2 Design: + - API v2 Design Overview: 05-internals/design/api-v2/overview.md + - Ontology Schemas: 05-internals/design/api-v2/ontology-schemas.md + - Smart IRIs: 05-internals/design/api-v2/smart-iris.md + - Content Wrappers: 05-internals/design/api-v2/content-wrappers.md + - How to Add an API v2 Route: 05-internals/design/api-v2/how-to-add-a-route.md + - JSON-LD Parsing and Formatting: 05-internals/design/api-v2/json-ld.md + - Ontology Management: 05-internals/design/api-v2/ontology-management.md + - DSP-API and Sipi: 05-internals/design/api-v2/sipi.md + - Gravsearch Design: 05-internals/design/api-v2/gravsearch.md + - Standoff Markup: 05-internals/design/api-v2/standoff.md + - Archival Resource Key (ARK): 05-internals/design/api-v2/ark.md + - SPARQL Query Design: 05-internals/design/api-v2/query-design.md + - Admin API Design: + - Administration: 05-internals/design/api-admin/administration.md - Development: - - Index: 05-internals/development/index.md - Overview: 05-internals/development/overview.md - Build and Running: 05-internals/development/building-and-running.md - Setup Visual Studio Code for development of DSP-API: 05-internals/development/vscode-config.md @@ -114,15 +104,14 @@ nav: - Generating Client Test Data: 05-internals/development/generating-client-test-data.md - Third-Party Dependencies: 05-internals/development/third-party.md - SIPI: - - Index: 06-sipi/index.md + - Overview: 06-sipi/index.md - Setting Up Sipi for DSP-API: 06-sipi/setup-sipi-for-dsp-api.md - Interaction between Sipi and DSP-API: 06-sipi/sipi-and-dsp-api.md - Lucene: - - Overview: 07-lucene/index.md - Lucene Query Parser Syntax: 07-lucene/lucene-query-parser-syntax.md - - Frequently Asked Questions: faq/index.md + - Frequently Asked Questions: 08-faq/index.md - Release Notes: - - Changelog: 00-release-notes/index.md + - Changelog: 09-release-notes/index.md plugins: - include-markdown