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>RmHome>RmSpecificationV2>RmSpecificationV2r20110930 (22 Sep 2011, IanGreen)
OSLC_logo.png

Open Services for Lifecycle Collaboration
Requirements Management Specification Version 2.0

Status: DRAFT 2.0 R2 Specification - XX XXXX XXXX

This Version

Latest Version PreviousVersion Authors Contributors

Table of Contents

License

88x31.png
This work is licensed under a Creative Commons Attribution License.

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

This family of documents defines the Open Services for Lifecycle Collaboration Requirements Management and Definition specification, also known as OSLC RM. These documents collectively define the OSLC RM 2.0 specification, which is part of the OSLC group of specifications. This specification supports key REST APIs for software Requirements Management systems. OSLC RM 2.0 takes an open, loosely coupled approach to specific lifecycle integration scenarios. The scenarios and this V2.0 specification were created by the OSLC RM Working Group. More information on the principles underlying OSLC and RM in particular can be found on the main OSLC site and the home page of the RM topic.

(this section is informative)

This specification builds on the Open Services for Lifecycle Collaboration (OSLC) Core v2.0 Specification to define the resources, properties and operations supported by an OSLC Requirements Definition and Management (OSLC-RM) provider.

Requirements Management resources include Requirements, Requirements Collections and supporting resources defined in the OSLC Core specification. The properties defined describe these resources and the relationships between resources. Operations are defined in terms of HTTP methods and MIME type handling. The resources, properties and operations defined do not form a comprehensive interface to Requirements Definition and Management, but instead target specific integration use cases documented by the OSLC-RM workgroup.

Terminology

Requirement Resource - Requirements are the basis for defining what the system stakeholders (users, customers, suppliers and so on) need from a system and also what the system must do in order to meet those needs, and how the surrounding processes must be orchestrated so that quality, scope and timescale objectives are satisfied.

RequirementCollection Resource - A collection of resources which constitute some statement of need.

Service Provider - an implementation of the OSLC Requirements Management specification.

Service Consumer/OSLC Consumer/Client - an implementation of an HTTP client which consumes resource models provided by a service provider.

Base Requirements

Compliance

This specification is based on OSLC Core Specification Version 2.0. OSLC RM consumers and service providers MUST be compliant with both the core specification and this RM specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

The following table summarizes the requirements from OSLC Core Specification as well as some additional ones specific to RM. Note that this specification further restricts some of the requirements for OSLC Core Specification. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

Requirement Level Meaning
Unknown properties and content MAY / MUST OSLC services MAY ignore unknown content and OSLC clients MUST preserve unknown content
Resource Operations MUST OSLC service MUST support resource operations via standard HTTP operations
Resource Paging MAY OSLC services MAY provide paging for resources but only when specifically requested by service consumer
Partial Resource Representations MUST / MAY OSLC services MUST support request for a subset of a resource's properties via the oslc.properties URL parameter retrieval via HTTP GET and MAY support via HTTP PUT
Partial Update MAY OSLC services MAY support partial update of resources using patch semantics
Service Provider Resources MAY / MUST OSLC service providers MAY provide a Service Provider Catalog and MUST provide a Service Provider resource
Creation Factories MUST / MAY OSLC service providers MUST provide at least one creation factory resource for requirements and MAY provide creation factory resources for requirement collections
Query Capabilities MUST OSLC service providers MUST provide query capabilities to enable clients to query for resources
Query Syntax MUST OSLC query capabilities MUST support the OSLC Core Query Syntax
Delegated UI Dialogs MUST OSLC Services MUST offer delegated UI dialogs (for both creation and selection) specified via service provider resource
UI Preview SHOULD OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources
HTTP Basic Authentication MAY OSLC Services MAY support Basic Authentication and SHOULD only do so only over HTTPS
OAuth Authentication MAY OSLC Services MAY support OAuth and MAY indicate the required OAuth URLs via the service provider resource
Error Responses MAY OSLC Services MAY provide error responses using Core defined error formats
RDF/XML Representations MUST OSLC services MUST support RDF/XML representations for OSLC Defined Resources
XML Representations MUST OSLC services MUST support XML representations that conform to the OSLC Core Guidelines for XML
JSON Representations MAY / MUST OSLC services MAY support JSON representations; those which do MUST conform to the OSLC Core Guidelines for JSON
HTML Representations MAY OSLC services MAY provide HTML representations for GET requests

