CmJsonFormatV1 < Main

This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.

TWiki>

Main Web>CmHome>CmSpecificationV1>CmJsonFormatV1 (28 May 2009, TWikiAdminUser) (raw view)

<h1 id="titleL2-community">Change Management JSON Formats<br /></h1>

_1.0 SPECIFICATION_

%TOC%
---++ Purpose

This specification describes how the JSON format is used to represent OSLC resources and collection of resources.
---++ Notation and Conventions

The key words &ldquo;MUST&rdquo;, &ldquo;MUST NOT&rdquo;, &ldquo;REQUIRED&rdquo;, &ldquo;SHALL&rdquo;, &ldquo;SHALL NOT&rdquo;, &ldquo;SHOULD&rdquo;, &ldquo;SHOULD NOT&rdquo;, &ldquo;RECOMMENDED&rdquo;, &ldquo;MAY&rdquo;, and &ldquo;OPTIONAL&rdquo; in this document are to be interpreted as described in [[http://www.ietf.org/rfc/rfc2119.txt][RFC2119]]. Domain name examples use [[http://tools.ietf.org/html/rfc2606][RFC2606]].
---++ Introduction

[[http://json.org][JSON]] (!JavaScript Object Notation) is a lightweight data-interchange format. Since it is easy for humans to read and write and easy for machines to parse and generate, it is a popular alternative to XML.

This document specifies how the JSON format is used to represent OSLC resources and collection of resources.

---++ Overall Structure

In order to preserve JSON's simplicity and lightweightness, OSLC records are directly mapped into JSON dictionaries without introducing additional structural levels. This means that record attributes and record meta data live in the same dictionary, and are not separated into sub-dictionaries (which would result in deeper nesting). Multi valued attributes are represented as inlined JSON arrays which are not themselves resources.
---++ Attribute Names

The *attribute names* must correspond to the names defined in the vocabulary for the resource.

Since JSON does not provide a name space mechanism like XML, the following rules are used when transforming a resource attribute name into an JSON property name:

   * a resource attribute name (including its name space prefix) is used without modification as the json property name
   * all attribute name have to start with a namespace prefix
   * namespaces used in the OSLC specification are fixed. So it is not possible to use a prefix other than "dc" for the namespace "http://purl.org/dc/elements/1.1/"

Since resource attributes names may contain characters with special json semantics (e.g. '.'), the corresponding json property names can be used from javascript only with the associative array syntax record["dc:creator"] instead of a more conventional record.creator.

---++ Attribute Values

The *attribute values* must conform to the following rules:

   * Strings and numbers: their literals, e.g. =Test= or =352=
   * Booleans: =true= or =false=
   * Timestamps: a timestamp as a string in the [[http://rfc.net/rfc3339.html][RFC3339]] format, e.g. =2008-09-16T08:42:11.265Z=
   * Simple References: the path to the referenced resource.

References (or links) to other OSLC resources are represented as a JSON dictionary with these properties:
   * rdf:resource the path to the referenced resource,
   * oslc_cm:label an optional title of the reference. It can be used to render the reference in the UI without having to fetch additional information through the rdf:resource link.

If inlining was requested for a complex reference, the inlined attributes are directly added to the JSON dictionary.

Multi valued attributes are represented as JSON arrays.

The following example shows a single change request record has with two meta-data attributes, four attributes from the Dublin Core specification, and three other attributes (the severity, keywords and related attributes being multi-valued).

<verbatim>{
  "rdf:about": "http:\/\/localhost:9080\/records\/1234",
  "dc:title": "A short summary of the Change Request",
  "dc:description": "a longer description of this Change Request...",
  "dc:creator" {
    "rdf:resource": "http:\/\/localhost:9080\/users\/john_doe"
  },
  "dc:created": "2008-09-16T08:42:11.265Z",
  "severity": {
    "rdf:resource": "http:\/\/localhost:9080\/severities\/severity.high"
  },
  "keywords": [ "foo" , "bar" ],
  "related": [
    {
      "rdf:resource":  "http:\/\/localhost:9080\/records\/1",
      "oslc_cm:label": "comment for record 1"
    }
    {
      "rdf:resource":  "http:\/\/localhost:9080\/records\/2",
      "oslc_cm:label": "comment for record 2"
    }
    {
      "rdf:resource":  "http:\/\/localhost:9080\/records\/3",
      "oslc_cm:label": "comment for record 3"
    }
  ]
} </verbatim>

This [[%ATTACHURL%/workitem-1level.json.txt][example]] shows a real, non-inlined (RTC) change request in JSON format. Please note that attributes in the rtc_cm name space are not part of the OSLC specification.

For the second [[%ATTACHURL%/workitem-2levels.json.txt][example]] inlining was requested for all first level reference attributes by using the following parameter:

<pre>{GET URL}?oslc_cm.properties=*{*}</pre>

---++ Collections

Collections of resources like the result set returned from a query are represented as an JSON array of JSON dictionaries. To allow for the =oslc_cm:next= and =oslc_cm:previous= attribute links used in paged query result, the array is embedded in one additional JSON dictionary. There may also be a =oslc_cm:totalCount= attribute who's value is a positive integer that represents the total number of resources that are a result of the request.

This example shows the second page of a paged query result (page size == 3) where there is a total count of 27 :

<verbatim>{
  "oslc_cm:next": "http:\/\/localhost:9080\/results\/3",
  "oslc_cm:previous": "http:\/\/localhost:9080\/results\/1", 
  "oslc_cm:totalCount" : 27,
  "oslc_cm:results": [
    {
      "rdf:resource": "http:\/\/localhost:9080\/records\/1234"
    },
    {
      "rdf:resource": "http:\/\/localhost:9080\/records\/1235"
    },
    {
      "rdf:resource": "http:\/\/localhost:9080\/records\/1236"
    }   
  ]
}</verbatim>

This [[%ATTACHURL%/workitem-collection.json.txt][example]] shows a collection of change requests returned from the following paged query (note: this example is not URL-encoded):
<pre>{Simple Query URL}?oslc_cm.query=dc:title="Junit*"&oslc_cm.properties=dc:identifier,dc:title,dc:creator{dc:title}&oslc_cm.pageSize=2 </pre>

Attachments

Topic attachments
I	Attachment	Action	Size	Date	Who
txt	workitem-1level.json.txt	manage	4.3 K	25 May 2009 - 14:05	AndreWeinand
txt	workitem-2levels.json.txt	manage	15.4 K	25 May 2009 - 14:05	AndreWeinand
txt	workitem-collection.json.txt	manage	1.1 K	25 May 2009 - 14:05	AndreWeinand

Topic revision: r21 - 28 May 2009 - 17:19:55 - TWikiAdminUser

Main.CmJsonFormatV1 moved from Main.CmJsonFormat on 28 May 2009 - 14:14 by ScottBosworth - put it back

Main

Webs
Main
Sandbox
TWiki

Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback