OSLC Core Specification - DRAFT

Overview

The Open Services for Lifecycle Collaboration (OSLC) initiative is creating a family of web services specifications for products, services and other tools that support all phases of the software and product lifecycle. Each part of the lifecycle or domain has it’s own work group and specification, for example there are Change Management, Quality Management, Estimation & Measurement and more. Each of the domain specifications are built upon this core specification.

This OSLC Core Specification sets out the common features that every OSLC Service can be expected to support using terminology from the World Wide Web Consortium (W3C). New terminology that we introduce can be found in the glossary section below. This specification is most about OSLC Services, it specifies what OSLC Services MUST, SHOULD and MAY do. It also contains some requirements for other OSLC specifications and for OSLC clients.

An OSLC Service is a resource that describes and links to other resources that enable a client to interact with the service. These resources are shown in the diagram below. An OSLC Service can have Resource Shapes that define the shape of resources managed by the service, Creation Resources for creating new resources in the service and a Query Resource that allows a client to navigate to any resource in the system.

OSLC Core Specification concepts and relationships

OSLC Resources are represented in a variety of formats. RDF/XML is required for all resources, but OSLC Services can also specify JSON, Turtle and Atom representations.

A word about RDF. The resource, property, value data model used for OSLC resources is based on Resource Description Framework (RDF) and OSLC requires RDF representations, but OSLC does not require implementors to provide an RDF triple-store or a SPARQL query-engine.

A word about Atom. Atom Publishing Protocol (APP) and Atom Syndication Format (ASF) formats are referenced in this document, but OSLC is not APP and OSLC implementations do not have to comply with APP.

Design considerations

The core philosophies of OSLC are to build on the powerful and scalable architecture of the World Wide Web and to do the simplest possible things that will work.

Build on the WWW. OSLC build on the architecture of the WWW and follows the REST architectural pattern. This means that OSLC services provide a uniform HTTP interface, OSLC URIs are stable and opaque and, in simple terms, OSLC works like the web.

Keep things simple. Doing the simplest things that will possibly work means a couple of different things in regard to OSLC. It means starting with simple and existing concepts. For example, we model everything as resources with property values. It means limiting the number of other specifications that we reference. Keeping things simple means building on established and well-known specifications, but also carefully limiting the number of other specifications that we reference. This simplicity is intended to make life easier for everybody: OSLC domain work groups, OSLC service implementers and OSLC client developers.

Accommodate different schemas. Because of the breadth of the OSLC domains, spanning lifecycle and platforms, OSLC has to work for systems with very different data schemas or no schemas at all. Flexibility is needed, but some OSLC Services must be able to offer resource shape information so that clients can learn what properties are allowed and required for resource creation, query and reporting.

Accommodate different representations. Different client platforms might require or at least prefer different representations. For example, in the browser a JSON or or Atom format representation might work best. OSLC Services will all support RDF/XML and may support other formats including JSON, Atom and Turtle.

Glossary of terms

This is a guide to some of the terminology used in this document. The following definitions are standard W3C concepts. OSLC uses these concepts without modification – their definitions are summarized here for the convenience of the reader. See http://www.w3c.org.

• Resource: A network data object or service that can be identified by a URI. Resources may be available in multiple representations (e.g. multiple languages, data formats, size, resolutions) or vary in other ways. (HTTP/1.1)

• Representation: An HTTP payload entity, included in an HTTP response, that is subject to content negotiation. There may exist multiple representations. associated with a particular HTTP response status. (HTTP/1.1)

• URI: Uniform Resource Identifiers are simply formatted strings which identify--via name, location, or any other characteristic -- a resource (HTTP/1.1)

Here are the OSLC specific terms used in this specification:

• OSLC Service: a set of resources that enable a web client to create, retrieve, update and delete resources managed by an Automated Lifecycle Management (ALM) product or online service offering.

• OSLC Resource: a resource that is managed by an OSLC Service, may have properties and may link to other resources including those provided by other OSLC Services.

• OSLC Defined Resource: a resource that is either defined by an OSLC specification, defined by an OSLC Resource Shape or both.

• OSLC Properties: OSLC properties describe the expected characteristics of the property values of OSLC resources. OSLC resources are not guaranteed to conform to the descriptions in OSLC Properties – the latter are only descriptions, Examples of characteristics described in OSLC Properties include their value types, allowed values, cardinality and optionality.