Specification Versioning

See Core Specification Version 2.0 - Specification Versioning.

Service providers that support the resource formats and services in this specification MUST add an HTTP response header of OSLC-Core-Version with a value of 2.0. Consumers SHOULD request formats and services defined in this document by providing a HTTP request header of OSLC-Core-Version with a value of 2.0. See section below on Version Compatibility with OSLC RM 1.0 Specifications.

This specification reserves, for possible future use, the use of the HTTP header OSLC-RM-Version. OSLC Providers MUST NOT use this HTTP header.

Namespaces

In addition to the namespace URIs and namespace prefixes oslc, rdf, dcterms and foaf defined in the Core Specification Version 2.0, OSLC RM defines the namespace URI of http://open-services.net/ns/rm# with a preferred namespace prefix of oslc_rm.

Resource Formats

In addition to the requirements for Core Specification Version 2.0 - OSLC Defined Resource Representations, this section outlines further refinements and restrictions.

For HTTP GET/PUT/POST requests on all OSLC RM and OSLC Core defined resource types,

Additionally, for HTTP GET,

For HTTP GET response formats for Query requests,

  • RM Providers MUST support RDF/XML representations with meda-type application/rdf+xml.
  • RM Providers MUST support XML representations with media-type application/xml.
  • RM Providers MAY support JSON representations with media-type application/json.

OSLC Providers MAY refuse to accept RDF/XML documents which do not have a top-level rdf:RDF document element. The OSLC Core describes an example, non-normative algorithm for generating RDF/XML representations of OSLC Defined Resources.

In addition to the resource formats defined above, providers MAY support additional resource formats; the meaning and usage of these resource formats is not defined by this specification.


Authentication

See Core Specification Version 2.0 - Authentication. OSLC RM places no additional constraints on authentication.

Error Responses

See Core Specification Version 2.0 - Error Responses. OSLC RM places no additional constraints on error responses.

Pagination

OSLC RM service providers SHOULD support pagination of query results as defined by the OSLC Core Specification. OSLC RM service providers MAY support pagination of a single resource's properties as defined by the OSLC Core Specification.

Requesting and Updating Properties

Requesting Selected Properties

A client may want to request a subset of a resource's properties as well as properties from a referenced resource. In order to support this behaviour a service provider MUST support the oslc.properties and oslc.prefix URL parameter on a HTTP GET request on individual resource request or a collection of resources by query. If the oslc.properties parameter is omitted on the request, or if the value of this parameter is "*", then all resource properties MUST be provided in the response. See OSLC Core Specification - Selective Property Values.

Updating Selected Properties

A provide MAY accept oslc.properties on a PUT with the meaning that only that subset of the resource's properties be updated.

If the parameter oslc.properties contains a valid resource property on the request that is not provided in the content, the server MUST treat that as a request to remove that property from the resource. If the parameter oslc.properties contains an invalid resource property, then a 409 Conflict MUST be returned.

RM Resource Definitions

Property value types that are not defined in the following sections, are defined in Core Specification Version 2.0 - Defining OSLC Properties.

The meaning of the columns in the following table is defined as follows. See also OSLC Core Specification Appendix A: Common Properties for further details on Resource Shapes.

  • Occurs: The multiplicity of the property (corresponds to "oslc:occurs" on an "oslc:Property" resource).
  • Read-only: Whether the Provider will accept value changes (corresponds to "oslc:readOnly" on an "oslc:Property" resource). "Unspecified" indicates that this specification places no requirements on a Provider's behaviour in this regard.
  • Value-type: Corresponds to "oslc:valueType" on an "oslc:Property" resource.
  • Representation: Corresponds to "oslc:representation" on an "oslc:Property" resource.
  • Range: Corresponds to "oslc:range" on an "oslc:Property" resource. "Any" indicates that this specification places no "oslc:range" constrains on a property. Consumers in particular should not make assumptions about the range of such properties.
  • Description: A textual description of the meaning of the property.

Resource Requirement

The meaning of Requirement resource properties are defined in the tables below, together with their multiplicity constraints. Requirement resource properties are not limited to the ones defined in this specification, service providers may provide additional properties. It is strongly recommended that any additional properties be defined in XML namespaces distinct from those defined by OSLC in these specifications. Requirement creation through a Creation Factory resource in the Service Description is REQUIRED by this specification.

