This specification defines the OSLC Requirements Management domain. The specification supports key RESTful web service interfaces for the management of Requirements, Requirements Collections and supporting resources defined in the OSLC Core specification. To support these scenarios, this specification defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, content type handling and resource formats.

Introduction

This specification defines the OSLC Requirements Management domain, also known as OSLC RM. The specification supports key RESTful web service interfaces for software Requirements Management systems. OSLC takes an open, loosely coupled approach to specific lifecycle integration scenarios. The scenarios and this specification were created by the OASIS OSLC OP TSC.

This specification builds on the Open Services for Lifecycle Collaboration Core Specification [[!OSLCCore3]] to define the resources, properties and operations supported by an OSLC Requirements Definition and Management (OSLC-RM) server.

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 OASIS OSLC OP.

Terminology

Terminology uses and extends the terminology and capabilities of [[!OSLCCore3]].

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.
Client
An implementation of the OSLC Requirement Management specifications as a client. OSLC RM Clients consume services provided by servers.
Server
An implementation of the OSLC Requirement Management specifications as a server. OSLC RM clients consume services provided by Servers. The use of the terms Client and Server are intended to distinguish typical consumers and providers of OSLC resources in a distributed environment based on REST. A particular application component could be a client for some OSLC domain services and a server for the same or another domain.

References

Base Requirements

The following sub-sections define the mandatory and optional requirements for an OSLC Requirements Management (OSLC RM) server.

Base Requirements

This specification is based on [[!OSLCCore3]]. OSLC RM servers MUST be compliant with both the core specification, MUST follow all the mandatory requirements in the normative sections of this specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

An OSLC RM server MUST implement the domain vocabulary defined in OSLC Requirements Management Version 2.1. Part 2: Vocabulary

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

Requirement Meaning
Unknown properties and content OSLC servers MAY ignore unknown content and OSLC clients MUST preserve unknown content
Resource Operations OSLC servers MUST support resource operations via standard HTTP operations
Resource Paging OSLC servers MAY provide paging for resources but only when specifically requested by client
Partial Resource Representations OSLC servers 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 OSLC servers MAY support partial update of resources using [[LDPPatch]].
Discovery OSLC servers MAY provide a Service Provider Catalog, MUST provide a Service Provider resource, and MAY provide other forms of discovery described in Core 3.0 Discovery.
Creation Factories OSLC servers MUST provide at least one creation factory resource for requirements and MAY provide creation factory resources for requirement collections
Query Capabilities OSLC servers MUST provide query capabilities to enable clients to query for resources
Query Syntax OSLC query capabilities MUST support the OSLC Core Query Syntax
Delegated UI Dialogs OSLC Services MUST offer delegated UI dialogs (for both creation and selection) specified via service provider resource
UI Preview OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources
HTTP Basic Authentication OSLC Servers MAY support Basic Authentication and SHOULD only do so only over HTTPS
OAuth Authentication OSLC Server MAY support OAuth and MAY indicate the required OAuth URLs via the service provider resource
Error Responses OSLC Servers MAY provide error responses using Core defined error formats
RDF/XML Representations OSLC servers MUST support RDF/XML representations for OSLC Defined Resources
XML Representations OSLC servers MUST support XML representations that conform to the OSLC Core Guidelines for XML
JSON Representations OSLC servers MAY support JSON representations; those which do MUST conform to the OSLC Core Guidelines for JSON
HTML Representations OSLC servers MAY provide HTML representations for GET requests

Specification Versioning

This specification follows the specification version guidelines given in [[!OSLCCore3]].

Namespaces

In addition to the namespace URIs and namespace prefixes oslc, rdf, dcterms and foaf defined in the [[!OSLCCore3]], 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 resource representations in [[!OSLCCore3]], this section outlines further refinements and restrictions.

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

  • RM Servers MUST support RDF/XML representations with media-type application/rdf+xml. RM Clients MUST be prepared to deal with any valid RDF/XML document.
  • RM Servers MUST support XML representations with media-type application/xml. The XML representations MUST follow the guidelines outlined in the OSLC Core Representations Guidance to maintain compatibility with [[!OSLCCore2]].
  • RM Servers MAY support JSON representations with media-type application/json. The JSON representations MUST follow the guidelines outlined in the OSLC Core Representations Guidance to maintain compatibility with [[!OSLCCore2]].

Additionally, for HTTP GET,

For HTTP GET response formats for Query requests,

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

OSLC Servers 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, Servers MAY support additional resource formats; the meaning and usage of these resource formats is not defined by this specification.

Authentication

[[!OSLCCore3]] specifies the recommended OSLC authentication mechanisms. In addition to the OSLC Core authentication requirements, OSLC RM servers SHOULD support [[!OpenIDConnect]].

Error Responses

[[!OSLCCoreVocab]] specifies the OSLC Core error responses. OSLC RM puts no additional constraints on error responses.

Pagination

OSLC RM servers SHOULD support pagination of query results and MAY support pagination of a single resource's properties as defined by [[!OSLCCore3]].

Requesting and Updating Properties

Requesting a Subset of Properties

A client MAY request a subset of a resource's properties as well as properties from a referenced resource. In order to support this behavior a server 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, then all resource properties MUST be provided in the response.

Updating a Subset of Properties

A client MAY request that a subset of a resource's properties be updated by using the [[LDPPatch]] PATCH method.

