Aggregation page of all the OSLC RM V1.0 specification pages.

To edit, please edit separate pages.

Requirements Management and Definition 1.0 Specification

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 1.0 specification, which is part of the OSLC group of specifications.

This specification supports key REST APIs for software Requirements Management systems. OSLC RM 1.0 takes an open, loosely coupled approach to specifc lifecycle integration scenarios. The scenarios and this V1.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.

Specification Working Group

Authors of the OSLC RM 1.0 Specification:

• SteveAbrams (IBM)
• AndyBerner (IBM)
• ScottBosworth (IBM)
• JimConallen (IBM)
• GeorgeDeCandio (IBM)
• BrendaEllis (Northrop Grumman Corporation)
• RainerE (Siemens)
• IanGreen (IBM; OSLC RM Lead)
• AndreasKeis (EADS)
• TorgeKummerow (EADS)
• ChrisMcGraw (IBM)
• PaulMcMahan (IBM)
• DevangParikh (IBM)
• VishyRamaswamy (IBM)
• RenRenganathan (Citigroup)
• DavidRuiz (Ravenflow)
• MatthewStone (Stoneworks)
• DominicTulley (IBM)
• RandyVogel (Accenture)
• SimonWills (Integrate)

(Please address all enquires to the OSLC RM Lead, IanGreen.)

Specification

Document
RESTful Services
Requirement resources
Requirement collection resources
Delegated Resource Selection and Creation
Requirements Management Service Description
Requirements Management Service Description Vocabulary

In addition, the OSLC-RM 1.0 specification relies on the OSLC Service Provider Catalog specification, part of the OSLC Common Services family of specifications.

Supporting Documents

These non-normative documents do not form part of the specification, but document the use cases, design decisions, and over rationale that led to the OSLC RM 1.0 specification. In any discrepancy between what is described in these documents and the actual specifications, the specification prevails.

Document
Scenarios and Use Cases
Resource Design Guidelines

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 Requirements Management 1.0 Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found here.

Warning: Can't find topic Main.RmCovenantV1

Service Provider Catalog

1.0 SPECIFICATION

Purpose

This specification, defined as part of the OSLC-CM 1.0 effort, describes OSLC service provider catalogs. These catalogs are used in the discovery of OSLC service providers, to simplify the configuration of tools that will integrate with providers of OSLC-defined services.

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.

Terminology

Service Provider Catalog Resource

An informational resource describing a browsable collection of service providers.

Service Provider Catalog Document

The representation of a Service Provider Catalog Resource. A RDF/XML-based document containing entries for service providers and subcatalogs thereof.

(domain-specific) Services Resource

An informational resource describing a set of domain-specific services.

(domain-specific) Services Document

The representation of a domain-specific Services Resource.

Change Management Services Resource

An informational resource describing a set of change management-specific services.

Change Management Services Document

The representation of a Change Management Services Resource.

Service Provider Catalog Resources

A Service Provider Catalog Resource is an informational resource describing a browsable collection of service providers.

The GET method on a Service Provider Catalog Resource retrieves a Service Provider Catalog Document. This specification only covers retrieving a Service Provider Catalog Resource with GET. The behavior of POST, PUT, and DELETE methods on Service Provider Catalog Resources are not covered in this specification.

Service Provider Catalog Documents

A Service Provider Catalog Document describes a catalog whose entries describe service providers or out-of-line subcatalogs.

The media type of a Service Provider Catalog Document is REQUIRED to be application/x-oslc-disc-service-provider-catalog+xml.

XML namespace abbreviations used in this specification:

• rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
• dc - Dublin Core Metadata Initiative (DCMI) properties namespace URI - http://purl.org/dc/terms/
• oslc_disc - OSLC Discovery XML namespace - http://open-services.net/xmlns/discovery/1.0/

A Service Provider Catalog Document is an RDF/XML document with this schematic format:

<?xml version="1.0"?>
<oslc_disc:ServiceProviderCatalog
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:dc="http://purl.org/dc/terms/"  
     xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"

     rdf:about="{self}">

  <dc:title>{catalog title}</dc:title>
  <oslc_disc:details rdf:resource="{catalog details uri}" />

  <oslc_disc:entry>
     <oslc_disc:ServiceProvider>
        <dc:title>{advisory service provider title}</dc:title>
        <oslc_disc:details rdf:resource="{service provider details uri}" />
        <oslc_disc:services rdf:resource="{services resource uri}" />
     </oslc_disc:ServiceProvider>
  </oslc_disc:entry>
   ...
 
  <oslc_disc:entry>
     <oslc_disc:ServiceProviderCatalog rdf:about="{subcatalog uri}" >
        <dc:title>{advisory subcatalog title}</dc:title>
     </oslc_disc:ServiceProviderCatalog>
  </oslc_disc:entry>
   ...

</oslc_disc:ServiceProviderCatalog>

The oslc_disc:entry elements describe either a single service provider ( oslc_disc:ServiceProvider element) or an out-of-line subcatalog ( oslc_disc:ServiceProviderCatalog element).

Although the document is RDF/XML, it is in a very restricted form designed to be used by RDF-unaware clients.

Constraints on Service Provider Catalog Documents:

