OSLC Link Discovery Management Version 1.0. Part 1: Specification

OSLC Link Discovery Management service defines an OSLC RESTful web services API for the discovering incoming and outgoing links to a set of optionally versioned resources. To support these scenarios, this specification defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, as well as HTTP response codes, content type handling and resource formats.

Introduction

OSLC specifications do not currently specify where links between resources are stored, or which server owns which links. OSLC specifications also do not address which links are stored for properties that might be considered inverses such as implements and implementedBy. Some implementations may choose to store both of these links, other implementations may store typically the outgoing link and use OSLC Query or other mechanisms to get incoming links.

With the introduction of OSLC Configuration Management, the simple technique of storing redundant backlinks becomes problematic for maintaining data consistency and is not recommended. Project Note OSLC Link Guidance recommends storing the link on only one side and using some mechanism to query incoming links from the other direction. One approach in common practice is to use OSLC query where a client queries each of its related servers for incoming links. While this peer-to-peer query addresses the fundamental issues of getting incoming links without storing redundant backlinks, it does not scale or perform well in situations with more than a small number of related providers.

A more scalable approach that has been practiced by several implementors such as IBM ELM and MID Smartfacts, is to manage a centralized link discovery service that enables OSLC clients to discover incoming links. For example, a requirements management (RM) application can display incoming links to specific requirement resources from test cases stored in a QM application. To an end user the incoming links are essential to carry out various lifecycle activities, such as understanding coverage and/or impact of a set of requirements.

OSLC link Discovery Management is an OSLC specification that defines a standard means for client applications to discover incoming and optionally outgoing links to/from resources. This specification follows existing practices for incoming links discovery and specifies the following services:

How to inquire incoming and optionnally outgoing links to resources for a provided set of resource URIs.
Incoming links service providers may operate in configuration enabled contexts, returning incoming and outgoing as concept URIs resolved to versions using a Configuration-Context.
A means of discovering service providers that contribute links to an LDM server.

A common way of ingesting and maintaining a link index to support the inquiries uses already standardized OSLC Tracked Resource Sets [[OSLCTRS]]. However, this specification does not specify how link discovery services ingest data from the various lifecycle providers, to support the link discovery services. LDM Server implementations may use any means for populating their required content.

This specification is a [[!OSLCCore3]] compliant specification, and as such most of its content are references to [[!OSLCCore3]].

Terminology

Link: An assertion or RDF triple consisting of a (subject, predicate, object) that manifests an instance of a relationship between the referenced subject and object OSLC resources. The subject in the triple is often referred to as the source resource of the Link. The object in the triple if often referred to as the target resource of the Link.
Link Type: The predicate or RDF property of a Link.
Incoming Links: All Links matching set of Link predicates and target (object) resources, i.e., (?, predicate, object) triples, the links where the given resources are objects of the predicates.
Outgoing Links: All Links matching a given set of source (subject) resources and Link predicates, i.e., (subject, predict, ?) triples, the links where the given resources are subjects of the predicates.
LDM Client: An implementation of an application that consumes services provided by LDM servers to discover the scope of available links, and incoming links to a particular set of target resources.
LDM Server: A server implementing the OSLC Link Discovery Management specification. OSLC LDM clients consume services provided by LDM Servers to discover incoming links. 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.

Base Requirements

The following sub-sections define the mandatory and optional requirements for an OSLC Link Discovery Management (LDM) server.

Base Compliance

This specification is based on [[!OSLCCore3]]. An OSLC LDM Server 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.

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

Requirement	Meaning
Absolute URIs	LDM Servers MUST use absolute URIs for all references to resources by properties
Resource Operations	LDM Servers MUST support resource operations via standard HTTP operations
Resource Paging	LDM Servers SHOULD provide resource paging, as defined in [[!OSLCCore3]]. In case resource paging is supported, stable paging is required. Note: as the LDM server implements a post-method as defined below, consider that instead of using oslc:nextPage in oslc:ResponseInfo, the use of oslc:postBody is required.
Discovery	The LDM Server URI is configured explicitly in each LDM client. Therefore, no dedicated discovery protocol is needed. Note: a scenario with multiple LDM Servers is possible, in which case multiple LDM Server URI are configured. This specification does not prescribe how these multiple LDM servers are managed together. A LDM Service SHOULD provide discovery of its link contributors via Service Provider Catalog which is pointing via `oslc:serviceProviderCatalog` to the contributing servers catalogs.
Authentication	LDM Services SHOULD follow the recommendations for Authentication specified in [[!OSLCCore3]].
Error Responses	LDM Servers SHOULD provide error responses using error formats as [[!OSLCCore3]]
RDF/XML Representations	LDM Servers MUST support RDF/XML and SHOULD support Turtle representations for OSLC Defined Resources
JSON+LD Representations	LDM Servers MAY support JSON+LD representations; those which do MUST conform to the OSLC Core Guidelines for JSON+LD

Specification Versioning

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

Resource Operations

LDM does not feature any resource operations other than retrieving a service provider catalog.

Authentication

See [[!OSLCCore3]], OSLC LDM puts no additional constraints on authentication. This specification, does not address access control for incoming and outgoing links in an LDM Server. LDM Servers may follow the access guidance provided in project note OSLC Tracked Resource Set Guidance Version 1.0, section Access Context Guidance.

Error Responses

The following error situations MUST be handled by an LDM Server. In case the error occurs, the subsequent oslc:error MUST be returned.

No Object resource provided
dcterms:identifier = “MissingObject” oslc:message = “No Object resource provided”

oslc:statusCode = 400 (Bad Request)
Too many Object resources requested An LDM Server MAY limit the amount of Object resources to be requested.
dcterms:identifier = “LimitReached” oslc:message = “Too many Object resources requested. Limit = $1” $1 = Maximum amount of Object concept resources

