Commit 51363165 authored by TextAPI Bot's avatar TextAPI Bot
Browse files

update versions

parent f10f26e7
Pipeline #347186 passed with stages
in 17 seconds
......@@ -109,3 +109,8 @@ pygmentCodeFences = true
name = '1.0.0'
url = 'archive/1.0.0/1.0.0'
parent = "archive"
[[menu.main]]
name = '1.1.0'
url = 'archive/1.1.0/1.1.0'
parent = "archive"
---
title: TextAPI Version 1.1.0 [1.1.0]
version: 1.1.0
---
- TextAPI at version 1.1.0: [Specification](../specs_1.1.0_1.1.0)
- AnnotationAPI at version 1.1.0: [Specification](../annotation_specs_1.1.0)
- Modules at version 1.1.0: [Specification](../modules_1.1.0)
The complete data regarding this release – incl. a JSON schema and an OpenAPI description file – can be found at [gitlab.gwdg.de](https://gitlab.gwdg.de/subugoe/emo/text-api/-/releases/v1.1.0).
---
title: AnnotationAPI Specification [1.1.0]
version: 1.1.0
---
## 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](https://tools.ietf.org/html/bcp14),
[RFC2119](https://tools.ietf.org/html/rfc2119) and
[RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear
in all capitals, as shown here.
This document is licensed under [CC-BY-ND-4.0](https://creativecommons.org/licenses/by-nd/4.0/legalcode) ([via SPDX](https://spdx.org/licenses/CC-BY-ND-4.0.html)).
The style of this documentation is adapted from [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)
specification.
## Status of this Document
The current version of this document is `1.0.0`.
The version number will be applied according to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
## Definitions
### W3C Annotations
The AnnotationAPI is an implementation of the [W3C Annotation Model](https://www.w3.org/TR/annotation-model/).
This means that we provide an [Annotation Collection](https://www.w3.org/TR/annotation-model/#annotation-collection) per resource and [Annotation Pages](https://www.w3.org/TR/annotation-model/#annotation-page) for each Annotation Collection.
The W3C specs, however, don't assume hierarchical/nested resources as we have in the IIIF derived TextAPI model.
In order to bring these two approaches together, all Objects of the TextAPI (Collection/Manifest/Item) provide an endpoint for delivering an Annotation Collection.
These list the next level items (Collection → Manifest, Manifest → Item, Item → Item) as Annotation Pages including all annotations on that level.
Since Collection Objects are on the top of the hierarchy there aren't any Annotation Pages provided for them.
Additions to the W3C model are marked with an `x-`.
### Cardinalities
| Cardinality | Description | REQUIRED |
|----|----|----|
| 1 | exactly one | yes |
| ? | zero or one | no |
| * | zero or more | no |
### Data Types
| Type | Description |
|----|----|
| \[\] | array |
| string | a sequence of characters, MAY be empty |
| IRI | a valid IRI, see [IRI Syntax](#iri-syntax) |
| MIME type | a valid MIME type according to IANA. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) |
| iso639-3 | alpha-3 language code according to [ISO 639-3](https://iso639-3.sil.org). In cases of alternative codes the usage of `bibliographic (B)` is REQUIRED. |
| int | a non-negative Integer value |
### IRI Syntax
The URI Syntax is used according to the one described at [IIIF](https://iiif.io/api/image/2.1/#uri-syntax).
We encourage to allow for IRI (an internationalizes superset or URI) on client side.
## Delivery Service / Available Endpoints
The AnnotationAPI delivery service is the description of endpoints.
All endpoints use the `https` protocol.
### Annotations for Collection Objects
`https://{server}{/prefix}/{collection}/annotationCollection.json`
Returns an [Annotation Collection](#annotation-collection) for the given collection.
### Annotations for Manifest Objects
`https://{server}{/prefix}/{collection}/{$manifest}/annotationCollection.json`
Returns an [Annotation Collection](#annotation-collection) for the given manifest.
---
`https://{server}{/prefix}/{collection}/{$manifest}/annotationPage.json`
Returns an [Annotation Page](#annotation-page) for the given manifest.
### Annotations for Item Objects
`https://{server}{/prefix}/{collection}/{$manifest}/{$page}/annotationCollection.json`
Returns an [Annotation Collection](#annotation-collection) for the given item.
---
`https://{server}{/prefix}/{collection}/{$manifest}/{$page}/annotationPage.json`
Returns an [Annotation Page](#annotation-page) for the given item.
## Schema
### Annotation Collection
An Annotation Collection presents an overview of the Annotation Pages provided for a given resource.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| @context | 1 | IRI | MUST be `http://www.w3.org/ns/anno.jsonld` |
| id | 1 | IRI | a unique identifier for the Annotation Collection |
| type | 1 | string | MUST be `AnnotationCollection` |
| label | 1 | string | a descriptive title for the Annotation Collection |
| total | ? | int | the number of annotations belonging to this Collection |
| first | 1 | IRI | an IRI pointing to the API endpoint of the first Annotation Page of this Collection |
| last | 1 | IRI | an IRI pointing to the API endpoint of the last Annotation Page of this Collection. identical to `first` if the collection has only one Annotation Page |
### Annotation Page
An Annotation Page lists all annotations that occur on them while linking to the previous and next Annotation Pages within an Annotation Collection.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| @context | 1 | IRI | MUST be `http://www.w3.org/ns/anno.jsonld` |
| id | 1 | IRI | a unique identifier for the Annotation Collection |
| type | 1 | string | MUST be `AnnotationPage` |
| partOf | 1 | \[[PartOf Object](#partof-object)\] | information about the Annotation Collection the pPage is part of |
| next | 1 | IRI | an IRI pointing to the API endpoint of the next Annotation Page of this Annotation Collection. MAY be `null` if there is no following Page |
| prev | 1 | IRI | an IRI pointing to the API endpoint of the previous Annotation Page of this Annotation Collection. MAY be `null` if there is no previous Page |
| startIndex | ? | int | a number denoting the position of this Page's first annotation, relative to the parent Annotation Collection |
| items | 1 | \[[Annotation Item Object](#annotation-item-object)\] | a sequence of annotations |
---
### PartOf Object
Represents a relation between an Annotation Page and an Annotation Collection.
Contains information about the Page's parent Annotation Collection.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| id | 1 | IRI | a unique identifier for the Annotation Collection |
| label | 1 | string | a descriptive title for the Annotation Collection |
| total | ? | int | the number of annotations belonging to this Collection. |
### Annotation Item Object
A sequence of annotations belonging to an Annotation Page.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| body | 1 | \[[Body Object](#body-object)\] | the content of the annotation |
| target | 1 | \[[Target Object](#target-object)\] | information about the target of the annotation |
| type | 1 | string | MUST be `Annotation`|
| id | 1 | IRI | a unique identifier for the annotation |
### Body Object
The content of the annotation.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| type | 1 | string | MUST be `TextualBody` |
| value | 1 | string | the content of the annotation |
| format | 1 | MIME type | `text/plain` OR `text/html` (see notes) |
| x-content-type | 1 | string | the semantic type of the annotation. can be chosen freely by each project, e.g. `Person` or `Place` |
#### Notes
When using HTML within `value` the set of allowed elements is limited to the following:
- p
- span
- a
Besides the `href` attribute for `html:a` no further attribute SHOULD be used.
### Target Object
Provides information about the target resource the annotation refers to.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| selector | 1 | [CssSelector](#selector-object-cssselector) or [Range Selector](#selector-object-range) | a selector pointing to the target |
| format | 1 | MIME type | the MIME type of the target resource |
| language | 1 | iso639-3 | the language of the target resource |
### Selector Object: CssSelector
Provides information about the target resource the annotation refers to.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| type | 1 | string | `CssSelector` |
| value | 1 | string | a CSS selector in most cases referencing an ID or class. |
### Selector Object: RangeSelector
Provides information about the target resource the annotation refers to.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| type | 1 | string | `RangeSelector` |
| startSelector | 1 | [Selector Object](#selector-object-cssselector) | `CssSelector` representing the start of the range. |
| endSelector | 1 | [Selector Object](#selector-object-cssselector) | `CssSelector` representing the end of the range. |
## Appendix
### Class Diagram
![UML class diagram](https://yuml.me/90d725ea.svg)
### Examples
#### Annotation Collection: Example for Collection
`https://www.example.com/collection/annotationCollection.json`
```json
{
"annotationCollection" : {
"total" : 52,
"@context" : "http://www.w3.org/ns/anno.jsonld",
"first" : "https://www.example.com/collection/manifest/annotationPage.json",
"label" : "Annotations for some collection.",
"last" : "https://www.example.com/collection/manifest/annotationPage.json",
"type" : "AnnotationCollection",
"id" : "https://www.example.com/annotationCollection/collection"
}
}
```
#### Annotation Collection: Example for Manifest
`https://www.example.com/collection/manifest/annotationCollection.json`
```json
{
"annotationCollection" : {
"total" : 23,
"@context" : "http://www.w3.org/ns/anno.jsonld",
"first" : "https://www.example.com/collection/manifest/page1/annotationPage.json",
"label" : "Annotations for some manifest.",
"last" : "https://www.example.com/collection/manifest/page12/annotationPage.json",
"type" : "AnnotationCollection",
"id" : "https://www.example.com/annotationCollection/collection/manifest"
}
}
```
#### Annotation Collection: Example for Item
`https://www.example.com/collection/manifest/page1/annotationCollection.json`
```json
{
"annotationCollection" : {
"total" : 2,
"@context" : "http://www.w3.org/ns/anno.jsonld",
"first" : "https://www.example.com/collection/manifest/page1/annotationPage.json",
"label" : "Annotations for some manifest, page1",
"type" : "AnnotationCollection",
"id" : "https://www.example.com/annotationCollection/collection/manifest/page1"
}
}
```
#### Annotation Page: Example for Manifest
`https://www.example.com/collection/manifest/annotationPage.json`
```json
{
"annotationPage" : {
"items" : [ {
"body": {
"type": "TextualBody",
"value": "A person's name.",
"format": "text/plain",
"x-content-type": "Person"
},
"target" : {
"format" : "text/xml",
"language" : "eng",
"selector" : {
"type" : "CssSelector",
"value" : "#MD775409N1l4l2l6l4l8l2"
}
},
"type" : "Annotation",
"id" : "https://www.example.com/annotationCollection/manifest/annotation-1"
}, {
"body": {
"type": "TextualBody",
"value": "The author probably means another person at this point.",
"format": "text/plain",
"x-content-type": "Editorial Comment"
},
"target" : {
"format" : "text/xml",
"language" : "eng",
"selector" : {
"type" : "CssSelector",
"value" : "#MD775409N1l4l2l6l4l8l2"
}
},
"type" : "Annotation",
"id" : "https://www.example.com/annotationCollection/manifest/annotation-2"
}],
"partOf" : {
"total" : 23,
"label" : "Annotations for some manifest.",
"id" : "https://www.example.com/annotationCollection/collection/manifest"
},
"@context" : "http://www.w3.org/ns/anno.jsonld",
"startIndex" : 1,
"prev" : null,
"next" : "https://www.example.com/collection/manifest2/annotationPage.json",
"id" : "https://www.example.com/annotationPage/collection/manifest"
}
}
```
#### Annotation Page: Example for Item
`https://www.example.com/collection/manifest/page1/annotationPage.json`
```json
{
"annotationPage" : {
"items" : [ {
"body": {
"type": "TextualBody",
"value": "This is a place in Azerbaijan.",
"format": "text/plain",
"x-content-type": "Person"
},
"target" : {
"format" : "text/xml",
"language" : "eng",
"selector" : {
"type" : "CssSelector",
"value" : "#MD775409N1l4l2l6l4l8l2"
}
},
"type" : "Annotation",
"id" : "https://www.example.com/annotationCollection/manifest/annotation-1"
}, {
"body": {
"type": "TextualBody",
"value": "A person's name.",
"format": "text/plain",
"x-content-type": "Person"
},
"target" : {
"format" : "text/xml",
"language" : "eng",
"selector" : {
"type" : "CssSelector",
"value" : "#MD775409N1l4l2l6l4l8l2"
}
},
"type" : "Annotation",
"id" : "https://www.example.com/annotationCollection/manifest/annotation-2"
}],
"partOf" : {
"total" : 2,
"label" : "Annotations for some manifest, page1.",
"id" : "https://www.example.com/annotationCollection/collection/manifest/page1"
},
"@context" : "http://www.w3.org/ns/anno.jsonld",
"startIndex" : 0,
"prev" : null,
"next" : "https://www.example.com/collection/manifest/page2/annotationPage.json",
"type" : "AnnotationPage",
"id" : "https://www.example.com/annotationPage/collection/manifest/page1"
}
}
```
---
title: Editions (Manuscripts)
subtitle: Module
version: 1.1.0
---
## 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](https://tools.ietf.org/html/bcp14),
[RFC2119](https://tools.ietf.org/html/rfc2119) and
[RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear
in all capitals, as shown here.
This document is licensed under [CC-BY-ND-4.0](https://creativecommons.org/licenses/by-nd/4.0/legalcode) ([via SPDX](https://spdx.org/licenses/CC-BY-ND-4.0.html)).
The style of this documentation is adapted from [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)
specification.
## Status of this Document
The current version of this document is `0.0.1` according
to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
As long as the version number is not increased to `1.0.0` this document is
considered to be an early draft and major changes MAY be implemented over night and
without any announcement.
## 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](#uri-syntax) |
| iso3166-2 | alpha-2 country code according to [ISO 3166 alpha-2](https://www.iso.org/iso-3166-country-codes.html) |
## Module Schema
If you decide to use this schema, make sure to set at least all required fields. Register the module in your main TextAPI in the [Module Object](/specs#modules-object).
This module claims the prefix `em-`.
### Collection Object
The following fields `MAY` be added to a [Collection Object](../specs_1.1.0/#collection-object) describing e.g. an edition comprising one or more manuscripts.
**Caution:** `em-editor` is required.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| em-editor | + | \[[Actor Object](../specs_1.1.0#actor-object)\] | a personal entity responsible for the edition (editor) |
| em-funder | * | \[[Actor Object](../specs_1.1.0#actor-object)\] | an entity responsible for funding the project in which the text(s) in focus is/are edited (funder) |
### Manifest Object
The following fields `MAY` be added to a [Manifest Object](../specs_1.1.0/#manifest-object) describing a manuscript or fragment.
**Caution:** `em-identifier` is required.
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| em-origin | ? | string | the origin of the manuscript. `MAY` also comprise full provenence information. |
| em-identifier | 1 | string | the identifier of the manuscript, e.g. a shelfmark |
| em-textClass | * | string | a term classifying the text's genre(s) or category/categories, preferably taken from a controlled vocabulary |
#### Repository Object
The following fields `MUST` be added to a [Repository Object](../specs_1.1.0/#repository-object) describing the current location of the manuscript:
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| em-repoCountry | 1 | iso3166-2 | the country in which the repository is located as ISO 3166 alpha-2 code, e.g. `DE` for Germany |
| em-repoPlace | 1 | string | the name of a settlement, e.g. city or village, in which the repository in focus is located |
---
title: Editions (Prints)
subtitle: Module
version: 1.1.0
---
## 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](https://tools.ietf.org/html/bcp14),
[RFC2119](https://tools.ietf.org/html/rfc2119) and
[RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear
in all capitals, as shown here.
This document is licensed under [CC-BY-ND-4.0](https://creativecommons.org/licenses/by-nd/4.0/legalcode) ([via SPDX](https://spdx.org/licenses/CC-BY-ND-4.0.html)).
The style of this documentation is adapted from [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)
specification.
## Status of this Document
The current version of this document is `0.0.1` according
to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
As long as the version number is not increased to `1.0.0` this document is
considered to be an early draft and major changes MAY be implemented over night and
without any announcement.
## Scope of this Module
This module serves metadata usually needed for editing printed editions.
Its metadata fields refer to the bibliographic information about the text edited, e.g. when and where it has been printed or which part of the printed text is covered.
## 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 |
## Module Schema
If you decide to use this schema, make sure to set at least all required fields. Register the module in your main TextAPI in the [Module Object](/specs#modules-object).
This module claims the prefix `ep-`.
### Manifest Object
| Field Name | Cardinality | Type | Description |
|----|----|----|----|
| ep-section-title | ? | string | the title of the edited section as provided by the print's editor. SHOULD be set only if a part of a printed text is edited |
| ep-editor | 1 | \[[Actor Object](#actor-object)\] | the editor of the printed text |
| ep-title | 1 | \[[Title Object](#title-object)\] | the title of the printed text |
| ep-publisher | 1 | \[[Actor Object](#actor-object)\] | the publisher of the print. This typically refers to a firm or another kind of institution |
| ep-pubPlace | 1 | string | the publication place of the printed text |
| ep-date | 1 | string | the year of the print's publication |
| ep-biblScope | 1 | string | the pages the edited section covers in the printed text in the format `pp–pp` or `full` if the complete printed text is edited |
---
title: Modules [1.1.0]
version:
---
When working with resources from different origins, having a standard that describes how certain things are done is most convenient.
The TextAPI has been designed to deliver text resources of various kinds in a standardized way and allows for customization where the API specifiation is not sufficient.
This approach bears both possibility and risk:
While it empowers projects to offer more details about their resources it can hugely decrease interoperability since every project is likely to define its own custom (metadata) keys.
This is where the TextAPI Modules come into play.
The TextAPI modules are sets of predefined metadata keys that projects typically want to provide for a certain type of text resource.
Opting for a module adds to the interoperability of the project APIs and reduces a project's need to forge their custom keys.
Nevertheless, a module's keys may be enhanced by further project specific customizations (preceding with the `x-` prefix).
Modules can also be combined if a text resource fits into more than one category.
## Usage
Register all used modules in the [Module Object](../specs_1.1.0#module-object)).
> **Caution**:
>
> If a module is chosen for providing additional fields, all cardinalities of the fields defined in the module's schema have to be met.
>
> Using e.g. only the fields that refer to a Collection Object while omitting the module's required fields for another Object is not possible.
## Available Modules
Currently the TextAPI provides the following modules:
- [Editions (Manuscripts)](../em)
- [Editions (Prints)](../ep)
---
title: TextAPI Specification [1.1.0]
version: 1.1.0
---
## 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](https://tools.ietf.org/html/bcp14),
[RFC2119](https://tools.ietf.org/html/rfc2119) and
[RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear
in all capitals, as shown here.
This document is licensed under [CC-BY-ND-4.0](https://creativecommons.org/licenses/by-nd/4.0/legalcode) ([via SPDX](https://spdx.org/licenses/CC-BY-ND-4.0.html)).
The style of this documentation is adapted from [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)
specification.
## Status of this Document