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.
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 provides the following 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.
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 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. A Query resource can have the following properties:
-
rdf:type
(URI): a Query Resource MUST include one rdf:type property with value of http://open-services.net/xmlns/oslc/2.0#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 and provides these properties:
-
rdf:type
(URI): a Resource Shape Resource MUST include one occurrence of this property with value http://open-services.net/xmlns/oslc/2.0#ResourceShape and MAY include other instances. TBD: reference standard
-
dc:title
(String): a Resource Shape Resource SHOULD include a title
-
oslc:Property
(Resource or URI): a Resource Shape SHOULD include one or more occurrences of oslc:Property
.
- A Resource Shape Resource MAY include other property values
- =oslc:PreserveUnknown (Boolean, optional, default is false): indicates whether unknown content is preserved in this shape.
A Resource Shape
SHOULD contain Property Resources.
Resource: Property
A Property describes one OSLC Property and provides these 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
Predicate |
Data type |
Min occurs |
Max occurs |
Title |
Description |
dc:title |
String |
0 |
1 |
Title |
See Dublin Core |
dc:description |
String |
0 |
1 |
Description |
See Dublin Core |
dc:creator |
String |
0 |
Any |
Creator |
See Dublin Core |
dc:contributor |
String |
0 |
Any |
Contributor |
See Dublin Core |
dc:created |
DateTime? |
0 |
1 |
Created |
See Dublin Core |
dc:modified |
DateTime? |
0 |
1 |
Modified |
See Dublin Core |
RDF Properties
TBD: complete this list of common RDF OSLC properties
Predicate |
Data type |
Min occurs |
Max occurs |
Title |
Description |
rdf:type |
String |
1 |
Any |
Resource |
Type |
Resource type URI |
rdf:about |
URI |
0 |
1 |
About URI |
URI of resource |
OSLC Properties
TBD: complete this list of common OSLC properties
Predicate |
Data type |
Min occurs |
Max occurs |
Title |
Description |
oslc:context |
URI |
0 |
Any |
URI Context |
A context associated with the resource, e.g. a project. |
oslc:nextPage |
URI |
0 |
1 |
Next Page |
Next page of resource |
OSLC Defined Resource 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 Defined Resources. 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 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
- 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:
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
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
- 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 (?)
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