## 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.

The style of this documentation is adapted from OpenAPI 3.0.2 specification.

## Status of this Document

The current version: 0.4.0.

## Definitions

### Cardinalities

Cardinality Description REQUIRED
1 exactly one yes
? zero or one no

### Data Types

Type Description
[…] array
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 a collection object.

https://{server}{/prefix}/{collection}/collection.json

### Manifest

Returns a manifest object.

https://{server}{/prefix}/{collection}/{manifest}/manifest.json

### Item

Returns an item object.

https://{server}{/prefix}/{collection}/{manifest}/{item}/{revision}/item.json

https://{server}{/prefix}/{collection}/{manifest}/{item}/latest/item.json

when a single item represents a complete text (whatever this means), the corresponding endpoint is REQUIRED to be available at

https://{server}{/prefix}/{collection}/{manifest}/{revision}/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.

### 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/emo/text-api/-/raw/main/jsonld/collection.jsonld
textapi 1 semver the TextAPI version covered by the implementation
title 1 [Title Object] the title of the collection
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
annotationCollection ? URL URL pointing to an Annotation Collection for the complete collection
modules ? [Module Object] the modules in use for this collection

#### Sequence Object

Represents a sequence of collections, manifests or items. Within a manifest it SHOULD contain items exclusively. An item that represents a complete manifest (i.e. that has the type full) MUST be the first item in the sequence.

Field Name Cardinality Type Description
@context 1 URL the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/emo/text-api/-/raw/main/jsonld/sequence.jsonld
id 1 URL URL to find a Manifest Object, Collection Object or Item Object
type 1 string one of collection, manifest, item
label ? string human-readable name or title. SHOULD correspond to the collection’s/manifest’s/item’s label or title property

#### Module Object

Gives information about which API modules are in use. If the Module Object is set, at least one modules has to be selected.

Note: The list of modules is contiuously enhanced.

Field Name Cardinality Type Description
edition-manuscripts ? boolean true or false
edition-prints ? boolean true or false

### 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/emo/text-api/-/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
actor ? [Actor Object] a personal entity related to the document (e.g. author or editor)
repository ? [Repository Object] a repository archiving the document(s) or source
image ? Image Object an image representing the resources (e.g. thumbnail or logo)
support ? [Support Object]
description ? string a short description of the object
annotationCollection ? URL URL pointing to an Annotation Collection for the complete manifest
modules ? [Module Object] the modules in use for this manifest.has to correspond to the Collection Object’s modules entry

#### 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/emo/text-api/-/raw/main/jsonld/repository.jsonld
label ? string the label as given by the hosting institution
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

#### Actor Object

Field Name Cardinality Type Description
@context 1 URL the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/emo/text-api/-/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
id ? string internal identifier
idref ? [Idref Object] authority files related to the person

A set of metadata describing the source or its context. Mainly used for key-value pairs.

Field Name Cardinality Type Description
key 1 string label
value ? string property. MUST be set if the object has no metadata field. MUST NOT be set if the object has a metadata field.
metadata ? [Metadata Object] further metadata that is subordinant to the current metadata entry. MUST be set if the object has no value field. MUST NOT be set if the object has a value field.

#### Image Object

An image representing the source or its provider. It is recommended that a IIIF Image API service is available for this image for manipulations such as resizing.

Field Name Cardinality Type Description
@context 1 URL the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/emo/text-api/-/raw/main/jsonld/image.jsonld
id 1 URL URL pointing to the image
manifest ? URL URL pointing to the image’s manifest 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
notes ? string further notes concerning the license. can be used e.g. for the attribution statement of CC BY

#### Support Object

Any material supporting the view is described and referenced in this object. This encompasses fonts and CSS, but also other material to support the rendering MAY be added on request.

Field Name Cardinality Type Description
@context 1 URL the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/emo/text-api/-/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
integrity ? Data Integrity Object information on data integrity

### Item Object

It is REQUIRED to be served at the corresponding endpoint.

When an item serves a complete version of a text, the type SHOULD be full. Any other (sliced) material is either a section or a page.

Field Name Cardinality Type Description
@context 1 URL the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/emo/text-api/-/raw/main/jsonld/item.jsonld
textapi 1 semver version number satisfied by the implementation
title ? [Title Object] the title of the item
type 1 string one of section, page, full
n ? string division number
lang 1 [iso639-3] language codes describing the resource
langAlt ? [string] alternative language name or code (when there is no iso639-3 code, e.g. karshuni)
content 1 [Content Object] different serializations of the item, e.g. HTML, plain text, XML, …
description ? string a short description of the object
image ? Image Object corresponding image
annotationCollection ? URL URL pointing to an Annotation Collection for this item
modules ? [Module Object] the modules in use for this item. has to correspond to the Collection Object’s modules entry

#### Content Object

Field Name Cardinality Type Description
@context 1 URL the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/emo/text-api/-/raw/main/jsonld/content.jsonld
url 1 URL URL pointing to the content
type 1 MIME type a MIME type. If several Content Objects with the same MIME type are provided, these SHOULD be distinguished with a MIME type parameter where the key is type and the value can be freely chosen, e.g. text/html;type=transcription.
integrity ? Data Integrity Object information on data integrity

### Title Object

Field Name Cardinality Type Description
@context 1 URL the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/emo/text-api/-/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

### Idref Object

Field Name Cardinality Type Description
@context 1 URL the JSON-LD context of this object. MUST be https://gitlab.gwdg.de/subugoe/emo/text-api/-/raw/main/jsonld/idref.jsonld
base ? URL the base URL to the authority file
type 1 string short title of the referenced authority
id 1 string the main ID referenced

### Data Integrity Object

This object contains information regarding data integrity (checksum) of the referenced resources. It SHOULD be used for all resources.

Field Name Cardinality Type Description
type 1 string algorithm to calculate checksum (e.g. MD5, SHA-256)
value 1 string the checksum

## Extensibility

All objects MAY be extended by own keywords, always prefixed by x-.

## Appendix

### Schema Files

An OpenAPI specification of the TextAPI can be found in the API’s repository.

An JSON Schema specification of the TextAPI can be found in the API’s repository.

### Example Objects

You can find examples in our git repository:

## Todos

We are working to improve the TextAPI. Please find our todo list attached to the git repo here.