• The root element MUST be oslc_disc:ServiceProviderCatalog.
• oslc_disc:ServiceProviderCatalog element:
  • MUST have a rdf:about attribute giving the URI of the catalog. The value of the root element MUST be a self link (i.e., reference the Service Provider Catalog Resource itself, either through an absolute or a relative URI reference). For non-root elements, this is the URI of the subcatalog.
  • MUST have a dc:title child element. For the root element, this is the displayable title of the catalog. For non-root elements, this is an advisory title of the subcatalog; it does not override a dc:title element of the referenced Service Provider Catalog Resource.
  • MAY have an oslc_disc:details child element.
  • MAY have any number of oslc_disc:entry child elements, including none. An inner element MUST have none (i.e., the subcatalog is described out-of-line).
  • The order of oslc_disc:entry child elements is not significant.
  • MAY have additional child elements not specified here.
• oslc_disc:ServiceProvider element describes a single service provider:
  • MUST have a dc:title child element giving a displayable title of the service provider.
  • MUST have a oslc_disc:services child element.
  • MAY have a oslc_disc:details child element.
  • MAY have additional child elements not specified here.
• oslc_disc:entry element:
  • MUST have a single child element that is either an oslc_disc:ServiceProvider or an oslc_disc:ServiceProviderCatalog element.
  • MAY have additional child elements not specified here.
• dc:title element:
  • MUST have content.
  • MUST NOT have child elements.
  • MAY have an xml:lang attribute giving the language of the content.
• oslc_disc:services element:
  • MUST have a rdf:resource attribute giving the URI of a domain-specific Services Resource (e.g., a Change Management Services Resource).
• oslc_disc:details element:
  • MUST have a rdf:resource attribute giving the URI of a browsable resource providing details of the service provider or catalog.
• All elements MAY have additional atttributes not specified here.

Clients MUST quietly ignore unknown elements and attributes that they encounter in a Service Provider Catalog Document.

Example

Example 1: A Service Provider Catalog Resource located at http://rtc1.example.com/jazz/workitems/ChangeManagementCatalog.xml. The document lists 2 service providers.

<?xml version="1.0"?>
<oslc_disc:ServiceProviderCatalog
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/terms/"  
  xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"

  rdf:about="http://rtc1.example.com/jazz/workitems/ChangeManagementCatalog.xml" >

  <dc:title>Change management service provider catalog</dc:title>

  <oslc_disc:entry>
     <oslc_disc:ServiceProvider>
        <dc:title>Project X</dc:title>
        <oslc_disc:details rdf:resource="http://rtc1.example.com/jazz/process/project-areas/_CGwYgAnrEd6_yLxvteIpZw" />
        <oslc_disc:services
             rdf:resource="http://rtc1.example.com/jazz/workitems/contexts/6ads5ad4a7ds47ad7s/services.xml" />
     </oslc_disc:ServiceProvider>
  </oslc_disc:entry>

  <oslc_disc:entry>
     <oslc_disc:ServiceProvider>
        <dc:title>Project Y</dc:title>
        <oslc_disc:details rdf:resource="http://rtc1.example.com/jazz/process/project-areas/_PVCFEAnrEd6_yLxvteIpZw" />
        <oslc_disc:services
             rdf:resource="http://rtc1.example.com/jazz/workitems/contexts/dsr4ae4desad47saed/services.xml" />
     </oslc_disc:ServiceProvider>
  </oslc_disc:entry>

</oslc_disc:ServiceProviderCatalog>

Example 2: A Service Provider Catalog Resource located at http://cq1.example.com/catalog. The document lists 1 service provider, and 1 subcatalog located at http://cq1.example.com/other-catalog.

<?xml version="1.0"?>
<oslc_disc:ServiceProviderCatalog
  xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/terms/"  

  rdf:about="http://cq1.example.com/catalog" >

  <dc:title>Change management service provider catalog</dc:title>

  <oslc_disc:entry>
     <oslc_disc:ServiceProvider>
        <dc:title>CQ Service for repo1</dc:title>
        <oslc_disc:details rdf:resource="http://cq1.example.com/browse?repo=repo1" />
        <oslc_disc:services rdf:resource="http://cq1.example.com/repos/repo1" />
     </oslc_disc:ServiceProvider>
  </oslc_disc:entry>

  <oslc_disc:entry>
     <oslc_disc:ServiceProviderCatalog rdf:resource="http://cq1.example.com/other-catalog">
        <dc:title>Others</dc:title>
     </oslc_disc:ServiceProviderCatalog>
  </oslc_disc:entry>

</oslc_disc:ServiceProviderCatalog>

Security

Access to a Service Provider Catalog Resource MAY be restricted.

RM Service Description Vocabulary

1.0 SPECIFICATION

Namespaces

This specification defines terms in the "http://open-services.net/xmlns/rm/1.0/" namespace. Abbreviated "oslc_rm" in this document.

User Dialog Resource

A dialogue resource describes a UI widget. Such widgets have a URI, a preferred width and height, and a title. These resources have rdf:type "oslc_rm:Dialog", with properties whose meaning is defined by the following table:

Property	Required	Description
dc:title	Yes	A human-readable title for the widget.
oslc_rm:hintWidth	Yes	Preferred width of the widget.
oslc_rm:hintHeight	Yes	Preferred height of the widget.
oslc_rm:widget	Yes	The URI of the web application which provides the widget.

Service Descriptor Resource

A resource of rdf:type "oslc_rm:ServiceDescriptor". Has properties whose meaning is defined by the following table:

