Notices
Copyright ©
OASIS Open
2023.
All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the
OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy").
The full Policy
may be found at the OASIS website.
This specification is published under the Attribution 4.0 International (CC BY 4.0).
Portions of this specification are also provided under the Apache License 2.0.
All contributions made to this project have been made under the
OASIS Contributor License Agreement (CLA).
For information on whether any patents have been disclosed that may be essential to implementing this specification,
and any offers of patent licensing terms,
please refer to the
Open Projects IPR Statements page.
This document and translations of it may be copied and furnished to others,
and derivative works that comment on or otherwise explain it or assist in its implementation
may be prepared, copied, published, and distributed, in whole or in part,
without restriction of any kind, provided that the above copyright notice
and this section are included on all such copies and derivative works.
However, this document itself may not be modified in any way,
including by removing the copyright notice or references to OASIS,
except as needed for the purpose of developing any document or deliverable
produced by an OASIS Open Project or OASIS Technical Committee
(in which case the rules applicable to copyrights,
as set forth in the OASIS IPR Policy, must be followed)
or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS
or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis
and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY
THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims
that would necessarily be infringed by implementations of this OASIS Project Specification
or OASIS Standard, to notify the OASIS TC Administrator and provide an indication of its
willingness to grant patent licenses to such patent claims in a manner consistent with the
IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership
of any patent claims that would necessarily be infringed by implementations of this specification
by a patent holder that is not willing to provide a license to such patent claims in a manner
consistent with the IPR Mode of the OASIS Open Project that produced this specification.
OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property
or other rights that might be claimed to pertain to the implementation or use of
the technology described in this document or the extent to which any license under
such rights might or might not be available;
neither does it represent that it has made any effort to identify any such rights.
Information on OASIS' procedures with respect to rights in any document or deliverable
produced by an OASIS Technical Committee can be found on the OASIS website.
Copies of claims of rights made available for publication and any assurances of licenses
to be made available, or the result of an attempt made to obtain a general license
or permission for the use of such proprietary rights by implementers or users of this
OASIS Open Project Specification or OASIS Standard, can be obtained from the OASIS TC Administrator.
OASIS makes no representation that any information or list of intellectual property rights
will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS,
the owner and developer of this specification,
and should be used only to refer to the organization and its official outputs.
OASIS welcomes reference to, and implementation and use of, specifications,
while reserving the right to enforce its marks against misleading uses. Please see
https://www.oasis-open.org/policies-guidelines/trademark/
for above guidance.
1. Introduction
This section is non-normative.
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 or implementedBy. Some implementations may choose to store both of these
links, other implementations may store one 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 is not recommended. 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 defines a standard means for client applications to
discover incoming links to resources. This specification follows existing practices for incoming links discovery
and specifies the following services:
-
How to inquire incoming links to versioned resources for a provided set of (displayed) concept resource URIs
and a given configuration context
-
Incoming links service providers operate in configuration enabled contexts. Therefore, the incoming link
inquiries shall specify configuration contexts for the links
- A means of discovering service providers that contribute links to an LDM server.
The specification does not specify how link discovery services ingest data from the various lifecycle providers,
in order to effectively support the inquiries. That said, a common way of ingesting and maintaining a link index
to support the inquiries uses already standardized OSLC Tracked Resource Sets [OSLC-TRS-v3.0]
This specification is a [OSLCCore3] compliant specification, and as such most of its content are references
to [OSLCCore3].
1.1 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.
- 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.
- Concept Resource
-
An artifact (a requirement, test case, source code file, etc.) as an overall entity, independent of any
specific version of that artifact. In Product Lifecycle Management (PLM) systems, this is often referred to
as a 'master' item or part, of which there are revisions and versions or iterations. As defined in
[OSLC-Config-1.0-Part1]
- Versioned Resource
-
The state (including the properties) of a concept resource can vary over time, or for other reasons. A
versioned resource is a concept resource that keeps track of different states. A version resource is a
resource that represents one specific state of a versioned resource. Not every past state is necessarily
kept; a server may elide or discard states that are no longer referenced. As defined in
[OSLC-Config-1.0-Part1]
1.2 Typographical Conventions and Use of RFC Terms
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
and notes in this specification are non-normative. Everything else in this specification is
normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL"
in this specification are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
2. Base Requirements
The following sub-sections define the mandatory and optional requirements for an OSLC Architecture Management
(OSLC AM) server.
2.1 Base Compliance
This specification is based on [OSLCCore3]. OSLC LDM 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.
[LDM-1]
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 the previous 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
[LDM-2] |
| Resource Operations |
LDM Servers MUST support resource operations via standard HTTP operations [LDM-3] |
| Resource Paging |
LDM Servers SHOULD provide resource paging, as defined in [OSLC-Core-3.0-Part1]. 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.
[LDM-4] |
| Discovery |
LDM Service 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 Service
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.
[LDM-5] |
| Authentication |
LDM Services SHOULD follow the recommendations for Authentication specified in [OSLCCore3]
[LDM-6] |
| Error Responses |
LDM Servers SHOULD provide error responses using OSLC Core defined error formats
[LDM-7] |
| RDF/XML Representations |
LDM Servers MUST support RDF/XML and SHOULD support Turtle representations for OSLC Defined Resources
[LDM-8] |
| JSON+LD Representations |
LDM Servers MAY support JSON+LD representations; those which do MUST conform to the OSLC Core Guidelines
for JSON+LD
[LDM-9] |
2.2 Specification Versioning
This specification follows the specification version guidelines given in [OSLCCore3].
2.3 Resource Operations
LDM does not feature any resource operations other than retrieving a service provider catalog. LDM services
return results in LDP containers.
2.4 Authentication
See [OSLCCore3], OSLC LDM puts no additional constraints on authentication.
2.5 Error Responses
The following error situations MUST be handled by the LDM-Server. In case the error occurs, the subsequent
oslc:error SHALL be returned.
[LDM-10]
-
No Object resource provided
dcterms:identifier = “MissingObject” oslc:message = “No Object resource provided”
oslc:statusCode = 400 (Bad Request)
-
Too many Object resources requested The 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)
[LDM-11]
-
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)
3. LDM Service Description
Discover links inquiry
LDM clients inquire for incoming links related to a set of target object 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 incoming links inquiry, the client provides:
-
Configuration Context [0..1]: URI
-
Object resource [0..*]: URI
-
Incoming link predicates [0..*]: URI
In case the Configuration Context is specified, any object- or subject-resource shall be specified based on
concept resources. The server MUST respond with a set of triples for the incoming links, which are valid for the
given Configuration Context. In case the Configuration Context is not specified, any object- or subject-resource
shall be specified based on unversioned resources. the server MUST respond with a set of triples for the
incoming links, which are not bound to a Configuration Context. Rationale: to support bidirectionality for
non-configuration aware links In case no predicates are provided, the server MUST provide all incoming links
irrespective of their predicate.
[LDM-13]
The LDM Server response is a set of triples consisting of
-
Subject resource: URI
-
Predicate: URI
should be one of the requested predicates, in case specified
-
Object resource: URI
should be one of requested Object concept resources
Based on the LDM service response, the LDM client would typically show the incoming link with an inverse
predicate label (e.g., “validated by” vs. “validates”). The inquiry MUST be implemented as an HTTP post request,
where the target concept resources and the predicates are provided with the request body.
[LDM-14]
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
Example 1
POST http://ldm.example.com:8080/
Content-Type: application/x-www-form-urlencoded
Configuration-Context: http://elm.example.com/gcm/baseline1URI
objectConceptResources=http://elm.example.com/rm/req1URI,http://elm.example.com/rm/req2URI
predicateFilters=http:// elm.example.com/implementsURI, http://elm.example.com/tracksURI
Response (in turtle):
Example 2
HTTP/1.1 200 OK
Content-Type: application/turtle
oslc_cm:implements http://elm.example.com/rm/req1URI
oslc_cm:tracks http://elm.example.com/rm/req1URI.
oslc_cm:tracks http://elm.example.com/rm/req2URI.
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.
