[oslc-core] Core 2.0 JSON Representation Guidelines - ambiguity in serialization of literals
John Arwe
johnarwe at us.ibm.com
Fri Aug 12 09:47:31 EDT 2011
At [1], under the rules to serialize each property, the prescription for
Literal is to set the field's value equal to the "string representation"
of the property value (pasted excerpt below, after [1]). People are
asking me if this means (for a value like 1.0 say in a property whose
value-type is float), if that means 1.0 or "1.0". Their interpretation of
[1] is that "1.0" is the required output, implying that its JSON-type must
be string; if the quotes were omitted, its JSON-type would be number, as I
read [7].
In looking at the related examples and information about existing
implementations (various flavors of "follow your nose" through the specs),
I cannot answer this unambiguously using only the specs I have examined.
Implementation samples suggest that the quotes are not required. Here is
a log of my travels; details for each are below.
[2] OSLC Core Specification:JSON Representation Examples appears to show
only string and dateTime literals. Since JSON does not have a native
dateTime type, that document appears to be silent on this question.
Recommendation: across the examples, cover each of the value-type
possibilities.
[3] Open Services for Lifecycle Collaboration Core Specification Version
2.0 Appendix A: Common Properties ; oslc:ResourceShape Resource lists
(after the table) the valid value-type values, which includes
integer/double and friends. But no examples (they're in [2] in theory,
fair enough if that were true). Hmm.
[4] Wander over to CM examples; change requests at least have some
booleans and dates, let's see how those are serialized in JSON as an
indicator at least. No such example.
[5] Remembering that CM defines a shape, and from [3] that shapes can have
an integer maxsize and a boolean or two, try looking at the CM Shape. Only
shown as an XML serialization :-(
[6] Having recently found out about the existence of a really good
jazz.net article on RTC 3's CM usage, comb through that looking for what
it tells me. While this is not a guarantee of the spec's intent, it at
least tells me what one implementation does, and since this implementation
was one of those involved in spec convergence, it's a better-than-random,
if not deterministic, example. Pay-dirt at last, in Example 6 where it
shows the serialization of oslc:responseInfo that includes
"oslc:totalCount": 7, ...i.e., no quotes.
[6] Reading down further, I see "dc:identifier": 73, in Appendix B. I'm
"sure" identifier is a string, so why not "73"? Checking in [3], indeed
the value type of identifier is "string". Now I'm really confused, or
there is a bug in the article and/or the implementation from which the
article was sourced.
[6] Futher down in Appendix B, "rtc_cm:archived": false, which is
consistent with totalCount (if the underlying intent is to use the JSON
built-in types to the degree they match the value-type) but not with
identifier.
[6] Yet further down, I find "rtc_cm:correctedEstimate": null, ...
suggesting there may be yet another ambiguity in the serialization rules.
I'm not sure what rule gets me to null, if all properties in RDF are
optional.
Wander over to the QM spec [8] and its examples [9] + shapes [10]. Mostly
strings, resources, and few dateTimes. All the samples+shapes are XML.
Wander over to [11] Reqts Mgmt (since I thought that was implemented), but
1.0 spec and wg page make me wonder. Don't find any samples/shapes.
Am I missing something that explains why each of the examples above is
either definitely right or definitely wrong, and similarly prescriptive
information for all other value-types?
[1]
http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixRepresentations?sortcol=table;up=#Guidelines_for_JSON
These are the property rules referred to above. For each property:
1.0 For each property of a resource
1.1 Add field to the resource's JSON object with name set to Prefixed Name
of property
1.1.1 If the property is specified as a single-valued property, then make
field's value literal or JSON Object
1.1.2 If the property is specified as a multi-valued property, then make
field's value JSON Array
1.2 Else if value-type is Literal
1.2.1 Set field's value to string representation of property value
1.3 Else if value-type is Resource with representation of Reference
[2] http://open-services.net/bin/view/Main/OSLCCoreSpecJSONExamples
[3]
http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA?sortcol=table;table=up#oslc_ResourceShape_Resource
[4] http://open-services.net/bin/view/Main/CmSpecificationV2Samples
[5] http://open-services.net/bin/view/Main/CmSpecificationV2Shapes
[6] https://jazz.net/wiki/bin/view/Main/WorkItemAPIsForOSLCCM20
[7] http://tools.ietf.org/html/rfc4627
[8] http://open-services.net/bin/view/Main/QmSpecificationV2
[9] http://open-services.net/bin/view/Main/QmSpecificationV2Samples
[10] http://open-services.net/bin/view/Main/QmSpecificationV2Shapes
[11] http://open-services.net/bin/view/Main/RmHome
Best Regards, John
Voice US 845-435-9470 BluePages
Tivoli OSLC Lead - Show me the Scenario
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-core_open-services.net/attachments/20110812/30fa7198/attachment-0003.html>
More information about the Oslc-Core
mailing list