• OSLC Resource Shape: defines the set of OSLC Properties expected by a particular application or operation. Examples of such applications or operations include OSLC Creation Resource and Query Resource. Other examples might include applications that display data in tables.

• OSLC Creation Resource. a URI used to create new resources via HTTP POST. An OSLC Service may provide one or more Creation Resources,

• OSLC Query Resource: conceptually a query resource is a family of resources that all share the same base URI and each summarize a set of other resources that match a query criteria. A client performs a query by forming a query resource URI and getting the a representation of those 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.

OSLC Defined Resources

An OSLC Resource is a resource managed by an OSLC Service. An OSLC Resource is typically something like a Change Request, a Requirement or some other Collaborative / Automated Life-Cycle Management (C/ALM) artifact or record, but an OSLC Resource could also be a video or a presentation file. This resource could be stored in a relational database, a flat-file on disk or a source code control system.

An OSLC Service can manage any type of resource and of any content type, but OSLC also defines a special set of resources. OSLC Defined Resources are specified in this document and can be specified in any OSLC specification. Resources are defined by the properties that are allowed and required in the resource.

OSLC Specifications MUST provide the following information when defining an OSLC Defined Resource:

• QName
• Type URI
• List of properties allowed by resource and for each property:
  • QName
  • Data type
    • String
    • Number
    • Boolean
    • DateTime
    • URI
    • In-line Resource: Type of OSLC Defined Resource to be in-lined
  • Min occurs
  • Max occurs
  • Title
  • Description
• Types of OSLC Defined Resources that may be in-lined

In addition to properties, an OSLC Defined Resource can also in-line other OSLC Defined Resources. The term in-line indicates that one resource and its properties, or a subset, will be represented in-line in the outer resource.

URI Query Parameters

OSLC Services MAY support the following query parameters in OSLC Defined Resource URIs:

• oslc.properties - (optional) clients can add if this query parameter to the URI of an OSLC Resource to obtain the URI for a resource with a subset of the resource's properties. The value of this property must be a comma separated list of property names. This parameter may only be used once in a URI.

Resource Creation

To create a resource, an OSLC client HTTP POSTs a representation of that resource to a Creation Resource. See the section on Creation Resources.

Resource Removal

To delete a resource, a client performs an HTTP DELETE on the resource's URI. OSLC Services SHOULD support HTTP DELETE for removal of resources.

Resource Update

To update an OSLC Resource in an OSLC Service, a client fetches a representation of that resource via HTTP GET. The client updates the representation and then uses HTTP PUT to send he new representation to the resource's URI. OSLC Services SHOULD support HTTP PUT for update of resources. OSLC Services MAY use other techniques for resource update.

Unknown properties and content

OSLC Services are allowed to discard unknown content, but OSLC clients are not. When changing OSLC defined properties or other content in an OSLC Defined Resource, an OSLC client MUST preserve all other properties in that resource including those not defined in the relevant Resource Shape or OSLC specification.

Service Resources

OSLC services are available via a Service Resource which specifies the other resources that a client needs to interact with the service.

Conceptual Model

A Service Resource describes the resource's that enable a client to interact with an OSLC Service.

• QName: oslc:Service
• Type URI: http://open-services.net/xmlns/oslc#Service
• Properties:
  • creationResource (URI, multi-value) - a Service MAY have one or more creation resources.
  • queryResource (URI, single value) - a Service MAY have one or more query resources.
  • resourceShapeResource (URI, multi-value) - a Service MAY have one or more Resource Shape Resources.
  • A Service Resource MAY provide other property values.

Creation Resources

To create a new OSLC Resource, an OSLC client POSTs a representation of that resource to a Creation Resource URI.

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.

Creating an OSLC Defined Resource

Special rules apply when creating an OSLC defined resource.

To create an OSLC Defined Resource, an OSLC Client first forms an representation of that resource including the desired and required property values and following the rules set out in the OSLC Representation section below. A client can learn what properties are allowed in a new OSLC Defined Resource via the OSLC specification that defines or, in some cases via a Resource Shape resource. Next the client uses HTTP POST to post that representation to a 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 resource returned MAY contain changes to properties made by the server or new properties added by the server.

