After the discussion in the OCCI ConfCall Ralf and I went through the JSON document and identified open issues and how we would solve them. The result is attached as pdf and committed to the new JSON branch in the OCCI WG Git. Following is a short explanation of the design goals: * the overall design goal was to create a data format which is independent from the transport protocol * also important was a compact representation of all OCCI Entities as they may be exchanged very often * OCCI Categories could be verbose to describe the Model in detail * information should be easily accessible Some explanations on specific sections: 4.1 - for attributes the dot notation should be used and each namespace should be rendered as a separate object. This follows best practice in JavaScript to handle nested attributes and should help adoption. 4.2 - type identifiers as used for 'kind', 'mixins' and 'action_categories' are pointers to other objects within the OCCI Core scope and thus are rendered in the top level object. 4.2 - id is rendered in the top level object. The reason is, that id is a pointer to the object itself, thus it is not an attribute, but a OCCI Core property of the object itself comparable to 'self' in many programming languages. Besides it is difficult to specify rules on how id must be rendered if it is not in the top level object. 4.2 - links are represented by the URN of their id following RFC 4122. This is a more compact representation of the link as we had it before. Also it resembles the behavior of id. Thus it is rendered in the top level object 4.3 - source and target are also pointers to objects within the OCCI Core object scope. Thus they are rendered in the top level object. Similar to id it is difficult to specify rules on how source and target must be rendered if they are not within the top level object. 4.3 - the type identifier in 'rel' is a pointer to a OCCI Category and thus rendered in the top level object 4.4 - instantiated actions need to be represented in a format similar to that of OCCI Entities. Actions don't have an 'id' as they are only used once and are not persistent 4.5 - term, scheme, attributes, actions and related are OCCI Core properties of the 'kind' object and thus rendered in the top level scope 4.5 - location is transport protocol specific, but must be an URI. Each transport protocol must specify guidelines for location 4.7 - the action category format is used to define actions similar to kinds describing OCCI entities 4.8 - the attribute description format has been simplified. The general description of attributes went to 4.1. The attribute properties have been reduced to mutable, required, type, default and description. As Pattern complicated matters a lot it was removed. Cheers, Florian
From the Feedback I received regarding the OCCI JSON data format, I updated the document with the following changes * changed the name of OCCI Action Categories to OCCI Action reflecting the changes in OCCI Core and in line with the way it is handled in the text rendering * changed name of OCCI Action to OCCI Action Instance. The Action instance format is now closer to the text rendering of action instantiations * removed restrictions on ID format, as the format is defined in OCCI Core * OCCI Link source and target are now URIs * If only one OCCI Resource is rendered alongside one or more OCCI Links, the OCCI Resource is the source of these OCCI Links if the source entry is omitted. This is now in line with the inline rendering of links in the text rendering * updated examples * some formatting changes From my point of view, the document is now quite mature and I would like to ask everyone to go through the document in detail and report back all outstanding issues, including spelling and grammar mistakes! Cheers, Florian Am 27.08.2012 um 15:14 schrieb Feldhaus, Florian:
After the discussion in the OCCI ConfCall Ralf and I went through the JSON document and identified open issues and how we would solve them. The result is attached as pdf and committed to the new JSON branch in the OCCI WG Git.
Following is a short explanation of the design goals: * the overall design goal was to create a data format which is independent from the transport protocol * also important was a compact representation of all OCCI Entities as they may be exchanged very often * OCCI Categories could be verbose to describe the Model in detail * information should be easily accessible
Some explanations on specific sections: 4.1 - for attributes the dot notation should be used and each namespace should be rendered as a separate object. This follows best practice in JavaScript to handle nested attributes and should help adoption. 4.2 - type identifiers as used for 'kind', 'mixins' and 'action_categories' are pointers to other objects within the OCCI Core scope and thus are rendered in the top level object. 4.2 - id is rendered in the top level object. The reason is, that id is a pointer to the object itself, thus it is not an attribute, but a OCCI Core property of the object itself comparable to 'self' in many programming languages. Besides it is difficult to specify rules on how id must be rendered if it is not in the top level object. 4.2 - links are represented by the URN of their id following RFC 4122. This is a more compact representation of the link as we had it before. Also it resembles the behavior of id. Thus it is rendered in the top level object 4.3 - source and target are also pointers to objects within the OCCI Core object scope. Thus they are rendered in the top level object. Similar to id it is difficult to specify rules on how source and target must be rendered if they are not within the top level object. 4.3 - the type identifier in 'rel' is a pointer to a OCCI Category and thus rendered in the top level object 4.4 - instantiated actions need to be represented in a format similar to that of OCCI Entities. Actions don't have an 'id' as they are only used once and are not persistent 4.5 - term, scheme, attributes, actions and related are OCCI Core properties of the 'kind' object and thus rendered in the top level scope 4.5 - location is transport protocol specific, but must be an URI. Each transport protocol must specify guidelines for location 4.7 - the action category format is used to define actions similar to kinds describing OCCI entities 4.8 - the attribute description format has been simplified. The general description of attributes went to 4.1. The attribute properties have been reduced to mutable, required, type, default and description. As Pattern complicated matters a lot it was removed.
Cheers, Florian
_______________________________________________ occi-wg mailing list occi-wg@ogf.org https://www.ogf.org/mailman/listinfo/occi-wg
On Mon, 24 Sep 2012 16:02:37 +0000, "Feldhaus, Florian"
From the Feedback I received regarding the OCCI JSON data format, I updated the document with the following changes
Excellent work Florian! Simple and elegant. Detailed feedback when I have had time for a thorough read-through. regards, Ralf
On Mon, 24 Sep 2012 16:02:37 +0000, "Feldhaus, Florian"
* changed name of OCCI Action to OCCI Action Instance. The Action instance format is now closer to the text rendering of action instantiations
With the Core errata changes OCCI Action is only an identifier of the invocable operation. It does not represent the operation itself. An OCCI Action instance is basically just a Category with a different class name. And being a type identifier it cannot contain e.g. attribute values. I would therefore propose to call this "Action _invocation_ format" instead. I have uploaded a commit implementing this change to the json branch. The commit only touches this issue and should be easy to back out if not desired. regards, Ralf
I like that idea Ralf, it embodies the fact that it is an invocation message with eventual invocation parameter values.SincerelyJamie
To: florian.feldhaus@gwdg.de Date: Tue, 25 Sep 2012 19:48:13 +0200 From: ralf@nyren.net CC: occi-wg@ogf.org Subject: Re: [occi-wg] OCCI JSON data format
On Mon, 24 Sep 2012 16:02:37 +0000, "Feldhaus, Florian"
wrote: * changed name of OCCI Action to OCCI Action Instance. The Action instance format is now closer to the text rendering of action instantiations
With the Core errata changes OCCI Action is only an identifier of the invocable operation. It does not represent the operation itself.
An OCCI Action instance is basically just a Category with a different class name. And being a type identifier it cannot contain e.g. attribute values.
I would therefore propose to call this "Action _invocation_ format" instead. I have uploaded a commit implementing this change to the json branch. The commit only touches this issue and should be easy to back out if not desired.
regards, Ralf _______________________________________________ occi-wg mailing list occi-wg@ogf.org https://www.ogf.org/mailman/listinfo/occi-wg
Hi,
Please find attached the updated JSON document with a, IMO, more
consistent description of the format used to invoke an OCCI Action.
Just to clarify, this refers to OCCI Actions as defined in the Core Model.
The HTTP operations GET/POST/PUT/DELETE are _not_ OCCI Actions.
OO: While an OCCI Kind identifies "class" an OCCI Action identifies a
"method" found in a class.
regards, Ralf
On Tue, 25 Sep 2012 19:48:13 +0200, Ralf Nyren
On Mon, 24 Sep 2012 16:02:37 +0000, "Feldhaus, Florian"
wrote: * changed name of OCCI Action to OCCI Action Instance. The Action instance format is now closer to the text rendering of action instantiations
With the Core errata changes OCCI Action is only an identifier of the invocable operation. It does not represent the operation itself.
An OCCI Action instance is basically just a Category with a different class name. And being a type identifier it cannot contain e.g. attribute values.
I would therefore propose to call this "Action _invocation_ format" instead. I have uploaded a commit implementing this change to the json branch. The commit only touches this issue and should be easy to back out if not desired.
regards, Ralf
participants (3)
-
Feldhaus, Florian
-
Jamie Marshall
-
Ralf Nyren