[oslc-core] Core 2.0 JSON Representation Guidelines - ambiguity in serialization of literals
Michael F Fiedler
fiedler at us.ibm.com
Wed Sep 21 08:14:59 EDT 2011
John Arwe raises four issues below. For discussion in today's Core
meeting if time allows:
1. Should OSLC numeric literals (Integer, Decimal, Double, Float) be
serialized to JSON with or without quotes?
I.e. as a JSON primitive number or a JSON primitive string? Section
1.2 of the Guidelines for JSON [1]
states that "If value-type is Literal...Set field's value to string
representation of property value" .
- Recommendation: JSON representation should be a number when
the Literal is numeric.
Clarify the Core spec to state:
If value-type is a Literal String, DateTime or XMLLiteral,
set the field's value to a JSON string
representation of the property value.
If value-type is a Literal numeric (Integer, Decimal,
Double, Float), set the field's value to a JSON number
If value-type is a Literal boolean, set the field's value to
a JSON boolean
2. The core spec is lacking in examples of JSON representations of OSLC
resources with literals other
than strings and date-times.
- Recommendation: Add additional examples to Core using the
guidelines in 1, above.
3. RTC uses a JSON number (i.e. no quotation marks) for a field that is
specified as a string in the spec (dcterms:identifier).
- Recommendation: Open a defect against RTC. Even though the
identifier value is [0-9]+, the JSON
representation of the field should be a string.
4. RTC serializes rtc_cm:correctedEstimate with a JSON representation of
null when there is no
value (XML representation is
<rtc_cm:correctedEstimate></rtc_cm:correctedEstimate>.
- Recommendation: Not an OSLC field, so outside the scope of the
spec. However, if this was an OSLC-defined
field, the value should not be returned in the XML or JSON
representations. Clarify the spec to state this.
Comments?
[1] -
http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixRepresentations?sortcol=table;up=#Guidelines_for_JSON
Regards,
Mike Fiedler
===================================
John Arwe johnarwe at us.ibm.com
Fri Aug 12 09:47:31 EDT 2011
Previous message: [oslc-core] JSON representation rules - typo
Next message: [oslc-core] AUTO: Martin Nally/Raleigh/IBM is out of
the office until 06/26/2000. (returning 08/22/2011)
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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
More information about the Oslc-Core
mailing list