Property	Required	Description
dc:title	Yes	The title of the service.
dc:description	Yes	The description of the service.
dc:contributor	No	The entity which provides this service implementation.

The dc:contributor, if present, MUST be an inline resource.

Contributor Resource

A resource of rdf:type "oslc_rm:Contributor" with properties whose meaning is defined by the following table:

Property	Required	Description
dc:title	Yes	The title of the contributor
dc:identifier	Yes	A means of identifying to the service consumer the contributor of this service. This can be of any form and need not be for human consumption. A domain name, URN or unique string may be appropriate. This identifier may be specifica to a product and/or service.
oslc_rm:icon	No	An icon representing the contributor of this service. The icon MUST be in favicon format and 16x16 pixels in size.
oslc_rm:home	No	An inline resource describing the main application home for this service provider.

Home Resource

A resource of rdf:type "oslc_rm:Home" may be provided in the dc:contributor of a oslc_rm:ServiceDescriptor. This resource has properties whose meaning is described by the following table:

Property	Required	Description
dc:title	Yes	The title of the application.
oslc_rm:application	Yes	The URI of the application.

Factory Resource

Factory resources have rdf:type "oslc_rm:Factory". Such resources have properties whose meaning is described by the following table:

Property	Required	Description
dc:title	Yes	Title of the factory.
oslc_rm:factory	Yes	The URI of the factory.

Requirements Management Service Description

1.0 SPECIFICATION

Introduction

Clients with a need to interact with a Requirements Management system need a mechanism for discovering the capabilities of that system, and the URIs used to access those capabilities. There are several aspects to the discovery process. First, clients may need to discover the existence of the RM system itself. On discovering that, clients will want to discover the contexts in which requirements and related artefacts and processes may exist (e.g., many RM systems have an organisational units such as "projects"). On identifying a context, the clients need to discover the services that are provided within that context. This portion of the OSLC RM specification addresses the latter two of these scenarios, the discovery of the RM system itself is outwith the scope of this revision of the specification. Therefore, this specification describes how an OSLC RM provider will expose context and service discovery, in terms of the required resource formats and namespaces.

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.

Terminology

Service Description Resource - an informational resource describing the capabilities and contextual configuration needed for a set of RM specific services.

Service Description Document - the representation of a RM Services Description Resource.

Service Provider - an implementation of the OSLC RM specification. OSLC RM clients consume these services.

Service Discovery

Starting with an entry point URI to a service provider, {base-url}, clients will discover the (typically hierarchical) arrangement of contexts managed by the application. To support the wide range of application and project configurations, OSLC is not specifying a predetermined arrangement of these contexts. Instead, clients will be able to iterate through a number of Service Provider Catalogs until the client identifies a context of interest, where the client will find an RM Service Description Resource.

The discovery model flow is as follows:

1. Request information from an OSLC RM based service provider.
2. If Response is a Service Provider Catalog:
   1. An entry is selected from the Service Provider Catalog
   2. With this entry's URI, goto to step #1
3. If the response is a Service Description Document then continue to next step.
4. Configuration has completed

The number of iterations over the configuration choices should be set by the client application, and/or the user of that client application.

Termination of the RM service discovery occurs when a the client application receives an HTTP response with a Content-Type of application/x-oslc-rm-service-description-1.0+xml and the service description document as the response's content body.

Service Description Resource

A Service Description Resource is an informational resource describing the contextual configuration needs of a service provider.

The GET method on a Service Description Resource MUST retrieve a Service Description Document. This specification only covers retrieving a Service Description Resource with GET. The behavior of POST, PUT, and DELETE methods on Service Description Resources are left Undefined in this specification (service consumers should refer to the section on Compliance in the RmRestApiV1 document).

Service Description Document

The Service Description Document provides configuration definitions needed by consumers of a service provider.

The Service Description Document MUST be identified using the media type of application/x-oslc-rm-service-description-1.0+xml.

XML namespace abbreviations used in this specification:

• rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
• dc - The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/
• oslc_rm - The Open Services for Lifecycle Collaboration Requirements Management namespace - http://open-services.net/xmlns/rm/1.0 /

Service Descriptor resource

A resource of rdf:type "oslc_rm:ServiceDescriptor" with the additional properites in the OSLC RM namespace:

Property	Required	Description
oslc_rm:requirementSelectionDialog	Yes	The oslc_rm:Dialog resource for the delegated selection of requirement resources.
oslc_rm:requirementCollectionSelectionDialog	Yes	The oslc_rm:Dialog resource for the delegated selection of requirement collection resources.
oslc_rm:requirementCreationDialog	Yes	The oslc_rm:Dialog resource for the delegated creation of requirement resources.
oslc_rm:requirementFactory	Yes	The oslc_rm:Factory resource for the programmatic creation of requirement resources.

oslc_rm:ServiceDescriptor is described in Service Description Vocabulary. In addition to the properties described above, service providers may provide other properties in non-OSLC namespace whose meaning is not described by this specification.

Example (RDF/XML)