oslc:statusCode = 400 (Bad Request)
Concept resource requested for Object resource without specified Configuration Context
dcterms:identifier = “BadObjectRequest” oslc:message = “Concept resource requested for Object resource without specified Configuration Context”

oslc:statusCode = 400 (Bad Request)

Pagination

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

LDM Service Description

Discover links inquiry

LDM clients inquire for links related to a set of source resources, typically owned and/or visualized by the client. The discover links inquiry is exposed under the discover-links path as described in the open-API section below. For the links inquiry, the client provides:

Configuration Context: An optional URI of an OSLC configuration context for resolving concept URIs to version resources
Resources: One or more URIs of resources for which links are being requested
Link predicates: Zero or more URIs of OSLC link types (or RDF properties) that are being requested
Direction: optional parameter indicating incoming or any links should be returned, incominig is the default

In case the Configuration Context is specified, any object or subject-resource MUST be specified based on concept resources. The server MUST respond with a set of triples for the links, which are valid for the given Configuration Context. In case the Configuration Context is not specified, any object or subject-resource MUST be specified based on unversioned resources. The server MUST respond with a set of triples for the links, which are not bound to any Configuration Context. In case no predicates are provided, the server MUST provide all incoming links irrespective of their predicate.

The optional direction parameter is assumed by default to be "incoming". If the value of Direction is "any" the LDM server MUST include incoming and outgoing links are in the result.

The LDM Server response is a set of link triples consisting of

Subject resource: URI
Predicate: URI
should be one of the requested link predicates, in case specified
Object resource: URI
should be one of requested Object concept resources

If the direction is "incoming", object resource should be one of requested Object concept resource. If the direction is "any", the subject resource or object resource should match one of the resource URIs specified

In case of AdditionalResouceProperties predicates specified, LDM MAY return additional triples {subject, predicate, object} where {subject} is one of the subjects in the link triples, and predicate is one of the AdditionalResourceProperties predicates. LDM Servers MAY support additional properties, it is not an error if the client requests them and the LDM Server doesn't have them.

Based on the LDM Server response, the LDM Client would typically show the incoming link with an inverse link label (e.g., “validated by” vs. “validates”), for incoming links.

The inquiry MUST be implemented as an HTTP POST request, where the target concept resources and the predicates are provided with the request body.

The following LDM example illustrates an OSLC RM client that inquires incoming links to requirements req1 and req2 in configuration baseline1 with predicates oslc_cm:tracks and oslc_cm:implements

POST http://ldm.example.com:8080/
Content-Type: text/turtle
Configuration-Context: http://elm.example.com/gcm/baseline1URI
 
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix ldp: <http://www.w3.org/ns/ldp# >.
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix oslc_ldm: <http://open-services/net/ns/ldm#>.
 
_:b1 oslc_ldm:resources
    <http://example.org/rm/req1URI >, <http://example.org/rm/req2URI>.
 
_:b2 oslc_ldm: linkPredicates
    oslc_cm:implementsRequirement, oslc_cm:tracksRequirement .

Response (in turtle):

        HTTP/1.1 200 OK
        Content-Type: text/Turtle
        Configuration-Context: http://example.org/gcm/baseline1URI
        
        @prefix oslc_cm: <http://open-services.net/ns/cm#> .
        @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
        @prefix dcterms: <http://purl.org/dc/terms/> .
        
        <http://example.org/cm/changeRequest1> oslc_cm:tracksRequirement  <http://example.org/rm/req1URI> .
        <http://example.org/cm/changeRequest2>  oslc_cm:tracksRequirement  <http://example.org/rm/req1URI> .
        <http://example.org/cm/changeRequest3>  oslc_cm:implementsRequirement  <http://example.org/rm/req2URI> .

Example2: requesting all links

POST http://ldm.example.com:8080/
Content-Type: text/turtle
Configuration-Context: http://elm.example.com/gcm/baseline1URI
  
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix oslc_rm: <http://open-services.net/ns/rm#>.
@prefix oslc_ldm: <http://open-services/net/ns/ldm#>.
  
_:b1 oslc_ldm:resources
    <http://example.org/rm/req1URI >, <http://example.org/rm/req2URI>.
  
_:b2 oslc_ldm:linkPredicates
    oslc_cm:implementsRequirement, oslc_rm:satisfyRequirement .

_:b3 oslc_ldm:direction “any”.

_:b4 oslc_ldm:additionalProperties  
  dcterms:title .

Response (in turtle):

  HTTP/1.1 200 OK
  
  Content-Type: text/turtle
  Configuration-Context: http://elm.example.com/gcm/baseline1URI
   
  @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
  @prefix oslc_am: <http://open-services.net/ns/am#>. 
  @prefix oslc_cm: <http://open-services.net/ns/cm#>.
  
    
    <http://example.com/cm/resource/workitem1URI>
      oslc_cm:tracks <http://elm.example.com/rm/req1URI>; 
      oslc_cm:tracks <http://elm.example.com/rm/req2URI>.
    <http://elm.example.com/rm/req1URI> 
      oslc_rm:satisfy <http://elm.example.com/rm/req2URI>
   <http://example.com/am/am1URI>
      oslc_am:implements <http://elm.example.com/rm/req1URI>.

LDM contributions discovery

A LDM Service provides discovery of its link contributors via Service Provider Catalog which is pointing via oslc:serviceProviderCatalog to the contributing servers catalogs.

The link contributions discovery is exposed under the root-services path as described in the open-API section below.

OpenApi specification of the LDM service

LDM servers MUST implement the OpenAPI specification given in OSLC LDM Version 1.0: Part 2: Machine-readable OpenAPI yaml.