Any resource asserted to be of rdf:type http://open-services.net/ns/rm#Requirement MUST conform to the constraints and meaning of properties defined below. Notice that partial representations of a requirement resource are admitted by this specification (for example, in query results, or where oslc.properties has been used), and such partial representations will in general not conform to these constraints.

  • Name: Requirement
  • Type URI http://open-services.net/ns/rm#Requirement

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
dcterms:title exactly-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content. SHOULD include only content that is valid inside an XHTML <span> element.
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element.
dcterms:identifier zero-or-one True String n/a n/a An identifier for a resource. This identifier may be unique with a scope that is defined by the RM provider. Assigned by the service provider when a resource is created. Not intended for end-user display.
oslc:shortTitle zero-or-one unspecified XMLLiteral n/a n/a Short name identifying a resource, often used as an abbreviated identifier for presentation to end-users. SHOULD include only content that is valid inside an XHTML <span> element.
dcterms:subject zero-or-many False String n/a n/a Tag or keyword for a resource. Each occurrence of a dcterms:subject property denotes an additional tag for the resource.
dcterms:creator zero-or-many unspecified Resource or Local Resource Either Reference or Inline any Creator(s) of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:contributor zero-or-many unspecified Resource or Local Resource Either Reference or Inline any Contributor(s) to resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core).
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp last latest resource modification (reference: Dublin Core).
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs.
oslc:serviceProvider zero-or-many unspecified Resource Reference oslc:ServiceProvider The scope of a resource is a URI for the resource's OSLC Service Provider.
oslc:instanceShape zero-or-one unspecified Resource Reference oslc:ResourceShape Resource Shape that provides hints as to resource property value-types and allowed values.
Prefixed Name Occurs Read-only Value-type Represen-tation Range Description
Relationship properties: This grouping of properties are used to identify relationships between resources managed by other OSLC Service Providers
oslc_rm:elaboratedBy zero-or-many False Resource Reference any Resource, such as a model element, which elaborates this requirement.
oslc_rm:elaborates zero-or-many False Resource Reference any Resource, such as a requirement, which is elaborated by this requirement.
oslc_rm:specifiedBy zero-or-many False Resource Reference any Resource, such as a model element, which specifies this requirement.
oslc_rm:specifies zero-or-many False Resource Reference any Resource, such as a requirement, which is specified by this requirement.
oslc_rm:affectedBy zero-or-many False Resource Reference any Requirement is affected by a resource, such as a defect or issue.
oslc_rm:trackedBy zero-or-many False Resource Reference any Resource, such as a change request, which track this requirement.
oslc_rm:implementedBy zero-or-many False Resource Reference any Resource, such as a change request, which implements this requirement.
oslc_rm:validatedBy zero-or-many False Resource Reference any Resource, such as a test case, which validates this requirement.

Resource RequirementCollection

The meaning of RequirementCollection resource properties are defined in the tables below, together with their multiplicity constraints. RequirementCollection resource properties are not limited to the ones defined in this specification, service providers may provide additional properties. It is strongly recommended that any additional properties be defined in XML namespaces distinct from those defined by OSLC in these specifications. RequirementCollection creation through a Creation Factory resource in the Service Description is OPTIONAL in this specification.