<?xml version="1.0" encoding="UTF-8"?>
<oslc_rm:ServiceDescriptor
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:oslc_rm="http://open-services.net/xmlns/rm/1.0/">
  rdf:about="http://example.com/services/rm-service-descriptor.xml">

    <dc:title xml:lang="en-GB">Braking System SRS</dc:title>
    <dc:description xml:lang="en-GB">DOORS OSLC RM 1.0 provider for Braking System SRS</dc:description>
    <dc:contributor>
      <oslc_rm:Contributor>
        <dc:title>IBM Rational DOORS</dc:title>
        <dc:identifier>com.ibm.rdm.doors</dc:identifier>
        <oslc_rm:icon rdf:resource="https://doors.example.com/resources/doorsicon.ico"/>
        <oslc_rm:home>
          <oslc_rm:Home>
            <dc:title>IBM Rational DOORS</dc:title>
            <oslc_rm:application rdf:resource="doors://doors.example.com/invokedoors"/>
          </oslc_rm:Home>
        </oslc_rm:home>
      </oslc_rm:Contributor>
    </dc:contributor>

    <oslc_rm:requirementSelectionDialog>
      <oslc_rm:Dialog>
        <dc:title>Web UI for selecting requirements.</dc:title>
        <oslc_rm:widget rdf:resource="https://www.example.com/webapp/requirementsPicker?SRS%20Braking"/>
        <oslc_rm:hintWidth>400px</oslc_rm:hintWidth>
        <oslc_rm:hintHeight>500px</oslc_rm:hintHeight>
      </oslc_rm:Dialog>
    </oslc_rm:requirementSelectionDialog>
    <oslc_rm:requirementCollectionSelectionDialog>
      <oslc_rm:Dialog>
        <dc:title>Web UI for selecting requirement collections.</dc:title>
        <oslc_rm:widget rdf:resource="https://www.example.com/webapp/requirementsPicker?Project=SRS%20Braking"/>
        <oslc_rm:hintWidth>400px</oslc_rm:hintWidth>
        <oslc_rm:hintHeight>500px</oslc_rm:hintHeight>
      </oslc_rm:Dialog>
    </oslc_rm:requirementCollectionSelectionDialog>
    <oslc_rm:requirementCreationDialog>
      <oslc_rm:Dialog>
        <dc:title>Web UI for creating requirements in SRS Braking.</dc:title>
        <oslc_rm:widget rdf:resource="https://www.example.com/webapp/requirementsCreator?Project=SRS%20Braking"/>
        <oslc_rm:hintWidth>400px</oslc_rm:hintWidth>
        <oslc_rm:hintHeight>500px</oslc_rm:hintHeight>
      </oslc_rm:Dialog>
    </oslc_rm:requirementCreationDialog>
    <oslc_rm:requirementFactory>
      <oslc_rm:Factory> 
        <dc:title>Factory for creating requirements in Braking System SRSX</dc:title>
        <oslc_rm:factory rdf:resource="https://www.example.com/requirementFactory?Project=SRS%20Braking"/>
      </oslc_rm:Factory> 
    </oslc_rm:requirementFactory>
  </oslc_rm:ServiceDescriptor>
</rdf:RDF> 

References

• W3C XML 1.0 - xml:lang
• Dublin Core Metadata Terms
• Collaborative Application Lifecycle Management with Rational Products - IBM Redbook

Requirement Resource Definition

1.0 SPECIFICATION

In this specification we refer to the RDF model as the canonical definition of the resource, and speak in terms of the vocabularies that are of interest in these models. RDF/XML will be used to illustrate examples since that is one of the supported representation formats required by this specification.

Namespaces

This specification is giving a description of the " http://open-services.net/xmlns/rm/1.0/" namespace by describing the meaning of the terms of that namespace and the way in which those terms are to be use with the terms of other vocabularies in order to describe a requirement. We will abbreviate this namespace to "oslc_rm" and will typically use that as a XML namespace prefix in RDF/XML documents. Other namespaces are also references as part of this specification:

• rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
• dc - Dublin Core Metadata Initiative (DCMI) properties namespace URI - http://purl.org/dc/terms/
• oslc_rm - OSLC RM XML namespace - http://open-services.net/xmlns/rm/1.0/
• foaf - http://xmlns.com/foaf/0.1/

Requirement Resource

The following table describes the RDF properties whose meaning is defined by this specification:

