[oslc-core] Core 2.0 JSON Representation Guidelines - ambiguity in serialization of literals

[John Arwe]

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