How does "formats" work?

[dret]

reading through https://tools.ietf.org/html/draft-nottingham-json-home-04 and looking at the example i cannot quite figure out how "formats" (https://tools.ietf.org/html/draft-nottingham-json-home-04#section-4.2) works.

• the section talks about GET and PUT, but those aren't the only methods for which it might be necessary to talk about "formats", right?
• how does the key/value structure work? the example has one key with an empty value, and the section defining "formats" links to a section marked "tbd".

i am working on getting an updated version of the XML syntax ready, and thus i am going through the syntax. however, this seems to be a general issue where it's hard to figure out how that specific feature is supposed to work.

[dret]

dret/I-D@68ee110 is my first stab at how to do this for the XML syntax. but i am sure this will need to be tweaked once i better understand the "formats" mechanism.

[dret]

thinking about this some more: maybe this is a combined "GET"/"PUT" hint that's kind of analogous to the "accept-*" ones? if so, for consistency what about having an "accept-put" and leave "formats" to only talk about the formats for retrieval?

[dret]

now i realize that this is how -02 worked and accept-put then disappeared in -03. to me that seems like a loss, but i am sure there was some reason to do it.

[dret]

i realize that this structure (using the example from the draft) is not good for the fine-grained "hints" concept. but it associates things more directly and maybe is easier to read and understand?

{"hints": {"allow": [
  {"GET": ["application/json"]},
  {"PUT": ["application/json"]},
  {"DELETE": []},
  {"PATCH": ["application/json-patch"]}
]}}

[mnot]

Good Q, although the phrasing reminds me of this :)

Will need to dig into it, not sure I can get to it soon, as I'm on the road for a while.

[dret]

On 2016-06-22 23:18, Mark Nottingham wrote:

Good Q, although the phrasing reminds me of this
https://www.youtube.com/watch?v=OvmvxAcT_Yc :)

no intention to be offensive on my side, sorry if it came across like
this. simply trying to figure it out as the XML format needs to be aligned.

Will need to dig into it, not sure I can get to it soon, as I'm on the
road for a while.