Unknown properties and content

An OSLC Service MAY discard property values in an OSLC Defined Resource that are not part of the resource's definition. Clients SHOULD assume that an OSLC Service will discard unknown property values unless the relevant Resource Shape's oslc:PreserveUnknown value is true.

Query Resources

An OSLC Service’s Query Resource provides a way for clients to navigate to all resources managed by the system.

Conceptual Model

Conceptually a Query Resource is member of family of resources that all share the same base Query Resource URI and each summarize a set of other resources that match a query criteria. To perform a query a client forms a query URI by adding query parameters to the Query Resource URI and then using HTTP GET to retrieve search results Query Resource.

Resource: Query

Each Query in the family represents a set of resources that meet query criteria encoded into its URI.

• QName: oslc:Query
• Type URI: http://open-services.net/xmlns/oslc#Query
• Properties:
  • rdf:type (URI): a Query Resource MUST include one rdf:type property with value of http://open-services.net/xmlns/oslc#Query and MAY include other instances of the rdf:type property with other values.
  • dc:title (String): a Query Resource SHOULD include a meaningful and non-empty title.
  • A Query MAY include other property values

In addition to properties, a Query resource also includes query results, a sequence of resources each with a URI and a subset of its own properties.

Forming a Query Resource URI

To find resources an OSLC client forms a Query Resource URI and then uses HTTP GET to retrieve properties of resources that match the criteria specified in the HTTP Query Parameters of the URI.

To form a Query Resource URI, a client combines the base Query Resource URI and adds query parameters that indicate the query criteria and optionally the properties desired in the results. You can find examples of Query Resource URIs below.

Query Parameters

TBD: merge in Query Syntax material here

Query Syntax

TBD: incorporate Query Syntax here

Resource Shape Resources

In some cases, to create resources and to query those that already exist within an OSLC Service, an OSLC client needs a way to learn which properties are commonly used in and/or required by the service. To meet this need, OSLC defines the notion of a Resource Shape Resource. OSLC Services MAY provide one or more Resource Shape Resources.

You can find the Resource Shapes for the resources defined in this document in the Appendix. An OSLC Specification SHOULD provide a Resource Shape resource for every resource it defines in RDF/XML and Turtle representation.

Conceptual Model

A Resource Shape is an OSLC Resource that defines one shape of OSLC Resource by listing the properties that are commonly used in and/or required in the shape.

Resource: Resource Shape

A Resource Shape Resource describes one type of resource.

• QName: oslc:ResourceShape
• Type URI: http://open-services.net/xmlns/oslc#ResourceShape
• Properties:
  • rdf:type (URI): a Resource Shape Resource MUST include one occurrence of this property with value http://open-services.net/xmlns/oslc#ResourceShape and MAY include other instances.
  • dc:title (String): a Resource Shape Resource SHOULD include a title
  • =oslc:PreserveUnknown (Boolean, optional, default is false): indicates whether unknown content is preserved in this shape.
  • oslc:Property (In-line Resource or URI): a Resource Shape SHOULD include one or more occurrences of oslc:Property.
  • A Resource Shape Resource MAY include other property values

Resource: Property

A Property describes one OSLC Property.

• QName: oslc:Property
• Type URI: http://open-services.net/xmlns/oslc#Property
• Properties
  • oslc:predicate (String) - a Property MUST include a predicate value, e.g. dc:title
  • dc:title (String): a Property SHOULD include a title
  • oslc:datatype (URI) - a Property MUST define one datatype. May be String, Integer, Number, Boolean, URI or a Resource type.
  • oslc:minOccurs (integer, optional, default 0) - minimum number of instances allowed
  • oslc:maxOccurs (integer, optional, default is no limit) - maximum number of instances allowed
  • oslc:allowedValue (String, optional, multiple allowed) - value allowed for property
  • oslc:defaultValue (String, optional) - default value for property
  • oslc:maxSize (integer, optional, default is no limit) - maximum length of string property in characters
  • oslc:readOnly (boolean, optional, default is false) - true if property is read-only.
  • A Property MAY include other property values.

Common Properties

These are common properties that are available for use in any OSLC Resource. Those who are defining new OSLC Services are strongly encouraged to use the common properties here rather than creating new properties.

