Change Management JSON Formats

1.0 SPECIFICATION

Purpose

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

Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

Introduction

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

{
  "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"
    }
  ]
} 

This 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 example inlining was requested for all first level reference attributes by using the following parameter:

{GET URL}?oslc_cm.properties=*{*}

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 :

{
  "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"
    }   
  ]
}

This example shows a collection of change requests returned from the following paged query (note: this example is not URL-encoded):

{Simple Query URL}?oslc_cm.query=dc:title="Junit*"&oslc_cm.properties=dc:identifier,dc:title,dc:creator{dc:title}&oslc_cm.pageSize=2