For compatibility with [[!OSLCCore2]], a Server MAY also support partial update by identifying those properties to be modified using the oslc.properties URL parameter on a HTTP PUT request.

If the parameter oslc.properties contains a valid resource property on the request that is not provided in the content, the server MUST set the resource's property to a null or empty value. If the parameter oslc.properties contains an invalid resource property, then a 409 Conflict MUST be returned.

Updating Multi-Valued Properties

For multi-valued properties that contain a large number of values, it may be difficult and inefficient to add or remove property values. OSLC RM servers MAY provide support for a partial update of the multi-valued properties as defined by draft specification [[LDPPatch]]. RM servers MAY also support partial updates through HTTP PUT where only the updated properties are included in the entity request body.

Labels for Relationships

Requirement Management relationships to other resources are represented by RDF properties. Instances of a relationship - often called links - are RDF triples with a subject URI, a predicate that is the property, and a value (or object) that is the URI of target resource. When a link is to be presented in a user interface, it may be helpful to display an informative and useful textual label instead of, or in addition to, the URI of the predicate and/or object. There are three items that clients could display:

Turtle example using a reified statement:

@prefix oslc_rm: <http://open-services.net/ns/rm#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .

<http://example.com/requ/4321>
  a <http://open-services.net/ns/rm#Requirement> ;
  oslc_rm:elaboratedBy <http://anotherexample.com/requ/123> .

<http://njh.me/#link1>
  a rdf:Statement ;
  rdf:subject <http://example.com/requ/4321> ;
  rdf:predicate oslc_rm:elaboratedBy ;
  rdf:object <http://anotherexample.com/requ/123> ;
  dcterms:title "Requirement 123: The system shall be robust" .

JSON-LD example using reified statement:

{
  "@context": {
    "dcterms": "http://purl.org/dc/terms/",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "oslc": "http://open-services.net/ns/core#",
    "oslc_rm": "http://open-services.net/ns/rm#"
  },
  "@id": "http://example.com/requ/4321",
  "@type": "oslc_rm:Requirement",
  "oslc_rm:elaboratedBy": {
    "@id": "http://anotherexample.com/requ/123",
    "dcterms:title": "Requirement 123: The system shall be robust"
  }
}

Vocabulary Terms and Constraints

OSLC Requirements Management Version 2.1. Part 2: Vocabulary defines the vocabulary terms and constraints for OSLC Requirements Management resources. These terms and constraints are specified according to [[!OSLCCoreVocab]].

RM Server Capabilities

Server Resources

RM Servers MUST provide one or more oslc:ServiceProvider resources. 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 beyond 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#.

RM servers MAY provide other forms of discovery described in Core 3.0 Discovery.

RM Servers MAY provide one more more oslc:ServiceProviderCatalog 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 beyond 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

RM Servers supporting resource creation MUST do so through oslc:CreationFactory resources, as defined by [[!OSLCCore3]]. Any such factory resources MUST be discoverable through oslc:Service resources. Servers SHOULD provide oslc:ResourceShape resources on oslc:CreationFactory resources as defined by [[!OSLCShapes]].

Query Capabilities

RM Servers MUST support query capabilities, as defined by [[!OSLCCore3]]. Servers SHOULD provide oslc:ResourceShape on oslc:QueryCapability resources as defined by [[!OSLCShapes]].

The Query Capability, if supported, MUST support these parameters:

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

Where oslc:ResourceShape is not supported by the Query Capability, Servers 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

RM Servers MUST support the selection and creation of resources by delegated web-based user interface dialogs Delegated Dialogs as defined by [[!OSLCCore3]].

RM Servers MAY support the pre-filling of creation dialogs based on the definition at Delegated Dialogs.

Usage Identifiers

RM Servers MAY identify the usage of various services with additional property values for the OSLC Core Discovery 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. RM Servers MAY provide their own usage URIs. Such usage URIs MUST be in a non-OSLC namespace.

Version Compatibility

Version Compatibility with 2.0 Specifications

The specification is updated to be based on the [[!OSLCCore3]] Specification. The changes are all upward compatible additions and therefore do not introduce incompatibilities with version 2.0.

Version Compatibility with 1.0 Specifications

The goal is to provide a smooth transition to 2.0 for both Clients and Servers. This section will clarify the usage of 1.0 media types so that Servers can support both 1.0 and 2.0 Clients 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. Clients who support both 1.0 and 2.0, should only preserve these resource URIs. When a Server 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.).

Acknowledgements

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Project Governing Board:

James Amsden, IBM (co-chair)
Andrii Berezovskyi, KTH (co-chair)
Bill Chown, Mentor
Wesley Coelho, Tasktop
Axel Reichwein, Koneksys

Techical Steering Committee:

James Amsden, IBM
Andrii Berezovskyi, KTH
Axel Reichwein, Koneksys

Additional Participants:

Andy Berner, IBM
Scott Bosworth, IBM
Jim Conallen, IBM
George De Candio, IBM
Jeremy Dick, Integrate
Brenda Ellis, Northrop Grumman
Rainer Ersch, Siemens
Ian Green, IBM
Dave Johnson, IBM
Andreas Keis, EADS
Nicholas Kruk, IBM
Chris McGraw, IBM
Paul McMahan, IBM
David Ruiz, Ravenflow
Matthew Stone, Stoneworks
Dominic Tulley, IBM
Simon Wills, Integrate

Change History

Revision Date Editor Changes Made
01 2018-05-22 Jad El-khoury Initial Committee Specification Draft migrated from open-services.net