Preliminaries
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14, RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here.
This document is licensed under CC-BY-ND-4.0 (via SPDX).
The style of this documentation is adapted from OpenAPI 3.0.2 specification.
Status of this Document
The current version of this document is: 0.0.1.
It refers to the following TextAPI version: 1.4.0
Definitions
Cardinalities
| Cardinality | Description | REQUIRED |
|---|---|---|
| 1 | exactly one | yes |
| ? | zero or one | no |
Data Types
| Type | Description |
|---|---|
| […] | array |
| int | integer |
| string | a sequence of characters, MAY be empty |
| boolean | true or false |
| URL | a valid URL pointing to a resource |
| MIME type | a valid MIME type according to IANA. See MDN |
| semver | a string matching the pattern ^\d+\.\d+\.\d+$, representing a semantic version number |
| iso639-3 | alpha-3 language code according to ISO 639-3 |
| SPDX | a valid SPDX identifier (see https://spdx.org/licenses/) or – if not applicable, e.g. for copyrighted resources – restricted |
URI Syntax
The URI Syntax is used according to the one described at IIIF.
We encourage to allow for IRI (an internationalizes superset or URI) on client side.
Delivery Service
The TextAPI delivery service is the description of endpoints.
It is REQUIRED to use the https protocol.
Collection
Returns the Collection Object.
https://eupt-dev.sub.uni-goettingen.de/api/eupt/collection.json
Manifest
Returns a Manifest Object.
https://eupt-dev.sub.uni-goettingen.de/api/eupt/KTU_1_14/manifest.json
Item
Returns an Item Object.
https://eupt-dev.sub.uni-goettingen.de/api/eupt/KTU_1_14/1/full.json
Schema
All fields that are not explicitly REQUIRED or described with MUST or SHALL are considered OPTIONAL. It is RECOMMENDED, however, to provide as much information as possible.
Actor Object
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/actor.jsonld |
| role | 1 | [string] | the role of a personal entity in relation to the parent object, MUST be collector in case of collections |
| name | 1 | string | the principal name of the person |
Collection Object
A collection contains a curated list of texts. It is REQUIRED to be served at the corresponding endpoint.
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/collection.jsonld |
| textapi | 1 | semver | the TextAPI version covered by the implementation |
| id | 1 | URL | URL pointing to this collection |
| title | 1 | [Title Object] | the title of the collection. the main title MUST be the first one in the array |
| collector | 1 | [Actor Object] | a personal entity responsible for the collection (collector) |
| description | ? | string | description of the collection |
| sequence | 1 | [Sequence Object] | a set of manifests included in this collection |
Content Object
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/content.jsonld |
| url | 1 | URL | URL pointing to the content |
| type | 1 | MIME type | a MIME type. either text/html;type=transcription or text/html;type=philology |
Idref Object
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/idref.jsonld |
| type | 1 | string | short title of the referenced authority |
| id | 1 | string | the main ID referenced |
Item Object
It is REQUIRED to be served at the corresponding endpoint.
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/item.jsonld |
| textapi | 1 | semver | version number satisfied by the implementation |
| id | 1 | URL | URL pointing to this item |
| type | 1 | string | one of section, page, full |
| lang | 1 | [iso639-3] | language codes describing the resource |
| content | 1 | [Content Object] | different serializations of the item, e.g. HTML, plain text, XML, … |
License Object
The license or any other appropriate rights statement the resources is served under. It is REQUIRED to use one of SPDX.
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| id | 1 | SPDX | an SPDX identifier |
Manifest Object
This is the main object in the schema to represent a single text, its derivatives (e.g. html) and therefore containing the metadata. It is REQUIRED to be served at the corresponding endpoint.
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/manifest.jsonld |
| textapi | 1 | semver | version number satisfied by the implementation |
| id | 1 | URL | URL pointing to this manifest |
| label | 1 | string | human-readable name or title |
| sequence | 1 | [Sequence Object] | a sequence of items |
| license | 1 | [License Object] | license under which the resource MUST be used |
Repository Object
A repository archiving the source or derivates, e.g. facsimiles or digitized versions.
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/repository.jsonld |
| url | 1 | URL | URL pointing to the website of the institution |
| baseUrl | 1 | URL | a base URL where id can be resolved |
| id | 1 | string | the identifier at the hosting institution |
Sequence Object
Represents a sequence of manifests or items. Within a manifest it SHOULD contain items exclusively.
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/sequence.jsonld |
| id | 1 | URL | URL to find a Manifest Object or Item Object |
| type | 1 | string | one of manifest, item |
| label | 1 | string | human-readable name or title. SHOULD correspond to the collection’s/manifest’s/item’s label or title property |
Support Object
Any material supporting the view is described and referenced in this object. This encompasses fonts and CSS.
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/support.jsonld |
| type | 1 | one of font, css |
|
| mime | 1 | MIME type | the MIME type for the resource |
| url | 1 | URL | URL pointing to the resource |
Title Object
| Field Name | Cardinality | Type | Description |
|---|---|---|---|
| @context | 1 | URL | the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/textapi/specs/-/raw/main/jsonld/title.jsonld |
| title | 1 | string | a single title |
| type | 1 | string | one of main, sub. if several titles are provided, at least one of them MUST have the type main |
Appendix
Class Diagram
A class diagram will be added in version 1.0.0.