Any resource asserted to be of rdf:type http://open-services.net/ns/rm#RequirementCollection MUST conform to the constraints and meaning of properties defined below. Notice that partial representations of a requirement collection resource are admitted by this specification (for example, in query results, or where oslc.properties has been used), and such partial representations will in general not conform to these constraints.

  • Name: RequirementCollection
  • Type URI http://open-services.net/ns/rm#RequirementCollection

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
dcterms:title exactly-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content. SHOULD include only content that is valid inside an XHTML <span> element.
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element.
dcterms:identifier zero-or-one True String n/a n/a An identifier for a resource. This identifier may be unique with a scope that is defined by the RM provider. Assigned by the service provider when a resource is created. Not intended for end-user display.
oslc:shortTitle zero-or-one unspecified XMLLiteral n/a n/a Short name identifying a resource, often used as an abbreviated identifier for presentation to end-users. SHOULD include only content that is valid inside an XHTML <span> element.
dcterms:subject zero-or-many False String n/a n/a Tag or keyword for a resource. Each occurrence of a dcterms:subject property denotes an additional tag for the resource.
dcterms:creator zero-or-many unspecified Resource or Local Resource Either Reference or Inline any Creator(s) of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:contributor zero-or-many unspecified Resource or Local Resource Either Reference or Inline any Creator(s) of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core).
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp last latest resource modification (reference: Dublin Core).
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs.
oslc:serviceProvider zero-or-many unspecified Resource Reference oslc:ServiceProvider The scope of a resource is a URI for the resource's OSLC Service Provider.
oslc:instanceShape zero-or-one unspecified Resource Reference oslc:ResourceShape Resource Shape that provides hints as to resource property value-types and allowed values.
Prefixed Name Occurs Read-only Value-type Represen-tation Range Description
OSLC RM: Start of additional properties
oslc_rm:uses zero-or-many unspecified Resource Reference any A collection uses a resource - the resource is in the requirement collection.
Prefixed Name Occurs Read-only Value-type Represen-tation Range Description
Relationship properties: This grouping of properties are used to identify relationships between resources managed by other OSLC Service Providers
oslc_rm:elaboratedBy zero-or-many False Resource Reference any Resource which elaborates this requirement collection.
oslc_rm:elaborates zero-or-many False Resource Reference any Resource which is elaborated by this requirement collection.
oslc_rm:specifiedBy zero-or-many False Resource Reference any Resource which specifies this requirement collection.
oslc_rm:specifies zero-or-many False Resource Reference any Resource which is specified by this requirement collection.
oslc_rm:affectedBy zero-or-many False Resource Reference any Requirement Collection is affected by resource, for example, a defect or issue.
oslc_rm:trackedBy zero-or-many False Resource Reference any Resource, such as a change request, which manages this requirement collection.
oslc_rm:implementedBy zero-or-many False Resource Reference any Resource, such as a change request, which implements this requirement collection.
oslc_rm:validatedBy zero-or-many False Resource Reference any Resource, such as a test plan, which which validates this requirement collection.

RM Relationship Properties

RM providers MUST accept relationship properties, as described in OSLC Core Link Guidance. The following relationship properties are defined by this specification:

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
dcterms:title zero-or-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) of the link represented as rich text in XHTML content. SHOULD include only content that is valid inside an XHTML <span> element.
dcterms:creator zero-or-many unspecified Resource or Local Resource Either Reference or Inline any Creator(s) of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:contributor zero-or-many unspecified Resource or Local Resource Either Reference or Inline any Creator(s) of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of link creation (reference: Dublin Core).
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp last latest link modification (reference: Dublin Core).

Relationship labels

When an RM relationship property is to be presented in a user interface, it may be helpful to provide an informative and useful textual label for that relationship instance. (This in addition to the relationship property URI and the object resource URI, which are also candidates for presentation to a user.) To this end, OSLC providers MAY suppport a dcterms:title link property in RM resource representations where a relationship property is permitted, using the anchor approach outlined in the OSLC Core Links Guidance.

Providers and consumers should be aware that the dcterms:title of a link is unrelated to the dcterms:title of the object resource. Indeed, links may carry other properties with names in common to the object of the link, but there is no specified relationship between these property values.

RM Service Provider Capabilities

Service Provider Resources

Service providers MUST provide one or more oslc:ServiceProvider resources as defined by Core Specification Version 2.0 - Service Provider Resource. Discovery of OSLC Service Provider Resources MAY be via one or more OSLC Service Provider Catalog Resources, or may be discovered by some other and/or additional Provider-specific means outwith the scope of this specification. The oslc:Service resources referenced by this oslc:ServiceProvider MUST have an oslc:domain of http://open-services.net/ns/rm#.

Service providers MAY provide one more more oslc:ServiceProviderCatalog resources as defined by Core Specification Version 2.0 - Service Provider Resources. Any such catalog resources MUST include at least one oslc:domain of http://open-services.net/ns/rm#. Discovery of top-level OSLC Service Provider Catalog Resources is outwith the scope of this specification.

Service providers MUST give an oslc:serviceProvider property on all OSLC Defined Resources. This property MUST refer to an appropriate oslc:ServiceProvider resource.

Creation Factories

