Creation Resources

A Creation Resource is used to create new OSLC Resources via HTTP POST.

• An HTTP POST of content to a Creation Resource URI MUST result in the creation of a new resource or an explanation of why creation did not occur via the appropriate HTTP status code.
• The response to a successful HTTP POST of content to a Creation Resource URI MUST include a HTTP Location header that specifies the URI of the newly created resource. TBD: do we need to state this, isn’t it just plain old HTTP?

Creating an OSLC Resource

To create an OSLC Resource, a client posts a resource representation to an creation resource URI.

• The response to a successful HTTP POST of a representation to a Creation Resource URI MAY include a representation of the newly created resource.
• The representation returned MAY contain changes to properties made by the server or new properties added by the server.

OSLC Representations

The conceptual model used in this specification is based on a simple model of resources and properties. This simple model allows for simple rules that can be used to generate representations for OSLC Resources. The rules in this section apply to all of the resources defined in this specification.

To encourage interoperability across OSLC domains and implementations, OSLC requires that services provide an RDF/XML representation. Services can also choose to provide additional representations: HTML, Turtle, JSON or Atom.

No new content-types

Note that existing standard content-types are used, e.g. application/rdf+xml in this document. The OSLC Core Specification does not introduce any new content-types and those who are defining new OSLC Services are strongly discouraged from introducing new content-types. OSLC Services MUST not define new content-types.

RDF/XML Representation

An OSLC Service MUST provide and accept RDF/XML representations of OSLC Resources.

RDF is very flexible and there are many ways that an OSLC Service could form valid RDF/XML representations. An OSLC Service should be able to store any resource, regardless of the content-type and the form of the RDF/XML representation. However, to enable inter-operation with standard XML processing tools, in two cases we must place some constraints on the way RDF/XML representations are formed:

• When an OSLC service creates an RDF/XML representation of a OSLC specified resource, the representation MUST comply with the rules below.
• When an OSLC client creates an RDF/XML representation of an OSLC specified resource for HTTP POST to an OSLC creation resource, the representation MUST comply with the rules below.

Rules for forming an RDF/XML representation of an OSLC Resource

• Returned when these content types requested: application/rdf+xml
• Returned as content-type: application/rdf+xml
• 1.0 Open the root <rdf:RDF> XML element
  • 1.1 Declare XML namespaces used

• 2.0 If the resource has properties then:
  • 2.1 Open XML element <rdf:Description>
  • 2.2 For each property contained in the resource, write one XML element.
    • Use the property name as namespace and name of the XML element.
    • If the property is of type URI, then put the URI In the rdf:about attribute of the XML element
    • If the property is not a URI then put its value inside the XML element
    • If the property is a string then escape the content
  • 2.3 Close with </rdf:Description>

• 3.0 If the resource includes other resources:
  • 3.1 If item is a Link Item
    • 3.2.1 Open XML element <rdf:Description> and put URI of item into the rdf:about attribute
    • 3.2.3 For each property contained in the item, write one XML element:
      • Use same rules as in 2.2
    • 3.2.4 Close with </rdf:Description>
  • 3.2 If item is a Value Item
    • 3.2.1 Open XML element using item name as element name
    • 3.2.3 For each property contained in the item, write one XML element:
      • Use same rules as in 2.2
    • 3.2.4 Close XML element of item
• 4.0 Close the root element with </rdf:RDF>

Examples

OSLC Resource

Heres’s an RDF-XML representation for a change request at URI http://example.com/data/9D764F35AD1

<rdf:RDF>
   <rdf:Description rdf:about="http://example.com/data/9D764F35AD1">
      <dc:title>Password protect the remote control panel</dc:title>
      <oslc:type>cm:ChangeRequest</oslc:type>
      <!-- other properties here... -->
   </rdf:Description>
</rdf:RDF>

OSLC Service Resource

Heres’s an RDF-XML representation for a service resource, showing how to represent a Service Resource with a Creation, Query and multiple resource shapes.

<rdf:RDF>
   <rdf:Description rdf:about="http://example.com/services">
      <dc:title>OSLC Service: Change Management</dc:title>
      <oslc:type>http://open-services.net/xmlns/</oslc:type>
      <oslc:creationResource>http://example.com/create-cr</oslc:creationResource>
      <oslc:queryResource>http://example.com/create-cr</oslc:queryResource>
      <oslc:resourceShapeResource>http://example.com/defectShape</oslc:resourceShapeResource>
      <oslc:resourceShapeResource>http://example.com/taskShape</oslc:resourceShapeResource>
      <oslc:resourceShapeResource>http://example.com/improvementShape</oslc:resourceShapeResource>
      <!-- other properties here... -->
   </rdf:Description>
