Content Negotiation (USX, USFM) and Scripture Burrito

[jonathanrobie]

In part related to #75

Scripture Burrito needs to support multiple representations of the same resource, e.g. USX and USFM representations of the same texts. You could easily imagine HTML representations or other formats.

I imagine the use case for this involves clients that can accept one representation but not another. This is analogous to what HTML calls content negotiation, which is well described here:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation

For Scripture Burrito, I think the key requirement is a declarative way to say that these representations are all representations of the same thing. I don't think we need to designate one as a source, USFM might not be the source if it is generated from USX or some other source, and the client that consumes it might not care as long as it knows that all representations are equivalent.

I don't think we need to include the code to transform among formats.

[mvahowe]

Content negotiation is server functionality, so this would be something to discuss as part of our specification for idServer behaviour.

We have ways to say how things are related to each other already:

• relationships between entries
• revisions of entries
• variants of entry/revisions

I don't think we need another way.

We also have a rich language for describing what servers and clients may accept, including

• flavorTypes
• flavors
• x-flavors
• conventions
• x-conventions

Also, flavors != mimetypes. Acceptability of content may include the mimetype of specific ingredients, but it's more likely to be about the ownership and structure of the burrito as a whole.

I've already implemented most of this, so I'm pretty sure it can work.

[jonathanrobie]

In Scripture Burrito, what is the correct way to define the relationship between two representations of the same resource (USX, USFM)?

On Tue, Mar 24, 2020 at 10:05 AM Mark Howe notifications@github.com wrote:

Content negotiation is server functionality, so this would be something to discuss as part of our specification for idServer behaviour.

We have two ways to say how things are related to each other already. I don't think we need a third day.

We also have a rich language for describing what servers and clients may accept, including

• flavorTypes
• flavors
• conventions

Also, flavors != mimetypes. Acceptability of content may include the mimetype of specific ingredients, but it's more likely to be about the ownership and structure of the burrito as a whole.

I've already implemented most of this, so I'm pretty sure it can work.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/bible-technology/scripture-burrito/issues/170#issuecomment-603258601, or unsubscribe https://github.com/notifications/unsubscribe-auth/AANPTPNDVJEKF2VMAXWC463RJC43PANCNFSM4LSTY5JA .

[mvahowe]

I've added some lists above.

[mvahowe]

And, as with every other conversation, the answer depends on what you mean by "the same".

[mvahowe]

eg USFM cannot be "the same as" USX which includes @loc attributes. It's impossible.

[mvahowe]

eg USX cannot represent invalid USFM.

[jonathanrobie]

If I have software that can read the Gospel of Mark, but not all formats, and I have a Scripture Burrito in my hands, I would like to be able to look at the available formats and pick one. No intermediate server required.

This seems like a fundamental relationship, the USFM, USX, and HTML representations of the same document.

[mvahowe]

If I have software that can read the Gospel of Mark, but not all formats, and I have a Scripture Burrito in my hands, I would like to be able to look at the available formats and pick one. No intermediate server required.

Where are you looking at these available formats, if not on a server?! There's no plan to put every available format into each Burrito. That strikes me as a terrible idea. I can list the reasons if it's really necessary.

[mvahowe]

This seems like a fundamental relationship, the USFM, USX, and HTML representations of the same document.

Does it? Why not USFM, USX, HTML, RTF, markdown...? And why not HTML2.1, HTML5, XHTML... And why not USX2, USX3, with and without footnotes, with and without cross-references... We could end up with 100 different versions of the same thing in every burrito, just in case someone wants it, and require all processors to produce all of those versions. We could probably get Amazon to pay us a commission for bloating everyone's bandwidth by a factor of 2.

This looks to me like a problem that is easy to solve with one USFM source plus some recipeSpecs to make derived variants on demand.

[jag3773]

It's possible that expressions cover this, but @jtauber will review the spec and issue and report back.

[jonathanrobie]

This is now moot.