[occi-wg] Summary of the JSON rendering discussion

[Feldhaus, Florian]

Following I try to summarize the recent discussion of the JSON rendering, please feel free to add, extend or correct it:
- different content types
 * different content types make it easier to identify the content of the message
 * content type negotiation may get more complicated
 * for GET requests, the client may know what type of content he's requesting (even though he may use different content types in Accept and doesn't know which one the server responds with)
 * for POST requests, the server doesn't know what content type he gets
- if just application/json is used as media type (instead of e.g. application/occi+json or more detailed content types), the client doesn't know which semantics the content have
- CDMI uses specific media types to help client and server to know the semantics of the content without first interpreting the content
- how should the location of the entities be named? location, href, uri?
- there should be a recommendation that the JSON format should be rendered compact (e.g. without unnecessary whitespaces) in production use
- how should the category identifier be called? rel, type? rel is based on the HTTP way of doing things
- make the JSON format as easy to use and as compact as possible
- there was a security issue with having JSON arrays at the top level. This issue is solved as of ECMAScript5 [1]. Using just an array with all categories or entities would be a compact rendering. Questions are:
-- Is ECMAScript5 already widely adopted?
-- when exactly does this security issue appear? Can it be exploited for HTTPS connections where the OCCI endpoint has been clearly identified by a valid certificate?
- should there be a JSON rendering of Locations or is it sufficient to have text/uri-list? Could a JavaScript implementation easily parse text/uri-list if the client intends to just get the locations of some object (maybe together with a filter)?

- rendering of entities:
-- is rel necessary for actions?
-- which fields are really necessary for links inside of entities? 
--- smallest version would be just the link location
--- title would be very handy for displaying in user interfaces
--- title, target uri/href, rel, link href/uri, link rel and attributes would make it easier for the client to directly use links, but may introduce a lot overhead for huge number of links
-- attributes should be rendered according to their hierarchy (e.g. as { 'occi': { 'core': { 'id': '123' } } } ). This makes using attributes very simple for clients, especially those written in JavaScript.
-- all attributes must be unique regardless how they are rendered. This should be taken care of in OCCI Core and may be achieved by using reversed domain names for user/provider defined mixins.
-- depending on the impact of the security issue with Top Level arrays, entities can be rendered either compact with only an array or a little more verbose by using a JSON object/hash with key 'entities' and the array of entities as value
-- should single entities be rendered differently from multiple entities? e.g. should a single entity be directly rendered as JSON object/hash with kind, mixins, … or should it be in the same format as multiple entities e.g. inside an array?

- rendering of categories:
-- should attributes be rendered as single string or as hierarchy of hashes (e.g. "occi.core.id" : ... vs. "occi": { "core: { "id": … } } }?
-- type should be extended with the restrictions defined in OCCI Core for the attribute type. This can be e.g. for string: choices / min_length, max_length and for numbers: bounds

Example of proposed compact rendering (save whitespaces) of OCCI entities by Jamie, Florian and others:
http://pastebin.com/aun0Ha2D

Combination of above rendering with Ralfs Collection format (replacing 'collection' to 'entity' because I don't like using the name collections when its an array of entities ;-) ):
http://pastebin.com/bffFtL19

Example of proposed category rendering by Ralf, extended by Jamie, Florian and others:
http://pastebin.com/txhnt7uX

[1] http://flask.pocoo.org/docs/security/#json-security

--Florian

-------------------------------------------------------------------------------
GWDG - Gesellschaft für wissenschaftliche
Datenverarbeitung mbH Göttingen
Am Fassberg 11, 37077 Göttingen

Fon: 0551 39-20364
Fax: 0551 201-2150
E-Mail: florian.feldhaus at gwdg.de
WWW: www.gwdg.de
-----------------------------------------------------------------------------------
Geschäftsführer: Prof. Dr. Ramin Yahyapour
Aufsichtsratsvorsitzender: Prof. Dr. Christian Griesinger
Sitz der Gesellschaft: Göttingen
Registergericht: Göttingen
Handelsregister-Nr. B 598
-----------------------------------------------------------------------------------