ionwg/ion-doc

Address Partially embedded vs. fully embedded resources

Opened this issue · 3 comments

fosrias commented

Involves the ability to provide information that an embedded/expanded instance resource is partial and how to access the full resource.

lhazlewood commented

I've been thinking how to deal with this:

This could be addressed in the current doc, but it would make the spec more than a data format specification (as it is now).

For example, Atom has two primary RFCs:

4287: covers only the data format/structure itself
5023: covers protocol semantics of how data is interchanged

Other than metadata that represents which fields are expandable (which probably should be codified in the format doc), how to expand (e.g. query parameters) is more suitable to a protocol doc.

This implies we have two approaches:

  1. A bigger all-encompassing spec
  2. A number of smaller targeted specs (like HTTP has recently become).

If we go the latter, we would probably have a spec for ion resources (i.e. normal JSON + a meta field), another for collections (being discussed in #2), and another for references (links), and another for protocol (HTTP) exchange.

Thoughts?

lhazlewood commented

I'm thinking the latter (2) makes more sense given how most data+protocol specs are being defined these days (HTTP revamp, JWT, etc). Thoughts?

fosrias commented

@lhazlewood So, one of the things @smizell and I have on a future list, is how to extend and whether that extension mechanism is built into the spec itself, or we have to chain other specs together and the burden that places on clients to know those specs.

Not sure the best approach there. I suspect, that what I consider a base level of functionality in the spec and you do ATM are probably a bit bigger than you are currently thinking. I think we should bounce some of these ideas around to clarify thoughts and perspectives on this and some of the other initial issues and then jump on skype or something and talk some of them out, as necessary. In any case, not sure the best approach.

I probably need to see how you are looking at this a bit in your response to the comments to get a better understanding of the delineation of different specs you discuss above.