Skip to content

Decision Tree: Issue 70

Jump to bottom
Jonathan Robie edited this page Nov 9, 2017 · 7 revisions

This is a decision tree for the following issue:

https://github.com/distributed-text-services/collection-api/issues/70

It is based on text proposed by Thibault. For each item, please enter your name, with an annotation saying one of the following:

  • "prefer", whether you prefer the proposed text or something else
  • "can live with", meaning this is not your preference but you would accept it
  • "cannot live with", meaning this is a deal breaker for you
  • "correction", with text to correct a technical error
  • "concur", meaning you can live with whatever the group decides I will provide examples using my own name. Looking at everyone's feedback we will try to find areas of consensus.

Default media type for document endpoints

  1. A DTS API must be able to reply with application/tei+xml content on the passage/document endpoint(s)
  • Jonathan: Can live with the above text. This works fine if the API is designed only to read documents and passages in a small number of formats, but would mean the API does not work for my applications. If we choose this route, we may want to consider limiting the TEI formats that a client should be expected to know. Few clients will be able to handle every possible TEI document.
  • Jonathan: Prefer the following: leave the media type up to the server, let servers and clients use content mediation. Perhaps say that a server must be able to serve a TEI document if it is available.
  • Bridget: Somewhere between prefer and can live with. I think starting with TEI/XML as a requirement makes sense, but it would be good to leave open the possibility for this to change in the future.

** Decision **: Support for TEI is mandatory, we can open it up later if there is a reason to.

  1. A DTS API can serve any other content types
  • Jonathan: Question - Under what circumstances would we allow this? If a server must provide application/tei+xml, and that is the usage we foresee, why allow this?
  • Bridget: I think the answer to Jonathan's question is that a text which can't serve its passages at TEI/XMl but could provide the entire document in some other format, such as PDF, should be able to be served by the collections part of the api.

** Decision **: We will allow a DTS API to serve other content types.

  1. In case of XML media type, the response must be well-formed xml
  • Bridget: prefer
  1. In case of a TEI Media Type, the response must be well-formed XML
  • Bridget: prefer

** Decision **: Restrict to well formed for #3 and #4, we can loosen this later if need be.

  1. In case of a TEI Media Type, the response must either be a full TEI document or a fragment
  • Jonathan: Question: Well-formed fragment? Well-balanced fragment? It should probably be one of the two.
  • Bridget: concur

** Decision **: Well-formed.
** Decision **: Thibault to raise separate issue on metadata.

  1. In case of a TEI Media Type, the response should be valid TEI Fragment
  • Jonathan: Question: Well-formed fragment? Well-balanced fragment? It should probably be one of the two.
  • Bridget: concur

** Decision **: Well-formed.

Default media type for fragments (e.g. in query / fulltext responses)

  1. the use of <ab type="extractedFragment"> or similar
  • Jonathan: I prefer this.
  • Bridget: concur
  1. the use of an existing wrapper outside of TEI
  • Jonathan: I can live with this.
  • Bridget: concur
  1. the use of a new wrapper for DTS
  • Jonathan: I can live with this.
  • Bridget: concur
  1. the request for a new tag in TEI
  • Jonathan: I prefer not to wait for TEI to do anything new.
  • Bridget: agree with Jonathan, I prefer not to have a dependency on a TEI change

** Decision **: For 7-10, we will make up our own wrapper and propose it to TEI. ** Action **: Hugh to propose a suitable wrapper.

Clone this wiki locally