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.

Fields that differ from the generic API, e.g. with stricter cardinalities, are highlighted in italics.

Status of this Document

The current version of this document is 1.1.0.

The version number will be applied according to Semantic Versioning 2.0.0.

Definitions

Cardinalities

Cardinality Description REQUIRED
1 exactly one yes
+ one or more yes
? zero or one no
* zero or more no

Data Types

Type Description
[…] array
string a sequence of characters, MAY be empty
URI a valid URI, see URI Syntax
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/

URI Syntax

The URI Syntax is used according to the one described at IIIF.

Delivery Service / Available Endpoints

The TextAPI delivery service is the description of endpoints. It is REQUIRED to use the https protocol.

Collection

Returns a Collection Object.

collection MUST be either syriac or arabic-karshuni.

Sample Call

https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/{collection}/collection.json

Manifest

Returns a Manifest Object.

Sample Call

https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/{collection}/{manifest}/manifest.json

Item

Returns an Item Object.

Sample Call

https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/{collection}/{manifest}/{item}/latest/item.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 served at the corresponding endpoint.

Field Name Cardinality Type Description
textapi 1 semver the TextAPI version covered by the implementation
title 1 [Title Object] the title of the collection
collector + [Actor Object] a personal entity responsible for the collection (collector)
description 1 string description of the collection
sequence 1 [Sequence Object] a set of manifests included in this collection
annotationCollection 1 URI URI pointing to an Annotation Collection for the complete collection

Manifest Object

This is the main object in the schema to represent a single text, its derivatives (e.g. HTML) and associated images. It is REQUIRED to be served at the corresponding endpoint.

Field Name Cardinality Type Description
textapi 1 semver version number satisfied by the implementation
id 1 URI URI pointing to this manifest
label 1 string human-readable name or title
metadata 1 [Metadata Object] contains the project specific info about editors, creation date/place and current location of a manuscript/book
sequence 1 [Sequence Object] a sequence of items
support 1 [Support Object] additinal files that help with the display of serializations
license 1 [License Object] license under which the resource MUST be used
annotationCollection 1 URI URI pointing to an Annotation Collection for the complete manifest

Item Object

It is REQUIRED to be served at the corresponding endpoint.

The type MUST be page.

Field Name Cardinality Type Description
textapi 1 semver version number satisfied by the implementation
title 1 [Title Object] the title of the item
type 1 string page
n 1 string page number as given in tei:pb/@n
lang 1 [iso639-3] language codes describing the resource
langAlt ? [string] alternative language code (when there is no iso639-3 code, e.g. karshuni)
x-langString 1 string a string listing all languages appearing in the document with their full English name (e.g. “Arabic, Karshuni”)
content 1 [Content Object] different serializations of the item, e.g. HTML, plain text, XML, …
image ? Image Object corresponding image as given in tei:pb/@facs
annotationCollection 1 URI URI pointing to an Annotation Collection for this item

Actor Object

