From df6bcee6321b08db93d6b30e015c69ff719a1d86 Mon Sep 17 00:00:00 2001 From: "Hugh A. Cayless" Date: Tue, 6 Aug 2024 10:31:16 -0400 Subject: [PATCH 1/6] Fix extraneous @s and add reference to BCP 47 for lang values. --- versions/unstable/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index 29d79ec..dc1ad7b 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -236,7 +236,7 @@ The values of this object's properties **MAY** be: - a literal that cannot be localized (such as `int` or `float`), - a URI, -- an array of objects with `@value` and `@lang` properties, +- an array of objects with `value` and `lang` properties (`lang` values **MUST** follow [BCP 47](https://www.rfc-editor.org/info/bcp47)), - an array of URIs. ### URI for Collection Endpoint Request From 1a58a0445c736abcee7cd13ab7851f1ebb31690d Mon Sep 17 00:00:00 2001 From: "Ian W. Scott" Date: Wed, 7 Aug 2024 20:28:42 -0400 Subject: [PATCH 2/6] Add view property for handling pagination and harmonize Collection in Navigation (#259) * Harmonized Resource object properties between Collection and Navigation endpoints * feat: Add pagination support to Collection and Navigation endpoints. Adds the optional `view` property for paginating responses and introducing the `Pagination` objects to describe the pagination. --- versions/unstable/README.md | 42 +++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index 5c880ed..c2f7ffe 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -12,6 +12,8 @@ Specifications - 2024-08-06 - Removed `maxCiteDepth` from Collection objects at the Collection endpoint now that we have a `CitationTree` object at the Resource level. + - Harmonized the properties for `Resource` objects between the Collection and Navigation endpoints. This involves adding required `document` and `navigation` properties, as well as allowing additional optional properties. Also removed the `document` and `navigation` properties from the `Navigation` object since these URI templates are now part of the `Resource` object. + - Added `view` properties for paginated responses to the Collection and Navigation endpoints. Added a `Pagination` object type to provide the pagination links. - 2024-05-24 - Removed `totalItems` from the Collection Endpoints (See https://github.com/distributed-text-services/specifications/issues/248, problem pointed out by @kbrueckmann) @@ -224,6 +226,7 @@ Properties for Collection or Resource objects: | `document` | URI Template | Y (if `@type` is `Resource`) | Link to the Document API endpoint for the `Resource`. | | `download` | URI or array | N | A link or a key: value list of media type: link to downloadable versions of the `Resource` | | `citationTrees` | array | N | A list of Citation Trees, outlining the types of citation in each of the `Resource`s citation tree(s). | +| `view` | Pagination | N | A Pagination object for paginated responses. | Additional properties for `Resource` objects: @@ -231,6 +234,8 @@ Additional properties for `Resource` objects: | ---- | ---- | -------- | ----------- | | `mediaTypes` | array | N | An array of string identifiers for the response body media types (Content-Type values) supported for the `Resource` in Document endpoint queries. | +If a response is paginated the response object **MUST** include the `view` property with a `Pagination` object as its value. + #### `MetadataObject` Structure In order to make metadata parsable across implementations of the APIs, we restrict the depth of properties in JSON-LD metadata objects. @@ -244,6 +249,17 @@ The values of this object's properties **MAY** be: - an array of objects with `value` and `lang` properties (`lang` values **MUST** follow [BCP 47](https://www.rfc-editor.org/info/bcp47)), - an array of URIs. +#### `Pagination` Structure + +| Name | Type | Required | Description | +| ---- | ---- | -------- | ----------- | +| `@id` | URI | Y | The identifier of the current page of the collection. This should be the full URI for the current request including the pagination request parameter | +| `@type` | string | Y | the type of the object. Must be `Pagination` | +| `first` | URI | Y | The URI for the first page of the paginated result set | +| `previous` | URI | Y | The URI for the previous page of the paginated result set | +| `next` | URI | Y | The URI for the next page of the paginated result set | +| `last` | URI | Y | The URI for the last page of the paginated result set | + ### URI for Collection Endpoint Request #### Query Parameters @@ -600,7 +616,7 @@ This is an example of a paginated request for a Child Collection's members. ], "view": { "@id": "/api/dts/collection/?id=lettres_de_poilus&page=19", - "@type": "PartialCollectionView", + "@type": "Pagination", "first": "/api/dts/collection/?id=lettres_de_poilus&page=1", "previous": "/api/dts/collection/?id=lettres_de_poilus&page=18", "next": "/api/dts/collection/?id=lettres_de_poilus&page=20", @@ -729,16 +745,17 @@ The top-level response object is a `Navigation` object answering a query about t | `@id` | URL | Y | The absolute URL of the current request including any query parameters. | | `@type` | string | Y | The object's RDF class which must be "Navigation". | | `dtsVersion` | string | Y | The version of the DTS specification providing the response. Default is "1-alpha". | -| `document` | URI template | Y | The URI template to the Document endpoint at which the text of nodes in the citation tree can be retrieved. | -| `navigation` | URI template | Y | The URI template to the Navigation endpoint at which the citation tree structure can be queried. | | `resource`| Resource | Y | The `Resource` whose citation tree is being queried. | | `ref` | CitableUnit | N | The `CitableUnit` in the citation tree which is being queried. | | `start` | CitableUnit | N | The `CitableUnit` at the beginning of the range in the citation tree which is being queried. | | `end` | CitableUnit | N | The `CitableUnit` at the end of the range in the citation tree which is being queried. | | `member` | array | N | An array of `CitableUnit` in the subtree specified by the query parameters. | +| `view` | Pagination | N | A Pagination object for paginated responses. | Because the `Navigation` object is a top-level object in the API, each object must also have a `@context` property pointing to a DTS JSON-LD context object such as "https://distributed-text-services.github.io/specifications/context/1-alpha1.json". +If a response is paginated the response object **MUST** include the `view` property with a `Pagination` object. + #### Resource | Name | Type | Required | Description | @@ -746,8 +763,11 @@ Because the `Navigation` object is a top-level object in the API, each object mu | `@id` | URI | Y | The URI of the `Resource`. | | `@type` | string | Y | The object's RDF class which must be "Resource". | | `collection` | URL template | Y | The URI template to the Collection endpoint at which the `Resource` can be found. | +| `navigation` | URI Template | Y | The URI template to the Navigation API endpoint for the `Resource`. | +| `document` | URI Template | Y | The URI template to the Document API endpoint for the `Resource`. | | `citationTrees` | array | Y | An array of `CitationTree` objects | -| `mediaTypes` | array | N | An array of string identifiers for the response body media types (Content-Type values) supported for the `Resource` in Document endpoint queries. | + +The `Resource` object may also contain the [optional properties](#scheme-for-collection-api-responses) described for the Collection endpoint. If a `Resource` has a single `CitationTree`, that `CitationTree` object cannot have an `identifier`. @@ -803,6 +823,20 @@ If the `CitableUnit` parent is the root level of the `Resource`, the value retur } ``` +#### Pagination + +This object is used to provide links to the first, previous, next, and last pages of a paginated response. Its properties are described above in the [Scheme for Collection API Responses](#scheme-for-collection-api-responses). For convenience, we repeat them here: + +| Name | Type | Required | Description | +| ---- | ------ | --------- | -----------------------------| +| `@id` | URI | Y | The absolute URI of the current request including any query parameters. | +| `@type` | string | Y | The object's type which must be "Pagination". | +| `first` | URI | Y | The URI of the first page of the paginated response. | +| `previous` | URI | Y | The URI of the previous page of the paginated response. | +| `next` | URI | Y | The URI of the next page of the paginated response. | +| `last` | URI | Y | The URI of the last page of the paginated response. | + + ### URI for Navigation Endpoint Requests #### Query Parameters From 415a2724ab4bae2740464f4dce4e3d104c69463a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thibault=20Cl=C3=A9rice?= Date: Thu, 8 Aug 2024 08:46:25 -0400 Subject: [PATCH 3/6] Made `citeType` required for `CiteStructure` objects. Fixes #261 --- versions/unstable/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index c2f7ffe..4c8dc8d 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -10,11 +10,13 @@ Specifications ## Changelogs + +- 2004-08-08 + - Made `citeType` required for `CiteStructure` objects. - 2024-08-06 - Removed `maxCiteDepth` from Collection objects at the Collection endpoint now that we have a `CitationTree` object at the Resource level. - Harmonized the properties for `Resource` objects between the Collection and Navigation endpoints. This involves adding required `document` and `navigation` properties, as well as allowing additional optional properties. Also removed the `document` and `navigation` properties from the `Navigation` object since these URI templates are now part of the `Resource` object. - Added `view` properties for paginated responses to the Collection and Navigation endpoints. Added a `Pagination` object type to provide the pagination links. - - 2024-05-24 - Removed `totalItems` from the Collection Endpoints (See https://github.com/distributed-text-services/specifications/issues/248, problem pointed out by @kbrueckmann) - `passage` property (URI template) moved to `document` for consistency between Collection and Navigation endpoint (See https://github.com/distributed-text-services/specifications/issues/249, problem pointed out by @philippepons) @@ -792,7 +794,7 @@ Values in the `mediaTypes` array must correspond to content types that the imple | Name | Type | Required | Description | | ---- | ------ | --------- | -----------------------------| | `citeStructure` | array | N | An array of `CiteStructure` objects. | -| `citeType` | string | N | A type of textual unit that appears at a given level in the citation tree. (E.g., "chapter", "verse") | +| `citeType` | string | y | A type of textual unit that appears at a given level in the citation tree. (E.g., "chapter", "verse") | #### CitableUnit From a6231aad7f34d08303faa52cdc6c98df2c909036 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thibault=20Cl=C3=A9rice?= Date: Thu, 8 Aug 2024 08:48:54 -0400 Subject: [PATCH 4/6] Definitely remove maxCiteDepth --- versions/unstable/README.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index c2f7ffe..907ef5a 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -10,6 +10,8 @@ Specifications ## Changelogs +- 2024-08-08 + - Removed `maxCiteDepth` everywhere, including in the example. - 2024-08-06 - Removed `maxCiteDepth` from Collection objects at the Collection endpoint now that we have a `CitationTree` object at the Resource level. - Harmonized the properties for `Resource` objects between the Collection and Navigation endpoints. This involves adding required `document` and `navigation` properties, as well as allowing additional optional properties. Also removed the `document` and `navigation` properties from the `Navigation` object since these URI templates are now part of the `Resource` object. @@ -463,7 +465,6 @@ Although, this is optional, the expansion of `@type:Resource`'s metadata is advi "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth" : 2, "citeStructure" : [ { "citeType": "poem", @@ -526,7 +527,6 @@ This example is a child Resource, i.e. document composed of passages of readable "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth" : 2, "citeStructure" : [ { "citeType": "poem", @@ -565,7 +565,6 @@ This example is a child Resource, i.e. document composed of passages of readable "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth" : 2, "citeStructure" : [ { "citeType": "front_matter" @@ -660,7 +659,6 @@ The example comes from Papyri.info and concerns a document that has been publish "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth" : 2, "citeStructure" : [ { "citeType": "column", @@ -784,7 +782,6 @@ Values in the `mediaTypes` array must correspond to content types that the imple | `identifier` | string | N | The string identifier of the `CitationTree`. | | `@type` | string | Y | The object's RDF class which must be "CitationTree". | | `citeStructure` | array | N | An array of `CiteStructure` objects. | -| `maxCiteDepth` | int | Y | An integer defining the maximum depth of the Resource's citation tree. | | `description` | string | N | A human readable description of the citation tree. | #### CiteStructure @@ -949,7 +946,6 @@ The client wants to retrieve an array of `CitableUnit`s that are part of the `Re "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth": 3, "citeStructure": [ { "@type": "CiteStructure", @@ -1048,7 +1044,6 @@ The client wants to retrieve an array of all `CitableUnit`s in the `Resource` id "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth" : 3, "citeStructure": [ { "@type": "CiteStructure", @@ -1201,7 +1196,6 @@ The client wants to retrieve an array of all `CitableUnit`s in the `Resource` id "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth": 3, "citeStructure": [ { "@type": "CiteStructure", @@ -1338,7 +1332,6 @@ The client wants to retrieve the citation subtree below `CitableUnit` "C1" but i "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth": 3, "citeStructure": [ { "@type": "CiteStructure", @@ -1473,7 +1466,6 @@ The client wants to retrieve `CitableUnit` "C1.E1" of the `Resource` "https://en "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth": 3, "citeStructure": [ { "@type": "CiteStructure", @@ -1574,7 +1566,6 @@ The client wants to retrieve an array of `CitableUnit`s in a specified range, in "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth": 3, "citeStructure": [ { "@type": "CiteStructure", @@ -1757,7 +1748,6 @@ Alternately, the same typology of `CitableUnits` and `CiteStructure` may be retr "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth": 3, "citeStructure": [ { "@type": "CiteStructure", @@ -1842,7 +1832,6 @@ It is up to the implementer to decide what optional metadata to provide using th "citationTrees": [ { "@type": "CitationTree", - "maxCiteDepth" : 3, "citeStructure": [ { "@type": "CiteStructure", From 77c4b201bdaa9ff00b838947186df130cb4673ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thibault=20Cl=C3=A9rice?= Date: Thu, 8 Aug 2024 08:52:01 -0400 Subject: [PATCH 5/6] Fix a typo in a URI template Fixed #501 --- versions/unstable/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index c2f7ffe..764079f 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -456,7 +456,7 @@ Although, this is optional, the expansion of `@type:Resource`'s metadata is advi "contributor": ["Aemilius Baehrens"], "language": ["la", "en"] }, - "collection": "/api/dts/collection/?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1(&nav}", + "collection": "/api/dts/collection/?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1{&nav}", "document": "/api/dts/document?resource=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1{&ref,start,end,tree,mediaType}", "navigation": "/api/dts/navigation?resource=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1{&ref,start,end,tree}", "download": "https://raw.githubusercontent.com/lascivaroma/priapeia/master/data/phi1103/phi001/phi1103.phi001.lascivaroma-lat1.xml", From 818d04f15a18ac1f0616f00629992a88194064e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thibault=20Cl=C3=A9rice?= Date: Thu, 8 Aug 2024 08:57:29 -0400 Subject: [PATCH 6/6] Add missing `@type` in examples of the Navigation endpoint Fixes #252 --- versions/unstable/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index 764079f..d11bc59 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -939,6 +939,7 @@ The client wants to retrieve an array of `CitableUnit`s that are part of the `Re { "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json", "dtsVersion": "1-alpha", + "@type": "Navigation", "@id": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula&down=1", "document": "https://example.org/api/dts/document/?resource=https://en.wikisource.org/wiki/Dracula{&ref,start,end,tree,mediaType}", "collection": "https://example.org/api/dts/collection/?resource=https://en.wikisource.org/wiki/Dracula{&page,nav}", @@ -1039,6 +1040,7 @@ The client wants to retrieve an array of all `CitableUnit`s in the `Resource` id "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json", "dtsVersion": "1-alpha", "@id":"https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula&down=2", + "@type": "Navigation", "document": "https://example.org/api/dts/document/?resource=https://en.wikisource.org/wiki/Dracula{&ref,start,end,tree,mediaType}", "collection": "https://example.org/api/dts/collection/?resource=https://en.wikisource.org/wiki/Dracula{&page,nav}", "navigation": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula{&ref,down,start,end,tree,page}", @@ -1191,6 +1193,7 @@ The client wants to retrieve an array of all `CitableUnit`s in the `Resource` id { "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json", "dtsVersion": "1-alpha", + "@type": "Navigation", "@id": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula&ref=C1&down=-1", "document": "https://example.org/api/dts/document/?resource=https://en.wikisource.org/wiki/Dracula{&ref,start,end,tree,mediaType}", "collection": "https://example.org/api/dts/collection/?resource=https://en.wikisource.org/wiki/Dracula{&page,nav}", @@ -1328,6 +1331,7 @@ The client wants to retrieve the citation subtree below `CitableUnit` "C1" but i { "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json", "dtsVersion": "1-alpha", + "@type": "Navigation", "@id": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula?ref=C1&down=2", "document": "https://example.org/api/dts/document/?resource=https://en.wikisource.org/wiki/Dracula{&ref,start,end,tree,mediaType}", "collection": "https://example.org/api/dts/collection/?resource=https://en.wikisource.org/wiki/Dracula{&page,nav}", @@ -1463,6 +1467,7 @@ The client wants to retrieve `CitableUnit` "C1.E1" of the `Resource` "https://en { "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json", "dtsVersion": "1-alpha", + "@type": "Navigation", "@id": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula&ref=C1.E1&down=1", "document": "https://example.org/api/dts/document/?resource=https://en.wikisource.org/wiki/Dracula{&ref,start,end,tree,mediaType}", "collection": "https://example.org/api/dts/collection/?resource=https://en.wikisource.org/wiki/Dracula{&page,nav}", @@ -1564,6 +1569,7 @@ The client wants to retrieve an array of `CitableUnit`s in a specified range, in { "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json", "dtsVersion": "1-alpha", + "@type": "Navigation", "@id": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula&down=1&start=C1&end=C3", "document": "https://example.org/api/dts/document/?resource=https://en.wikisource.org/wiki/Dracula{&ref,start,end,tree,mediaType}", "collection": "https://example.org/api/dts/collection/?resource=https://en.wikisource.org/wiki/Dracula{&page,nav}", @@ -1747,6 +1753,7 @@ Alternately, the same typology of `CitableUnits` and `CiteStructure` may be retr { "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json", "dtsVersion": "1-alpha", + "@type": "Navigation", "@id": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula&ref=C1", "document": "https://example.org/api/dts/document/?resource=https://en.wikisource.org/wiki/Dracula{&ref,start,end,tree,mediaType}", "collection": "https://example.org/api/dts/collection/?resource=https://en.wikisource.org/wiki/Dracula{&page,nav}", @@ -1832,6 +1839,7 @@ It is up to the implementer to decide what optional metadata to provide using th { "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json", "dtsVersion": "1-alpha", + "@type": "Navigation", "@id": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula&ref=C2.E2", "document": "https://example.org/api/dts/document/?resource=https://en.wikisource.org/wiki/Dracula{&ref,start,end,tree,mediaType}", "collection": "https://example.org/api/dts/collection/?resource=https://en.wikisource.org/wiki/Dracula{&page,nav}",