├── .gitignore
├── CITATION.cff
├── Cookbook.md
├── FAQ.md
├── Gemfile
├── Gemfile.lock
├── Organization.md
├── README.md
├── _config.yml
├── _data
└── navigation.yml
├── _layouts
└── single.html
├── assets
├── css
│ └── main.scss
├── img
│ ├── citation-tree_dracula-example.png
│ ├── googlegroup.png
│ └── tree-traversal_example.png
└── js
│ └── lunr
│ └── lunr-store.js
├── changelogs.md
├── context
├── 1-alpha1.json
├── 1.0.0-rc1.json
├── 1.0.0draft-2.json
└── dts-ontology.ttl
├── discussions
├── KnownIssues.csv
└── userstories.csv
├── usecases
└── navigation.csv
└── versions
├── 1-alpha
└── README.md
├── 1-draft2
├── Collections.md
├── Document.md
├── Entry.md
├── Navigation.md
└── README.md
└── unstable
└── README.md
/.gitignore:
--------------------------------------------------------------------------------
1 | .bundle
2 | _site
3 | vendor
4 | MyNotes.md
5 |
6 | .DS_Store
--------------------------------------------------------------------------------
/CITATION.cff:
--------------------------------------------------------------------------------
1 | # This CITATION.cff file was generated with cffinit.
2 | # Visit https://bit.ly/cffinit to generate yours today!
3 |
4 | cff-version: 1.2.0
5 | title: Distributed Text Services Specifications
6 | message: >-
7 | If you use this software, please cite it using the
8 | metadata from this file.
9 | type: software
10 | authors:
11 | - given-names: Hugh
12 | family-names: Cayless
13 | affiliation: Duke University
14 | - family-names: Clérice
15 | given-names: Thibault
16 | affiliation: Inria
17 | - given-names: Robie
18 | family-names: Jonathan
19 | - given-names: Ian
20 | family-names: Scott
21 | affiliation: Michigan State University
22 | - given-names: Bridget
23 | family-names: Almas
24 | identifiers:
25 | - type: url
26 | value: 'https://www.w3id.org/dts'
27 | repository-code: >-
28 | https://github.com/distributed-text-services/specifications
29 | url: 'https://w3id.org'
30 | license: CC-BY-4.0
31 | version: 1-alpha
32 |
--------------------------------------------------------------------------------
/Cookbook.md:
--------------------------------------------------------------------------------
1 | # Cookbook
2 |
3 | ## What is the cookbook ?
4 |
5 | The cookbook is a set of recipes to help you deal with common questions about how you might want to express some things using DTS. These are not *enforced* standard practices but recommendations.
6 |
7 | ## IIIF
8 |
9 | ### Link manifests to a catalog entry
10 |
11 | To link a manifest to a catalog entry, we recommend using the Dublin Core Terms property "dct:source" with some human readable information on top of the link:
12 |
13 | ```json
14 | {
15 | "@context": {
16 | "@vocab": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
17 | "sc": "http://iiif.io/api/presentation/2#"
18 | },
19 | "@id": "/a/collection/uri",
20 | "@type" : "Resource",
21 | "title" : "A title",
22 | "totalItems": 0,
23 | "totalParents": 1,
24 | "totalChildren": 0,
25 | "passage": "/api/dts/document?id=/a/collection/uri",
26 | "references": "/api/dts/navigation?id=/a/collection/uri",
27 | "citeDepth": 2,
28 | "dublinCore": {
29 | "source": [
30 | {
31 | "@id": "https://a/manifest/uri",
32 | "@type": "sc:Manifest",
33 | "title": "A manifest title"
34 | }
35 | ]
36 | }
37 | }
38 | ```
39 |
40 | ### Link manifests to a passage
41 |
42 | The operation is really close to the [previous one](#link-manifests-to-a-catalog-entry) as `dublinCore` is also available in the [Navigation endpoint](./navigation-endpoint.html)
43 |
44 | ```json
45 | {
46 | "@context": {
47 | "@vocab": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
48 | "sc": "http://iiif.io/api/presentation/2#"
49 | },
50 | "@id":"/api/dts/navigation/?id=/a/text/id&level=2",
51 | "citeDepth" : 2,
52 | "level": 2,
53 | "member": [
54 | {"ref": "ref 1"},
55 | {
56 | "ref": "ref 2",
57 | "dublinCore": {
58 | "source": [
59 | {
60 | "@id": "https://a/manifest/uri",
61 | "@type": "sc:Manifest",
62 | "title": "A manifest title"
63 | }
64 | ]
65 | }
66 | },
67 | ],
68 | "passage": "/dts/api/document/?id=/a/text/id{&ref}{&start}{&end}"
69 | }
70 | ```
71 |
72 |
--------------------------------------------------------------------------------
/FAQ.md:
--------------------------------------------------------------------------------
1 | # Frequently Asked Questions about DTS
2 |
3 | ## What is DTS?
4 |
5 | DTS is an API for collections of TEI documents.
6 |
7 | ## Why does TEI need an API for collections?
8 |
9 | DTS provides a standard way for clients to interact with collections of TEI documents. A standard API allows users to access many text collections using the same client software. It also allows editors to publish text collections in a usable way that existing clients can use.
10 |
11 | ## Where can I download DTS and start using it?
12 |
13 | You can’t. DTS defines the way that programs communicate with each other. An end-user will use this software. For software developers, there are libraries that support DTS, they are listed [here](../index.html#reference-implementations).
14 |
15 | ## What can clients do with these documents?
16 |
17 | Anything the client knows how to do with textual data. For instance, this data can be presented to users in a reading environment, analyzed for linguistic, literary, and discourse features, or presented in tools that allow users to annotate the text to create useful data.
18 |
19 | ## Will DTS help make my texts FAIR?
20 |
21 | Yes! Publishers of digital text collections can use the DTS API to help them make their textual data Findable, Accessible, Interoperable and Reusable (FAIR).
22 |
23 | DTS supports FAIR data practices for textual data by:
24 |
25 | * encouraging publishers to use stable persistent identifiers for their texts and their collections
26 | * supporting the use of standard vocabularies for the descriptive metadata
27 | * enabling expression of metadata separate from the textual content itself
28 | * providing documented (but unconstrained) access to the information about the structure of a textual resource, down to the level of a citation
29 | * enabling detailed specification of relations among textual resources
30 |
31 | ## What kind of API is DTS?
32 |
33 | DTS is a REST API that works a lot like a web browser. When client software makes a request, the server responds by giving it a document. The client can use the information in this document to make further requests. The API is defined purely in terms of Web requests using HTTP and the documents and headers that the server provides in response to those requests. This means that DTS is language independent, easy to debug, and scales well to large numbers of users. For API geeks, here are the buzzwords: DTS is a pure hypermedia-centric REST API, defined in terms of HTTP conventions.
34 |
35 | DTS is built like you would build a website: everything is discoverable, sorted so that users (clients) can easily find what they want. On top of that, it uses vocabularies that are linked and shared and which you can find all over the web of data.
36 |
37 | ## What is Hydra? Why Hydra?
38 |
39 | Hydra provides a good framework for building REST APIs. We wanted to use a standard instead of starting from scratch. We wanted good support for JSON and pure hypermedia-based APIs. Hydra provides core functionality and provides extensibility that allows us to customize to fit our model. (We tried three or four other approaches before choosing Hydra. We know there are religious debates about APIs, this one worked well for our use cases.)
40 |
41 | ## If I implement the DTS API for my text collection what does it enable?
42 |
43 | Implementing the DTS API enables consumers of the data to easily retrieve:
44 |
45 | * Lists of collection members
46 | * Metadata about individual collection items
47 | * Lists of citeable passages within a text
48 | * Lists of citeable passages within a text as groups of client-defined sizes (e.g. groups of 10 lines)
49 | * Metadata about the citation structure of a document
50 | * A single text passage at any level of the citation hierarchy
51 | * A range of text passages with a clearly defined start and end passage
52 | * An entire text
53 |
54 | ## What identifier schemes does DTS require and support?
55 |
56 | DTS supports any identifier scheme for collections and documents which can expressed safely as a URL parameter.
57 |
58 | ## Does DTS supported nested collections (e.g. collections of collections)?
59 |
60 | Yes.
61 |
62 | ## Does DTS support text citation hierarchies of multiple levels?
63 |
64 | Yes.
65 |
66 | ## Does DTS support text citation hierarchies which vary within a document?
67 |
68 | Yes.
69 |
70 | ## Can I use DTS if I don't publish my texts in TEI/XML?
71 |
72 | Yes, partially.
73 |
74 | The DTS Collection and Navigations endpoints can be used to provide navigation capabilities across
75 | collections of texts and within a textual document regardless of the data format. However, the Document endpoint only suppoorts
76 | TEI texts.
77 |
78 | ## What is the relationship between DTS and CTS? Are they redundant?
79 |
80 | The Distributed Text Services effort was inspired, informed and influenced by the [Canonical Text Services protocol](http://cite-architecture.github.io/cts/) (CTS). CTS has allowed many classical, canonical texts encoded in TEI to be made available in a machine-actionable, linked open data fashion. However, the CTS API is tightly coupled to the CTS URN identifier system which does not support citation systems used by more modern content or other forms of writing, such as papyri or inscriptions. The API also does not adhere to modern community standards for Web APIs.
81 |
82 | DTS was created to address these limitations and enable standardized, machine-actionable operations across a wide variety of texts. DTS is a community-driven initiative that defines a Hypermedia-driven Web Application Programming Interface (API) for working with collections of text as machine-actionable linked data. The DTS specification does not dictate how collections should be organized, what type of persistent identifiers should be used to reference them, what ontologies to use for metadata, how the texts themselves are structured, or how the API itself is to be implemented. It aims to be as generic as possible, providing simple operations for navigating collections, navigating within a text and retrieving textual content. By defining a standard, easily adoptable specification for navigating and interacting with a text collection as machine-actionable data, DTS hopes to provide a standard way to share and reuse collections of textual data.
83 |
84 |
--------------------------------------------------------------------------------
/Gemfile:
--------------------------------------------------------------------------------
1 | source "https://rubygems.org"
2 |
3 | gem "github-pages", group: :jekyll_plugins
4 |
5 | gem "tzinfo-data"
6 | gem "wdm", "~> 0.1.0" if Gem.win_platform?
7 |
8 | # If you have any plugins, put them here!
9 | group :jekyll_plugins do
10 | gem "jekyll-paginate"
11 | gem "jekyll-sitemap"
12 | gem "jekyll-gist"
13 | gem "jekyll-feed"
14 | gem "jemoji"
15 | gem "jekyll-include-cache"
16 | gem "jekyll-algolia"
17 | gem "jekyll-octicons"
18 | end
19 | # Added at 2019-10-09 09:53:47 +0200 by thibault:
20 | gem "pkg-config", "~> 1.3"
21 |
--------------------------------------------------------------------------------
/Gemfile.lock:
--------------------------------------------------------------------------------
1 | GEM
2 | remote: https://rubygems.org/
3 | specs:
4 | activesupport (4.2.11.1)
5 | i18n (~> 0.7)
6 | minitest (~> 5.1)
7 | thread_safe (~> 0.3, >= 0.3.4)
8 | tzinfo (~> 1.1)
9 | addressable (2.8.0)
10 | public_suffix (>= 2.0.2, < 5.0)
11 | algolia_html_extractor (2.6.4)
12 | json (~> 2.0)
13 | nokogiri (~> 1.10)
14 | algoliasearch (1.27.1)
15 | httpclient (~> 2.8, >= 2.8.3)
16 | json (>= 1.5.1)
17 | coffee-script (2.4.1)
18 | coffee-script-source
19 | execjs
20 | coffee-script-source (1.11.1)
21 | colorator (1.1.0)
22 | commonmarker (0.17.13)
23 | ruby-enum (~> 0.5)
24 | concurrent-ruby (1.1.9)
25 | dnsruby (1.61.3)
26 | addressable (~> 2.5)
27 | em-websocket (0.5.1)
28 | eventmachine (>= 0.12.9)
29 | http_parser.rb (~> 0.6.0)
30 | ethon (0.12.0)
31 | ffi (>= 1.3.0)
32 | eventmachine (1.2.7)
33 | execjs (2.7.0)
34 | faraday (0.17.0)
35 | multipart-post (>= 1.2, < 3)
36 | ffi (1.11.1)
37 | filesize (0.2.0)
38 | forwardable-extended (2.6.0)
39 | gemoji (3.0.1)
40 | github-pages (201)
41 | activesupport (= 4.2.11.1)
42 | github-pages-health-check (= 1.16.1)
43 | jekyll (= 3.8.5)
44 | jekyll-avatar (= 0.6.0)
45 | jekyll-coffeescript (= 1.1.1)
46 | jekyll-commonmark-ghpages (= 0.1.6)
47 | jekyll-default-layout (= 0.1.4)
48 | jekyll-feed (= 0.11.0)
49 | jekyll-gist (= 1.5.0)
50 | jekyll-github-metadata (= 2.12.1)
51 | jekyll-mentions (= 1.4.1)
52 | jekyll-optional-front-matter (= 0.3.0)
53 | jekyll-paginate (= 1.1.0)
54 | jekyll-readme-index (= 0.2.0)
55 | jekyll-redirect-from (= 0.14.0)
56 | jekyll-relative-links (= 0.6.0)
57 | jekyll-remote-theme (= 0.4.0)
58 | jekyll-sass-converter (= 1.5.2)
59 | jekyll-seo-tag (= 2.5.0)
60 | jekyll-sitemap (= 1.2.0)
61 | jekyll-swiss (= 0.4.0)
62 | jekyll-theme-architect (= 0.1.1)
63 | jekyll-theme-cayman (= 0.1.1)
64 | jekyll-theme-dinky (= 0.1.1)
65 | jekyll-theme-hacker (= 0.1.1)
66 | jekyll-theme-leap-day (= 0.1.1)
67 | jekyll-theme-merlot (= 0.1.1)
68 | jekyll-theme-midnight (= 0.1.1)
69 | jekyll-theme-minimal (= 0.1.1)
70 | jekyll-theme-modernist (= 0.1.1)
71 | jekyll-theme-primer (= 0.5.3)
72 | jekyll-theme-slate (= 0.1.1)
73 | jekyll-theme-tactile (= 0.1.1)
74 | jekyll-theme-time-machine (= 0.1.1)
75 | jekyll-titles-from-headings (= 0.5.1)
76 | jemoji (= 0.10.2)
77 | kramdown (= 1.17.0)
78 | liquid (= 4.0.0)
79 | listen (= 3.1.5)
80 | mercenary (~> 0.3)
81 | minima (= 2.5.0)
82 | nokogiri (>= 1.10.4, < 2.0)
83 | rouge (= 3.11.0)
84 | terminal-table (~> 1.4)
85 | github-pages-health-check (1.16.1)
86 | addressable (~> 2.3)
87 | dnsruby (~> 1.60)
88 | octokit (~> 4.0)
89 | public_suffix (~> 3.0)
90 | typhoeus (~> 1.3)
91 | html-pipeline (2.14.0)
92 | activesupport (>= 2)
93 | nokogiri (>= 1.4)
94 | http_parser.rb (0.6.0)
95 | httpclient (2.8.3)
96 | i18n (0.9.5)
97 | concurrent-ruby (~> 1.0)
98 | jekyll (3.8.5)
99 | addressable (~> 2.4)
100 | colorator (~> 1.0)
101 | em-websocket (~> 0.5)
102 | i18n (~> 0.7)
103 | jekyll-sass-converter (~> 1.0)
104 | jekyll-watch (~> 2.0)
105 | kramdown (~> 1.14)
106 | liquid (~> 4.0)
107 | mercenary (~> 0.3.3)
108 | pathutil (~> 0.9)
109 | rouge (>= 1.7, < 4)
110 | safe_yaml (~> 1.0)
111 | jekyll-algolia (1.5.0)
112 | algolia_html_extractor (~> 2.6)
113 | algoliasearch (~> 1.26)
114 | filesize (~> 0.1)
115 | jekyll (>= 3.6, < 5.0)
116 | json (~> 2.0)
117 | nokogiri (~> 1.6)
118 | progressbar (~> 1.9)
119 | verbal_expressions (~> 0.1.5)
120 | jekyll-avatar (0.6.0)
121 | jekyll (~> 3.0)
122 | jekyll-coffeescript (1.1.1)
123 | coffee-script (~> 2.2)
124 | coffee-script-source (~> 1.11.1)
125 | jekyll-commonmark (1.3.1)
126 | commonmarker (~> 0.14)
127 | jekyll (>= 3.7, < 5.0)
128 | jekyll-commonmark-ghpages (0.1.6)
129 | commonmarker (~> 0.17.6)
130 | jekyll-commonmark (~> 1.2)
131 | rouge (>= 2.0, < 4.0)
132 | jekyll-default-layout (0.1.4)
133 | jekyll (~> 3.0)
134 | jekyll-feed (0.11.0)
135 | jekyll (~> 3.3)
136 | jekyll-gist (1.5.0)
137 | octokit (~> 4.2)
138 | jekyll-github-metadata (2.12.1)
139 | jekyll (~> 3.4)
140 | octokit (~> 4.0, != 4.4.0)
141 | jekyll-include-cache (0.2.0)
142 | jekyll (>= 3.7, < 5.0)
143 | jekyll-mentions (1.4.1)
144 | html-pipeline (~> 2.3)
145 | jekyll (~> 3.0)
146 | jekyll-octicons (9.1.1)
147 | jekyll (~> 3.1)
148 | octicons (= 9.1.1)
149 | jekyll-optional-front-matter (0.3.0)
150 | jekyll (~> 3.0)
151 | jekyll-paginate (1.1.0)
152 | jekyll-readme-index (0.2.0)
153 | jekyll (~> 3.0)
154 | jekyll-redirect-from (0.14.0)
155 | jekyll (~> 3.3)
156 | jekyll-relative-links (0.6.0)
157 | jekyll (~> 3.3)
158 | jekyll-remote-theme (0.4.0)
159 | addressable (~> 2.0)
160 | jekyll (~> 3.5)
161 | rubyzip (>= 1.2.1, < 3.0)
162 | jekyll-sass-converter (1.5.2)
163 | sass (~> 3.4)
164 | jekyll-seo-tag (2.5.0)
165 | jekyll (~> 3.3)
166 | jekyll-sitemap (1.2.0)
167 | jekyll (~> 3.3)
168 | jekyll-swiss (0.4.0)
169 | jekyll-theme-architect (0.1.1)
170 | jekyll (~> 3.5)
171 | jekyll-seo-tag (~> 2.0)
172 | jekyll-theme-cayman (0.1.1)
173 | jekyll (~> 3.5)
174 | jekyll-seo-tag (~> 2.0)
175 | jekyll-theme-dinky (0.1.1)
176 | jekyll (~> 3.5)
177 | jekyll-seo-tag (~> 2.0)
178 | jekyll-theme-hacker (0.1.1)
179 | jekyll (~> 3.5)
180 | jekyll-seo-tag (~> 2.0)
181 | jekyll-theme-leap-day (0.1.1)
182 | jekyll (~> 3.5)
183 | jekyll-seo-tag (~> 2.0)
184 | jekyll-theme-merlot (0.1.1)
185 | jekyll (~> 3.5)
186 | jekyll-seo-tag (~> 2.0)
187 | jekyll-theme-midnight (0.1.1)
188 | jekyll (~> 3.5)
189 | jekyll-seo-tag (~> 2.0)
190 | jekyll-theme-minimal (0.1.1)
191 | jekyll (~> 3.5)
192 | jekyll-seo-tag (~> 2.0)
193 | jekyll-theme-modernist (0.1.1)
194 | jekyll (~> 3.5)
195 | jekyll-seo-tag (~> 2.0)
196 | jekyll-theme-primer (0.5.3)
197 | jekyll (~> 3.5)
198 | jekyll-github-metadata (~> 2.9)
199 | jekyll-seo-tag (~> 2.0)
200 | jekyll-theme-slate (0.1.1)
201 | jekyll (~> 3.5)
202 | jekyll-seo-tag (~> 2.0)
203 | jekyll-theme-tactile (0.1.1)
204 | jekyll (~> 3.5)
205 | jekyll-seo-tag (~> 2.0)
206 | jekyll-theme-time-machine (0.1.1)
207 | jekyll (~> 3.5)
208 | jekyll-seo-tag (~> 2.0)
209 | jekyll-titles-from-headings (0.5.1)
210 | jekyll (~> 3.3)
211 | jekyll-watch (2.2.1)
212 | listen (~> 3.0)
213 | jemoji (0.10.2)
214 | gemoji (~> 3.0)
215 | html-pipeline (~> 2.2)
216 | jekyll (~> 3.0)
217 | json (2.6.1)
218 | kramdown (1.17.0)
219 | liquid (4.0.0)
220 | listen (3.1.5)
221 | rb-fsevent (~> 0.9, >= 0.9.4)
222 | rb-inotify (~> 0.9, >= 0.9.7)
223 | ruby_dep (~> 1.2)
224 | mercenary (0.3.6)
225 | mini_portile2 (2.8.5)
226 | minima (2.5.0)
227 | jekyll (~> 3.5)
228 | jekyll-feed (~> 0.9)
229 | jekyll-seo-tag (~> 2.1)
230 | minitest (5.14.4)
231 | multipart-post (2.1.1)
232 | nokogiri (1.15.6)
233 | mini_portile2 (~> 2.8.2)
234 | racc (~> 1.4)
235 | octicons (9.1.1)
236 | nokogiri (>= 1.6.3.1)
237 | octokit (4.14.0)
238 | sawyer (~> 0.8.0, >= 0.5.3)
239 | pathutil (0.16.2)
240 | forwardable-extended (~> 2.6)
241 | pkg-config (1.3.9)
242 | progressbar (1.10.1)
243 | public_suffix (3.1.1)
244 | racc (1.7.3)
245 | rb-fsevent (0.10.3)
246 | rb-inotify (0.10.0)
247 | ffi (~> 1.0)
248 | rouge (3.11.0)
249 | ruby-enum (0.7.2)
250 | i18n
251 | ruby_dep (1.5.0)
252 | rubyzip (2.0.0)
253 | safe_yaml (1.0.5)
254 | sass (3.7.4)
255 | sass-listen (~> 4.0.0)
256 | sass-listen (4.0.0)
257 | rb-fsevent (~> 0.9, >= 0.9.4)
258 | rb-inotify (~> 0.9, >= 0.9.7)
259 | sawyer (0.8.2)
260 | addressable (>= 2.3.5)
261 | faraday (> 0.8, < 2.0)
262 | terminal-table (1.8.0)
263 | unicode-display_width (~> 1.1, >= 1.1.1)
264 | thread_safe (0.3.6)
265 | typhoeus (1.3.1)
266 | ethon (>= 0.9.0)
267 | tzinfo (1.2.10)
268 | thread_safe (~> 0.1)
269 | tzinfo-data (1.2019.3)
270 | tzinfo (>= 1.0.0)
271 | unicode-display_width (1.6.0)
272 | verbal_expressions (0.1.5)
273 |
274 | PLATFORMS
275 | ruby
276 |
277 | DEPENDENCIES
278 | github-pages
279 | jekyll-algolia
280 | jekyll-feed
281 | jekyll-gist
282 | jekyll-include-cache
283 | jekyll-octicons
284 | jekyll-paginate
285 | jekyll-sitemap
286 | jemoji
287 | pkg-config (~> 1.3)
288 | tzinfo-data
289 |
290 | BUNDLED WITH
291 | 1.16.1
292 |
--------------------------------------------------------------------------------
/Organization.md:
--------------------------------------------------------------------------------
1 | # Organization
2 |
3 | The Distributed Text Services is a organized and led by a community of volunteers. It is not currently a legal entity. Decisions are made collectively by the [Technical Committee](#technical_committee). Members of this committee share ownership of the GitHub repository and the Google Group. The committee also is responsible for the evolution and documentation of the specification itself.
4 |
5 | ## Technical Committee
6 |
7 | * The **Technical committee** is responsible for voting on feature requests and bugs.
8 | * Having been established, the committee itself is now responsible for approving new members to the committee.
9 | * New feature requests must be voted on by the technical committee in order to be approved as additions to the specification.
10 | * Committee members have 1 month after a feature request is officially opened for voting to provide their vote. Not submitting a vote within that time frame is the same as voting yes. An exception is made for feature requests opened for voting in July and August. The voting period for these is extended to 2 months.
11 | * Decisions are normally made by consensus. If there is need for a vote, the chair is responsible for determining a fair process and ensuring adequately informed discussion ahead of time.
12 | * Consensus means that there is adequate representation, nobody cannot live with the decision, and there is general approval for the decision.
13 |
14 | ## Roles
15 |
16 | ### Technical Committee Member
17 |
18 | * attends at least 1/2 of the regular teleconferences
19 | * is responsible for voting on new feature requests and bugs
20 | * must take into account issues raised by observers and users of the standard
21 | * is responsible for contributing to development of specification features and bug fixes
22 |
23 | ### Chair of the Technical Committee
24 |
25 | The chair has the responsibility to run the meetings, create agendas, ensure that issues are adequately understood before decisions are made, and seek decisions by consensus whenever possible. The chair also ensures that decisions are adequately recorded and assigns and tracks action items.
26 |
27 | ### Ambassador
28 |
29 | * distinguishes a member of the community who makes material contributions to the effort.
30 | * comments on documentation, stays abreast of decisions, provides use cases.
31 |
32 | ### Contributor
33 |
34 | * comments on documentation, stays abreast of decisions, provides use cases.
35 |
36 | ## Technical Committee Members
37 |
38 | - Hugh Cayless (Duke University)
39 | - Thibault Clérice (Inria)
40 | - Jonathan Robie (Biblica, Inc)
41 | - Ian W. Scott (Tyndale Seminary)
42 |
43 | ## Past Members
44 |
45 | - Bridget Almas (Alpheios.net)
46 | - Vincent Jolivet (Ecole Nationale des Chartes)
47 |
48 | ## Ambassadors
49 |
50 | - Matteo Romanello (EPFL)
51 | - Pietro Liuzzo (Hamburg Universität)
52 |
53 | ## Minutes of meetings
54 |
55 | Technical committee minutes can be found at [github.com/distributed-text-services/meeting-notes](https://github.com/distributed-text-services/meeting-notes)
56 |
57 |
58 | ## Specific situations
59 |
60 | ### *Question:* What about excused absences?
61 |
62 | Excused absences are recorded and may be taken into account if a decision to remove a committee member needs to be made.
63 |
64 | ### *Question:* How flexible are we on dates?
65 |
66 | If a member of the technical committee can't make it, we can negotiate dates.
67 |
68 | ### *Question:* What happens if there is no consensus ?
69 |
70 | If consensus cannot be reached in a meeting, we will generally postpone the decision pending further discussion. If we find ourselves unable to reach a decision on an important issue, the chair will work with participants or appoint someone else to work with participants beyond meeting time to try to find agreement. If we simply cannot reach a decision, the group needs to decide how to proceed.
71 |
72 | #### *Question:* What about conflict of interest with the chair, when the chair has a strong opinion?
73 |
74 | * Group members can always say they believe the chair should recuse for a decision or other activity
75 | * Group members can ask chair to be excessively clear whether operating as a member or chairing
76 |
77 | ### *Question:* what is the process for officially opening the voting period for a feature or bug request
78 |
79 | (i.e. does the clock start when the item is submitted, is there a formal triage process, etc.)
80 |
81 | * In general, anything at all complicated should be submitted at least 1 week before a meeting that decides on it.
82 | * If there is consensus to make a decision in a meeting, we can decide
83 |
84 | ## Past and Present Contributors
85 |
86 | The following individuals have contributed to this effort:
87 |
88 | * Bridget Almas
89 | * Hugh Cayless
90 | * Thibault Clérice
91 | * Zachary Fletcher
92 | * Vincent Jolivet
93 | * Pietro Liuzzo
94 | * Emmanuelle Morlock
95 | * Jonathan Robie
96 | * Matteo Romanello
97 | * James Tauber
98 | * Jeffrey C. Witt
99 | * Ian W. Scott
100 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Distributed Text Services (DTS)
2 |
3 | [ Google group](https://groups.google.com/forum/#!forum/distributed-text-services){: .btn .btn--info .btn--x--small}
4 | [ Raise Issues and Ask Questions](https://github.com/distributed-text-services/specifications/issues){: .btn .btn--info .btn--x--small}
5 | [ Check Source and Propose Changes](https://github.com/distributed-text-services/specifications){: .btn .btn--info .btn--x--small}
6 |
7 | *The DTS Specification is currently in a public comment period following the 1-alpha release.*
8 |
9 | ## What is DTS?
10 |
11 | **The Distributed Text Services (DTS) Specification defines an API for working with collections of text as machine-actionable data.**
12 |
13 | Publishers of digital text collections can use the DTS API to help them make their textual data Findable, Accessible, Interoperable and Reusable (FAIR).
14 |
15 | DTS enables _machine-consumption_ of digital text collections, and can be used by consumers of these collections in a variety of ways, such as for data analysis and the development of user-interfaces, tools and services.
16 |
17 | DTS is a _specification_ for an API and not in and of itself an implementation of that API. Reference Implementations are available (see below) and individual text publishers are encouraged to implement this API in their own projects where appropriate.
18 |
19 | See the [FAQ](FAQ.html) for more information and a list of frequently asked questions about DTS.
20 |
21 | ## Supported Operations
22 |
23 | DTS specifies 3 distinct operation endpoints:
24 |
25 | - Navigation _across texts_ is supported by the [Collection Endpoint](versions/unstable/#collection-endpoint)
26 | - Navigation _within a text_ is supported by the [Navigation Endpoint](versions/unstable/#navigation-endpoint)
27 | - Retrieval of complete or partial texts is supported by the [Document Endpoint](versions/unstable/#document-endpoint)
28 |
29 | The Collection and Navigation endpoints return JSON-LD. The Document endpoint is specified to return TEI/XML of the requested text or fragment.
30 |
31 | ## Capabilities
32 |
33 | The DTS API provides the following core capabilities to clients:
34 |
35 | * Retrieve lists of collection members
36 | * Retrieve metadata about individual collection items
37 | * Retrieve lists of citeable passages within a text
38 | * Retrieve metadata about the citation structure of a document
39 | * Retrieve a single text passage at any level of the citation hierarchy
40 | * Retrieve a range of text passages with a clearly defined start and end passage
41 | * Retrieve an entire text
42 |
43 | ## Generic Implementations
44 |
45 | This list includes implementations that should be generic enough to be compatible with a lot of different corpora.
46 |
47 | * [MyDapytains](https://github.com/distributed-text-services/MyDapytains) is a python implementation by a member of the technical committee which uses Flask for web and SaxonC implementation for XPath, XSLT and XQuery.
48 | * [DoTS](https://github.com/chartes/dots) is an implementation from Biblissima + & the Ecole nationale des chartes built on top of BaseX.
49 |
50 | ### Implementation of older versions (Before 1-alpha)
51 |
52 | The following open source libraries implement the DTS API (1.0 Draft):
53 |
54 | * [TEI Publisher client](https://teipublisher.com/exist/apps/tei-publisher/doc/blog/tei-publisher-50.xml)
55 | * Implementation of the DTS API + a Client interface to the API
56 | * Currently supports browsing collections and document retrieval, but not navigation.
57 | * [MyCapytain](https://github.com/Capitains/MyCapytain/tree/3.0.0) + [Nautlius](https://github.com/Capitains/Nautilus/tree/dts-draft-1)
58 | * MyCapytain is a Python library that implements the DTS data model and Nautlius is a Python library that implements the DTS API Endpoints backed by the MyCapytain libary. Both operate on TEI text collections that adhere to the [Capitains Guidelines](http://capitains.org/pages/guidelines)
59 | * [Perseids DTS API](https://github.com/perseids-project/dts-api/)
60 | * Ruby on Rails implementation of the DTS API . Operates on TEI text collections that adhere to the [Capitains Guidelines](http://capitains.org/pages/guidelines)
61 |
62 | ## Known Corpora Accessible via the DTS API
63 |
64 | The following open source libraries implement the DTS API (1.0 Draft):
65 |
66 | * Dracor
67 | * Ecole Nationale des Chartes and
68 | * A small collection of contemporaneous and medieval French literature. The contemporaneous texts are lightly marked up, and the medieval texts are finely annotated. Uses the MyCapytain/Nautilus libraries.
69 | * Alpheios
70 | * A small collection of Latin and Greek texts that have been aligned with linguistic annotations for learning ancient languages. Uses the MyCapytain/Nautilus libraries.
71 | * Perseids
72 | * Serves all textual resources available from Perseus within the Ancient Greek and Latin corpora as well as some resources in Hebrew and Farsi.
73 | * Beta maṣāḥǝft
74 | * Collection of written artefacts from the highlands of Ethiopia and Eritrea mainly in Gǝʿǝz (Classical Ethiopic). In the collection are present both transcriptions of manuscripts and editions of textual units. The scarce availability of transcriptions as well as available editions means that the actual text contents are few in comparison with the textual units and written artefacts identified and described.
75 | * Epigraphische Datenbank Heidelberg
76 | * A corpus of 80,000 short texts from the Latin epigraphic databases.
77 |
78 |
--------------------------------------------------------------------------------
/_config.yml:
--------------------------------------------------------------------------------
1 | remote_theme: "mmistakes/minimal-mistakes@4.16.4"
2 | minimal_mistakes_skin: "contrast"
3 |
4 | title: Distributed Text Services
5 | description: The Distributed Text Services (DTS) Specification defines a Hypermedia-Driven Web API for working with collections of text as machine-actionable data.
6 | repository: "distributed-text-services/specifications"
7 | search: true
8 | search_full_content: true
9 | plugins:
10 | - jekyll-paginate
11 | - jekyll-sitemap
12 | - jekyll-gist
13 | - jekyll-feed
14 | - jemoji
15 | - jekyll-include-cache
16 | - jekyll-font-awesome-sass
17 | defaults:
18 | # _posts
19 | - scope:
20 | path: ""
21 | type: page
22 | values:
23 | layout: single
24 | share: true
25 | author_profile: false
26 | related: false
27 | toc: true
28 | toc_label: "Table of Contents"
29 | toc_icon: "cog"
30 | toc_level: 3
31 | toc_left: true
32 | sidebar: false
33 | classes: wide
34 |
35 | bradcrumbs: true
36 | breadcrumb_home_label : "Home"
37 | breadcrumb_separator : "/"
38 |
--------------------------------------------------------------------------------
/_data/navigation.yml:
--------------------------------------------------------------------------------
1 | # main links
2 | main:
3 | - title: "API Documentation"
4 | url: "versions/unstable/"
5 | - title : "Organization"
6 | url: "Organization.html"
7 | - title : "Cookbook"
8 | url: "Cookbook.html"
9 | - title: "FAQ"
10 | url: "FAQ.html"
11 | - title : "Workshops"
12 | url: "https://distributed-text-services.github.io/workshops"
13 |
--------------------------------------------------------------------------------
/_layouts/single.html:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | ---
4 |
5 | {% if page.header.overlay_color or page.header.overlay_image or page.header.image %}
6 | {% include page__hero.html %}
7 | {% elsif page.header.video.id and page.header.video.provider %}
8 | {% include page__hero_video.html %}
9 | {% endif %}
10 |
11 | {% if page.url != "/" and site.breadcrumbs %}
12 | {% unless paginator %}
13 | {% include breadcrumbs.html %}
14 | {% endunless %}
15 | {% endif %}
16 |
17 |
18 |
28 |
29 |
30 |
31 | {% if page.sidebar %}
32 | {% include sidebar.html %}
33 | {% elsif page.toc_left %}
34 |
{{ site.data.ui-text[site.locale].related_label | default: "You May Also Enjoy" }}
107 |
108 | {% for post in site.posts limit:4 %}
109 | {% if post.id == page.id %}
110 | {% continue %}
111 | {% endif %}
112 | {% include archive-single.html type="grid" %}
113 | {% endfor %}
114 |
115 |
116 | {% endif %}
117 |
118 |
--------------------------------------------------------------------------------
/assets/css/main.scss:
--------------------------------------------------------------------------------
1 | ---
2 | # Only the main Sass file needs front matter (the dashes are enough)
3 | ---
4 | @charset "utf-8";
5 |
6 | @import url("https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css");
7 | @import "minimal-mistakes/skins/{{ site.minimal_mistakes_skin | default: 'default' }}"; // skin
8 | @import "minimal-mistakes"; // main partials
9 |
10 | article {
11 | font-size: $type-size-6!important;
12 | }
13 | .btn {
14 | &--x--small {
15 | font-size: $type-size-7;
16 | padding: 0.25em 0.5em!important;
17 | }
18 | }
19 | a {
20 | text-decoration: none!important;
21 | }
--------------------------------------------------------------------------------
/assets/img/citation-tree_dracula-example.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/distributed-text-services/specifications/460ccfd4c35002676f60b893f505513d73badb1a/assets/img/citation-tree_dracula-example.png
--------------------------------------------------------------------------------
/assets/img/googlegroup.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/distributed-text-services/specifications/460ccfd4c35002676f60b893f505513d73badb1a/assets/img/googlegroup.png
--------------------------------------------------------------------------------
/assets/img/tree-traversal_example.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/distributed-text-services/specifications/460ccfd4c35002676f60b893f505513d73badb1a/assets/img/tree-traversal_example.png
--------------------------------------------------------------------------------
/assets/js/lunr/lunr-store.js:
--------------------------------------------------------------------------------
1 | ---
2 | layout: null
3 | ---
4 |
5 | var store = [
6 | {%- assign docs = site.pages | where_exp:'doc','doc.url contains "html"' -%}
7 | {%- for doc in docs-%}
8 | {%- if doc.header.teaser -%}
9 | {%- capture teaser -%}{{ doc.header.teaser }}{%- endcapture -%}
10 | {%- else -%}
11 | {%- assign teaser = site.teaser -%}
12 | {%- endif -%}
13 | {
14 | "title": {{ doc.title | jsonify }},
15 | "excerpt":
16 | {%- if site.search_full_content == true -%}
17 | {{ doc.content | newline_to_br |
18 | replace:" ", " " |
19 | replace:"", " " |
20 | replace:"", " " |
21 | replace:"", " " |
22 | replace:"", " " |
23 | replace:"", " " |
24 | replace:"", " " |
25 | replace:"", " "|
26 | strip_html | strip_newlines | jsonify }},
27 | {%- else -%}
28 | {{ doc.content | newline_to_br |
29 | replace:" ", " " |
30 | replace:"", " " |
31 | replace:"", " " |
32 | replace:"", " " |
33 | replace:"", " " |
34 | replace:"", " " |
35 | replace:"", " " |
36 | replace:"", " "|
37 | strip_html | strip_newlines | truncatewords: 50 | jsonify }},
38 | {%- endif -%}
39 | "categories": {{ doc.categories | jsonify }},
40 | "tags": {{ doc.tags | jsonify }},
41 | "url": {{ doc.url | absolute_url | jsonify }},
42 | "teaser":
43 | {%- if teaser contains "://" -%}
44 | {{ teaser | jsonify }}
45 | {%- else -%}
46 | {{ teaser | absolute_url | jsonify }}
47 | {%- endif -%}
48 | }{%- unless forloop.last and l -%},{%- endunless -%}
49 | {%- endfor -%}
50 | ]
51 |
--------------------------------------------------------------------------------
/changelogs.md:
--------------------------------------------------------------------------------
1 | Changelogs
2 | ==========
3 |
4 | # 1-draft2 to 1-alpha
5 |
6 | ## Hydra
7 |
8 | We do not adhere anymore **strictly** to Hydra, but draw inspiration from it. The stale status of Hydra puyshed us to move away from complete conformance.
9 |
10 | ## Versioning
11 |
12 | Version is now displayed in a `dtsVersion`
13 |
14 | ## Conformance clarification
15 |
16 | - Added a conformance level 0 and a conformance level 1. Conformance level 1 has a single change compared to level 0: the ability to use ranges in Navigation and Document.
17 | - The API now requires implementation of all endpoints.
18 |
19 | ## Navigation endpoint changes
20 |
21 | - Added a new introduction to the Navigation documentation
22 | - Defined what a citation tree is
23 | - Redefined all classes of object found in the Navigation endpoint (fixes [Issue #184](https://github.com/distributed-text-services/specifications/issues/184) and [Issue #194](https://github.com/distributed-text-services/specifications/issues/194))
24 | - Interactive pagination (user defined page size) has been dropped
25 |
26 | ### Specification changes
27 |
28 | - Reworked the traversal system of the Navigation endpoint in order to clarify the impact of the `down` parameter
29 | - Clarified that document traversal is in document order and defined it
30 | - Provided the ability to retrieve the data to create a table of contents (fixes [Issue #226](https://github.com/distributed-text-services/specifications/issues/226))
31 | - Described the behavior of each combination of query parameters `down`, `start`, `end`, and `ref` (fixes [Issue #91](https://github.com/distributed-text-services/specifications/issues/91) and [Issue #194](https://github.com/distributed-text-services/specifications/issues/194))
32 | - Provided the ability to retrieve siblings of a `CitableUnit`
33 | - Added a `tree` query parameter for handling multiple citation trees (fixes [Issue #142](https://github.com/distributed-text-services/specifications/issues/142), [Issue #223](https://github.com/distributed-text-services/specifications/issues/223), [Issue #202](https://github.com/distributed-text-services/specifications/issues/202))
34 | - Moved `maxCiteDepth` to be a property of `CitationTree` rather than `Resource`
35 | - Encapsulated `citeStructure` inside a `citationTrees` property with respective changes to the relevant classes
36 | - Listed a set of query parameter combinations that would return HTTP errors
37 | - Clarified a way to request only the metadata of a `CitableUnit` without its descendants (fixes [Issue #198](https://github.com/distributed-text-services/specifications/issues/198))
38 |
39 | #### Renamed query parameters, value and properties
40 |
41 | - Changed "max" for `?down` to `-1` when querying for the deepest point in a citation tree
42 | - Changed the `?id` query parameter name to `?resource`
43 | - Renamed the `id` property of `CitableUnit`s to `identifier`
44 |
45 | #### Dropped functionalities
46 |
47 | - Dropped the `groupBy` query parameter
48 |
49 | ## Document Endpoint changes
50 |
51 | - Clarified error codes and condition of errors generations.
52 | - Removed URI templates as per Hydra definition.
53 | - Document endpoints does not require TEI anymore, but still recommend providing XML TEI output.
54 |
55 | ### Specifications changes
56 |
57 | - Added attributes to the `` element to allow for identifying specific nodes within the wrapped TEI (Fixes https://github.com/distributed-text-services/specifications/issues/133)
58 | - Removed the requirement for `Link` and `Media-Type` HTTP Response Headers
59 | - Implementation stil **should** provide such capacity.
60 | - Added implementation of multiple trees through the `?tree` parameter ( (fixes https://github.com/distributed-text-services/specifications/issues/142, https://github.com/distributed-text-services/specifications/issues/223, https://github.com/distributed-text-services/specifications/issues/202)
61 |
62 | #### Renamed query parameters, value and properties
63 |
64 | - Renamed `?id` query parameter identifying a `Resource` to `?resource`
65 | - Renamed the `?format` query parameter for content-negociation to `?mediaType` (Implements parts of https://github.com/distributed-text-services/specifications/issues/225)
66 | - Renamed the `` XML node for XML/TEI responses to ``.
67 |
68 | ## Collection Endpoints changes
69 |
70 | - Interactive pagination (user defined page size) has been dropped
71 |
--------------------------------------------------------------------------------
/context/1-alpha1.json:
--------------------------------------------------------------------------------
1 | {
2 | "@context": {
3 | "hydra": "https://www.w3.org/ns/hydra/core#",
4 | "dct": "http://purl.org/dc/terms/",
5 | "dts": "https://w3id.org/dts/api#",
6 |
7 | "Collection": "dts:Collection",
8 | "Resource": "dts:Resource",
9 | "CitableUnit": "dts:CitableUnit",
10 | "EntryPoint": "dts:EntryPoint",
11 |
12 | "statusCode": "hydra:statusCode",
13 | "Status": "hydra:Status",
14 |
15 | "title": "hydra:title",
16 | "description": "hydra:description",
17 | "member": "hydra:member",
18 | "totalItems": "hydra:totalItems",
19 |
20 | "id": "@id",
21 | "type": "@type",
22 | "lang": "@language",
23 | "value": "@value",
24 | "dublinCore": {
25 | "@id": "dts:dublinCore",
26 | "@context": {
27 | "@vocab": "http://purl.org/dc/terms/"
28 | }
29 | },
30 |
31 | "totalChildren": "dts:totalChildren",
32 | "totalParents": "dts:totalParents",
33 | "maxCiteDepth": "dts:maxCiteDepth",
34 | "references": "dts:references",
35 | "download": "dts:download",
36 | "passage": "dts:passage",
37 |
38 | "extensions": "dts:extensions",
39 | "citeStructure": {
40 | "@id": "dts:citeStructure",
41 | "@type": "@list"
42 | },
43 | "citeType": {
44 | "@id": "dts:citeType",
45 | "@type": "@value",
46 | },
47 |
48 | "referenceNode": "dts:referenceNode",
49 | "level": "dts:level",
50 | "parent": "dts:parent",
51 | "ref": "dts:ref",
52 | "start": "dts:start",
53 | "end": "dts:end"
54 | }
55 | }
56 |
--------------------------------------------------------------------------------
/context/1.0.0-rc1.json:
--------------------------------------------------------------------------------
1 | {
2 | "@context": {
3 | "dts": "https://w3id.org/dts/api#",
4 | "dct": "http://purl.org/dc/terms/",
5 |
6 | "CitableUnit": "dts:CitableUnit",
7 | "CitationTree": "dts:CitationTree",
8 | "CiteStructure": "dts:CiteStructure",
9 | "Collection": "dts:Collection",
10 | "EntryPoint": "dts:EntryPoint",
11 | "MetadataObject": "dts:MetadataObject",
12 | "Navigation": "dts:Navigation",
13 | "Pagination": "dts:Pagination",
14 | "Resource": "dts:Resource",
15 |
16 | "citationTrees": "dts:citationTrees",
17 | "citeStructure":"dts:citeStructure",
18 | "description": "dts:description",
19 | "dublinCore": {
20 | "@id": "dts:dublinCore",
21 | "@context": {
22 | "@vocab": "http://purl.org/dc/terms/"
23 | }
24 | },
25 | "end": "dts:end",
26 | "extensions": "dts:extensions",
27 | "first": "dts:first",
28 | "last": "dts:last",
29 | "member": "dts:member",
30 | "next": "dts:next",
31 | "previous": "dts:previous",
32 | "ref": "dts:ref",
33 | "resource": "dts:resource",
34 | "start": "dts:start",
35 | "title": "dits:title",
36 | "view": "dts:view",
37 |
38 | "citeType": "dts:citeType",
39 | "collection": "dts:collection",
40 | "document": "dts:document",
41 | "download": "dts:download",
42 | "dtsVersion": "dts:dtsVersion",
43 | "identifier": "dts:identifier",
44 | "level": "dts:level",
45 | "mediaTypes": "dts:mediaTypes",
46 | "navigation": "dts:navigation",
47 | "parent": "dts:parent",
48 | "totalChildren": "dts:totalChildren",
49 | "totalParents": "dts:totalParents"
50 |
51 | }
52 | }
53 |
--------------------------------------------------------------------------------
/context/1.0.0draft-2.json:
--------------------------------------------------------------------------------
1 | {
2 | "@context": {
3 | "hydra": "https://www.w3.org/ns/hydra/core#",
4 | "dct": "http://purl.org/dc/terms/",
5 | "dts": "https://w3id.org/dts/api#",
6 |
7 | "Collection": "dts:Collection",
8 | "Resource": "dts:Resource",
9 | "CitableUnit": "dts:CitableUnit",
10 | "EntryPoint": "dts:EntryPoint",
11 |
12 | "statusCode": "hydra:statusCode",
13 | "Status": "hydra:Status",
14 |
15 | "title": "hydra:title",
16 | "description": "hydra:description",
17 | "member": "hydra:member",
18 | "totalItems": "hydra:totalItems",
19 |
20 | "id": "@id",
21 | "type": "@type",
22 | "lang": "@language",
23 | "value": "@value",
24 | "dublinCore": {
25 | "@id": "dts:dublinCore",
26 | "@context": {
27 | "@vocab": "http://purl.org/dc/terms/"
28 | }
29 | },
30 |
31 | "totalChildren": "dts:totalChildren",
32 | "totalParents": "dts:totalParents",
33 | "maxCiteDepth": "dts:maxCiteDepth",
34 | "references": "dts:references",
35 | "download": "dts:download",
36 | "passage": "dts:passage",
37 |
38 | "extensions": "dts:extensions",
39 | "citeStructure": {
40 | "@id": "dts:citeStructure",
41 | "@type": "@list"
42 | },
43 | "citeType": {
44 | "@id": "dts:citeType",
45 | "@type": "@value",
46 | },
47 |
48 | "referenceNode": "dts:referenceNode",
49 | "level": "dts:level",
50 | "parent": "dts:parent",
51 | "ref": "dts:ref",
52 | "start": "dts:start",
53 | "end": "dts:end"
54 | }
55 | }
56 |
--------------------------------------------------------------------------------
/context/dts-ontology.ttl:
--------------------------------------------------------------------------------
1 | @prefix dts: .
2 | @prefix dct: .
3 | @prefix owl: .
4 | @prefix rdf: .
5 | @prefix rdfs: .
6 | @prefix xsd: .
7 |
8 |
9 | a owl:Ontology ;
10 | owl:versionInfo "unstable";
11 | rdfs:label "Distributed Text Services (DTS) Vocabulary" ;
12 | rdfs:seeAlso "https://distributed-text-services.github.io/specifications" .
13 |
14 | ### Classes ###
15 |
16 | dts:CitableUnit
17 | a owl:Class ;
18 | rdfs:label "Citable Unit" ;
19 | rdfs:isDefinedBy .
20 |
21 | dts:CitationTree
22 | a owl:Class ;
23 | rdfs:label "Citation Tree" ;
24 | rdfs:isDefinedBy .
25 |
26 | dts:CiteStructure
27 | a owl:Class ;
28 | rdfs:label "Cite Structure" ;
29 | rdfs:isDefinedBy .
30 |
31 | dts:Collection
32 | a owl:Class ;
33 | rdfs:label "Collection" ;
34 | rdfs:isDefinedBy .
35 |
36 | dts:EntryPoint
37 | a owl:Class ;
38 | rdfs:label "Entrypoint" ;
39 | rdfs:isDefinedBy .
40 |
41 | dts:MetadataObject
42 | a owl:Class ;
43 | rdfs:label "Metadata Object" ;
44 | rdfs:isDefinedBy .
45 |
46 | dts:Navigation
47 | a owl:Class ;
48 | rdfs:label "Navigation" ;
49 | rdfs:isDefinedBy .
50 |
51 | dts:Pagination
52 | a owl:Class ;
53 | rdfs:label "Pagination" ;
54 | rdfs:isDefinedBy .
55 |
56 | dts:Resource
57 | a owl:Class ;
58 | rdfs:label "Resource" ;
59 | rdfs:isDefinedBy .
60 |
61 | ### Object Properties ###
62 |
63 | dts:dublinCore
64 | a owl:ObjectProperty ;
65 | rdfs:domain [
66 | a owl:Class ;
67 | owl:unionOf (dts:Collection dts:Resource dts:CitableUnit)
68 | ] ;
69 | rdfs:range dts:MetadataObject ;
70 | rdfs:label "dublinCore" ;
71 | rdfs:comment "Metadata following the Dublin Core Terms scheme" ;
72 | rdfs:isDefinedBy .
73 |
74 | dts:extensions
75 | a owl:ObjectProperty ;
76 | rdfs:domain [
77 | a owl:Class ;
78 | owl:unionOf (dts:Collection dts:Resource dts:CitableUnit)
79 | ] ;
80 | rdfs:range dts:MetadataObject ;
81 | rdfs:label "extensions" ;
82 | rdfs:comment "Supplementary metadata following other schemes apart from Dublin Core Terms" ;
83 | rdfs:isDefinedBy .
84 |
85 | dts:citationTrees
86 | a owl:ObjectProperty;
87 | rdfs:domain dts:Resource ;
88 | rdfs:range dts:CitationTree ;
89 | rdfs:label "citationTrees" ;
90 | rdfs:comment "Citation Tree, outlining the types of citation in each of the Resources citation tree" ;
91 | rdfs:isDefinedBy .
92 |
93 | dts:view
94 | a owl:ObjectProperty;
95 | rdfs:domain [
96 | a owl:Class ;
97 | owl:unionOf (dts:Collection dts:Resource)
98 | ] ;
99 | rdfs:range dts:Pagination ;
100 | rdfs:label "view" ;
101 | rdfs:comment "Pagination object for paginated responses" ;
102 | rdfs:isDefinedBy .
103 |
104 | dts:first
105 | a owl:ObjectProperty;
106 | rdfs:domain dts:Pagination ;
107 | rdfs:range [
108 | a owl:Class ;
109 | owl:unionOf (dts:Collection dts:Navigation)
110 | ] ;
111 | rdfs:label "first" ;
112 | rdfs:comment "First page of the paginated result set" ;
113 | rdfs:isDefinedBy .
114 |
115 | dts:previous
116 | a owl:ObjectProperty;
117 | rdfs:domain dts:Pagination ;
118 | rdfs:range [
119 | a owl:Class ;
120 | owl:unionOf (dts:Collection dts:Navigation)
121 | ] ;
122 | rdfs:label "previous" ;
123 | rdfs:comment "Previous page of the paginated result set" ;
124 | rdfs:isDefinedBy .
125 |
126 | dts:next
127 | a owl:ObjectProperty;
128 | rdfs:domain dts:Pagination ;
129 | rdfs:range [
130 | a owl:Class ;
131 | owl:unionOf (dts:Collection dts:Navigation)
132 | ] ;
133 | rdfs:label "next" ;
134 | rdfs:comment "Next page of the paginated result set" ;
135 | rdfs:isDefinedBy .
136 |
137 | dts:last
138 | a owl:ObjectProperty;
139 | rdfs:domain dts:Pagination ;
140 | rdfs:range [
141 | a owl:Class ;
142 | owl:unionOf (dts:Collection dts:Navigation)
143 | ] ;
144 | rdfs:label "last" ;
145 | rdfs:comment "Last page of the paginated result set" ;
146 | rdfs:isDefinedBy .
147 |
148 | dts:resource
149 | a owl:ObjectProperty;
150 | rdfs:domain dts:Navigation ;
151 | rdfs:range dts:Resource ;
152 | rdfs:label "resource" ;
153 | rdfs:comment "The Resource whose citation tree is being queried" ;
154 | rdfs:isDefinedBy .
155 |
156 | dts:ref
157 | a owl:ObjectProperty ;
158 | rdfs:domain dts:Navigation ;
159 | rdfs:range dts:CitableUnit ;
160 | rdfs:label "ref" ;
161 | rdfs:comment "The CitableUnit in the citation tree which is being queried" ;
162 | rdfs:isDefinedBy .
163 |
164 | dts:start
165 | a owl:ObjectProperty ;
166 | rdfs:domain dts:Navigation ;
167 | rdfs:range dts:CitableUnit ;
168 | rdfs:label "start" ;
169 | rdfs:comment "The CitableUnit at the beginning of the range in the citation tree which is being queried" ;
170 | rdfs:isDefinedBy .
171 |
172 | dts:end
173 | a owl:ObjectProperty ;
174 | rdfs:domain dts:Navigation ;
175 | rdfs:range dts:CitableUnit ;
176 | rdfs:label "end" ;
177 | rdfs:comment "The CitableUnit at the end of the range in the citation tree which is being queried" ;
178 | rdfs:isDefinedBy .
179 |
180 | dts:citationTrees
181 | a owl:ObjectProperty ;
182 | rdfs:domain dts:Resource ;
183 | rdfs:range dts:CitationTree ;
184 | rdfs:label "citationTrees" ;
185 | rdfs:comment "Links to a CitationTree object" ;
186 | rdfs:isDefinedBy .
187 |
188 | dts:citeStructure
189 | a owl:ObjectProperty ;
190 | rdfs:domain [
191 | a owl:Class ;
192 | owl:unionOf (dts:CiteStructure dts:CitationTree)
193 | ] ;
194 | rdfs:range dts:citeStructure ;
195 | rdfs:label "citeStructure" ;
196 | rdfs:comment "CiteStructure objects" ;
197 | rdfs:isDefinedBy .
198 |
199 | dts:title
200 | a owl:ObjectProperty ;
201 | rdfs:label "title" ;
202 | rdfs:comment "A name for a Collection or Resource."
203 | rdfs:domain [
204 | a owl:Class ;
205 | owl:unionOf (dts:Collection, dts:Resource) ;
206 | ] ;
207 | rdfs:range xsd:string ;
208 | rdfs:isDefinedBy .
209 |
210 | dts:description
211 | a owl:ObjectProperty ;
212 | rdfs:label "description" ;
213 | rdfs:comment "Short description of a Collection or Resource"
214 | rdfs:domain [
215 | a owl:Class ;
216 | owl:unionOf (dts:Collection, dts:Resource) ;
217 | ] ;
218 | rdfs:range xsd:string ;
219 | rdfs:isDefinedBy .
220 |
221 | dts:member
222 | a owl:ObjectProperty ;
223 | rdfs:label "member" ;
224 | rdfs:comment "Contains members of a collection."
225 | rdfs:domain dts:Collection
226 | rdfs:range [
227 | a owl:Class ;
228 | owl:unionOf (dts:Collection, dts:Resource) ;
229 | ] ;
230 | rdfs:isDefinedBy .
231 |
232 | ### Data Properties ###
233 |
234 | dts:dtsVersion
235 | a owl:DatatypeProperty ;
236 | rdfs:domain [
237 | a owl:Class ;
238 | owl:unionOf (dts:EntryPoint dts:Collection dts:Resource dts:Navigation)
239 | ] ;
240 | rdfs:range xsd:string ;
241 | rdfs:label "dtsVersion" ;
242 | rdfs:comment "The version of the DTS specification providing the response" ;
243 | rdfs:isDefinedBy .
244 |
245 | dts:collection
246 | a owl:DatatypeProperty ;
247 | rdfs:domain [
248 | a owl:Class ;
249 | owl:unionOf (dts:EntryPoint dts:Collection dts:Resource)
250 | ] ;
251 | rdfs:range dts:UriTemplate ; # Custom Datatype, see below
252 | rdfs:label "collection" ;
253 | rdfs:comment "Link to the Collection API endpoint" ;
254 | rdfs:isDefinedBy .
255 |
256 | dts:navigation
257 | a owl:DatatypeProperty ;
258 | rdfs:domain [
259 | a owl:Class ;
260 | owl:unionOf (dts:EntryPoint dts:Collection dts:Resource)
261 | ] ;
262 | rdfs:range dts:UriTemplate ; # Custom Datatype, see below
263 | rdfs:label "navigation" ;
264 | rdfs:comment "Link to the Navigation API endpoint" ;
265 | rdfs:isDefinedBy .
266 |
267 | dts:document
268 | a owl:DatatypeProperty ;
269 | rdfs:domain [
270 | a owl:Class ;
271 | owl:unionOf (dts:EntryPoint dts:Resource)
272 | ] ;
273 | rdfs:range dts:UriTemplate ; # Custom Datatype, see below
274 | rdfs:label "document" ;
275 | rdfs:comment "Link to the Document API endpoint" ;
276 | rdfs:isDefinedBy .
277 |
278 | dts:totalParents
279 | a owl:DatatypeProperty ;
280 | rdfs:domain [
281 | a owl:Class ;
282 | owl:unionOf (dts:Collection dts:Resource)
283 | ] ;
284 | rdfs:range xsd:integer ;
285 | rdfs:label "totalParents" ;
286 | rdfs:comment "Total number of parent Collections or Resources" ;
287 | rdfs:isDefinedBy .
288 |
289 | dts:totalChildren
290 | a owl:DatatypeProperty ;
291 | rdfs:domain dts:Collection ; # not dts:Resource!
292 | rdfs:range xsd:integer ;
293 | rdfs:label "totalChildren" ;
294 | rdfs:comment "Total number of child Collections or Resources" ;
295 | rdfs:isDefinedBy .
296 |
297 | dts:download
298 | a owl:DatatypeProperty ;
299 | rdfs:domain [
300 | a owl:Class ;
301 | owl:unionOf (dts:Collection dts:Resource)
302 | ] ;
303 | rdfs:range [
304 | a owl:Class ;
305 | owl:unionOf (xsd:anyURI xsd:string) # range could be either a URI or a key:value pair of mediaType:URL (no example in Specification, therefore xsd:string at the moment)
306 | ] ;
307 | rdfs:label "download" ;
308 | rdfs:comment "A link or a key: value list of media type: link to downloadable versions" ;
309 | rdfs:isDefinedBy .
310 |
311 | dts:mediaTypes
312 | a owl:DatatypeProperty ;
313 | rdfs:domain dts:Resource ;
314 | rdfs:range xsd:string ; # in the Specification it is "array"
315 | rdfs:label "mediaTypes" ;
316 | rdfs:comment "string identifiers for the response body media types (Content-Type values) supported for the Resource in Document endpoint queries" ;
317 | rdfs:isDefinedBy .
318 |
319 | dts:identifier
320 | a owl:DatatypeProperty ;
321 | rdfs:domain [
322 | a owl:Class ;
323 | owl:unionOf (dts:CitationTree dts:CitableUnit)
324 | ] ;
325 | rdfs:range xsd:string ;
326 | rdfs:label "identifier" ;
327 | rdfs:comment "String identifier of the Citation Tree or Citable Unit" ;
328 | rdfs:isDefinedBy .
329 |
330 | dts:citeType
331 | a owl:DatatypeProperty ;
332 | rdfs:domain [
333 | a owl:Class ;
334 | owl:unionOf (dts:CiteStructure dts:CitableUnit)
335 | ] ;
336 | rdfs:range xsd:string ;
337 | rdfs:label "citeType" ;
338 | rdfs:comment "Type of textual unit that appears at a given level in the citation tree. (E.g., “chapter”, “verse”)" ;
339 | rdfs:isDefinedBy .
340 |
341 | dts:level
342 | a owl:DatatypeProperty ;
343 | rdfs:domain dts:CitableUnit ;
344 | rdfs:range xsd:integer ;
345 | rdfs:label "level" ;
346 | rdfs:comment "Number identifying the depth at which the CitableUnit is found within the citation tree of the Resource" ;
347 | rdfs:isDefinedBy .
348 |
349 | dts:parent
350 | a owl:DatatypeProperty ;
351 | rdfs:domain dts:CitableUnit ;
352 | rdfs:range dts:NullableString ; # Should be nullable string, need to define that datatype, see below
353 | rdfs:label "parent" ;
354 | rdfs:comment "String identifier of the hierarchical parent of the CitableUnit in the Resource" ;
355 | rdfs:isDefinedBy .
356 |
357 | # Custom Datatypes
358 |
359 | dts:NullableString
360 | a rdfs:Datatype ;
361 | rdfs:label "nullable string" ;
362 | rdfs:comment "A string that can be null or empty" ;
363 | owl:equivalentClass [
364 | a owl:Class ;
365 | owl:unionOf (
366 | [ a rdfs:Datatype ;
367 | owl:onDatatype xsd:string ;
368 | owl:withRestrictions ([ xsd:minLength 0 ]) ]
369 | [ a owl:DataRange ; owl:oneOf ( "" ) ]
370 | )
371 | ] ;
372 | rdfs:isDefinedBy .
373 |
374 | dts:UriTemplate
375 | a rdfs:Datatype ;
376 | rdfs:label "uri template" ;
377 | rdfs:comment "The Distributed Text Services specifications reuse the RFC 6570 for defining the syntax of URI templates used to build URL on the API in its various endpoints" ;
378 | rdfs:seeAlso ;
379 | owl:equivalentClass [
380 | a rdfs:Datatype ;
381 | owl:onDatatype xsd:string ;
382 | owl:withRestrictions (
383 | [
384 | xsd:pattern ".*\\{[^}]*\\}.*" ; # strings containing {} placeholders, maybe must be refined
385 | ]
386 | )
387 | ] ;
388 | rdfs:isDefinedBy .
--------------------------------------------------------------------------------
/discussions/KnownIssues.csv:
--------------------------------------------------------------------------------
1 | Level,Title,Description
2 | Metadata,Edition have only one language,CTS right now accepts only one language for its editions. What about text which do not have clear first language (Religious texts Bodin ?)
3 | Request,Inventory needs pagination or filtering,For text repository with thousands of text; it is not possible to reply with full inventory.
4 |
--------------------------------------------------------------------------------
/discussions/userstories.csv:
--------------------------------------------------------------------------------
1 | As,I want to,So that,Access Type,Data Type,
2 | client application,query for digital resources represented by an abstract work,I can retrieve digital resources,search,ID,
3 | client application,query whether a specific digital edition is available,I can know whether I can retrieve it,search,ID,
4 | client application,access the most recent version of a digital edition of an abstract work,I can do something with it,read,content,
5 | client application,find which digital editions of an abstract work are available,I can choose one,search,ID,
6 | client application,be served an alternate edition if the one I asked for is not available but another is,I can automatically resolve references to other versions,read,collection,
7 | client application,find out if any editions of a work are available which have a specific passage range,I can choose one that will resolve my passage reference,search,ID,
8 | client application,perform CRUD operations on a named curated collection of texts,can offer custom subsets,update,collection,
9 | client application,retrieve a specific passage of a text,I can do something with it,read,content,
10 | client application,get a list of available works filtered by author,I can choose one,search,metadata,
11 | client application,get a list of available works filtered by texgroup,I can choose one,search,metadata,
12 | client application,get a list of available editions or translations filtered by author,I can choose one,search,metadata,
13 | client application,get a list of available editions or translations filtered by author and language,I can choose one,search,metadata,
14 | client application,retrieve the entire contents of a text,I can do something with it,read,content,
15 | client application,retrieve an ordered list of available passages in a text,I can choose one,search,ID,
16 | client application,find the previous and next passages for a given passage,I can navigate a text,search,ID,
17 | client application,get descriptive metadata about a specific edition,I can do something with it,read,metadata,
18 | client application,get descriptive metadata about a work,I can do something with it,read,metadata,
19 | client application,get descriptive metadata about a textgroup,I can do something with it,read,metadata,
20 | client application,get descriptive metadata about an author,I can do something with it,read,metadata,
21 | client application,find out which repositories are available,I can choose one,search,collection,
22 | client application,find out which repositories contain a specific work,I can choose one,search,ID,
23 | client application,find out which repositories contain a specific edition of a work,I can choose one,search,ID,
24 | canonical texts contributor (?),post my new edition of a text with an id,it can be queried via DTS,update,ID,
25 | canonical texts contributor (?),post my new collection of texts with an id,it can be queried via DTS,update,collection,
26 | canonical texts contributor (?),I want to increment the canonical references list,so that people can use it as canonical,update,collection,
27 | client application,query for literature papyri inscriptions from one service,so that I don’t have to query different things,search,ID,
28 | client application,get a standard final result (first line of translation in english or first line of latin text) if I don’t specify further my query,so that I don’t need to care about the several options,read,content,
29 | client application,use several traditional systems to retrive the text I mean,so that I don’t need to know the canonical reference (the system knows it),read,content,
30 | user,to see what’s canonical,I know what to query for,search,collection,
31 | client application,get the first page of a text,I can read it,read,content,
32 | client application,get the first page of the current text,I can read it,read,content,
33 | client application,get the next page of the current text,I can read it,read,content,
34 | client application,get the previous page of the current text,I can read it,read,content,
35 | client application,get the table of contents of the current text,I can find what I am looking for,read,content,
36 | client application,full-text search the contents of the current text,I can find examples or known texts,search,content,
37 | client application,full-text search the contents of a collection of texts,I can find examples or known texts,search,content,
38 | client application,full-text search the contents of a collection of texts filtered by metadata,I can find examples or known texts that satisfy metadata conditions,search,content,
39 | client application,get the revision history for a text,I can see what was changed by whom for what reason on what date,search,metadata,
40 | client application,get a specific book of the Bible such as John and see all available manuscripts and critical editions,I can pick one to read,search,content,
41 | client application,get a specific chapter of a book of the Bible such as John 1 and see all available manuscripts and critical editions,I can read it,search,content,
42 | client application,get a specific verse of a book of the Bible such as John 2:1 and see all available manuscripts and critical editions,I can read it,search,content,
43 | client application,get annotations on a specific book/chapter/verse/word,I can see what others have said about it,search,content,
44 | client application,get annotations by a specific user or group on a specific book/chapter/verse/word,I can see what others have said about it,search,content,
45 | client application,get annotations by users or groups with specific characteristics on a specific book/chapter/verse/word,I can see what others have said about it,search,content,
46 | client application,get papyrii and transcriptions for a specific book/chapter/verse/word,I can read the original artifact with a little help,search,content,
47 | client application,insert an annotation on a text or image of a specific book/chapter/verse/word,I can collect and share my thoughts,update,content,
48 | client application,vote on another person's annotation, I can have my own favorites to find easily and make these more prominent for others, update, content,
49 |
50 |
--------------------------------------------------------------------------------
/usecases/navigation.csv:
--------------------------------------------------------------------------------
1 | ID,Priority,I want to...,In order to...,Deeper Example
2 | 1,0,retrieve all passages references of a text at the root level,present what are the main parts of the text,
3 | 2,0,retrieve all passages references of a text at any given level,know more about the architecture of a given node,
4 | 3,0,retrieve all passages reference of a text in a traversing way,do not have to query every level one by one,
5 | 4,0,retrieve siblings of a passage range,navigate from one passage range to another,
6 | 5,0,retrieve siblings of a passage range,propose a semi-automatic way to browse texts,
7 | 6,1,retrieve passages types,identify how to serve ranges based on types,A text is built on two architectures (book-poem-line; poem-line); I need to know where the architecture changes to build a well-thought table of content
8 | 7,1,retrieve passages types,identify some ruptures in the narrative flow,One could argue that knowing we move from poem to poem means passages references are the lowest continuous unit of consolidated narratives. The last word of the poem 1 is not tied to the first word of poem 2.
9 | 8,2,retrieve title of passages,build a more human-readable table of content, I do not want as a data consummer to have to parse XML TEI documents and be dependant on the scheme implemented for TOC building
10 | 9,3,retrieve author of passages,display more in depth information,
11 | 10,0,retrieve the ancestors of a passage identifier,I can provide link to broader views of the current passage,
12 | 11,?,browse all passages references depending on a specific citation scheme,present a different view of a document,I want to be able to present a fac-simile view of a document and a canonical view of a document
13 | 12,?,browse all passages filtered on some type,not display side citation system,I have a text in a repository where they allow people to cite notes but as a NLP researcher I do not care about these notes as they are not part of the original text
14 | 13,?,retrieve the lang of passages,propose different tool in my UI for understanding the text,
15 | 14,?,not be forced to give unecessary metadata or metadata that I don't have,not to make up dummy data to stick to the standard,
16 |
--------------------------------------------------------------------------------
/versions/1-draft2/Collections.md:
--------------------------------------------------------------------------------
1 | ## Status of this Document
2 |
3 | - This Version: 1-draft2
4 |
5 | This document reflects the status of the version 1-draft2, check API Documentation for the current correct version.
6 |
7 | # Collection Endpoint
8 |
9 | The collection endpoint is used for navigating collections. A collection contains metadata for the collection itself and an array of members. Each member is either a collection or the metadata for a document.
10 |
11 | DTS does not specify URLs. Clients should discover URLs using navigation and link relations since URLs may differ among implementations.
12 |
13 | ### Hydra Representation and Hierarchy
14 |
15 | DTS does not specify any particular hierarchy of collections. A collection might provide all documents in a flat collection or a collection hierarchy organized by geography, time, or any other convenient logical grouping.
16 |
17 | ## Scheme
18 |
19 | Everything that is not marked as Optional is mandatory.
20 |
21 | JSON wide attributes :
22 |
23 | - `@context` must set the default vocabulary to Hydra and provide DCT, TEI and DTS namespace prefixes
24 |
25 | Item properties :
26 |
27 | - `title` is a single string. Additional descriptions may be placed in `dublinCore` using `title`, e.g. for internationalization.
28 | - `@id` is the identifier of the object (TODO: add language recommending the use of URIs for ids)
29 | - `@type` is either `Collection` or `Resource`
30 | - `totalItems` - total number of items that you can find in the members property (irrespective of pagination)
31 | - `totalChildren` - total number of members that you will find if you do nav=children
32 | - `totalParents` - total number of members that you will find if you do nav=parents
33 | - (Required on Resource) `maxCiteDepth` declare the maximum depth of a readable resource.
34 | - (Optional) `description` is a string that describes the object. Additional descriptions may be placed in `dublinCore` using `description`, e.g. for internationalization.
35 | - (Optional) `member` contains members of the collection
36 | - (Optional) `dublinCore` contains Dublin Core Terms metadata
37 | - (Optional) `extensions` contains any supplementary information provided by other ontologies/domains
38 | - (Optional) `references` contains links to the Navigation API route for the object (TODO: mandatory in children of `member`?)
39 | - (Optional) `passage` contains a link to the Document API for the object
40 | - (Optional) `download` contains a link or a list of links to a downloadable format of the object (TODO: decide on link or map of type:URL)
41 | - (Optional) `citeStructure` holds a declared citation tree, see [Child Readable Collection](#child-readable-collection) below.
42 |
43 | ## URI
44 |
45 | ### Query Parameters
46 |
47 | The collection endpoint supports the following query parameters:
48 |
49 | | name | description | methods |
50 | |------|------------------------------------------|---------|
51 | | id | identifier for a collection or document. | GET |
52 | | page | page of the current collection's members | GET |
53 | | nav | whether members of the collection are its `children` (default) or `parents` | GET |
54 |
55 | ### URI Template
56 |
57 | Here is a template of the URI for Collection API. The route itself (`/dts/api/collection/`) is up to the implementer.
58 |
59 | ```json
60 | {
61 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
62 | "@type": "IriTemplate",
63 | "template": "/dts/api/collection/?id={collection_id}&page={page}",
64 | "variableRepresentation": "BasicRepresentation",
65 | "mapping": [
66 | {
67 | "@type": "IriTemplateMapping",
68 | "variable": "collection_id",
69 | "required": false
70 | },
71 | {
72 | "@type": "IriTemplateMapping",
73 | "variable": "page",
74 | "required": false
75 | }
76 | ]
77 | }
78 | ```
79 |
80 | ## Examples
81 |
82 | ### Root collection
83 |
84 | This is an example of a top-level Collection that groups texts into 3 categories.
85 |
86 | #### Example of url :
87 |
88 | - `/api/dts/collection/`
89 | - `/api/dts/collection/?id=general`
90 |
91 | #### Headers
92 |
93 | | Key | Value |
94 | | --- | ----- |
95 | | Content-Type | Content-Type: application/ld+json |
96 |
97 | #### Response
98 |
99 | ```json
100 | {
101 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
102 | "@id": "general",
103 | "@type": "Collection",
104 | "totalItems": 2,
105 | "totalParents": 0,
106 | "totalChildren": 2,
107 | "title": "Collection Générale de l'École Nationale des Chartes",
108 | "dublinCore": {
109 | "publisher": ["École Nationale des Chartes", "https://viaf.org/viaf/167874585"],
110 | "title": [
111 | {"lang": "fr", "value": "Collection Générale de l'École Nationale des Chartes"}
112 | ]
113 | },
114 | "member": [
115 | {
116 | "@id" : "cartulaires",
117 | "title" : "Cartulaires",
118 | "description": "Collection de cartulaires d'Île-de-France et de ses environs",
119 | "@type" : "Collection",
120 | "totalItems" : 10,
121 | "totalParents": 1,
122 | "totalChildren": 10
123 | },
124 | {
125 | "@id" : "lasciva_roma",
126 | "title" : "Lasciva Roma",
127 | "description": "Collection of primary sources of interest in the studies of Ancient World's sexuality",
128 | "@type" : "Collection",
129 | "totalItems" : 1,
130 | "totalParents": 1,
131 | "totalChildren": 1
132 | },
133 | {
134 | "@id" : "lettres_de_poilus",
135 | "title" : "Correspondance des poilus",
136 | "description": "Collection de lettres de poilus entre 1917 et 1918",
137 | "@type" : "Collection",
138 | "totalItems" : 10000,
139 | "totalParents": 1,
140 | "totalChildren": 10000
141 | }
142 | ]
143 | }
144 | ```
145 |
146 |
147 | ### Child collection containing a single work
148 |
149 | The example is a child of the parent root collection. It contains a single textual work as a member collection.
150 |
151 | #### Example of url :
152 |
153 | - `/api/dts/collection/?id=lasciva_roma`
154 |
155 | #### Headers
156 |
157 | | Key | Value |
158 | | --- | ----- |
159 | | Content-Type | Content-Type: application/ld+json |
160 |
161 | #### Response
162 |
163 | ```json
164 | {
165 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
166 | "@id": "lasciva_roma",
167 | "@type": "Collection",
168 | "totalItems": 3,
169 | "totalParents": 1,
170 | "totalChildren": 3,
171 | "title" : "Lasciva Roma",
172 | "description": "Collection of primary sources of interest in the studies of Ancient World's sexuality",
173 | "dublinCore": {
174 | "creator": [
175 | "Thibault Clérice", "http://orcid.org/0000-0003-1852-9204"
176 | ],
177 | "title" : [
178 | {"lang": "la", "value": "Lasciva Roma"},
179 | ],
180 | "description": [
181 | {
182 | "lang": "en",
183 | "value": "Collection of primary sources of interest in the studies of Ancient World's sexuality"
184 | }
185 | ],
186 | },
187 | "member": [
188 | {
189 | "@id" : "urn:cts:latinLit:phi1103.phi001",
190 | "title" : "Priapeia",
191 | "dublinCore": {
192 | "type": [
193 | "http://chs.harvard.edu/xmlns/cts#work"
194 | ],
195 | "creator": [
196 | {"lang": "en", "value": "Anonymous"}
197 | ],
198 | "language": ["la", "en"],
199 | "description": [
200 | { "lang": "en", "value": "Anonymous lascivious Poems" }
201 | ],
202 | },
203 | "@type" : "Collection",
204 | "totalItems": 1,
205 | "totalParents": 1,
206 | "totalChildren": 1
207 | }
208 | ]
209 | }
210 | ```
211 |
212 | ### Child collection representing a single work
213 |
214 | The example is a child collection. It represent a single textual work and its members are textual Resources that are individual expressions of that work. These Resources are therefore Readable Collections.
215 |
216 |
217 | #### Note
218 |
219 | Although, this is optional, the expansion of `@type:Resource`'s metadata is advised to avoid multiple API calls.
220 |
221 | #### Example of url :
222 |
223 | - `/api/dts/collection/?id=urn:cts:latinLit:phi1103.phi001`
224 |
225 | #### Headers
226 |
227 | | Key | Value |
228 | | --- | ----- |
229 | | Content-Type | Content-Type: application/ld+json |
230 |
231 | #### Response
232 |
233 | ```json
234 | {
235 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
236 | "@id": "urn:cts:latinLit:phi1103.phi001",
237 | "@type": "Collection",
238 | "title" : "Priapeia",
239 | "dublinCore": {
240 | "type": ["http://chs.harvard.edu/xmlns/cts#work"],
241 | "creator": [
242 | {"lang": "en", "value": "Anonymous"}
243 | ],
244 | "language": ["la", "en"],
245 | "title": [{"lang": "la", "value": "Priapeia"}],
246 | "description": [{
247 | "lang": "en",
248 | "value": "Anonymous lascivious Poems "
249 | }]
250 | },
251 | "totalItems" : 1,
252 | "totalParents": 1,
253 | "totalChildren": 1,
254 | "member": [
255 | {
256 | "@id" : "urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
257 | "@type": "Resource",
258 | "title" : "Priapeia",
259 | "description": "Priapeia based on the edition of Aemilius Baehrens",
260 | "totalItems": 0,
261 | "totalParents": 1,
262 | "totalChildren": 0,
263 | "dublinCore": {
264 | "title": [{"lang": "la", "value": "Priapeia"}],
265 | "description": [{
266 | "lang": "en",
267 | "value": "Anonymous lascivious Poems "
268 | }],
269 | "type": [
270 | "http://chs.harvard.edu/xmlns/cts#edition",
271 | "Text"
272 | ],
273 | "source": ["https://archive.org/details/poetaelatinimino12baeh2"],
274 | "dateCopyrighted": 1879,
275 | "creator": [
276 | {"lang": "en", "value": "Anonymous"}
277 | ],
278 | "contributor": ["Aemilius Baehrens"],
279 | "language": ["la", "en"]
280 | },
281 | "passage": "/api/dts/document?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
282 | "references": "/api/dts/navigation?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
283 | "download": "https://raw.githubusercontent.com/lascivaroma/priapeia/master/data/phi1103/phi001/phi1103.phi001.lascivaroma-lat1.xml",
284 | "maxCiteDepth": 2,
285 | "citeStructure": [
286 | {
287 | "citeType": "poem",
288 | "citeStructure": [
289 | {
290 | "citeType": "line"
291 | }
292 | ]
293 | }
294 | ]
295 | }
296 | ]
297 | }
298 | ```
299 |
300 | ### Child Readable Collection (i.e. a textual Resource)
301 | This example is a child Readable Collection, i.e. a textual Resource which is composed of passages of readable text. The response includes fields which identify the urls for the other 2 DTS api endpoints for further exploration of this Collection: references for retrieval of passage references and passage for retrieval of the entire collection of text passages (i.e the full document itself).
302 |
303 | #### Example of url :
304 |
305 | - `/api/dts/collection/?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1`
306 |
307 | #### Headers
308 |
309 | | Key | Value |
310 | | --- | ----- |
311 | | Content-Type | Content-Type: application/ld+json |
312 |
313 | #### Response Example 1
314 |
315 | ```json
316 | {
317 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
318 | "@id": "urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
319 | "@type" : "Resource",
320 | "title" : "Priapeia",
321 | "description": "Priapeia based on the edition of Aemilius Baehrens",
322 | "totalItems": 0,
323 | "totalParents": 1,
324 | "totalChildren": 0,
325 | "dublinCore": {
326 | "title": [{"lang": "la", "value": "Priapeia"}],
327 | "description": [{
328 | "lang": "en",
329 | "value": "Anonymous lascivious Poems "
330 | }],
331 | "type": [
332 | "http://chs.harvard.edu/xmlns/cts#edition",
333 | "Text"
334 | ],
335 | "source": ["https://archive.org/details/poetaelatinimino12baeh2"],
336 | "dateCopyrighted": 1879,
337 | "creator": [
338 | {"lang": "en", "value": "Anonymous"}
339 | ],
340 | "contributor": ["Aemilius Baehrens"],
341 | "language": ["la", "en"]
342 | },
343 | "passage": "/api/dts/document?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
344 | "references": "/api/dts/navigation?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
345 | "download": "https://raw.githubusercontent.com/lascivaroma/priapeia/master/data/phi1103/phi001/phi1103.phi001.lascivaroma-lat1.xml",
346 | "maxCiteDepth": 2,
347 | "citeStructure": [
348 | {
349 | "citeType": "poem",
350 | "citeStructure": [
351 | {
352 | "citeType": "line"
353 | }
354 | ]
355 | }
356 | ]
357 | }
358 | ```
359 |
360 | #### Response Example 2
361 |
362 | ```json
363 | {
364 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
365 | "@id": "https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica",
366 | "@type" : "Resource",
367 | "title" : "Bucolica",
368 | "totalItems": 0,
369 | "totalParents": 1,
370 | "totalChildren": 0,
371 | "passage": "/api/dts/document?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica",
372 | "references": "/api/dts/navigation?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica",
373 | "download": "https://github.com/sjhuskey/Calpurnius_Siculus/blob/master/editio.xml",
374 | "maxCiteDepth": 2,
375 | "citeStructure": [
376 | {
377 | "citeType": "front"
378 | },
379 | {
380 | "citeType": "poem",
381 | "citeStructure": [
382 | {
383 | "citeType": "line"
384 | }
385 | ]
386 | }
387 | ]
388 | }
389 | ```
390 |
391 |
392 | ### Paginated Child Collection
393 |
394 | This is an example of a paginated request for a Child Collection's members.
395 |
396 | #### Example of url :
397 |
398 | - `/api/dts/collection/?id=lettres_de_poilus&page=19`
399 |
400 | #### Headers
401 |
402 | | Key | Value |
403 | | --- | ----- |
404 | | Content-Type | Content-Type: application/ld+json |
405 |
406 | #### Response
407 |
408 | ```json
409 | {
410 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
411 | "@id" : "lettres_de_poilus",
412 | "@type" : "Collection",
413 | "totalItems" : 10000,
414 | "totalParents": 1,
415 | "totalChildren": 10000,
416 | "title": "Lettres de Poilus",
417 | "dublinCore": {
418 | "publisher": ["École Nationale des Chartes", "https://viaf.org/viaf/167874585"],
419 | "title": [
420 | {"lang": "fr", "value" : "Lettres de Poilus"}
421 | ]
422 | },
423 | "member": ["member 190 up to 200"],
424 | "view": {
425 | "@id": "/api/dts/collection/?id=lettres_de_poilus&page=19",
426 | "@type": "PartialCollectionView",
427 | "first": "/api/dts/collection/?id=lettres_de_poilus&page=1",
428 | "previous": "/api/dts/collection/?id=lettres_de_poilus&page=18",
429 | "next": "/api/dts/collection/?id=lettres_de_poilus&page=20",
430 | "last": "/api/dts/collection/?id=lettres_de_poilus&page=500"
431 | }
432 | }
433 | ```
434 |
435 | ### Parent Collection Query
436 |
437 | This is an example of a query for the parents of a Collection. Note that, in this context, `totalItems` == `totalParents`
438 |
439 | #### Example of url :
440 |
441 | - `/api/dts/collection/?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1&nav=parents`
442 |
443 | #### Headers
444 |
445 | | Key | Value |
446 | | --- | ----- |
447 | | Content-Type | Content-Type: application/ld+json |
448 |
449 | #### Response
450 |
451 | ```json
452 | {
453 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
454 | "@id": "urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
455 | "@type" : "Resource",
456 | "title" : "Priapeia",
457 | "description": "Priapeia based on the edition of Aemilius Baehrens",
458 | "totalItems": 1,
459 | "totalParents": 1,
460 | "totalChildren": 0,
461 | "dublinCore": {
462 | "title": [{"lang": "la", "value": "Priapeia"}],
463 | "description": [{
464 | "lang": "en",
465 | "value": "Anonymous lascivious Poems "
466 | }],
467 | "type": [
468 | "http://chs.harvard.edu/xmlns/cts#edition"
469 | ],
470 | "source": ["https://archive.org/details/poetaelatinimino12baeh2"],
471 | "dateCopyrighted": 1879,
472 | "creator": [
473 | {"lang": "en", "value": "Anonymous"}
474 | ],
475 | "contributor": ["Aemilius Baehrens"],
476 | "language": ["la", "en"]
477 | },
478 | "passage": "/api/dts/document?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
479 | "references": "/api/dts/navigation?id=urn:cts:latinLit:phi1103.phi001.lascivaroma-lat1",
480 | "download": "https://raw.githubusercontent.com/lascivaroma/priapeia/master/data/phi1103/phi001/phi1103.phi001.lascivaroma-lat1.xml",
481 | "maxCiteDepth": 2,
482 | "citeStructure": [
483 | {
484 | "citeType": "poem",
485 | "citeStructure": [
486 | {
487 | "citeType": "line"
488 | }
489 | ]
490 | }
491 | ],
492 | "member": [
493 | {
494 | "@id" : "urn:cts:latinLit:phi1103.phi001",
495 | "title" : "Priapeia",
496 | "dublinCore": {
497 | "type": [
498 | "http://chs.harvard.edu/xmlns/cts#work"
499 | ],
500 | "creator": [
501 | {"lang": "en", "value": "Anonymous"}
502 | ],
503 | "language": ["la", "en"],
504 | "description": [
505 | { "lang": "en", "value": "Anonymous lascivious Poems" }
506 | ],
507 | },
508 | "@type" : "Collection",
509 | "totalItems": 1,
510 | "totalParents": 1,
511 | "totalChildren": 1,
512 | }
513 | ]
514 | }
515 | ```
516 |
--------------------------------------------------------------------------------
/versions/1-draft2/Document.md:
--------------------------------------------------------------------------------
1 | ## Status of this Document
2 |
3 | - This Version: 1-draft2
4 |
5 | This document reflects the status of the version 1-draft2, check API Documentation for the current correct version.
6 |
7 | # Document Endpoint
8 |
9 | The Document endpoint is used to access and modify the content of document, as opposed to metadata (which is found in collections). Implementations must at least support reading document using `GET` requests as described below. The other request methods (POST, PUT, DELETE) are not required and they may be implemented selectively. For example, an implementation could allow `PUT` operations to update the contents of a document, but not support the total removal of document sections using `DELETE`. If an implementation is going to allow modification of document contents please do so using these methods as described below. An implementation should always document clearly which methods are supported for this endpoint. This should be included both in the human-readable API guidelines and in the endpoint's machine-readable documentation using the `supportedOperation` term. (See the section [Machine Readable Endpoint Documentation](#machine-readable-documentation-of-supported-methods) below.)
10 |
11 | ## Default Request and Response Body Format
12 |
13 | Implementations of the DTS Document endpoint **must**, at minimum, return textual data in an XML format compliant with the Text Encoding Initiative (TEI) guidelines (`application/tei+xml` response format). The XML must be well formed and valid. This should be the default response format.
14 |
15 | Implementations **may** return requested data in as many other formats as the content provider wishes. Other formats should not be included in the default response, but should be returned (one format per request) when an alternate format is specified in the request.
16 |
17 | The root node of the XML response must be the `` root element of the namespace `http://www.tei-c.org/ns/1.0`. So a response would normally look like this:
18 |
19 | ```xml
20 |
21 |
22 |
23 |
24 | ```
25 | If the request returns a complete document, it is returned directly inside this `` element.
26 |
27 | If the data to be returned is not a complete document, the textual data should be embedded in the `` element of the DTS Namespace (`https://w3id.org/dts/api#`) like this:
28 |
29 | ```xml
30 |
31 |
32 |
33 |
34 |
35 |
36 | ```
37 | There is no limitation as to what can be contained by `dts:fragment` or what its siblings can be provided they are well formed and valid. The only limiting factor is that `dts:fragment` should contain the requested textual data. This permits an implementation to return contextual material elsewhere within the root `TEI` node alongside the requested fragment. Note, though, that most metadata should be accessed through the `collection` endpoint instead.
38 |
39 | For requests that include a document as the request body (`PUT` and `POST`) this request body is not required to follow these same guidelines. It is **recommended**, though, that implementations do accept TEI-compliant XML documents and fragments (as described [above](#default-request-and-response-body-format)) as the default. Implementations **may** also allow a request body in any other format, but only when a format is specified via the `format` query parameter.
40 |
41 | ## Preserving the Integrity of Edited Documents
42 |
43 | Implementations of the DTS specification need not allow any write, update, or delete operations. If they do, however, this raises questions around how to maintain the integrity of the document on the server.
44 |
45 | ### Validating Changes to Documents
46 |
47 | Because of its flexibility, at some points this specification relies on clients to ensure that the textual data they submit is correctly structured. This requires more than simply that clients submit valid XML when creating or editing a text segment. It is strongly recommended that servers implementing these methods offer robust validation of any submitted text. For servers using TEI XML in requests, this should include validating that the submitted text or fragment
48 |
49 | - is well-formed XML
50 | - satisfies the requirements of the TEI schema
51 | - is consistent with the citation structure of the document being edited
52 | - is consistent with the specific application of the TEI specification being used by the implementing project
53 |
54 | Failure to meet any of these criteria should result in a failed request and an error response that pinpoints the problem in the submitted text as specifically as possible.
55 |
56 | ### Restricting the Scope of Editing Operations
57 |
58 | This burden of validation can be mitigated by restricting editing operations to one bottom-level segment of the document at a time. In a document with a three-level structural hierarchy of book, paragraph, and line, this would mean that only one line could be edited or deleted at a time. Such a restriction would allow the server to easily control the XML document structure. It would also, though, make some larger-scale editing operations unwieldy.
59 |
60 | This specification leaves the choice to enforce editing restrictions like this up to the implementer. If such restrictions are imposed, any request that is rejected as a result must be accompanied by a clear error message. The error message must (a) explain the restriction, and (b) provide a URL where the restriction is documented.
61 |
62 | ## URI
63 |
64 | ### Query Parameters
65 |
66 | The Document endpoint supports the following query parameters:
67 |
68 | | Name | Description | Methods |
69 | |------|------------------------------------------|---------|
70 | | id | (Required) Identifier for a document. Where possible this should be a URI | GET, POST, PUT, DELETE |
71 | | ref | Passage identifier (used together with `id`; can’t be used with `start` and `end`) | GET, PUT, DELETE |
72 | | start | (For range) Start of a range of passages (can’t be used with `ref`) | GET, PUT, DELETE |
73 | | end | (For range) End of a range of passages (requires `start` and no `ref`) | GET, PUT, DELETE |
74 | | after | (Optional) Passage after which the new segment should be inserted | POST |
75 | | before | (Optional) Passage after which the new segment should be inserted | POST |
76 | | token | (May be required by implementation) Authentication token for access control | POST, PUT, DELETE |
77 | | format | (Optional) Specifies a data format for response/request body other than the default | GET, POST, PUT, DELETE |
78 |
79 | Note that for GET requests one may either provide a `ref` parameter __or__ a pair of `start` and `end` parameters. A request cannot combine `ref` with the other two. If, say, a `ref` and a `start` are both provided this should cause the request to fail.
80 |
81 | Two parameters are used only when creating new document sections using a POST request: `after` and `before`. These allow one to specify where a new text segment should be inserted. One or the other of `after` and `before` must be included in a POST request unless one is creating the first text segment in a new document.
82 |
83 | Where the implementation needs to control who can access, create, or modify server data, the `token` parameter also allows for token-based authentication (as with OAuth 2.0) if desired. It is up to the implementation to decide how such tokens should be generated and processed.
84 |
85 | ### URI Template
86 |
87 | Here is a template of the URI for the Document API. The route itself (here `/dts/api/document/`) is up to the implementer.
88 |
89 | ```json
90 | {
91 | "@context": {
92 | "@vocab": "https://www.w3.org/ns/hydra/core#",
93 | "dc": "http://purl.org/dc/terms/",
94 | "dts": "https://w3id.org/dts/api#"
95 | },
96 | "@type": "IriTemplate",
97 | "template": "/dts/api/document/?id={document_id}&dts:ref={dts:ref}&start={start}&end={end}",
98 | "variableRepresentation": "BasicRepresentation",
99 | "mapping": [
100 | {
101 | "@type": "IriTemplateMapping",
102 | "variable": "collection_id",
103 | "required": true
104 | },
105 | {
106 | "@type": "IriTemplateMapping",
107 | "variable": "dts:ref",
108 | "required": false
109 | },
110 | {
111 | "@type": "IriTemplateMapping",
112 | "variable": "start",
113 | "required": false
114 | },
115 | {
116 | "@type": "IriTemplateMapping",
117 | "variable": "end",
118 | "required": false
119 | },
120 | {
121 | "@type": "IriTemplateMapping",
122 | "variable": "after",
123 | "required": false
124 | },
125 | {
126 | "@type": "IriTemplateMapping",
127 | "variable": "before",
128 | "required": false
129 | },
130 | {
131 | "@type": "IriTemplateMapping",
132 | "variable": "token",
133 | "required": false
134 | },
135 | {
136 | "@type": "IriTemplateMapping",
137 | "variable": "format",
138 | "required": false
139 | }
140 | ]
141 | }
142 | ```
143 |
144 | ## Machine-Readable Endpoint Documentation
145 |
146 | Machine-readable documentation for the endpoint should be made available in JSON-LD format following the Hydra Core Vocabulary specification. In this documentation the "supportedOperations" term must be used to specify which http methods the implementation supports for this endpoint. The value for "supportedOperations" should be an array of Hydra `Operation` objects, one object for each supported http method.
147 |
148 | ## Batch Requests
149 |
150 | For the sake of simplicity and usability the DTS guidelines do not allow for batch operations, i.e. fetching or altering more than one passage of text in the same request. Implementations should encourage client software and other consumers of their API to use multiple asynchronous requests instead.
151 |
152 | ## GET Requests on the Document Endpoint
153 |
154 | ### GET query parameters
155 |
156 | The only strictly required parameter for a `GET` Document request is `id`. This value specifies the document to be queried. If no particular reference is specified with other parameters, the response should return the entire document. If only one structural segment of the document is desired, this should be specified using the `ref` parameter. The `ref` value may specify a segment at any structural level of the document. For example, in a document segmented in two structural levels (book and line), a `ref` value of "5" should return all of book 5. A `ref` value of "5.2" should return just line 2 from book 5.
157 |
158 | If a continuous sequence of structural segments is being requested, then no `ref` value should be specified. Instead, the `start` and `end` parameters should specify the first and last segments of the sequence to be returned. If only `start` is specified, with no `end` value, the request should be understood as having an implicit `end` parameter specifying the last structural segment of the document. In other words, a request with a `start` value of "5.2" and no explicit `end` value should return all of the document from 5.2 (inclusive) to the end. Likewise, if only an `end` parameter is specified, the server should understand an implicit `start` pointing to the first segment of the document.
159 |
160 | As with `ref`, the level of specificity in the `start` and `ref` values should determine the structural level used to demarcate the segments returned. A query with "start=5.2&end=6.1" should return every line from 5.2 to 6.1 (inclusive). A query with "start=5&end=6" should return every line from the beginning of book 5 to the end of book 6 (inclusive).
161 |
162 | No request should include both a `ref` parameter and either `start` or `end`. Any request that does include both should prompt a `400(Bad Request)` error.
163 |
164 | ### GET request body
165 |
166 | A `GET` request should not include a body. If one is included it should be ignored.
167 |
168 | ### GET Responses
169 |
170 | #### Status codes
171 |
172 | A successful `GET` request to the Document endpoint should return the status code `200(OK)`.
173 |
174 | If a `GET` request is unsuccessful because of problems with the request parameters, the return status code should be `400(Bad Request)` or a custom status code in the 4XX series signaling a more specific error.
175 |
176 | If a `GET` request is unsuccessful because the specified id matches no document on the server, the return status code should be `404(Not Found)`
177 |
178 | #### Successful GET response headers
179 |
180 | The response after a successful `GET` request contains the following response headers:
181 |
182 | | name | description |
183 | |------|-------------|
184 | | Link | Gives location of api documentation as well as links to neighbouring document segments and other related api endpoints |
185 | | Content-Type | Content type of the response body (by default `application/tei+xml`)|
186 |
187 | ##### Link header
188 |
189 | When applicable, the following links must be provided in the 'Link' header:
190 |
191 | | Name of the property | Description of its value |
192 | | -------------------- | ------------------------ |
193 | | http://www.w3.org/ns/hydra/core#apiDocumentation | The URL for the Hydra-compliant machine-readable documentation for this implementation of the Document endpoint |
194 | | prev | Previous passage of the document in the Document endpoint |
195 | | next | Next passage of the document in the Document endpoint |
196 | | up | Parent passage of the document in the Document endpoint. If the current request is already for the entire document, no `up` link will be provided. If the only parent is the entire document, the `up` value will link to the document as a whole. |
197 | | first | First passage of the document in the Document endpoint |
198 | | last | The URL for the last passage of the document in the Document endpoint |
199 | | contents | The URL for the Navigation Endpoint for the current document |
200 | | collection | The URL for the Collection endpoint for the current document |
201 |
202 | #### Successful response body
203 |
204 | The response body after a successful `GET` request should contain an XML document representing the requested text segment. This XML should be formatted as described above under "[Default Request and Response Body Format](#default-request-and-response-body-format)".
205 |
206 | #### Unsuccessful response headers
207 |
208 | An unsuccessful `GET` request should return the following headers:
209 |
210 | | name | description |
211 | |------|-------------|
212 | | Link | The URL for the Hydra-compliant machine-readable `Document` endpoint documentation with a "rel" value of "http://www.w3.org/ns/hydra/core#apiDocumentation |
213 | | Content-type | Content type of the response body (by default `application/tei+xml`) |
214 |
215 | #### Unsuccessful response body
216 |
217 | If a `GET` response returns an error code, the response body should contain an XML object following the DTS specification for XML status responses (https://w3id.org/dts/api). For example, this would be a well-formed response body for a `400(Bad Request)` error:
218 |
219 | ```xml
220 |
221 | Invalid request parameters
222 | The query parameters were not correct.
223 |
224 | ```
225 |
226 | For a `400(Bad Request)` error, the `` should provide as much information as possible about which submitted data was missing or unacceptable. It should indicate whether:
227 | - there were missing required query parameters
228 | - any query parameters held unacceptable values, such as a document id that does not match any document on the server
229 | - the query parameters were acceptable but no such section exists for the requested document
230 |
231 | It is strongly recommended that projects implement more specific 4XX-series error responses to handle specific errors. In such cases the `` of the error response should include both an explanation of the issue and the URL for the necessary documentation.
232 |
233 | ### GET Example 1: Retrieve a passage using `ref`
234 |
235 | Retrieve the passage `2` of the document labeled by the identifier `https://papyri.info/ddbdp/bgu;11;2029/source`.
236 |
237 | #### GET request url
238 |
239 | - GET `/dts/api/document/?id=https://papyri.info/ddbdp/bgu;11;2029/source&ref=2`
240 |
241 | #### Successful GET response status
242 |
243 | - 200(OK)
244 |
245 | #### Successful GET response headers
246 |
247 | | Key | Value |
248 | | --- | ----- |
249 | | Content-Type | Content-Type: application/tei+xml |
250 | | Link | ; rel="http://www.w3.org/ns/hydra/core#apiDocumentation", ; rel="prev", ; rel="next", ; rel="last", ;rel="up", ; rel="contents", ; rel="collection" |
251 |
252 | #### Successful GET response body
253 |
254 | ```xml
255 |
256 |
257 |
258 |
259 |
260 | bgu.11.2029
261 |
262 |
263 | Duke Collaboratory for Classics Computing (DC3)
264 | bgu.11.2029
265 | 0001;11;2029
266 | bgu;11;2029
267 | 9566
268 | 9566
269 |
270 |
271 |
272 |
273 |
274 |
275 |
276 | τετελώνηταιδιὰπύλης Διονυσιάδος
277 |
278 |
279 | ```
280 |
281 | ### GET Example 2: Retrieve a passage using `start` and `end`
282 |
283 | Retrieve the passages 1.1.1 to the passage 1.1.2 of the document labeled by the identifier `urn:cts:latinLit:phi1318.phi001.perseus-lat1`.
284 |
285 | #### GET request url
286 |
287 | - GET `/dts/api/document/?id=urn:cts:latinLit:phi1318.phi001.perseus-lat1&start=1.1.1&end=1.1.2`
288 |
289 | #### Successful GET response status
290 |
291 | - 200(OK)
292 |
293 | #### Successful GET response headers
294 |
295 | | Key | Value |
296 | | --- | ----- |
297 | | Content-Type | Content-Type: application/tei+xml |
298 | | Link | ; rel="http://www.w3.org/ns/hydra/core#apiDocumentation", ; rel="next", ; rel="last", ; rel="up", ; rel="contents", ; rel="collection" |
299 |
300 | #### Successful GET response body
301 |
302 | ```xml
303 |
304 |
305 |
306 |
307 |
308 |
309 |
310 |
311 |
312 |
Frequenter hortatus es, ut epistulas, si quas paulo curatius scripsissem, colligerem publicaremque. Collegi non servato temporis ordine - neque enim historiam componebam -, sed ut quaeque in manus venerat.
313 |
314 |
315 |
Superest ut nec te consilii nec me paeniteat obsequii. Ita enim fiet, ut eas quae adhuc neglectae iacent requiram et si quas addidero non supprimam. Vale.
316 |
317 |
318 |
319 |
320 |
321 |
322 |
323 |
324 | ```
325 |
326 | ### GET Example 3: Retrieve a full document
327 |
328 | Retrieve the full document labeled by the identifier `https://papyri.info/ddbdp/bgu;11;2029/source`
329 |
330 | #### GET request url
331 |
332 | - GET `/dts/api/document/?id=https://papyri.info/ddbdp/bgu;11;2029/source`
333 |
334 | #### Successful GET response status
335 |
336 | - 200(OK)
337 |
338 | #### Successful GET response headers
339 |
340 | | Key | Value |
341 | | --- | ----- |
342 | | Content-Type | Content-Type: application/tei+xml |
343 | | Link | ; rel="http://www.w3.org/ns/hydra/core#apiDocumentation", ; rel="contents", ; rel="collection" |
344 |
345 | #### Successful GET response body
346 |
347 | ```xml
348 |
349 |
350 |
354 |
355 |
356 |
357 | bgu.11.2029
358 |
359 |
360 | Duke Collaboratory for Classics Computing (DC3)
361 | bgu.11.2029
362 | 0001;11;2029
363 | bgu;11;2029
364 | 9566
365 | 9566
366 |
367 |
407 |
408 |
409 |
410 |
411 | ```
412 |
413 | ## POST Requests on the Document Endpoint
414 |
415 | The `POST` method of the Document endpoint allows for creation of new textual passages in a resource. __This method requires that the document already has a metadata record accessible via the Collection endpoint__.
416 |
417 | Note that this method should __not__ be used to modify existing segments of text. In other words, if the specified reference label already exists in the document on the server, this method should return an error and refuse to perform the requested operation. If, for example, a document already has a line 6 following the existing line 5, then `POST` cannot be used to insert new or added text in that existing line 6. Modification of the text in existing document segments must be done using the `PUT` method instead.
418 |
419 | ### POST Query parameters
420 |
421 | The only strictly required parameters for a `POST` Document request are `id` and (if supported) `token`. If neither `before` nor `after` is supplied, the server should interpret the request as supplying the initial form of a new document. In that case, the request should fail if (a) some text already exists for that document, or (b) the request body contains a `` element.
422 |
423 | In most cases, though, the request will be inserting a new structural segment into a document that already contains some segments. In such instances, the query must include either a `before` or an `after` parameter to indicate where the new text segment will be inserted.
424 |
425 | **Neither the `ref` parameter nor the pair of `start`/`end` parameters should be provided in a `POST` Document request. The reference information for the inserted segment(s) should be drawn on the server side from the text in the request body. If an implementation follows the DTS recommendation to accept POST data in TEI XML format, then the reference information should be extracted on the server side from the standard TEI attributes in the XML of the request body.** This is to avoid the possibility of conflicts in which the embedded referencing in the document body is different than the reference information provided through URL parameters.
426 |
427 | Note that the `after` or `before` reference should also determine the depth of the insertion in the document's citation structure. The lowest structural level specified in the `after` or `before` reference is the level at which the contents of the XML `` will be inserted. In other words, the new segment will be taken to be a sibling to the segment specified in that reference.
428 |
429 | If the implementation accepts a request body in any format other than TEI-compliant XML, this must be clearly and prominently communicated in the API documentation. If the implementation accepts multiple different data formats in the response body, one should be designated as the default. (Again, it is recommended but not required that the default be TEI-compliant XML.) Any `POST` request that uses a supported format other than the implementation's default must use the `format` parameter to indicate how its body is encoded.
430 |
431 | ### POST Request Body
432 |
433 | When XML is being used as the default `POST` format, the request body must be a properly formed `` root node containing TEI-compliant XML. See the further specifications under "[Default Request and Response Body Format](#default-request-and-response-body-format)" above.
434 |
435 | Note that in most cases the actual text to be inserted is the __contents__ of the inner `` element in the request body. The only exception to this rule is where no structural segment has yet been created for a document, in which case the entire `` rootnode (along with all its contents) will be accepted as the initial form of the document.
436 |
437 | ### POST Responses
438 |
439 | #### Status codes
440 |
441 | A successful `POST` request to the Document endpoint should return the status code `201(Created)`.
442 |
443 | If a `POST` request is unsuccessful because the specified id does not match any document on the server, the return status code should be "404(Not Found)". If a `POST` request is unsuccessful because of other problems with the request content (i.e., parameters or request body), then the return status code should be "400(Bad Request)" or a custom status code in the 4XX series signaling a more specific error.
444 |
445 | A `POST` request should return "409(Conflict)" if it would create a new initial form of a document for which some segments already exist (even if those segments are empty). This would happen when no `after` or `before` parameter is supplied, but at least one segment of the document already exists on the server (even if it contains only an empty string).
446 |
447 | A `POST` Document request also may not result in a text segment whose reference identifier is the same as that of an existing segment. If, for example, a document already includes a segment "4.23.8", then a `POST` request which would result in a *second* segment "4.23.8" should fail and return "409(Conflict)".
448 |
449 | #### Successful response headers
450 |
451 | The response headers after a successful `POST` Document request should include a `Location` value. This should be the URL where the newly inserted text segment(s) can be retrieved via a `GET` request. The response should also include a `Content-type` header with a value of "application/tei+xml". Finally, a `Link` header should specify the URL for the machine-readable endpoint documentation with a "rel" value of "http://www.w3.org/ns/hydra/core#apiDocumentation".
452 |
453 | #### Successful response body
454 |
455 | The response body after a successful `POST` request should contain an XML object representing the newly created text segment (and any children). This should be identical to the response a client would receive using a `GET` request to the `Location` indicated in the response header. This will also mean that, in implementations using TEI XML, most successful `POST` requests will return an XML document identical to the one originally sent by the client.
456 |
457 | #### Unsuccessful response headers
458 |
459 | In an unsuccessful request, the response headers should include a `Link` whose value is the URL for the Document endpoint documentation with a "rel" value of "http://www.w3.org/ns/hydra/core#apiDocumentation". The response should also include a `Content-type` header with a value of "application/tei+xml".
460 |
461 | #### Unsuccessful response body
462 |
463 | If a response returns an error code, the response body should contain an XML object following the DTS specification for XML status responses (https://w3id.org/dts/api). For example, this would be a well-formed response body for a `400(Bad Request)` error:
464 |
465 | ```xml
466 |
467 | Improperly Formed Request Body
468 | The body of a `POST` request to the Document endpoint on this server must be properly formed XML. If it is submitting the initial text for a new document, the request body must be a rootnode with properly formed and schema-compliant children.
469 |
470 | ```
471 |
472 | For a `400(Bad Request)` error, the `` should provide as much information as possible about which submitted data was missing or unacceptable. It should indicate whether:
473 | - there were missing required query parameters
474 | - any query parameters held unacceptable values
475 | - the request body did not have properly formed XML
476 | - the request body was properly formed but carried unacceptable values
477 |
478 | It is strongly recommended that projects implement more specific 4XX-series error responses to handle more specific validation errors such as
479 | - XML that fails to satisfy the TEI schema
480 | - XML that conflicts with the current document's citation structure
481 | - XML that violates other project-specific conventions for implementing the TEI specification
482 | In such cases the `` of the error response should include both an explanation of the issue and the URL for the necessary documentation.
483 |
484 | If a response returns a status of `409(Conflict)` then the XML `` element should contain an indication that the request would result in a duplicate segment in the document's citation structure.
485 |
486 | ### POST Example 1: Creating the initial text for a new document
487 |
488 | In this example we will submit the first structural segments to constitute a new document. Prior to this operation no segments exist for the document on the server. This first `POST` request only creates verses 1-2 of chapter 1 in the document identified by the URN `urn:cts:ancJewLit:1Enoch`.
489 |
490 | Note that a metadata record for the document must already have been added via the Collection endpoint. This is the only way to establish a valid identifier for the document, which is then used for the Document `POST` request.
491 |
492 | Note too that a `` element precedes the main `` element. If a `` is included with the initial form of the document, its metadata should be extracted and integrated with the data accessible via the Collection endpoint.
493 |
494 | #### POST request URL
495 |
496 | Notice that this request omits the usual `before` or `after` parameters.
497 |
498 | - `/api/dts/document/?id=urn:cts:ancJewLit:1Enoch&token=XXXXX`
499 |
500 | #### POST request body
501 |
502 | ```xml
503 |
504 |
505 |
506 |
507 |
571 |
572 |
573 |
574 | ```
575 |
576 | ### POST Example 2: Creating a new section of text in an existing document
577 |
578 | In this example we will create a new text segment in the existing document `urn:cts:ancJewLit:1Enoch`. Initially we created the document with just verses 1 and 2 of chapter 1. We will now add a third verse to that same first chapter.
579 |
580 | #### POST request URL
581 |
582 | - `/api/dts/document?id=urn:cts:ancJewLit:1Enoch&after=1:2&token=XXXXX`
583 |
584 | #### POST request body
585 |
586 | Note that since some text already exists for this document, the new segment is submitted in a `` element.
587 |
588 | ```xml
589 |
590 |
591 |
592 |
638 |
639 |
640 | ```
641 |
642 | ## PUT Requests on the Document Endpoint
643 |
644 | The `PUT` method of the Document endpoint allows for modification of existing textual passages in a resource.
645 |
646 | Note that this method should __not__ be used to create new structural segments of text. For example, if the citation structure of the document already contains a section "5.7.31" then the `PUT` method may be used to modify that section. If section "5.7.31" does not already exist in the document on the server, an attempt to edit that segment using `PUT` should result in an error response. The `POST` method must first be used to add that segment to the document. Likewise, `PUT` should never result in the deletion of a segment in the document's citation structure. Of course, other XML entities below lowest level of a document's citation structure may be freely added or removed by the `PUT` method.
647 |
648 | ### PUT Query parameters
649 |
650 | The three required parameters for a `PUT` Document request are `id`, `token` (if supported by the implementation), and `ref`. Only one structural segment of the document may be modified in a single `PUT` request.
651 |
652 | The `ref` reference determines the structural depth of the modification. Suppose a document has a three-level citation structure represented in XML by nested `
` elements. A `PUT` request with a `ref` of "3.16.8" will replace just one `
` element at the lowest structural level. If the request is instead sent with a `ref` parameter of "3.16", the submitted `
` element will replace the second-level `
` with the identifier "3.16". In the latter case, the submitted `
` element will need to contain the same series of nested `
` elements that represent the existing bottom-level segments in the server's version of the file: "3.16.1", "3.16.2", "3.16.3", etc. It is recommended that implementations check the submitted text before performing upper-level modifications like this, to ensure that no lower-level structural segments are being created or destroyed. Alternately, an implementation may avoid this issue by only allowing `PUT` requests at the lowest level of the document's citation structure.
653 |
654 | ### PUT Request Body
655 |
656 | As with `POST` requests, it is recommended that implementations accept TEI-compliant XML as the default format for the `PUT` request body. This makes particularly good sense since it allows clients to modify and return the same XML document they retrieved by default with a `GET` request. If other data formats are supported (or used as the default) __the same formats must be accepted for `POST` and `PUT` request bodies__.
657 |
658 | When XML is accepted, the body of the `PUT` request must be wrapped in a TEI rootnode containing a `` entity. See the further specifications under "[Default Request and Response Body Format](#default-request-and-response-body-format)" above.
659 |
660 | The contents of this `` must be a single XML element (along with its enclosed text and/or children) representing the modified form of the target document section. This single element inside the `` will replace the corresponding XML element in the document on the server.
661 |
662 | The text/XML submitted in the body of a Document's `PUT` request will completely replace the XML entity representing the identified text segment. So the submitted fragment __must include the outer element__ identified by the "ref" value. If you identify your submitted text as a modified version of line "12", and if each line is represented by a TEI `` element, you would include the opening and closing tags `` and `` around the changed content. By including this outer tag in the `PUT` body we allow modification to be made to that outer element's attributes.
663 |
664 | ### PUT Responses
665 |
666 | #### Status codes
667 |
668 | If the specified section of the document is successfully modified, the response status should be `200(OK)`.
669 |
670 | If no structural section exists with an identifier matching the `ref` parameter in the request, the response status should be `404(Not Found)`. Similarly, the response should be `404(Not Found)` if the id supplied does not correspond to any document on the server. If there is some other problem with the request data, the response status should be `400(Bad Request)` or a custom status code in the 4XX series signaling a more specific error.
671 |
672 | #### Successful response headers
673 |
674 | The response headers after a successful `PUT` request should include the following headers:
675 |
676 | | name | description |
677 | |------|-------------|
678 | | Location | The URL where the newly modified document section can be retrieved via a `GET` request |
679 | | Link | The URL for the `Document` endpoint documentation with a "rel" value of "http://www.w3.org/ns/hydra/core#apiDocumentation" (e.g., ; rel="http://www.w3.org/ns/hydra/core#apiDocumentation") |
680 | | Content-Type | Content type of the response body (by default `application/tei+xml`)|
681 |
682 | #### Successful response body
683 |
684 | In a successful `PUT` request, the response body should be an XML object with the same structure as the body of a `GET` response, but containing the the newly modified contents of the specified text section. Although the implementation may require other formats for the `PUT` request body, __the response body *must* by default be formatted in XML as detailed [above](#default-request-and-response-body-format).__ By comparing the original `GET` response body with the response body from the `PUT` request, the client can quickly recognize whether the correct information was updated on the server. Where TEI-compliant XML is accepted as the default for request bodies, this will also mean that the response body is identical to the body submitted in the `PUT` request.
685 |
686 | #### Unsuccessful response headers
687 |
688 | The response after an unsuccessful `PUT` request should include the following headers:
689 |
690 | | name | description |
691 | |------|-------------|
692 | | Link | The URL for the `Document` endpoint documentation with a "rel" value of "http://www.w3.org/ns/hydra/core#apiDocumentation" (e.g., ; rel="http://www.w3.org/ns/hydra/core#apiDocumentation") |
693 | | Content-type | Content type of the response body (by default `application/tei+xml`) |
694 |
695 | #### Unsuccessful response body
696 |
697 | If a response returns an error code, the response body should contain an XML object following the DTS specification for XML status responses (https://w3id.org/dts/api). For example, this would be a well-formed response body for a `400(Bad Request)` error:
698 |
699 | ```xml
700 |
701 | Improperly Formed Request Body
702 | The body of a `PUT` request to the Document endpoint on this server must be properly formed XML.
703 |
704 | ```
705 |
706 | If a response returns a status of `404(Not Found)` then the `` contents should indicate that no section with the requested `ref` identifier exists and that the section must be created before it can be modified.
707 |
708 | If the status code is `400(Bad Request)` then the `` should clarify which parts of the request data were not acceptable.
709 |
710 | ### PUT Example 1: Changing the child elements in a bottom-level section
711 |
712 | In this example we will change the contents of the section with the reference "1:3" in the document with the id "urn:cts:ancJewLit:1Enoch". Since this document is a critical edition, that section contains a series of TEI `` elements, each of which contains a set of parallel `` elements with alternate textual variants. In the middle `` element we will add a third `` option that is empty, representing a manuscript which lacks any corresponding words.
713 |
714 | #### PUT request URL
715 |
716 | - `/api/dts/document?id=urn:cts:ancJewLit:1Enoch&ref=1:3&token=XXXXX`
717 |
718 | #### PUT request body
719 |
720 | If you compare this with the initial XML submitted in the `POST` Example 1 [above](#post-example-1-creating-the-initial-text-for-a-new-document), you will notice that the modification in this case involves changes to the XML child elements, not just to the text they contain. This is permissible since those child elements are below the lowest *structural* level of the document (i.e., the lowest level that can be referenced in the document's standard referencing scheme).
721 |
722 | ```xml
723 |
724 |
725 |
726 |
774 |
775 |
776 | ```
777 |
778 | ## DELETE on the Document Endpoint
779 |
780 | The `DELETE` method of the Document endpoint allows for removal of a segment of text from a document. Note that the `DELETE` operation removes the specified segments entirely from the document's reference structure. So if you `DELETE` the segment designated "12.6.2" from a document, there should thereafter be no line "2" in section "12.6" of the server document. If, instead, you simply want to remove the text of a segment, leaving the segment itself in the document structure, you should use the `PUT` method to replace the text with an empty string.
781 |
782 | ### DELETE Query Parameters
783 |
784 | The query parameters that *must* be accepted for a `DELETE` request are the `id` of the document, `token` (if supported by the implementation), and the same three parameters used in `GET` requests: `ref`, `start`, and `end`.
785 |
786 | Multiple structural segments of the document may be deleted simultaneously. The `start` and `end` parameters should be used as described [above](#get-query-parameters) for the Document `GET` method, but with one key difference: __both__ a `start` and an `end` parameter must be provided. This is to prevent the accidental deletion of everything before or after the provided reference. If a `start` parameter is provided without a corresponding `end` (or vice versa), the request should trigger an error.
787 |
788 | Note that the depth of the reference provided in the `ref` (or `start`/`end`) parameters determines the depth of the delete operation. If a document has three structural levels, and a `DELETE` request is submitted with a `ref` of "12.6", then *all* of the second-level section "12.6" will be removed from its structure. If a `ref` of "12" is submitted for that same document, all of the top-level section "12" will be removed.
789 |
790 | ### DELETE Request Body
791 |
792 | `DELETE` requests do not include a body.
793 |
794 | ### DELETE Responses
795 |
796 | #### Status codes
797 |
798 | With a `DELETE` request the returned status code should vary depending on on whether the operation has already concluded when the response is sent. If the deletion is done synchronously, and is finished at response time, the returned status code should be `200(OK)`. If the request simply began an asynchronous deletion process, still incomplete at response time, then the response should return `202(Accepted)`.
799 |
800 | If no item exists with the `id` specified in the request URL, the response status should be `404(Not Found)`. Similarly, if the document contains no structural segment matching the specific `ref` (or `start`/`end`) value, the response should return `404(Not Found)`. If there is some other problem with the request data, the response status should be `400(Bad Request)` or a custom status code in the 4XX series signaling a more specific error.
801 |
802 | #### Successful response headers
803 |
804 | The response for a successful `DELETE` request should include a "Content-Type" header indicating the content type of the response body. By default this must be `application/tei+xml`
805 |
806 | Unlike with other methods, the response headers after a successful `DELETE` request should *not* include a `Location` header.
807 |
808 | A "Link" header should also be included specifying the URL for the machine-readable API documentation with a "rel" value of "http://www.w3.org/ns/hydra/core#apiDocumentation".
809 |
810 | #### Successful response body
811 |
812 | In a successful `DELETE` request, the response body should be an XML object with the same structure as a `GET` response (see [above](#default-request-and-response-body-format)), but containing the old contents of the deleted text section. This allows the client to quickly recognize whether the correct segment(s) was removed on the server.
813 |
814 | #### Unsuccessful response headers
815 |
816 | The response after an unsuccessful `DELETE` request should include a "Content-type" header with the value "application/tei+xml" unless a non-default format has been specified in the request.
817 |
818 | A "Link" header should also be included specifying the URL for the machine-readable API documentation with a "rel" value of "http://www.w3.org/ns/hydra/core#apiDocumentation".
819 |
820 | #### Unsuccessful response body
821 |
822 | If a response returns an error code, the response body should contain an XML object following the DTS specification for XML status responses (https://w3id.org/dts/api). For example, this would be a well-formed response body for a `404(Not Found)` error:
823 |
824 | ```xml
825 |
826 | Segment Not Found
827 | The document you requested does exist, but no structural segment exists corresponding to the reference in your request.
828 |
829 | ```
830 |
831 | If a response returns a status of `404(Not Found)` then the `description` value should indicate whether the problem arose from the requested `id` value or the requested `ref` value. In other words, does the requested document not exist on the server, or does that document not contain the requested structural segment(s)?
832 |
833 | If the status code is `400(Bad Request)` then the `` should clarify which parts of the request data were not acceptable.
834 |
835 | ### DELETE Example 1: Removing a Segment from a Document
836 |
837 | In this example we will use a `DELETE` request to remove the section with the reference "1:3" from the document with the `id` "urn:cts:ancJewLit:1Enoch". Since this document is a critical edition, that section contains XML markup for the variant readings as well as the text of each reading. This will be a synchronous `DELETE` operation, so the successful response code will be `200(OK)`.
838 |
839 | #### DELETE request URL
840 |
841 | - `/api/dts/document?id=urn:cts:ancJewLit:1Enoch&ref=1:3&token=XXXXX`
842 |
843 | #### DELETE request body
844 |
845 | No body should be sent with the `DELETE` request.
846 |
847 | #### Successful DELETE response status
848 |
849 | - `200(OK)`
850 |
851 | #### Successful DELETE response headers
852 |
853 | | key | Value |
854 | | --- | ----- |
855 | | Content-Type | application/ld+json |
856 | | Link | ; rel="http://www.w3.org/ns/hydra/core#apiDocumentation" |
857 |
858 | #### successful DELETE response body
859 |
860 | ```xml
861 |
862 |
863 |
864 |
877 |
878 |
879 | ```
880 |
--------------------------------------------------------------------------------
/versions/1-draft2/Entry.md:
--------------------------------------------------------------------------------
1 | ## Status of this Document
2 |
3 | - This Version: 1-draft2
4 |
5 | This document reflects the status of the version 1-draft2, check API Documentation for the current correct version.
6 |
7 |
8 | # Endpoint Basics
9 |
10 | ## Vocabulary
11 |
12 | - *Collection* : an identifiable aggregation of digital resources which has meaning in a specific research context. Resources may be virtual or real.
13 |
14 | - *Readable Collection* : a specific type of *Collection* which represents an aggregation of readable text passages (e.g. a structured text)
15 |
16 | - *Reference* : Identifier of a citable node inside a *Readable Collection* (aka text)
17 |
18 | ## Media Types
19 |
20 | The Collection and Navigation endpoints of the DTS API output `application/ld+json` adhering to Hydra conventions [http://www.hydra-cg.com](http://www.hydra-cg.com). The `@id` of any resource can be any URI, which may be a URL or a URI.
21 |
22 | The Document endpoint of the DTS API __must__ be able to return `application/tei+xml`. Implementers of the API may return additional media-types for document content, including, HTML, PDF, syntax trees, or image formats.
23 |
24 | ## Depth of secondary properties
25 |
26 | In properties such as `dts:extensions` and `dts:dublinCore`, the following rule apply regarding the maximum depth of metadata encoding :
27 |
28 | - `collection["dts:extensions"]` and `collection["dts:dublinCore"]` are namespaced dictionaries, working with `collection["@graph"]`
29 | - `collection["extensions or dublinCore"]["prefix:term"]` can be :
30 | - a literal that cannot be localized (such as int) : `collection["extensions or dublinCore"]["prefix:term"] : 5`
31 | - a URIRef : `collection["extensions or dublinCore"]["prefix:term"] : "A String"`
32 | - a list of literal, including localized ones : `collection["extensions or dublinCore"]["prefix:term"] : [{"@value": "Literal", "@lang": "eng"}]`
33 | - a list of URIRef: `collection["extensions or dublinCore"]["prefix:term"] : ["http://wikidata.org/object/Author"]`
34 |
35 | ## HTTP Status Codes
36 |
37 | Standard conventions for HTTP Status Codes are used. No custom status codes are allowed. The Document endpoint may report error codes in XML. See the individual endpoint specifications for detailed information.
38 |
39 | ## Error messages
40 |
41 | Parts of the APIs whose response format is LD+JSON should follow the [Hydra standard for error presentation](https://www.hydra-cg.com/spec/latest/core/#description-of-http-status-codes-and-errors) :
42 |
43 | ```json
44 | {
45 | "@context": "http://www.w3.org/ns/hydra/context.jsonld",
46 | "@type": "Status",
47 | "statusCode": 429,
48 | "title": "Too Many Requests",
49 | "description": "A maximum of 500 requests per hour and user is allowed.",
50 | }
51 | ```
52 |
53 | The **same** situation in the Document API will be encoded in XML :
54 |
55 | ```xml
56 |
57 | Too Many Requests
58 | A maximum of 500 requests per hour and user is allowed.
59 |
60 | ```
61 |
62 | ## Base API Endpoint
63 |
64 | A client needs to know the URL of the base DTS API endpoint, which is determined by the server. (In this example, the path of the base endpoint is `/dts/api`, but a server can choose a different relative URL.)
65 |
66 | If the client does a `GET` on the base API endpoint,, the following response is returned:
67 |
68 | ```
69 | {
70 | "@context": "/dts/api/contexts/EntryPoint.jsonld",
71 | "@id": "/dts/api/",
72 | "@type": "EntryPoint",
73 | "collection": "/dts/api/collection/",
74 | "document": "/dts/api/document/",
75 | "navigation" : "/dts/api/navigation"
76 | }
77 | ```
78 |
79 | This response provides the base path for each of the 3 specified endpoints: collection, navigation and document. All other resources can be discovered via navigation of individual endpoint responses. Base paths to individual endpoints URLs shown in response payloads may vary from these base endpoint paths.
80 |
--------------------------------------------------------------------------------
/versions/1-draft2/Navigation.md:
--------------------------------------------------------------------------------
1 | ## Status of this Document
2 |
3 | - This Version: 1-draft2
4 |
5 | This document reflects the status of the version 1-draft2, check API Documentation for the current correct version.
6 |
7 | # Navigation Endpoint
8 |
9 | The Navigation endpoint provides a JSON object listing passages that are accessible for navigation from a given reference within a resource. While the Collection endpoint allows for traversing of collections and their constituent Resources, the Navigation endpoint is used for traversing the internal citation tree of an individual Resource.
10 |
11 | Responses from the Navigation endpoint assume by default that the user is traversing the document downward in the citation tree. A request to the Navigation endpoint specifies a reference within a resource, and the response lists the references that are immediately above or below that reference point in the citation tree. The response also identifies the parent reference of that current node.
12 |
13 | ## Scheme for Navigation Endpoint Responses
14 |
15 | These are the JSON properties allowed in the object returned from a Navigation request. All top-level properties are mandatory.
16 |
17 | | name | description |
18 | | ---- | -----------------------------------------|
19 | | `@id` | the ID of the current request. This value should be the request URL including any query parameters. |
20 | | `maxCiteDepth` | a number defining the maximum depth of the document's citation tree. *E.g.*, if the a document has up to three levels, `maxCiteDepth` should be the number 3. |
21 | | `citeType` | defines the default type of references listed in `member`. |
22 | | `level` | a number identifying the hierarchical level of the requested identifier (i.e., in the `ref` or `start`/`end` query parameters), counted relative to the top of the document's citation tree. *E.g.*, if a the requested identifier is at the second hierarchical level (like `{"ref": "1.1"}`) then the `level` in the response should be the number 2. (The Resource as a whole is considered level 0.) |
23 | | `passage` | the URI template to the Document endpoint at which the text of passages corresponding to these references can be retrieved. |
24 | | `parent` | the unique passage identifier for the hierarchical parent of the current node in the document structure, defined by the `ref` query parameter. If the query specifies a range rather than a single `ref`, no parent should be specified and `parent` should have a value of "null". |
25 | | `member` | a list of passage references matching the requested parameters. This can be a list of single `ids` as objects with `ref` values: `[{"ref": "a"}, {"ref": "b"}, {"ref": "1.1"}]`. Or the list can contain ranges with `start` and `end` values in place of `ref` values: `[{"start": "a", "end": "b"}, {"start": "1.1", "end": "1.3"}]`. Each item in the member list should also include its own `level` parameter specifying the hierarchical level of that identifier in the document.|
26 |
27 |
28 | Within the `member` list, each object may have the following properties:
29 |
30 | | name | constraint | description |
31 | | ---- | ---------- | -----------------------------------------|
32 | | `ref` | required unless `start` and `end` supplied | the unique passage identifier for one node in the citation structure of the Resource |
33 | | `start` | required if `ref` is not present; requires that `end` is also supplied | the unique passage identifier for the first member of a range of sequential passages. This parameter is inclusive, so the supplied reference is considered part of the specified range. |
34 | | `end` | required if `ref` is not present; requires that `start` is also supplied | the unique passage identifier for the last member of a range of sequential passages. This parameter is inclusive, so the supplied reference is considered part of the specified range. |
35 | | `citeType` | optional | identifies the passage type for the specified passage or range. *E.g.*, `{"ref": "1.2", "citeType": "Poem"}` |
36 | | `dublinCore` | optional | contains Dublin Core Terms metadata for the specified passage or range. *E.g.*, `{ref": "1.2", "dublinCore": {"author": "Balzac"}}` |
37 | | `extensions` | Optional | contains metadata for the specified passage or range from other namespaces |
38 |
39 |
40 | ### Unique `ref` identifiers
41 |
42 | Note that all identifiers used as a `ref` value must be unique within the current resource. This is the case for the values retured in the `member` list as well as in the `parent` property.
43 |
44 | ### Values for the `parent` Property
45 |
46 | The format for the returned `parent` value will depend on where the current `ref` stands in the resource's hierarchical structure.
47 |
48 | - If the requested `ref` is the identifier for the **resource as a whole**, and that resource has no hierarchical parent, the value returned for `parent` should be "null".
49 | - If the requested `ref` identifies **one of the top level** of the resource's hierarchical divisions, the `parent` property should be an object identifying the document as a whole and specifying that its `@type` is a "Resource". For example: `{"@type": "Resource", "@id": "urn:cts:greekLit:tlg0012.tlg001.opp-grc5"}`
50 | - If the requested `ref` identifies **a node at a lower level** of the resource's hierarchical divisions, so that the parent is another division within the citation structure, the `parent` value will be a list of objects much like the list returned for the `member` property, each object identifying one reference that is the current node's direct parent. In this case, though, each object should also include an `@type` value of "CitableUnit". For example: `{"@type": "CitableUnit", "ref": "1.1.1"}`. If only one parent exists then a single object may be returned rather than an array of objects.
51 | - If the request is **relative to a *range*** rather than a single *reference*, then the request again cannot be relied upon to have a single common hierarchical parent. So the `parent` value for a range request should again be the value "null". If a client wishes to discover the parent for the milestone references at the start and end of the range (specified in the "start" and "end" query parameters), a seprate request should be made for each of these references as individual locations using the "ref" parameter.
52 |
53 |
54 | ## URI for Navigation Endpoint Requests
55 |
56 | ### Query Parameters
57 |
58 | | name | description | methods |
59 | |------|------------------------------------------|---------|
60 | | id | the unique identifier (normally a URN) for the Resource being navigated | GET |
61 | | ref | (NOT used with `start` and `end`) a single passage identifier providing the point of reference for the Navigation request within the Resource. Such identifiers should be unique within a given Resource. | GET |
62 | | start | (NOT used if a `ref` is specified, requires `end` as well) Start of the range passages to serve as the reference point for the Navigation request. This parameter is inclusive, so the supplied reference is considered part of the specified range. | GET |
63 | | end | (NOT used if a `ref` is specified, requires `start` as well) End of the range of passages to serve as the reference point for the Navigation request. This parameter is inclusive, so the supplied reference is considered part of the specified range. | GET |
64 | | down | the depth (as a number or the string "max") for reference identifiers (members) to be retrieved, relative to the specified `ref` or `start`/`end` values. *E.g.*, if a request should return the children of the passage "1.2", then the `ref` parameter should be "1.2" and the `down` parameter should be `1`. The default value is `1`. If the descendants of the passage at the maximum depth of the document's structure are desired, a value of "max" may be supplied instead of a number. A value of `0` indicates that members should be at the same hierarchical level as the specified `ref` or `start`/`end` identifiers. When a `start` and `end` value for a range are supplied, a value of `0` indicates that the returned members should be all the references in the specified range *at the same hierarchical level* as the `start` and `end`. When a single `ref` value is supplied with a `down` value of 0, no members are returned, and the return object contains only metadata on the requested node itself.| GET |
65 | | groupBy | Retrieve passages in groups of this size instead of single units. This would normally mean that the `member` list returned would be a list of ranges, each of which contains this number of passages. | GET |
66 | | max | Allows for limiting the number of results and getting pagination | GET |
67 | | exclude | Exclude keys in members' object such as `exclude=extensions` | GET |
68 |
69 | ### Response Headers
70 |
71 | The response contains the following response headers:
72 |
73 | | name | description |
74 | |------|-------------|
75 | | Link | Gives relation to next and previous pages |
76 |
77 | ### URI Template
78 |
79 | Here is a template of the URI for Navigation API. The route itself (`/dts/api/navigation/`) is up to the implementer.
80 |
81 | ```json
82 | {
83 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
84 | "@type": "IriTemplate",
85 | "template": "/dts/api/navigation/?id={collection_id}{&ref}{&level}{&start}{&end}{&page}",
86 | "variableRepresentation": "BasicRepresentation",
87 | "mapping": [
88 | {
89 | "@type": "IriTemplateMapping",
90 | "variable": "id",
91 | "property": "hydra:freetextQuery",
92 | "required": true
93 | },
94 | {
95 | "@type": "IriTemplateMapping",
96 | "variable": "ref",
97 | "property": "hydra:freetextQuery",
98 | "required": false
99 | },
100 | {
101 | "@type": "IriTemplateMapping",
102 | "variable": "page",
103 | "property": "hydra:freetextQuery",
104 | "required": false
105 | },
106 | {
107 | "@type": "IriTemplateMapping",
108 | "variable": "groupBy",
109 | "property": "hydra:freetextQuery",
110 | "required": false
111 | },
112 | {
113 | "@type": "IriTemplateMapping",
114 | "variable": "down",
115 | "property": "hydra:freetextQuery",
116 | "required": false
117 | },
118 | {
119 | "@type": "IriTemplateMapping",
120 | "variable": "start",
121 | "property": "hydra:freetextQuery",
122 | "required": false
123 | },
124 | {
125 | "@type": "IriTemplateMapping",
126 | "variable": "end",
127 | "property": "hydra:freetextQuery",
128 | "required": false
129 | }
130 | ]
131 | }
132 | ```
133 |
134 | ## Examples
135 |
136 | ### Example 1: Requesting top-level children of a textual Resource
137 |
138 | The client wants to retrieve a list of passage identifiers that are part of the textual Resource identified as *urn:cts:greekLit:tlg0012.tlg001.opp-grc5*. In other words, the client wants a list of the top-level references in the resource's citation structure. So the `id` parameter supplied in the query is the identifier of the Resource as a whole.
139 |
140 | #### Example of url :
141 |
142 | - `/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc5&down=1`
143 |
144 | #### Headers
145 |
146 | | Key | Value |
147 | | --- | ----- |
148 | | Content-Type | Content-Type: application/ld+json |
149 |
150 | #### Response
151 |
152 | ```json
153 | {
154 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
155 | "@id":"/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc&down=1",
156 | "maxCiteDepth" : 2,
157 | "level": 0,
158 | "member": [
159 | {"ref": "1", "level": 1},
160 | {"ref": "2", "level": 1},
161 | {"ref": "3", "level": 1}
162 | ],
163 | "passage": "/dts/api/document/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc{&ref}{&start}{&end}",
164 | "parent": null
165 | }
166 | ```
167 |
168 | ### Example 2: Requesting all descendants of a textual Resource at a specified level
169 |
170 | The client wants to retrieve a list of passage identifiers that are part of the textual Resource identified by *urn:cts:greekLit:tlg0012.tlg001.opp-grc5* and can be found at the second level of the citation tree of the document. Although the second structural level is being returned, we are not requesting the descendants of any single upper-level node. The references returned are in relation to the document as a whole. So the parent node is the whole document.
171 |
172 | #### Example of url :
173 |
174 | - `/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc5&down=2`
175 |
176 | #### Headers
177 |
178 | | Key | Value |
179 | | --- | ----- |
180 | | Content-Type | Content-Type: application/ld+json |
181 |
182 | #### Response
183 |
184 | ```json
185 | {
186 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
187 | "@id":"/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc&down=2",
188 | "maxCiteDepth" : 2,
189 | "level": 0,
190 | "member": [
191 | {"ref": "1.1", "level": 2},
192 | {"ref": "1.2", "level": 2},
193 | {"ref": "2.1", "level": 2},
194 | {"ref": "2.2", "level": 2},
195 | {"ref": "3.1", "level": 2},
196 | {"ref": "3.2", "level": 2}
197 | ],
198 | "passage": "/dts/api/document/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc{&ref}{&start}{&end}",
199 | "parent": {"@type": "Resource", "@ref": "/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc"}
200 | }
201 | ```
202 |
203 | ### Example 3: Requesting children of one top-level structural division of a Resource
204 |
205 | The client wants to retrieve a list of passage identifiers that are children of the textual Resource identified by *urn:cts:greekLit:tlg0012.tlg001.opp-grc5* and its division `1`. Since the desired members are direct children of the specified reference, the `down` parameter may be omitted and the default value of `1` will be used. Since the specified reference, the point from which the descendants are viewed, is at the top level of the structural hierarchy, the parent in the return value is still the document as a whole.
206 |
207 | #### Example of url :
208 |
209 | - `/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc5&ref=1`
210 |
211 | #### Headers
212 |
213 | | Key | Value |
214 | | --- | ----- |
215 | | Content-Type | Content-Type: application/ld+json |
216 |
217 | #### Response
218 |
219 | ```json
220 | {
221 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
222 | "@id":"/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc&ref=1",
223 | "maxCiteDepth" : 2,
224 | "level": 1,
225 | "member": [
226 | {"ref": "1.1", "level": 2},
227 | {"ref": "1.2", "level": 2}
228 | ],
229 | "passage": "/dts/api/document/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc{&ref}{&start}{&end}",
230 | "parent": {"@type": "Resource", "@ref": "/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc"}
231 | }
232 | ```
233 |
234 | ### Example 4: Requesting grandchild descendants of a top-level structural division
235 |
236 | The client wants to retrieve a list of grand-children passage identifiers that are part of the textual Resource identified by *urn:cts:latinLit:phi1294.phi001.perseus-lat2* and its passage `1`. Since the specified reference, the point from which the descendants are viewed, is at the top level of the structural hierarchy, the parent in the return value is still the document as a whole.
237 |
238 | #### Example of url :
239 |
240 | - `/api/dts/navigation/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2&ref=1&down=2`
241 |
242 | #### Headers
243 |
244 | | Key | Value |
245 | | --- | ----- |
246 | | Content-Type | Content-Type: application/ld+json |
247 |
248 | #### Response
249 |
250 | ```json
251 | {
252 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
253 | "@id":"/api/dts/navigation/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2&ref=1&down=2",
254 | "maxCiteDepth" : 3,
255 | "level": 1,
256 | "member": [
257 | {"ref": "1.1.1", "level": 3},
258 | {"ref": "1.1.2", "level": 3},
259 | {"ref": "1.2.1", "level": 3},
260 | {"ref": "1.2.2", "level": 3}
261 | ],
262 | "passage": "/dts/api/document/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2{&ref}{&start}{&end}",
263 | "parent": {"@type": "Resource", "ref": "/api/dts/navigation/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2"}
264 | }
265 | ```
266 |
267 | ### Example 5: Requesting children of a lower-level structural division
268 |
269 | The client wants to retrieve a list of child passage identifiers that are part of the textual Resource identified by *urn:cts:latinLit:phi1294.phi001.perseus-lat2* and its passage "1.1". The returned parent is the direct parent (or parents) of the specified reference ("1.1"). Since it is not the document as a whole, the parent `@type` is "CitableUnit" rather than "Resource".
270 |
271 | #### Example of url :
272 |
273 | - `/api/dts/navigation/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2&ref=1.1&down=1`
274 |
275 | #### Headers
276 |
277 | | Key | Value |
278 | | --- | ----- |
279 | | Content-Type | Content-Type: application/ld+json |
280 |
281 | #### Response
282 |
283 | ```json
284 | {
285 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
286 | "@id":"/api/dts/navigation/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2&ref=1.1&down=1",
287 | "maxCiteDepth" : 3,
288 | "level": 2,
289 | "member": [
290 | {"ref": "1.1.1", "level": 3},
291 | {"ref": "1.1.2", "level": 3}
292 | ],
293 | "passage": "/dts/api/document/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2{&ref}{&start}{&end}",
294 | "parent": {"@type": "CitableUnit", "ref": "1"}
295 | }
296 | ```
297 |
298 | ### Example 6: Requesting a range of passage references between milestones
299 |
300 | The client wants to retrieve a list of passage identifiers which are between two milestones. In this case there is no single parent node shared by the whole requested range, so no parent is returned. Since the reference list to be returned is at the *same* structural level as the supplied milestones, the `down` query parameter is "0".
301 |
302 |
303 |
304 | #### Example of url :
305 |
306 | - `/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc5&down=0&start=1&end=3`
307 |
308 | #### Headers
309 |
310 | | Key | Value |
311 | | --- | ----- |
312 | | Content-Type | Content-Type: application/ld+json |
313 |
314 | #### Response
315 |
316 | ```json
317 | {
318 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
319 | "@id":"/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc&down=0&start=1&end=3",
320 | "maxCiteDepth" : 2,
321 | "level": 1,
322 | "member": [
323 | {"ref": "1", "level": 1},
324 | {"ref": "2", "level": 1},
325 | {"ref": "3", "level": 1}
326 | ],
327 | "passage": "/dts/api/document/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc{&ref}{&start}{&end}",
328 | "parent": null
329 | }
330 | ```
331 |
332 | ### Example 7: Requesting descendants of the references in a specified range
333 |
334 | The client wants to retrieve a list of passage identifiers which are between two milestones. Since the `level` query parameter is "1", the returned references are one level below the milestones specified. I.e., the returned references are all *children* of structural divisions between the two milestones. In this case there is no single parent node shared by the whole requested range, so no parent is returned.
335 |
336 | #### Example of url :
337 |
338 | - `/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc5&down=1&start=1&end=3`
339 |
340 | #### Headers
341 |
342 | | Key | Value |
343 | | --- | ----- |
344 | | Content-Type | Content-Type: application/ld+json |
345 |
346 | #### Response
347 |
348 | ```json
349 | {
350 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
351 | "@id":"/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc&down=1&start=1&end=3",
352 | "maxCiteDepth" : 2,
353 | "level": 1,
354 | "member": [
355 | {"ref": "1.1", "level": 2},
356 | {"ref": "1.2", "level": 2},
357 | {"ref": "2.1", "level": 2},
358 | {"ref": "2.2", "level": 2},
359 | {"ref": "3.1", "level": 2},
360 | {"ref": "3.2", "level": 2},
361 | ],
362 | "passage": "/dts/api/document/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc{&ref}{&start}{&end}",
363 | "parent": null
364 | }
365 | ```
366 |
367 | ### Example 8: Passages grouped by the provider
368 |
369 | The client wants to retrieve a list of grand-children ranges of two identifiers that are part of the textual Resource identified by *urn:cts:latinLit:phi1294.phi001.perseus-lat2* and its passage `1`. In this case the references are returned as ranges, each of which groups a number of sequential references equal to the `groupBy` request parameter. Since the specified ref is at the top structural level of the document, the returned parent is the entire Resource.
370 |
371 | #### Example of url :
372 |
373 | - `/api/dts/navigation/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2&ref=1&down=2&groupBy=2`
374 |
375 | #### Headers
376 |
377 | | Key | Value |
378 | | --- | ----- |
379 | | Content-Type | Content-Type: application/ld+json |
380 |
381 | #### Response
382 |
383 | ```json
384 | {
385 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
386 | "@id":"/api/dts/navigation/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2&ref=1&down=2&groupBy=2",
387 | "maxCiteDepth" : 3,
388 | "level": 1,
389 | "member": [
390 | {"start": "1.1.1", "end": "1.1.2", "level": 3},
391 | {"start": "1.2.1", "end": "1.2.2", "level": 3},
392 | ],
393 | "passage": "/dts/api/document/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2{&ref}{&start}{&end}"
394 | "parent": {"@type": "Resource", "ref": "/dts/api/document/?id=urn:cts:latinLit:phi1294.phi001.perseus-lat2{&ref}{&start}{&end}"}
395 | }
396 | ```
397 |
398 | ### Example 9: Retrieval of typology of references
399 |
400 | Some passages may have a metadata type. The `citeType` refers to the type of a citable node. The node expects a free text or a RDF Class. A default type can be given at the root of the response object.
401 |
402 | #### Example of url :
403 |
404 | - `/api/dts/navigation/?id=http://data.bnf.fr/ark:/12148/cb11936111v`
405 |
406 | #### Headers
407 |
408 | | Key | Value |
409 | | --- | ----- |
410 | | Content-Type | Content-Type: application/ld+json |
411 |
412 | Example using *Les Liaisons Dangereuses* by Pierre Choderlos de Laclos
413 |
414 | ```json
415 | {
416 | "@context": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
417 | "@id":"/api/dts/navigation/?id=http://data.bnf.fr/ark:/12148/cb11936111v",
418 | "maxCiteDepth" : 1,
419 | "level": 0,
420 | "citeType": "letter",
421 | "member": [
422 | // The two following items are not letters : the data provider notes this different
423 | { "ref": "Av", "citeType": "preface", "level": 1},
424 | { "ref": "Pr", "citeType": "preface", "level": 1},
425 | // Given the fact the following nodes have no citeType, they inherit of the root object citeType : letter
426 | { "ref": "1", "level": 1},
427 | { "ref": "2", "level": 1},
428 | { "ref": "3", "level": 1},
429 | // And so on
430 | ],
431 | "passage": "/dts/api/document/?id=http://data.bnf.fr/ark:/12148/cb11936111v{&ref}{&start}{&end}",
432 | "parent": null
433 | }
434 | ```
435 |
436 |
437 | ### Example 10: Retrieval of titles and generic metadata
438 |
439 | The client wants the list of passages with their title and domain-specific vocabularies. If the given data provider has a title, then it will be provided.
440 |
441 | #### Example of url :
442 |
443 | - `/api/dts/navigation/?id=http://data.bnf.fr/ark:/12148/cb11936111v`
444 |
445 | #### Headers
446 |
447 | | Key | Value |
448 | | --- | ----- |
449 | | Content-Type | Content-Type: application/ld+json |
450 |
451 | Example using *Les Liaisons Dangereuses* by Pierre Choderlos de Laclos
452 |
453 | ```json
454 | {
455 | "@context": {
456 | "@vocab": "https://distributed-text-services.github.io/specifications/context/1.0.0draft-2.json",
457 | "foo": "http://foo.bar/ontology#"
458 | },
459 | "@id":"/api/dts/navigation/?id=http://data.bnf.fr/ark:/12148/cb11936111v",
460 | "maxCiteDepth" : 1,
461 | "level": 0,
462 | "member": [
463 | {
464 | "ref": "Av",
465 | "level": 1,
466 | "dublinCore": {
467 | "title": "Avertissement de l'Éditeur"
468 | }
469 | },
470 | {
471 | "ref": "Pr",
472 | "level": 1,
473 | "dublinCore": {
474 | "title": "Préface"
475 | }
476 | },
477 | {
478 | "ref": "1",
479 | "level": 1,
480 | "dublinCore": {
481 | "title": "Lettre 1"
482 | },
483 | "extensions": {
484 | "foo:fictionalSender": "Cécile Volanges",
485 | "foo:fictionalRecipient": "Sophie Carnay"
486 | }
487 | },
488 | {
489 | "ref": "2",
490 | "level": 1,
491 | "dublinCore": {
492 | "title": "Lettre 2"
493 | },
494 | "extensions": {
495 | "foo:fictionalSender": "La Marquise de Merteuil",
496 | "foo:fictionalRecipient": "Vicomte de Valmont"
497 | }
498 | }
499 | {
500 | "ref": "3",
501 | "level": 1,
502 | "dublinCore": {
503 | "title": "Lettre 3"
504 | },
505 | "extensions": {
506 | "foo:fictionalSender": "Cécile Volanges",
507 | "foo:fictionalRecipient": "Sophie Carnay"
508 | }
509 | },
510 | // And so on
511 | ],
512 | "passage": "/dts/api/document/?id=http://data.bnf.fr/ark:/12148/cb11936111v{&ref}{&start}{&end}",
513 | "parent": null
514 | }
515 | ```
516 |
--------------------------------------------------------------------------------
/versions/1-draft2/README.md:
--------------------------------------------------------------------------------
1 | ## Status of this Document
2 |
3 | - This Version: 1-draft2
4 |
5 | This document reflects the status of the version 1-draft2, check API Documentation for the current correct version.
6 |
7 | -----
8 |
9 |
10 | This part of the website / repository holds the Draft version 2 (Pre release of the Alpa)
11 |
12 | The last change was performed December 2, 2022
13 |
14 | Endpoints:
15 |
16 | - [Entry](Entry.md)
17 | - [Collections](Collections.md)
18 | - [Navigation](Navigation.md)
19 | - [Document](Document.md)
--------------------------------------------------------------------------------