</rdf:RDF>

OSLC Query Resource

Heres’s an RDF-XML representation for a query resource, showing how to represent a resource of type oslc:Query containing items of type oslc:QueryResult.

<rdf:RDF>
   <rdf:Description rdf:about="http://example.com/query?oslc%3Aquery=remote">
      <dc:title>Query results for term 'remote'</dc:title>
      <rdf:type>oslc:Query</oslc:type>
      <oslc:nextPage>http://example.com/query?oslc%3Aquery=remote&page=2</oslc:nextPage>
      <!-- other properties here... -->
   </rdf:Description>

   <rdf:Description rdf:about="http://example.com/data/9D764F35AD1">
      <dc:title>Password protect the remote control panel</dc:title>
      <rdf:type>cm:ChangeRequest</oslc:type>
      <!-- other properties here... -->
   </rdf:Description>

   <rdf:Description rdf:about="http://example.com/data/9D764F35777">
      <dc:title>Build a remote control panel</dc:title>
      <oslc:type>cm:Requirement</oslc:type>
      <!-- other properties here... -->
   </rdf:Description>

   <rdf:Description rdf:about="http://example.com/data/9D764F3534F">
      <dc:title>Remote Control Firmware</dc:title>
      <rdf:type>cm:Asset</oslc:type>
      <!-- other properties here... -->
   </rdf:Description>
</rdf:RDF>

Turtle Representation

An OSLC Service MAY provide and understand Turtle representations of some OSLC Resources.

TBD: rules for generating a Turtle representation

• Returned when these content types requested: application/x-turtle

• Returned as content-type: application/x-turtle

Properties

TBD: How properties are represented

Query resources and paging

TBD: How lists of query results, each with properties, are represented and made pageable

JSON Representation

An OSLC Service MAY provide and understand JSON representations of some OSLC Resources.

• Returned when these content types requested: application/json

• Returned as content-type: application/json

TBD: rules for generating a JSON representation

• 1.0 Create JSON Object

• 2.0 If resource has properties then add JSON pair named ‘description’ with a JSON Array value:
  • 2.1 For each property add JSON Object to array with
    • Add field ‘name’ : set to property name,
    • Add field ‘value’ : set to property value

• 3.0 If the resource has a list of items then add JSON field named ‘items’ of type JSON Array
  • 3.1 For each item in the list add a JSON Object to the array and to that object:
    • Add field ‘description’ of type JSON Array
    • For each property of the item add JSON Object to array
    • Add field ‘name’ and set to property name
    • Add field ‘value’ and set to property value

Atom Representation

An OSLC Service MAY provide and understand Atom representations of some OSLC Resources.

Properties

TBD: How properties are represented, how to represent OSLC Resource as Atom Entry etc.

Query resources and paging

TBD: How list of query results, each with properties, are represented and made pageable. How to represent query results as Atom Feed, using Atom Entry defined above for each item.

Service Resource Representation

TBD: How to represent a Service Resource as an Atom Publishing Protocol (APP) Service Document.

Authentication

OSLC Services use standard web protocols for authentication, these are the options allowed:

TBD: OSLC Services MAY protect resources with HTTP Basic Authentication. OSLC Services that use HTTP Basic Authentication SHOULD do so only via SSL.

TBD: OSLC Services MAY protected resources with OAuth Authentication. OSLC Services that use HTTP Basic Authentication SHOULD provide Two-legged OAuth Authentication as an option.

TBD: OSLC Services MAY protected resources with Form Based Authentication. Services that use Form Based Authentication MUST implement Form Based Authentication as specified below in OSLC Form Based Authentication.

OSLC Form Based Authentication

TBD: specify how form based authentication works, because it is non-standard (?)

How to use the OSLC Core Specification

This sections describes how to use the OSLC Core Specification from two points of view. The OSLC Work Group point of view explains to work-group members how to create OSLC specifications for new domains by building on the core. The consumer point of view explains to those writing client code that uses an OSLC Service how to use the Core specification.

Guidelines for OSLC Work Groups

TBD

Guidelines for consumers of OSLC specifications

TBD

Appendix: Resource Shapes

This section provides Resource Shapes for each of the OSLC Defined Resources in the this document.

Each is provided in RDF/XML and Turtle representations.

Query Resource

TBD

Service Resource

TBD

References

TBD: clean this up and refer to specifications that we actually reference in this document

• Hyper-text Transfer Protocol (HTTP/1.1)
• URI Generic Syntax
• RDF / XML Syntax Specification (Revised)
• Resource Definition Framework (RDF) Concepts and Abstract Syntax
• Atom Publishing Protocol
• Atom Syndication Format