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.
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 uses and extends the terminology and capabilities of [[!OSLCCore3]].
The following sub-sections define the mandatory and optional requirements for an OSLC Requirements Management (OSLC RM) server.
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 |
This specification follows the specification version guidelines given in [[!OSLCCore3]].
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
.
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,
application/rdf+xml
. RM
Clients MUST be prepared to deal with any valid RDF/XML document.
application/xml
. The XML
representations MUST follow the guidelines outlined in the
OSLC Core Representations Guidance
to maintain compatibility with [[!OSLCCore2]].
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,
application/rdf+xml
.application/xml
.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.
[[!OSLCCore3]] specifies the recommended OSLC authentication mechanisms. In addition to the OSLC Core authentication requirements, OSLC RM servers SHOULD support [[!OpenIDConnect]].
[[!OSLCCoreVocab]] specifies the OSLC Core error responses. OSLC RM puts no additional constraints on error responses.
OSLC RM servers SHOULD support pagination of query results and MAY support pagination of a single resource's properties as defined by [[!OSLCCore3]].
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.
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.
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.
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" } }
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 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.
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]].
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:
rdf:Description
and rdfs:member
as defined by
Core Specification Appendix B:Representations and Examples - RDF/XML Examples.
oslc:results
array. See
Core Specification Appendix B: Representations and Examples - Guidelines for JSON.
The stability of query results is OPTIONAL (see Core Specification Version 2.0 - Stable Paging).
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.
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.
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.
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.).
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
Revision | Date | Editor | Changes Made |
---|---|---|---|
csprd01 | 2018-05-31 | Mark Schulte and Jad El-khoury | Initial Committee Specification Draft migrated from open-services.net |
cs01 | 2018-08-24 | Jad El-khoury | Committee Specification 01 |
psd02 | 2019-10-01 | Jad El-khoury | Project Specification Draft 02 |
PS01 | 2020-09-03 | Jad El-khoury |
|