Dublin Core Properties

TBD: complete this list of common DC OSLC properties

RDF Properties

TBD: complete this list of common RDF OSLC properties

OSLC Properties

TBD: complete this list of common OSLC properties

OSLC Defined Resource Representations

This section specifies how representations of OSLC Defined Resources are created. The rules in this section apply to all of the resources defined in this specification and all OSLC Services.

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 all OSLC Defined Resources and according to the rules below.

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

• Returned when these content types requested: application/rdf+xml
• Returned as content-type: application/rdf+xml
• 1.0 Open the root element using the resource's QName
  • 1.1 Declare XML namespaces used
  • 1.2 Add rdf:about attribute with resources URI, if it has one
• 2.0 If the resource has other properties then:
  • 2.2 For each property contained in the resource, write one XML element.
    • Use the property's QName as name of the XML element.
    • If the property value is a URI, then put the URI In the rdf:about attribute of the XML element
    • If the property value is not a URI then put its value inside the XML element
    • If the property value is an in-line resource then represent it as a resource with these rules
  • 2.3 Close the XML element
• 3.0 For each in-lined resource
  • 3.1 Represent the resource using these rules

Examples

OSLC Resource

For this example we will define a fictional OSLC Defined Resource called oslc:FooReport as follows:

• QName: oslc_foo:FooReport
• Type URI: http://open-services.net/xmlns/example-2.0#FooReport
• Properties
  • dc:title (String, required, max occurs=1)
  • oslc_fm:FooMeasurement (In-line oslc_fm:FooMeasurement, max occurs=no limit)

• QName: oslc_foo:FooMeasurement
• Type URI: http://open-services.net/xmlns/example-2.0#FooMeasurement
• Properties
  • dc:title (String, required)
  • dc:date (DateTime? , required)
  • oslc_foo:FooIndex (Number, required)

Here is how an oslc:FooReport would be represented:

<oslc:FooReport rdf:about="http://example.com/data/9D764F35AD1">
   <dc:title>Foo Report for development organization</dc:title>

   <oslc:FooMeasurement>
      <dc:title>Foo Measurement for Accounting System UI Module</dc:title>
      <oslc_foo:Index>34.55</oslc_foo:Index>
      <!-- other foo measurement properties here... -->
   </oslc:FooMeasurement>

   <oslc:FooMeasurement>
      <dc:title>Foo Measurement for Accounting System POS Module</dc:title>
      <oslc_foo:Index>28.41</oslc_foo:Index>
      <!-- other foo measurement properties here... -->
   </oslc:FooMeasurement>

   <oslc:FooMeasurement>
      <dc:title>Foo Measurement for Accounting System AX5 Module</dc:title>
      <oslc_foo:Index>30.08</oslc_foo:Index>
      <!-- other foo measurement properties here... -->
   </oslc:FooMeasurement>

</oslc:FooReport>

OSLC Service Resource

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

<oslc:Service 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... -->
</oslc:Service> 

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.

<oslc:Query 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... -->

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

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

   <oslc_foo:FooReport rdf:about="http://example.com/data/9D764F3534F">
      <dc:title>Remote Control Firmware Foo Measurement Report</dc:title>
      <!-- other properties here... -->
   </oslc_foo:FooReport>

</oslc:Query 

Turtle Representation

An OSLC Service MAY provide and understand Turtle representations of some OSLC Defined Resources and according to the rules below.

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

Rules for forming a Turtle representation

TBD

Examples

TBD

JSON Representation

An OSLC Service MAY provide and understand JSON representations of some OSLC Defined Resources and according to the rules below.

• Returned when these content types requested: application/json
• Returned as content-type: application/json

Rules for forming a JSON representation

TBD

• 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

Examples

TBD

Atom Representation

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

Rules for forming an Atom format representation

TBD

Examples

TBD

Authentication

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

HTTP Basic Authentication

TBD: OSLC Services MAY protect resources with HTTP Basic Authentication.

OSLC Services that use HTTP Basic Authentication SHOULD do so only via SSL.

OAuth Authentication

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.

Form Based Authentication

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 (?)

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.

oslc:Service

TBD

oslc:ResourceShape

TBD

oslc:Property

TBD

oslc:Query

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