[occi-wg] OCCI JSON Rendering Draft

[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...

> -> 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.

> - 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.

> 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.

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.

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

> Mixins
> - can mixins be related to kinds?

No. This is well-defined in OCCI Core.

> -> 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.

> 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 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_.

> 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.

regards, Ralf