[occi-wg] OCCI JSON Rendering Draft

[Feldhaus, Florian]

Hi Ralf,

do you have any more comments to the JSON Rendering? Else I would like to proofread it over the weekend and prepare a near final version.

Some replies to your comments:

Am 08.05.2012 um 21:57 schrieb Ralf Nyren:

> On Tue, 08 May 2012 16:17:57 +0200, Feldhaus, Florian <florian.feldhaus at gwdg.de> wrote:
> 
>> Locations
>> - do UUIDs have to be globally unique, unique for all resources within a provider, or for all resources of a certain kind?
> 
> According to OCCI Core occi.core.id must be unique within the service providers name-space.
> 
> UUIDs should be rather unique in general me thinks, kind of their purpose…

ok. UUIDs should be unique for the service provider. But if the underlying service has non unique IDs (like OpenNebula), does OCCI have to convert them to unique ones? For the JSON Rendering this is not relevant. Maybe we can discuss the creation of UUIDs in a separate mail thread.

>> -> I would prefer if we don't restrict this too much, thus it would be sufficient to restrict in OCCI Core, that UUIDs are unique for all resources of a certain kind for one OCCI endpoint. The UUID is created by the backend (underlying service provider) or with information from it. Thus, if the resource is migrated to a different service provider, it gets a different UUID anyway.
> 
> I think we should leave it as it is in OCCI Core, that is  occi.core.id MUST be unique within the service provider's name-space. Having a Compute and a StorageLink with the same UUID must not be possible.

see above.

>> - I'm not too happy with having the location being part of the kind/mixin rendering, as it is specific to the HTTP representation of the OCCI objects. I thought we might be able to introduce some guideline to derive the location from the term of the kind/mixin and it's related kinds/mixins (e.g. term recursively prepended by term of related kind/mixin). The only problem is, that mixins can have multiple relations. Thus we might have multiple locations for the same mixin. I don't see a problem with it, but it might lead to confusion.
> 
> Please view the "location" as a pointer to where you can find a representation of the Collection implied by the Kind/Mixin.
> 
> If you want to keep the JSON serialization "clean" simply say location is a string with the above semantics.

Ok, I'm convinced.

> 
>> Link
>> - for Target and Source the URI is sufficient, all further information can be retrieved by the client. There may also be mechanisms to ask the server to directly supply all resources connected via links. But that should be taken care of in HTTP rendering then.
>> - Source is optional when rendered within resource. Then the link definition is the same for top level link renderings and link renderings within resources.
> 
> Inline rendering of Link attributes must be supported. As with the text/plain rendering they would be optional but the format should support them.

Inline rendering is supported. I just don't see a difference between inline rendering and direct rendering of a link except the source attribute which is not needed for inline links.

> Sorry to be so hard on this but I believe it very important to keep as close as possible to the existing text/plain rendering in terms of the information transferred. If we start changing too much the JSON rendering will take forever to get ready.

I don't see a difference to the text/plain rendering for links as they currently are in the JSON Rendering.

> Additionally I find the title of the target Resource to be quite handy. Imagine rendering a Resource with click-able links for example.

I find it handy as well, BUT:
The title is currently an attribute of entity and thus must be rendered as part of the attributes. We could go down two roads:
- Render title twice, once directly in the resource (similar to kind) and once within the resources attributes
- Define all OCCI Core attributes (e.g. occi.core.id, occi.core.title, occi.core.summary, occi.core.source, occi.core.target) to be rendered directly within the resource. In my opinion this would be a very good solution and would be much more intuitive for people using or implementing OCCI than the current solution. This should then also be changed in the text/plain rendering, but we have to revise that anyway.

> 
>> Mixins
>> - can mixins be related to kinds?
> 
> No. This is well-defined in OCCI Core.

Ok.

>> -> I have a resource template as example and was wondering, how one would specify occi.compute.core for this template. If the mixin is related to compute, the attributes are all derived from the compute kind description and can be set to new defaults with the mixin.
> 
> There is no restrictions on which attributes a Mixin could define. You could have a Mixin defining the occi.compute.speed attribute for instance.
> 
> To create a template with a default value for occi.compute.speed you create a Mixin defining attribute occi.compute.speed with property "default" set to the desired value.

Ok.

>> Action
>> - should action really not be derived from category?
> 
> The Action class represent an invocable action. The Category instance describes the type, i.e. a sub-class of Action. I do agree though that the modelling of the Action is a weak part of OCCI Core.

I don't think so. In the OCCI Core model, the Action describes some invocable action of an entity and is not the invocable action itself. Action cannot be instantiated! Currently I'm quite often being asked: "Why does action contain a category? That doesn't make sense!". If we would make Action to be derived from Category, no one outside the OCCI WG would miss it and we wouldn't be asked so many questions about actions. Again, a discussion for OCCI Core, not for JSON.

>> -> I don't see any reason for the current solution (action containing a category). It would be much more consistent, if the Action would also be derived from Category.
> 
> Category, Kind and Mixin are type identifiers. Instances of Category/Kind/Mixin describe other classes such as Resource and Link.
> 
> This is the tricky part of the OCCI Core model. You have (in OO language) _objects_ which describe other _classes_.

Hm. As stated above, I see Actions as describing class methods. Maybe we can rethink the Actions and then maybe change them in OCCI Core. Something for a separate thread.

> 
>> Formatting
>> - Currently the JSON examples are a bit hard to read. Maybe we could use the LaTeX package "minted" to do automatic highlighting?
> 
> I would be a bit careful with colors in the document but give it a go so we can see :)
> 
> Regarding the examples could you replace the example values and instead put in the JSON type in italics instead?
> 
> E.g.:
> {
>  "resources": [
>   {
>     "kind": *string*,
>     "mixins: [ *string*, ... ]
>  }]
> }
> 
> Pure examples could then be saved for a separate section at the end of the document.

That's a good idea.

Cheers,
Florian
-------------- 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/20120511/fb80029e/attachment.bin>