ok. i'd be more than happy to help, and maybe simplifying the whole
thing (as suggested in #193) to be more about interconnecting resources
and not so much about capabilities would make it easier to move forward.

[mnot]

no intention to be offensive on my side, sorry if it came across like
this. simply trying to figure it out as the XML format needs to be aligned.

Oh, no, sorry! Was not trying to imply that, just being silly. Sorry.

[mnot]

I think it boils down to whether the formats you can GET and PUT are always the same (provided you're allowed to perform both methods, of course).

I can imagine that an API only wants to consume data in one format, but can provide it in more than one.

acceptPut, perhaps?

[mnot]

BTW, I'm thinking about ditching representation hints altogether; I think all of the semantics necessary for a home doc can be communicated in the media type / link relation + target attributes. Thoughts?

[asbjornu]

I think the less JSON Home tries to do, the better. It can very quickly end up duplicating the efforts of Web API specification languages such as Swagger, RAML, API Blueprint, Hydra, etc. As far as I understand, that's not the intention of JSON Home. The only thing I'd ensure is that these specification formats can easily be referenced from the JSON Home document.

[dret]

On 2016-11-23 21:29, Asbjørn Ulsberg wrote: I think the less JSON Home tries to do, the better. It can very quickly end up duplicating the efforts of Web API specification languages such as Swagger <http://swagger.io/>, RAML <https://raml.org/>, API Blueprint <https://apiblueprint.org/>, Hydra <http://www.hydra-cg.com/>, etc. As far as I understand, that's not the intention of JSON Home. The only thing I'd ensure is that these specification formats can easily be referenced from the JSON Home document.

https://tools.ietf.org/html/draft-wilde-service-link-rel should help with that (without requiring any specific support in JSON home).

[asbjornu]

@dret: True, thanks for the pointer!

[dret]

On 2016-11-22 22:48, Mark Nottingham wrote: BTW, I'm thinking about ditching representation hints altogether; I think all of the semantics necessary for a home doc can be communicated in the media type / link relation + target attributes. Thoughts?

i think that's a smart move. we had these discussions somewhere else already, with a variety of parties (you and me included) trying to come up with something akin to representation hints, and the various approaches never seemed to quite make everybody happy. if the home format is extensible enough that later on, such representation hints could be added, if a standard is created and people want to embed them, then things are in good shape. i generally agree with @asbjornu here that this should be rather minimal in scope.

[handrews]

@mnot does "ditching representation hints" just refer to "formats" or to the whole hints section?

[dret]

On 2016-12-27 13:25, Henry Andrews wrote: @mnot <https://github.com/mnot> does "ditching representation hints" just refer to "formats" or to the whole hints section?

my interpretation is that it refers to the whole concept of representation hints. but i am not sure.

[handrews]

@dret my question was more on what qualifies as a "representation" hint vs (possibly) other types of resource hints. Like is the "allow" hint a representation hint? It doesn't technically say anything about the representation itself.

[dret]

On 2016-12-29 12:54, Henry Andrews wrote: @dret <https://github.com/dret> my question was more on what qualifies as a "representation" hint vs (possibly) other types of resource hints. Like is the "allow" hint a representation hint? It doesn't technically say anything about the representation itself.

true, but it tells you how you can interact with it. and "representation hints" as a separate concept are gone from https://tools.ietf.org/html/draft-nottingham-json-home-05 anyway, now there only are "resource hints". but anyway, exegesis does not make a lot of sense here, let's see what @mnot says.

[handrews]

but anyway, exegesis does not make a lot of sense here, let's see what
@mnot says.

Agreed. My interest is that many of the hints complement what JSON Hyper-Schema does, and I'm trying to figure out if it makes sense to use JSON Hyper-Schema and JSON Home together. It would also help me decide whether to push for HTTP-related hints in JSON Hyper-Schema or not. It's been proposed, but honestly if JSON Home can address those in a way that complements JSON Hyper-Schema, I'd rather leave HTTP-specific things out of Hyper-Schema (not that I'm making that decision on my own, but I can push for or against it :-)

[dret]

On 2016-12-29 13:18, Henry Andrews wrote: but anyway, exegesis does not make a lot of sense here, let's see what @mnot <https://github.com/mnot> says. Agreed. My interest is that many of the hints complement what JSON Hyper-Schema does, and I'm trying to figure out if it makes sense to use JSON Hyper-Schema and JSON Home together. It would also help me decide whether to push for HTTP-related hints in JSON Hyper-Schema or not. It's been proposed, but honestly if JSON Home can address those in a way that complements JSON Hyper-Schema, I'd rather leave HTTP-specific things out of Hyper-Schema (not that I'm making that decision on my own, but I can push for or against it :-)

going off-topic: the whole hyper-schema part is a pretty big burden on the spec already. from what the majority of people are looking for, it might make sense to factor that out into a separate spec and keep JSON schema lean and simple. i would definitely think very carefully about extending that part even further.

[handrews]

going off-topic: the whole hyper-schema part is a pretty big burden on
the spec already.

It technically is a separate spec, we've just been updating their drafts at the same time. But they don't have to reach RFC at the same time. I don't want to derail this discussion further so if I'm missing your point feel free open an issue over on the JSON Schema repo or mailing list.

[dret]

9f865df leaves the general concept more or less unchanged and adds acceptPut as discussed earlier in this issue. i am wondering about the comments made above about unbundling the home format and the general idea of link descriptions/hints. aren't these two orthogonal concepts that can be combined, but also both make sense as standalone specifications?

[mnot]

Well, it changes formats to cover GET (and by extension, HEAD), not PUT.

Which comments were about unbundling the home format? I read them as a side conversation about JSON Hyper Schema.

[dret]

On 2017-02-22 07:12, Mark Nottingham wrote: Which comments were about unbundling the home format? I read them as a side conversation about JSON Hyper Schema.

maybe different people have different views and/or goals. my view still is (as mentioned in comments in this issue) that it might be best for home documents to just provide a basic structure for home documents, and to leave the hinting part as a separate exercise. i think that's what both https://tools.ietf.org/html/draft-nottingham-link-hint and https://tools.ietf.org/html/draft-wilde-link-desc had in mind. my main motivation for this is that hints are a valuable thing in itself, and bundling them into the home document spec might make reuse harder and less attractive for others. to some extent the hints are visible by themselves through the proposed registry and that is great, because this registry then can grow without updates to the home spec. but just as a matter of trying to create a better separation of concerns, it might be better to separate home document and hints.