[occi-wg] JSON Rendering

[Feldhaus, Florian]

Hi,

how do we proceed?

Following a some responses to your comments:

Am 04.04.2012 um 10:59 schrieb Ralf Nyren:

> On Tue, 03 Apr 2012 14:31:24 +0200, Feldhaus, Florian <florian.feldhaus at gwdg.de> wrote:
> 
>> Hi,
>> 
>> once again I would like to reiterate the JSON rendering. First a short overview what Alexander and I think are the main points we should address:
>> - remove all HTTP Rendering specific parts from the JSON rendering
> 
> Remember that an OCCI rendering (as currently specified) includes _both_ protocol and data format at the moment.

That's only partly true. A "pure" JSON rendering can already exist independently from the HTTP Rendering without any trouble in rendering. 

> I like the idea of having a common HTTP Protocol rendering spec which the JSON rendering could be built upon though.

I second this and would like to move forward. Any comments on the best strategy? Do we need to create a version 1.2 for the HTTP rendering?

> However, the current HTTP rendering doc lacks things like e.g. request parameters in URL which I would say is necessary to have a sane JSON rendering.

I don't think so. The rendering should be independently of the transport protocol. If I ask your server to send me a file by mail containing the JSON rendering of all resources, that should work as well. 

> Updating the HTTP rendering doc to have a clear separation between protocol and data format would address this of course.
> 
>> - make the JSON rendering slim and remove everything which is not a representation of the OCCI model
> 
> You mean the pagination links etc? Or something else as well?

I meant the HTTP rendering parts, the pagination links and the rendering itself being reasonably slim.

>> - consider using RFC 5988 "Web Linking" for collection information (e.g. index, next, previous,…)
> 
> Gary and I had an email conversation which resulted in a solution where all info necessary for pagination would end up in the request URL. I.e. basically eliminating the need for using special headers (such as RFC 5988).
> 
> The request parameters to a collection simply allow you to specify the amount of resource instances you want returned either _before_ or _after_ a specific occi.core.id.

Do you have some examples? IMHO this should go to the revised HTTP rendering document.

>> Examples:
>> http://pastebin.com/ZK9Uf0K1 (Entities)
> 
> Nice, I like that you keep the "attributes" hash now ;)
> 
> How do you render Link attributes for the links tied to an OCCI Resource?

In the example you can see Links are rendered as a hash containing href and kind. The only really necessary part is the href location. Everything else is optional and could be retrieved by the client using separate HTTP requests. It would also be possible to omit the hash and just render all link hrefs in an array. To allow for a slim rendering and also allow for additional information to be send to the client, I would suggest that we specify a hash with at least the href and optional all other parameters valid for the link. We could even go so far as to use the link rendering for rendering link attributes within resources.

>> To keep the mail short, a detailed discussion can be found in the attached text document.
> 
> Just picking out one thread:
> 
>> resources and links should be represented differently. The entry "links" is unique for resources and the entries "target" and "source" are unique for links.
> 
> Sounds goods. So the top-level hash of the collection format would have one hash "resources" and another hash "links" then?
> I mean, we still have to cover the case where the client asks for "everything" at the top-level URL and thus gets both Resources and Links in the response.

I would suggest to have a content-type for entities. It should contain a hash with "links" and "resources". Both then are arrays of hashes.

>> In OCCI Core the attribute names should be changed from occi.core.source and occi.core.target to just source and target, as both are representing connections to other resources from within the OCCI model (similar to links in resources, or kind in entity).
> 
> occi.core.source and occi.core.target was named simply source/target up until just before the OCCI HTTP Rendering doc was published.
> 
> The fundamental problem here is that we have two different sorts of "attributes".
> 1. Attributes as part of the OCCI Core model. These include both Entity.id, Entity.title, Resource.summary, Resource.links, Link.target, Link.source, etc
> 2. Attributes as exposed by an OCCI rendering. The HTTP Rendering exposes id, title, summary as attributes as well as target and source. However the Resource.links attribute is not exposed as an attribute...
> 
> There is no clear distinction here which IMO leads to confusion.
> 
> Also remember that a subclass of OCCI Link may have Link.target pointing at some arbitrary external object.

In my opinion, source and target always point to resources, even if they lie outside the OCCI model. They contain complex data types like kind or mixin and not primitive data types like id, title or summary.

> regards, Ralf
> _______________________________________________
> occi-wg mailing list
> occi-wg at ogf.org
> https://www.ogf.org/mailman/listinfo/occi-wg

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4964 bytes
Desc: not available
URL: <http://www.ogf.org/pipermail/occi-wg/attachments/20120405/c09eb393/attachment.bin>