Field Name Cardinality Type Description
role + [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

Content Object

Field Name Cardinality Type Description
url 1 URL URL pointing to the content
type 1 string 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.

Metadata Object

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 1 string property

Idref Object

Field Name Cardinality Type Description
base ? URI the base URI to the authority file
type 1 string short title of the referenced authority
id 1 string the main ID referenced

Image Object

An image representing the source or its provider. The URI points to TextGrid’s IIIF Image API service which also allows for manipulations such as resizing. The URI can have one of the following forms:

  • https://ahikar.sub.uni-goettingen.de/api/images/{$image-uri} for a complete page
  • https://ahikar.sub.uni-goettingen.de/api/images/{$image-uri}/{$x-offset},{$y-offset},{$width},{$height} for an image section described by {$x-offset}, {$y-offset}, {$width}, and {$height} as a sequence of percentages
Field Name Cardinality Type Description
id 1 URI URI pointing to the image
manifest ? URL URL pointing to the image’s manifest object
license 1 License Object the license for the image that MUST be used

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
notes ? string further notes concerning the license. can be used e.g. for the attribution statement of CC BY

Sequence Object

Represents a sequence of collections, manifests or items Within a manifest it SHOULD contain items exclusively.

Field Name Cardinality Type Description
id 1 URI URI to find a Manifest Object, Collection Object or Item Object
type 1 string one of collection, manifest, item

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
type 1 xs:string MUST be either font or 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
title 1 string a single title
type 1 string one of main, sub

Revision History / Changelog

Version Date Description
1.0.0 2020-07-14 initial version
1.1.0 2020-08-25 add more metadata for manifests/editions (x-editor, x-date, x-origin, x-location)
1.1.1 2021-01-18 update examples concerning Title Object
1.2.0 2021-02-04 move extensions to Metadata Object
2.0.0 2021-02-18 add Content Object for providing several serializations
2.0.1 2021-03-09 add missing docs for Support Object

Appendix

Class Diagram

UML class diagram

// Ahiqar TextAPI
// ------------------

// classes
[Collection|entrypoint|- textapi 1; -description 1; -annotationCollection 1 {bg:yellow}]

[Manifest|entrypoint| -textapi 1; -id 1; -label 1; -metadata 1; -license 1; -annotationCollection 1 {bg:yellow}]

[Item| -textapi 1; -type 1; -n 1; -lang 1; -langAlt ?; -content 1; -image ?; -annotationCollection 1]

// objects
[Sequence|-id; -type]

[Actor| -role; -name; -id]

[Image| -id; -manifest]

[License| -id; -notes ?]

[Title| -title; -type]

[Idref| -base ?; -type| -id]

[Content| -url; -type]

[Support| -type; -mime; -url]

// imports
[Collection]-[Title]
[Collection]-[Actor]
[Collection]-[Sequence]

[Manifest]-[Sequence]
[Manifest]-[Actor]
[Manifest]-[Image]
[Manifest]-[License]
[Manifest]-[Support]

[Item]-[Title]
[Item]-[Image]
[Item]-[Content]

[Actor]-[Idref]

[Image]-[License]

Example Objects

collection.json

https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/3r132/collection.json

{
  "textapi": "1.8.0",
  "title": [
    {
      "title": "The Story and Proverbs of Ahikar the Wise",
      "type": "manifest"
    },
    null
  ],
  "collector": {
    "role": "collector",
    "name": "Prof. Dr. theol. Kratz, Reinhard Gregor",
    "idref": {
      "base": "http://d-nb.info/gnd/",
      "id": "115412700",
      "type": "GND"
    }
  },
  "description": "Main collection for the Ahikar project. Funded by DFG, 2019–2020. University of Göttingen",
  "annotationCollection": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/3r132/annotationCollection.json",
  "sequence": [
    {
      "id": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/3r132/3r84g/manifest.json",
      "type": "collection"
    },
    {
      "id": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/3r132/3r84h/manifest.json",
      "type": "collection"
    },
    {
      "id": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/3r132/arabic-karshuni/manifest.json",
      "type": "collection"
    }
  ]
}

manifest.json

https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/3r178/manifest.json

{
  "textapi": "1.8.0",
  "id": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/3r178/manifest.json",
  "label": "Cod. ARABE 3637",
  "metadata": [
    {
      "key": "Editors",
      "value": "Simon Birol, Aly Elrefaei"
    },
    {
      "key": "Date of creation",
      "value": "1772"
    },
    {
      "key": "Place of origin",
      "value": "Aleppo, Syria"
    },
    {
      "key": "Current location",
      "value": "Bibliothèque Nationale de France, France"
    }
  ],
  "license": "CC0-1.0",
  "annotationCollection": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/3r178/annotationCollection.json",
  "sequence": [
    {
      "id": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/3r178/140/latest/item.json",
      "type": "item"
    },
    {
      "id": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/3r178/141/latest/item.json",
      "type": "item"
    },
    ...
  ]
}

item.json

https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/3r1gh/140/latest/item.json

{
  "textapi": "1.8.0",
  "title": {
    "title": "The Proverbs or History of Aḥīḳar the wise, the scribe of Sanḥērībh, king of Assyria and Nineveh",
    "type": "main"
  },
  "type": "page",
  "n": "140",
  "content": [
    {
      "url": "https://ahikar.sub.uni-goettingen.de/api/content/3r1gh/140.html",
      "type": "application/xhtml+xml;type=transcription"
    },
    {
      "url": "https://ahikar.sub.uni-goettingen.de/api/content/3r1gh.txt",
      "type": "text/plain"
    }
  ],
  "lang": [
    "ara",
    "syc",
    "eng",
    "lat"
  ],
  "langAlt": [
    "karshuni",
    "syc-syrj",
    "syc-syrn"
  ],
  "x-langString": "Arabic, Classical Syriac, Eastern Syriac, English, Karshuni, Latin, Western Syriac",
  "image": {
    "id": "https://ahikar.sub.uni-goettingen.de/api/images/3r1gj",
    "license":
      {
        "id": "CC-BY-SA-4.0",
        "notes": "Provided by some other data source."
      }
  },
  "annotationCollection": "https://ahikar.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/3r1gh/140/annotationCollection.json"
}