Service providers supporting resource creation MUST do so through oslc:CreationFactory resources, as defined by Core Specification Version 2.0 - Creation Factories. Any such factory resources MUST be discoverable through oslc:Service resources. Providers SHOULD provide oslc:ResourceShape resources on oslc:CreationFactory resources as defined by OSLC Core Specification Appendix A: Common Properties - Resource Shapes.

Query Capabilities

Service providers MUST support query capabilities, as defined by Core Specification Version 2.0 - Query Capabilities. Providers SHOULD provide oslc:ResourceShape on oslc:QueryCapability resources as defined by OSLC Core Specification Appendix A: Common Properties - Resource Shapes.

The Query Capability MUST support these parameters:

  • oslc.where
  • oslc.select
  • oslc.properties
  • oslc.prefix

Where oslc:ResourceShape is not supported by the Query Capability, providers SHOULD use the following guidance to represent query results:

The stability of query results is OPTIONAL (see Core Specification Version 2.0 - Stable Paging).

Delegated UIs

OSLC RM service providers MUST support the selection and creation of resources by delegated web-based user interface dialogs Delegated UIs as defined by OSLC Core.

OSLC RM service providers MAY support the pre-filling of creation dialogs based on the definition at Delegated UIs.

Usage Identifiers

OSLC RM service provider MAY identify the usage of various services with additional property values for the OSLC Core defined oslc:usage property on oslc:Dialog, CreationFactory and QueryCapability. The oslc:usage property value of http://open-services.net/ns/core#default SHOULD be used to designate the default or primary service to be used by consumers when multiple entries are found.

There are no additional usage identifiers defined by this specification. OSLC Providers MAY provide their own usage URIs. Such usage URIs MUST be in a non-OSLC namespace.

Version Compatibility with 1.0 Specifications

The goal is to provide a smooth transition to 2.0 for both Consumers and Providers. This section will clarify the usage of 1.0 media types so that Providers can support both 1.0 and 2.0 Consumers when HTTP requests are made for a resource with the same URI.

Network addressable resource URIs used for 1.0 resources for these types: Requirement, RequirementCollection, ServiceDescriptor and ServiceProviderCatalog, should not have to change. Consumers who support both 1.0 and 2.0, should only preserve these resource URIs. When a Provider starts to serve 2.0 resource formats, for instance the ServiceProvider resource, it is recommended to update its locally stored or cached information about the contents of the ServiceProvider resource as the URIs to various capabilities may have changed (query, delegated UIs, factories, etc.).

Media Types

To identify a format of RDF/XML, the media type used for RM resource representations MUST be application/rdf+xml. The usage of the OSLC RM 1.0 defined media types of application/x-oslc-rm-requirement-1.0+xml, application/x-oslc-rm-requirement-collection-1.0+xml, application/x-oslc-rm-service-description-1.0+xml and application/x-oslc-disc-service-provider-catalog+xml is deprecated.

Requesting formats

RM 1.0 consumers wanting to request 1.0 resource formats will not need to change if they used 1.0 defined media types ( application/x-oslc-rm*), see OSLC-RM 1.0. RM 2.0 consumers should use media types as defined in this specification for requests, excluding the OSLC RM 1.0 specific media types ( application/x-oslc-rm*). RM consumers supporting both 1.0 and 2.0, should request request both 1.0 and 2.0 media types on HTTP GET requests as usually done with HTTP request parameter Accept giving appropriate quality (See HTTP Accept) weighting to help distinguish their preferred content.

For additional guidance, a RM 2.0 consumer or provider MAY reference the OSLC-Core-Version HTTP header with a value of 2.0.

Appendix A: Samples

See RmSpecificationV2Samples

Appendix B: Resource Shapes

See RmSpecificationV2Shapes

Appendix C: Notices and References

Contributors

Reporting Issues on the Specification

The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Requirements Management Mailing List

Known issues and resolutions relating to this specification may be found at RmSpecificationV2Issues.

Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant for implementations of the this, the RM 2.0 Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found here.

References

Edit | Attach | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 22 Sep 2011 - 16:43:55 - IanGreen
Main.RmSpecificationV2r20110930 moved from Main.RmSpecificationV2r2 on 22 Sep 2011 - 16:43 by IanGreen - put it back
 
This site is powered by the TWiki collaboration platform 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