From c1159a99b407ad9ab4a95a1c2116cb087199f266 Mon Sep 17 00:00:00 2001 From: Ian Scott Date: Tue, 6 Aug 2024 11:42:06 -0400 Subject: [PATCH 1/4] Harmonized Resource object properties between Collection and Navigation endpoints --- versions/unstable/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index ac9e967..5299615 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -12,6 +12,7 @@ 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. - 2024-05-24 - Removed `totalItems` from the Collection Endpoints (See https://github.com/distributed-text-services/specifications/issues/248, problem pointed out by @kbrueckmann) @@ -729,8 +730,6 @@ 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. | @@ -746,8 +745,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`. From 53004a1303cdc3f7b6a808b733e51005cb79dfee Mon Sep 17 00:00:00 2001 From: Ian Scott Date: Tue, 6 Aug 2024 12:25:52 -0400 Subject: [PATCH 2/4] feat: Add pagination support to Collection and Navigation endpoints. Adds the required `view` property for paginated responses and introducing the `PartialCollectionView` and `PartialNavigationView` objects to describe the pagination. --- versions/unstable/README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index 5299615..86bc699 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -13,6 +13,7 @@ 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 `PartialCollectionView` and `PartialNavigationView` object to describe the pagination. - 2024-05-24 - Removed `totalItems` from the Collection Endpoints (See https://github.com/distributed-text-services/specifications/issues/248, problem pointed out by @kbrueckmann) @@ -225,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` | PartialCollectionView | N | A PartialCollectionView object for paginated responses. | Additional properties for `Resource` objects: @@ -232,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 `PartialCollectionView` 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. @@ -245,6 +249,17 @@ The values of this object's properties **MAY** be: - an array of objects with `@value` and `@lang` properties, - an array of URIs. +#### `PartialCollectionView` 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 `PartialCollectionView` | +| `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 @@ -735,9 +750,12 @@ The top-level response object is a `Navigation` object answering a query about t | `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` | PartialNavigationView | N | A PartialNavigationView 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 `PartialNavigationView` object. + #### Resource | Name | Type | Required | Description | @@ -805,6 +823,20 @@ If the `CitableUnit` parent is the root level of the `Resource`, the value retur } ``` +#### PartialNavigationView + +This object is used to provide links to the first, previous, next, and last pages of a paginated response. + +| 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 "PartialNavigationView". | +| `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 33a381d87356454e471b56e7e8d66b759b1f0a68 Mon Sep 17 00:00:00 2001 From: Ian Scott Date: Wed, 7 Aug 2024 20:00:54 -0400 Subject: [PATCH 3/4] Amalgamated the new pagination opjects into a single type: Pagination --- versions/unstable/README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index 86bc699..1f09236 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -13,7 +13,7 @@ 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 `PartialCollectionView` and `PartialNavigationView` object to describe the pagination. + - 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) @@ -226,7 +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` | PartialCollectionView | N | A PartialCollectionView object for paginated responses. | +| `view` | Pagination | N | A Pagination object for paginated responses. | Additional properties for `Resource` objects: @@ -234,7 +234,7 @@ 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 `PartialCollectionView` object as its value. +If a response is paginated the response object **MUST** include the `view` property with a `Pagination` object as its value. #### `MetadataObject` Structure @@ -249,12 +249,12 @@ The values of this object's properties **MAY** be: - an array of objects with `@value` and `@lang` properties, - an array of URIs. -#### `PartialCollectionView` Structure +#### `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 `PartialCollectionView` | +| `@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 | @@ -616,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", @@ -750,11 +750,11 @@ The top-level response object is a `Navigation` object answering a query about t | `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` | PartialNavigationView | N | A PartialNavigationView object for paginated responses. | +| `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 `PartialNavigationView` object. +If a response is paginated the response object **MUST** include the `view` property with a `Pagination` object. #### Resource @@ -823,14 +823,14 @@ If the `CitableUnit` parent is the root level of the `Resource`, the value retur } ``` -#### PartialNavigationView +#### Pagination -This object is used to provide links to the first, previous, next, and last pages of a paginated response. +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 "PartialNavigationView". | +| `@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. | From 04f6e28b4e19db6dc8f4b753b25920659cd8bd2a Mon Sep 17 00:00:00 2001 From: Ian Scott Date: Thu, 8 Aug 2024 10:34:03 -0400 Subject: [PATCH 4/4] In Navigation examples, moved `collection`, `navigation`, and `document` properties from root of Navigation object to be properties of Resource--as per the changed spec --- versions/unstable/README.md | 48 ++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/versions/unstable/README.md b/versions/unstable/README.md index 1f09236..2031134 100644 --- a/versions/unstable/README.md +++ b/versions/unstable/README.md @@ -940,12 +940,12 @@ 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", "@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}", - "navigation": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula{&ref,down,start,end,tree,page}", "resource": { "@id": "https://en.wikisource.org/wiki/Dracula", "@type": "Resource", + "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}", "citationTrees": [ { "@type": "CitationTree", @@ -1039,12 +1039,12 @@ 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", - "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}", "resource": { "@id": "https://en.wikisource.org/wiki/Dracula", "@type": "Resource", + "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}", "citationTrees": [ { "@type": "CitationTree", @@ -1192,12 +1192,12 @@ 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&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}", - "navigation": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula{&ref,down,start,end,tree,page}", "resource": { "@id": "https://en.wikisource.org/wiki/Dracula", "@type": "Resource", + "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}", "citationTrees": [ { "@type": "CitationTree", @@ -1329,12 +1329,12 @@ 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", "@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}", - "navigation": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula{&ref,down,start,end,tree,page}", "resource": { "@id": "https://en.wikisource.org/wiki/Dracula", "@type": "Resource", + "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}", "citationTrees": [ { "@type": "CitationTree", @@ -1464,12 +1464,12 @@ 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", "@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}", - "navigation": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula{&ref,down,start,end,tree,page}", "resource": { "@id": "https://en.wikisource.org/wiki/Dracula", "@type": "Resource", + "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}", "citationTrees": [ { "@type": "CitationTree", @@ -1565,12 +1565,12 @@ 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", "@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}", - "navigation": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula{&ref,down,start,end,tree,page}", "resource": { "@id": "https://en.wikisource.org/wiki/Dracula", "@type": "Resource", + "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}", "citationTrees": [ { "@type": "CitationTree", @@ -1748,12 +1748,12 @@ 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", "@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}", - "navigation": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula{&ref,down,start,end,tree,page}", "resource": { "@id": "https://en.wikisource.org/wiki/Dracula", "@type": "Resource", + "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}", "citationTrees": [ { "@type": "CitationTree", @@ -1833,12 +1833,12 @@ 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", "@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}", - "navigation": "https://example.org/api/dts/navigation/?resource=https://en.wikisource.org/wiki/Dracula{&ref,down,start,end,tree,page}", "resource": { "@id": "https://en.wikisource.org/wiki/Dracula", "@type": "Resource", + "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}", "citationTrees": [ { "@type": "CitationTree",