Property	Required on Read	Required on Write	Read-only	Represents
dc:title	Yes	Yes	No	The title of the requirement.
dc:description	Yes	Yes	No	The primary content of the requirement.
dc:creator	No	No	Yes	The entity that created the requirement. The value of this element is free form text, or may be a FOAF Person element. If the entity has a URI it should be represented as a rdf:resource attribute of this element.
dc:contributor	No	No	Yes	The entity that last modified the requirement. The value of this element is free form text, or may be a FOAF Person element. If the entity has a URI it should be represented as a rdf:resource attribute of this element.
dc:created	Yes	No	Yes	Date of creation of the requirement. Can be expressed as free form text, or in a standard form. When in a form that can be automated, the rdf:datatype attribute with a public date time URI should be present to assist the client in parsing the value (i.e. http://www.w3.org/2001/XMLSchema#dateTime).
dc:modified	Yes	No	Yes	Date of the last modification of the requirement. Can be expressed as free form text, or in a standard form. When in a form that can be automated, the rdf:datatype attribute with a public date time URI should be present to assist the client in parsing the value (i.e. http://www.w3.org/2001/XMLSchema#dateTime).

Properties from other vocabularies may be present in the representation of an <oslc_rm:Requirement/> element, but the meaning of those properties is not defined by this specification. The dc:description and dc:title are provided inline (by an RDF literal value) and MAY contain XHTML markup, indicated by rdf:parseType="Literal" on the RDF property element. This XHTML markup, if present, MUST be valid XHTML and MUST be wholly contained within a single XHTML div element.

The media type for such representations MUST be "application/x-oslc-rm-requirement-1.0+xml", which is an RDF/XML representation of a requirement resource.

Links

A link from a requirement is represented by an RDF resource (an RDF URI Reference). In the RDF/XML, these are represented as XML attributes "rdf:resource". These links are used to describe binary trace relationships as well as non-trace linkages to other resources. The example below shows a trace relationship "validated by" which has been modelled with a property "calm:validatedBy". Such properties MAY be multi-valued, meaning that the same property can appear more than once. The example below illustrates this with the "calm:validatedBy" link.

Example requirement in RDF/XML representation

Here is an example showing the RDF/XML of a requirement. Notice that properties from other vocabularies are present in this representation. In this example, the dc:description is provided inline as plain text; the dc:title contains some XHTML markup and is modelled by an XML Literal in the RDF.

GET http://rrc.example.com/requirements/24
with Accept header application/x-oslc-rm-requirement-1.0+xml

<?xml version="1.0" encoding="UTF-8"?>
<oslc_rm:Requirement
       xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:oslc_rm="http://open-services.net/xmlns/rm/1.0/"
       xmlns:calm="http://jazz.net/xmlns/prod/jazz/calm/1.0/"
       xmlns:acme="http://acme.example.com/xmlns/"
       xmlns:dc="http://purl.org/dc/terms/"
       rdf:about="http://rrc.example.com/requirements/24">
    <dc:creator>Ian Green</dc:creator>
    <dc:created>17 July 1900</dc:created>
    <dc:modified>1 August 2009</dc:modified>
    <dc:title rdf:parseType="Literal">
        <xhtml:div xmlns:xhtml="http://http://www.w3.org/1999/xhtml">
         Signal frequency <xhtml:b>triggering</xhtml:b> shall be modulation-exempt
        </xhtml:div>
    </dc:title>
    <dc:description>Signal frequency triggering shall be compliant with ISO-7488-II Part 4.</dc:description>        
        
    <!-- Some properties whose meaning is not defined by OSLC RM -->
    <!-- Notice that validatedBy is multi-valued -->
    <acme:processLinkage rdf:resource="urn:process-id:6363" />
    <calm:implementedBy
         rdf:resource="http://rtc.example.com/wi/242" />             
    <calm:validatedBy
         rdf:resource="http://rqm.example.com/testcase/6524" />
    <calm:validatedBy
         rdf:resource="http://rqm.example.com/testcase/6525" />
</oslc_rm:Requirement>

Requirement Collection Resource Definition

1.0 SPECIFICATION

A Requirement Collection is an ordered collection containing references to requirement resources. The semantics of the collection is as follows:

A requirement MAY be present in more than one collection at a time.

The lifetime of a collection and the lifetime of a requirement is not constrained by this specification; specifically, deletion of a collection MAY result in the deletion of the collected requirements.

The collection is closed: that is, requirements which are not stated to be a member of that collection are to be interpreted as NOT belonging to that collection.

Namespaces

This specification is giving a description of the " http://open-services.net/xmlns/rm/1.0/" namespace by describing the meaning of the terms of that namespace and the way in which those terms are to be use with the terms of other vocabularies in order to describe a requirement. We will abbreviate this namespace to "oslc_rm" and will typically use that as a XML namespace prefix in RDF/XML documents.

Other namespaces used in this specification:

• rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
• oslc_rm - OSLC RM XML namespace - http://open-services.net/xmlns/rm/1.0/
• dc - Dublin Core Metadata Initiative (DCMI) properties namespace URI - http://purl.org/dc/terms/

Requirement Collection Resource

RDF/XML Representation of Requirement Collection Resource

A requirement collection is a resource having rdf:type rdf:Bag and oslc_rm:RequirementCollection. The table below describes the RDF/XML representation of a requirement collection. The provider MUST support the RDF/XML representation of requirement collections using media type application/x-oslc-rm-requirement-collection-1.0+xml.

The following table describes the RDF properties whose meaning is defined by this specification:

Property	Required on Read	Required on Write	Read-only	Represents
dc:title	Yes	Yes	No	The title of the collection.
dc:description	No	No	No	The description of the collection.
dc:creator	Yes	No	Yes	The entity that created the collection. The value of this element is free form text, or may a FOAF Person element. If the user has a URI it should be represented as a rdf:resource attribute of this element.
dc:created	Yes	No	Yes	Date of creation of the collection. May be expressed as free form text, or in a standard form. When in a form that can be automated, the rdf:datatype property with a public date time URI should be present to assist the client in parsing the value (i.e. http://www.w3.org/2001/XMLSchema#dateTime).
dc:modified	Yes	No	Yes	Date of the last modification of the collection. May be expressed as free form text, or in a standard form. When in a form that can be automated, the rdf:datatype property with a public date time URI should be present to assist the client in parsing the value (i.e. http://www.w3.org/2001/XMLSchema#dateTime).
rdf:li	No	No	No	RDF list item addressing each of the collected resources.

Properties from other vocabularies may be present in the representation of a requirement collection resource, but the meaning of those properties is not defined by this specification.

The requirement collection should be interpreted as being closed and having set-like sematics (repetition MAY be present and must be tolerated by service consumers; service providers MUST tolerate repetition but are not required to preserve that repetition); typing the collection as an rdf:Bag emphasises this to some degree. (In the future, other collection semantics may be defined, and in such an eventuality, other rdf:type collections may be introduced.)

It is permissible for a requirement collection to "collect" zero requirement resources; in such cases, there will be no <rdf:li/> elements in its representation.

Example

Here is an example showing the RDF/XML of a requirement collection which contains three referenced requirements.

GET http://rrc.example.com/collection/10
with Accept header application/x-oslc-rm-requirement-collection-1.0+xml

<?xml version="1.0" encoding="UTF-8"?>
<oslc_rm:RequirementCollection
          xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
          xmlns:oslc_rm="http://open-services.net/xmlns/rm/1.0/"
          xmlns:dc="http://purl.org/dc/terms/"
          xmlns:calm="http://jazz.net/xmlns/calm/1.0/"
          rdf:about="http://rrc.example.com/collection/10">
        <rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Bag"/>
        <dc:title>Enhancements for patch 2</dc:title>
        <dc:description>Enhancements for patch 2, as reviewed and agreed with client</dc:description>
        <dc:creator>Ian Green</dc:creator>
        <dc:modified>28 August 2009</dc:modified>
        <dc:created>27 August 2009</dc:created>
        <calm:validatedBy rdf:resource="http://rqm.example.com/testplans/34"/>
        <rdf:li rdf:resource="http://rrc.example.com/requirements/34"/>
        <rdf:li rdf:resource="http://rrc.example.com/requirements/63"/>
        <rdf:li rdf:resource="http://rrc.example.com/requirements/902"/>
</oslc_rm:RequirementCollection>

 
 

Requirements Management REST API

1.0 SPECIFICATION

Introduction

This specification defines a resource model of requirements and other artefacts from the domain of requirements definition and management. The resource model is defined in terms of representations of resources, media types, the basic HTTP 1.1 methods and response codes. The capabilities of this "RESTful" API is not declared nor intended to be general purpose; they are driven by a set of scenarios that were the focus of the work group which authored this specification.

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.

Core resource summary

Resource	URI	GET	POST	PUT	DELETE	Description
Requirement	{URI}	MUST	Undefined	MUST	MAY	Representation of a requirement (see Requirement resource)
Requirement Collection	{URI}	MUST	Undefined	MUST	MAY	A collection of references to requirements (see Requirement Collection resource)

Creation and Selection of Resources

The RM resource model supports the creation of certain resources via "factory" resources. Requirements can also be created via delegated web UIs. Details of each of these capabilities will follow in subsequent sections; the following table provides a summary:

Purpose	Resource	URL	Support
Requirement Creation	oslc_rm:requirementFactory	{Requirement Factory}	MUST
Requirement Selection UI	oslc_rm:requirementSelectionDialog in service discovery document	{Requirement Selection URL}	MUST
Requirement Creation UI	oslc_rm:requirementCreationDialog in service discovery document	{Requirement Creation URL}	MUST
Requirement Collection Selection UI	oslc_rm:requirementCollectionSelectionDialog in service discovery document	{Collection Selection URL}	MUST

Namespaces Used

The following table lists the namespace prefixes and associated namespaces used for samples and specification text. Service Providers MUST support these reserved namespace prefixes.

Prefix	Namespace	Defined
oslc_rm	http://open-services.net/xmlns/rm/1.0/	By this specification
oslc_disc	http://open-services.net/xmlns/discovery/1.0/	Service Provider Catalog
dc	http://purl.org/dc/terms/	Dublin Core Terms
rdf	http://www.w3.org/1999/02/22-rdf-syntax-ns#	RDF/XML
rdfs	http://www.w3.org/2000/01/rdf-schema#	RDF Schema

Media Types Used

The following table summarizes the MIME media types used for various resource requests. See appropriate sections for specification requirements on usage.

Media Type	Defined	Resource
application/x-oslc-rm-service-description-1.0+xml	Service Discovery Document	Service Description Document
application/x-oslc-disc-service-provider-catalog+xml	Service Provider Catalog	Service Provider Catalog
application/x-oslc-rm-requirement-1.0+xml	Requirement Resource Definition	Requirement.
application/x-oslc-rm-requirement-collection-1.0+xml	Requirement Collection Resource Definition	Requirement collection.
application/xml text/xml	W3C Extensible Markup Language (XML)	General XML format request/response
application/xhtml+xml	W3C XHTML 1.1	XHTML presentation format
text/html	W3C HTML 4	HTML presentation format
application/rdf+xml	RDF/XML media type	General XML representation of RDF

General Remarks

Service providers MUST follow the HTTP/1.1 (RFC 2616) specification.

In particular:

• Providers MUST support server-side content negotiation using the HTTP standard Accept header as per the HTTP/1.1 specification. If an Accept header is supplied and has more than one MIME type, then the server will determine the MIME type to be used for the response entity. If none is provided then a default is used, appropriate to the resource URI. If the requested MIME type is unknown, a HTTP response code of 415 Unsupported Media Type MUST be returned.
• Servers MUST correctly use the standard HTTP response codes - resource-specific interpretation of response codes is given elsewhere in this specification, on a resource-by-resource, method-by-method basis.

Providers implementing this specification SHOULD refrain from inventing MIME types with a subtype having "x-oslc-" as a prefix, which have not been defined by OSLC specifications. In this way providers can offer representations that are not defined by this specification, but in a safe way which will avoid collision with OSLC-defined MIME types that may appear in future revisions of OSLC specifications.

Each of the operations on a given URI may support a different default MIME type, as described elsewhere in this specification.

HEAD behaves as GET in all cases, with the exception that the response entity is omitted in the case of HEAD.

Required and read-only resource properties

The resource model describes properties as

• "required on read" or "not required on read"
• "required on write", or "not required on write"

Each resource representation describes various properties, their meaning, and behaviour on read (GET/HEAD) and write (POST/PUT).

A provider MUST respond with a 400 (Forbidden) when a service consumer attempts to update a resource (using POST/PUT) with a representation where one or more "required on write" properties is absent. A provider MUST tolerate an update (a POST/PUT) to a resource with a representation regardless of whether any "not required on write" properties are absent.

A provider MUST include in all resource representations those "required on read" properties (on GET/HEAD). Properties which are "not required on read" MAY be excluded.

This specification defines the meaning of several properties in the RM resource model, some of which are declared to be "not required on read". The RM resource model specification is open (in the sense that providers MAY contribute properties from other vocabularies, and providers MAY tolerate clients contributing properties from other vocabularies): such foreign properties MUST be treated as "not required on read", and "required on write".

Compliance

All implementations of this interface MUST implement all of the REQUIRED behaviours. Such implementations are termed "conditionally compliant". Implementations which additionally implement all of the OPTIONAL behaviours are "unconditionally compliant".

Certain facets of behaviour are explicitly left "undefined" by this specification; providers are free to implement any behaviour in such cases. However, clients consuming OSLC RM services are strongly recommended not to exploit or to rely on such behaviours since future revisions of this specification may require compliant implementations to change those behaviours. (Notice as a special case that service providers may choose to implement "undefined" in this specification as "405 (Method Not Allowed)": consumer reliance on this response code would be contrary to this recommendation.)

Resource Model

Requirement Resource

Requirement resource formats are defined elsewhere in this specification (see requirement resources).

The following table describes HTTP methods on requirement resources:

Method	Required	Comments
GET/HEAD	MUST	Fetches a representation of the requirement [1].
PUT	MUST	Updates the resource with the supplied representation [1,2].
POST	Undefined	The behaviour of a POST to a requirement resource is not defined by this specification.
DELETE	MAY	Deletes the resource [3].

Notes:

1. Providers MUST support application/x-oslc-rm-requirement-1.0+xml media type for requirement resources. The behaviour with other media types is not defined by this specification.

2. A service provider MUST support at least the following HTTP response status codes in response to a PUT to a requirement resource:

   Code	Content	Description
   403 (Forbidden)	Error message	The request is well-formed but is invalid in some other way. This request should not be retried. (This would happen if the requirement representation were missing one or more of its required properties.)
   404 (Not found)	Error message	The request URI was not found on the server.
   406 (Not Acceptable)	Error message	The supplied media type is not acceptable as a representation of a requirement. A list of acceptable content types SHOULD be supplied in the response entity.
   409 (Conflict)	Error message	The request is well-formed but is invalid in some other way. A description of the problem MAY be provided in the response body.
   415 (Unsupported Media Type)	Error message	The Content-Type of the request is not recognised by the server. The provider SHOULD provide a list of acceptable content types in the response body.

3. Providers MAY support DELETE on requirement resources. Those which do not support DELETE on a requirement resource MUST respond with a 405 (Method Not Supported). A successful deletion SHOULD cause subsequent requests to access that resource to return a 404 (Not Found) or 410 (Gone). Service consumers may use OPTIONS to determine whether or not a provider supports DELETE on a requirement by doing an OPTIONS on a URI "*" with Content-Type set to application/x-oslc-rm-requirement-1.0+xml. Providers supporting DELETE MUST indicate in the OPTIONS response whether or not DELETE is supported.

Requirement Factory

Requirements are created by POSTing an application/x-oslc-rm-requirement-1.0+xml resource representation to the {Requirement Factory} URI described in the service document. Service providers MUST support this media type on POST. Requirement resource formats are defined elsewhere in this specification (see requirement resources).

The following table describes the HTTP methods on the {Requirement Factory}:

Method	Required	Comment
GET/HEAD	Undefined	[1]
PUT	MUST	Returns 405 (Method Not Allowed) [2]
POST	MUST	Creates a new requirement [3].
DELETE	MUST	Returns 405 (Method Not Allowed) [2]

Notes:

1. The behaviour of GET on the {Requirement Factory} is undefined.
2. PUT/DELETE on {Requirement Factory} is not allowed and MUST result in a 405 (Method Not Allowed) for all media types.
3. The provider MUST support application/x-oslc-rm-requirement-1.0+xml media type on POST. The behaviour with other media types is not defined by this specification. Additional details on POST are given below.

A service provider MUST support at least the following HTTP response status codes in response to a POST to the {Requirement Factory}:

Code	Content	Description
201(Created)	Requirement resource	Representation of the created requirement. The Location header MUST contain the URI of the newly created requirement [1].
400 (Bad request)	Error message	The POST could not be processed because the request was not well-formed.
403 (Forbidden)	Error message	The request is well-formed but is invalid in some other way. This request should not be retried. (This would happen if the requirement representation were missing one or more of its required properties.)
404 (Not found)	Error message	The request URI was not found on the server.
406 (Not Acceptable)	Error message	The supplied media type is not acceptable as a representation of a requirement. A list of acceptable media types SHOULD be supplied in the response entity.
409 (Conflict)	Error message	The request is well-formed but is invalid in some other way. A description of the problem MAY be provided in the response body.
415 (Unsupported Media Type)	Error message	The Content-Type of the request is not recognised by the server. The provider SHOULD provide a list of acceptable content types in the response body.

Notes:

1. The rdf:about property in the POSTed requirement resource representation MAY be ignored. This specification does not provide a means for the client to propose a URI for the newly created requirement resource (for example, using rdf:about or a "Name" header in the HTTP request). It is recommended that clients POST representations containing rdf:about="".

Requirement Collection Resource

Requirement collection resource formats are defined elsewhere in this specification (see requirement collection resources).

The following table describes operations on requirement collection resources:

Method	Required	Comments
GET/HEAD	MUST	Fetches a representation of the collection [1].
PUT	MUST	Updates a the collection resource [2,3].
POST	Undefined
DELETE	MAY	Deletes the collection resource [4].

Notes:

1. Providers MUST support application/x-oslc-rm-requirement-collection-1.0+xml content type for requirement collection resources. The behaviour with other media types is not defined by this specification.
2. Provides MUST support application/x-oslc-rm-requirement-collection-1.0+xml content type for requirement collection resources. The behaviour with other media types is not defined by this specification. Sservice provider MUST support at least the following HTTP response status codes in response to a PUT to a requirement collection resource:

3. Code	Content	Description
   403 (Forbidden)	Error message	The request is well-formed but is invalid in some other way. This request should not be retried. (This would happen if the requirement representation were missing one or more of its required properties.)
   404 (Not found)	Error message	The request URI was not found on the server.
   406 (Not Acceptable)	Error message	The supplied media type is not acceptable as a representation of a requirement collection. A list of acceptable content types SHOULD be supplied in the response entity.
   409 (Conflict)	Error message	The request is well-formed but is invalid in some other way. A description of the problem MAY be provided in the response body.
   415 (Unsupported Media Type)	Error message	The Content-Type of the request is not recognised by the server. The provider SHOULD provide a list of acceptable content types in the response body.

4. Providers MAY support DELETE on a requirement collection resource. Providers which do not support DELETE MUST respond with a 405 (Method Not Allowed). A successful resource deletion SHOULD cause subsequent access to that requirement collection resource to yield a 410 (Gone) or a 404 (Not Found). This specification leaves as Undefined the effect upon the requirements referenced by a collection when that collection is successfully deleted. (In particular, services consumers must not assume that deleting a collection will delete each of the requirements contained in that collection.) Service consumers should use OPTIONS to determine whether or not a provider supports DELETE on a requirement collection by doing an OPTIONS on a URI "*" with Content-Type set to application/x-oslc-rm-requirement-collection-1.0+xml. Providers MUST indicate in the OPTIONS response whether or not DELETE is supported.

Delegated RM request actions

Some requirements management service providers have Web-based UI that can perform complex actions for handling of rules needed for selection of requirements, for example, providing navigation, query and search capabilities to locate requirements and collections of requirements. Clients of these services can utilize this capability within their own Web UI by following some simple standards-based methods for cross application interaction. This is interaction is detailed in a separate specification document titled Delegated Resource Selection and Creation. Conforming service providers MUST support this delegated model.

Security and Authentication

Service providers and consumers MAY support HTTP basic authentication.

Service providers and consumers MAY support OAuth.

Service providers and consumers MAY use the secure communication protocol HTTPS (HTTP interaction using Transport Layer Security).

Error Status Information

Whenever an HTTP request results in an error, a status code in the range of 400-599 is returned from the server. A service provider returns a response body containing additional information about the error. The response's body media type MUST be application/rdf+xml, with the following properties defined in the http://open-services.net/xmlns/rm/1.0 namespace:

• oslc_rm:statusCode - required element containing HTTP status code corresponding to this request (this is a replication of the code in the response status line).
• oslc_rm:message - required element containing an error message string suitable for presentation to a user of the client
• oslc_rm:url - optional element whose string content is a URL indicating a Web presentation giving more information on the error
  • oslc_rm:rel - optional attribute with value of "alternate" indicating that it is an alternate method to resolve the error
  • oslc_rm:hintWidth - optional attribute
  • oslc_rm:hintHeight - optional attribute

Implementations MAY provide additional properties. The error message text SHOULD be appropriate to the locale of the requesting client.

Error status examples:

In application/rdf+xml format:

<?xml version="1.0" encoding="UTF-8"?>
<rdm:Error
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:rdm="http://open-services.net/xmlns/rm/1.0/">
   <rdm:statusCode>404</rdm:statusCode>
    <rdm:message>
       A requirement with the given URI wasn't found on this server.
    </rdm:message>
</rdm:Error>

References

• HTTP/1.1 (RFC2616)
• IANA MIME Media Types
• RM Service Description
• Requirement Resource Definition
• Requirement Collection Resource Definition
• Delegated Resource Selection and Creation
• OSLC Service Provider Catalog

End of the specification