From a9ca514a8402434d8384fbe8dea2f3806d7c1b69 Mon Sep 17 00:00:00 2001
From: Jim Amsden <jimamsden@gmail.com>
Date: Thu, 21 Nov 2024 08:22:22 -0500
Subject: [PATCH] Initial review updates of LDM Specification

More changes are needed: Possibly remove Direction, define the vocabulary terms used in the POST entity request body, clarify config aware is optional in the intro, further considerations on authentication, support for additional properties is optional
---
 specs/ldm/link-discovery-management-spec.html | 252 ++++++++----------
 1 file changed, 109 insertions(+), 143 deletions(-)

diff --git a/specs/ldm/link-discovery-management-spec.html b/specs/ldm/link-discovery-management-spec.html
index 426efb0..a7f0ba2 100644
--- a/specs/ldm/link-discovery-management-spec.html
+++ b/specs/ldm/link-discovery-management-spec.html
@@ -5,8 +5,8 @@
     <title>OSLC Link Discovery Management Version 1.0. Part 1: Specification</title>
     <meta
       name="description"
-      content="This specification defines the OSLC Link Discovery Management, a RESTful web
-services interface for discovering incoming links."
+      content="This specification defines OSLC Link Discovery Management, a RESTful web
+services interface for an application to discover incoming links."
     />
 
     <script
@@ -16,7 +16,7 @@
     ></script>
     <script class="remove">
       var status = "PSD";
-      var revision = 1;
+      var revision = 2;
 
       var wdBase = "https://oslc-op.github.io/oslc-specs/specs/ldm/";
       var oasisBase = "https://docs.oasis-open-projects.org/oslc-op/ldm/v1.0/";
@@ -44,8 +44,8 @@
         ],
 
         publishDate: "2023-12-21T12:00Z",
-        //previousPublishDate: "2021-09-30",
-        //previousMaturity: "PS",
+        previousPublishDate: "2023-12-21T12:00Z",
+        previousMaturity: "PSD",
 
         thisVersion: thisBase + "link-discovery-management-spec.html",
         prevVersion: "",
@@ -93,15 +93,15 @@
         chairs: [
           {
             name: "Jim Amsden",
-            mailto: "jamsden@us.ibm.com",
-            company: "IBM",
-            companyURL: "http://www.ibm.com/",
+            mailto: "jimamsden@gmail.com",
+            company: "",
+            companyURL: "",
           },
           {
             name: "Jad El-khoury",
-            mailto: "jad@kth.se",
-            company: "KTH",
-            companyURL: "https://www.kth.se/en",
+            mailto: "jad.elkhoury@lynxwork.com",
+            company: "LYNXWORK",
+            companyURL: "https://lynxwork.com",
           },
         ],
 
@@ -110,35 +110,20 @@
         wgShortName: "oslc-op",
 
         // Namespaces defined by this TC
-        namespaces: [{ href: "http://open-services.net/ns/core/am#", prefix: "oslc_am" }],
+        namespaces: [],
 
         localBiblio: {
-          OSLCAM2: {
-            title: "OSLC Architecture Management Specification Version 2.0",
-            href:
-              "http://open-services.net/wiki/architecture-management/OSLC-Architecture-Management-Specification-Version-2.0/",
-            authors: ["Jim Conallen"],
-            status: "Finalized",
-            publisher: "https://open-services.net/",
-          },
-          OSLCCore2: {
-            title: "OSLC Core Specification 2.0",
-            href: "https://archive.open-services.net/bin/view/Main/OslcCoreSpecification",
-            authors: ["Dave Johnson", "S. Speicher"],
-            status: "Finalized",
-            publisher: "https://open-services.net/",
-          },
           OSLCCore3: {
             title: "OSLC Core Version 3.0. Part 1: Overview",
             href: "https://docs.oasis-open-projects.org/oslc-op/core/v3.0/oslc-core.html",
             authors: ["Jim Amsden", "S. Speicher"],
-            status: "Project Specification Draft",
+            status: "OASIS Standard",
             publisher: "OASIS",
           },
           OSLCPreview: {
             title: "OSLC Core Version 3.0. Part 3: Resource Preview0",
             href: "https://docs.oasis-open-projects.org/oslc-op/core/v3.0/resource-preview.html",
-            status: "Project Specification Draft",
+            status: "OASIS Standard",
             publisher: "OASIS",
           },
           DublinCore: {
@@ -203,7 +188,7 @@
             title: "OSLC Core Version 3.0. Part 7: Vocabulary",
             href: "https://docs.oasis-open-projects.org/oslc-op/core/v3.0/core-vocab.html",
             authors: ["Jim Amsden", "S. Padgett", "S. Speicher"],
-            status: "Project Specification Draft",
+            status: "OASIS Standard",
             publisher: "OASIS",
           },
           OpenIDConnect: {
@@ -215,35 +200,28 @@
             title: "OSLC Core Version 3.0. Part 6: Resource Shape",
             href: "https://docs.oasis-open-projects.org/oslc-op/core/v3.0/resource-shape.html",
             authors: ["Arthur Ryman", "Jim Amsden"],
-            status: "Project Specification Draft",
+            status: "OASIS Standard",
             publisher: "OASIS",
           },
-          OSLCRM20: {
-            title: "Open Services for Lifecycle Collaboration Requirements Management Specification Version 2.0",
-            href: "https://archive.open-services.net/bin/view/Main/RmSpecificationV2",
-            authors: ["Ian Green"],
-            status: "Finalized",
-            publisher: "https://open-services.net",
-          },
-          OSLCCM20: {
-            title: "Open Services for Lifecycle Collaboration Change Management Specification Version 2.0",
-            href: "https://archive.open-services.net/bin/view/Main/CmSpecificationV2",
-            authors: ["Steve Speicher"],
-            status: "Finalized",
-            publisher: "https://open-services.net",
+          OSLCQuery: {
+            title: "OSLC Query Version 3.0",
+            href: "https://docs.oasis-open-projects.org/oslc-op/query/v3.0/oslc-query.html",
+            authors: ["David Honey", "Jim Amsden"],
+            status: "OASIS Standard",
+            publisher: "OASIS",
           },
-          OSLCRM: {
-            title: "OSLC Requirements Management Version 2.1. Part 1: Specification",
-            href: "https://open-services.net/spec/rm/latest",
-            authors: ["Ian Green", "Jad El-khoury"],
-            status: "Project Specification Draft",
+          OSLCTRS: {
+            title: "OSLC Tracked Resource Set Version 3.0. Part 1: Specification",
+            href: "https://docs.oasis-open-projects.org/oslc-op/trs/v3.0/tracked-resource-set.html",
+            status: "OASIS Standard",
+            authors: ["Steve Speicher", "Frank Budinsky", "Vivek Garg", "Nick Crossley"],
             publisher: "OASIS",
           },
-          OSLCQM: {
-            title: "OSLC Quality Management 2.1. Part 1: Specification",
-            href: "https://open-services.net/spec/qm/latest",
-            authors: ["Paul McMahan", "Jim Amsden", "Gray Bachelor"],
-            status: "Project Specification Draft",
+          OSLCConfig: {
+            title: "OSLC Configuration Management Version 1.1. Part 1: Overview",
+            href: "https://docs.oasis-open-projects.org/oslc-op/config/v1.1/oslc-config-mgt.html",
+            status: "OASIS Standard",
+            authors: ["Nick Crossley"],
             publisher: "OASIS",
           },
         },
@@ -274,7 +252,8 @@ <h2>Introduction</h2>
       </p>
       <p>
         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
+        becomes problematic for maintaining data consistency and is not recommended. Project Note <a href="https://docs.oasis-open-projects.org/oslc-op/link-guidance/v1.0/link-guidance.html">
+        OSLC Link Guidance</a> 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
@@ -289,25 +268,25 @@ <h2>Introduction</h2>
         lifecycle activities, such as understanding coverage and/or impact of a set of requirements.
       </p>
       <p>
-        OSLC link Discovery Management is an OSLC specification defines a standard means for client applications to
+        OSLC link Discovery Management is an OSLC specification that 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:
       </p>
       <ul>
         <li>
-          How to inquire incoming links to versioned resources for a provided set of (displayed) concept resource URIs
+          How to inquire incoming links to versioned resources for a provided set of concept resource URIs
           and a given configuration context
         </li>
         <li>
           Incoming links service providers operate in configuration enabled contexts. Therefore, the incoming link
-          inquiries shall specify configuration contexts for the links
+          inquiries specify configuration contexts for the links
         </li>
         <li>A means of discovering service providers that contribute links to an LDM server.</li>
       </ul>
       <p>
         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]
+        to support the inquiries uses already standardized OSLC Tracked Resource Sets [[OSLCTRS]]
       </p>
       <p>
         This specification is a [[!OSLCCore3]] compliant specification, and as such most of its content are references
@@ -320,7 +299,7 @@ <h3>Terminology</h3>
           <dt><dfn>Link</dfn></dt>
           <dd>
             An assertion or RDF triple consisting of a (subject, predicate, object) that manifests an instance of a
-            relationship between the referenced subject and object.
+            relationship between the referenced subject and object OSLC resources.
           </dd>
 
           <dt>LDM Client</dt>
@@ -337,22 +316,6 @@ <h3>Terminology</h3>
             particular application component could be a client for some OSLC domain services and a server for the same
             or another domain.
           </dd>
-          <dt>Concept Resource</dt>
-          <dd>
-            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]
-          </dd>
-
-          <dt>Versioned Resource</dt>
-          <dd>
-            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]
-          </dd>
         </dl>
       </section>
       <section id="conventions"></section>
@@ -362,14 +325,14 @@ <h3>Terminology</h3>
       <h2>Base Requirements</h2>
 
       <p>
-        The following sub-sections define the mandatory and optional requirements for an OSLC Architecture Management
-        (OSLC AM) server.
+        The following sub-sections define the mandatory and optional requirements for an OSLC Link Discovery Management
+        (LDM) server.
       </p>
 
       <section id="baseCompliance">
         <h2>Base Compliance</h2>
         <p class="conformance">
-          This specification is based on [[!OSLCCore3]]. OSLC LDM servers MUST be compliant with both the core
+          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.
         </p>
@@ -377,7 +340,7 @@ <h2>Base Compliance</h2>
         <p>
           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
+          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.
         </p>
 
@@ -402,7 +365,7 @@ <h2>Base Compliance</h2>
             <tr>
               <td>Resource Paging</td>
               <td class="conformance">
-                LDM Servers SHOULD provide resource paging, as defined in [OSLC-Core-3.0-Part1]. In case 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.
@@ -411,11 +374,11 @@ <h2>Base Compliance</h2>
             <tr>
               <td>Discovery</td>
               <td class="conformance">
-                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
+                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.
+                which is pointing via <code>oslc:serviceProviderCatalog</code> to the contributing servers catalogs.
               </td>
             </tr>
             <tr>
@@ -427,7 +390,7 @@ <h2>Base Compliance</h2>
             <tr>
               <td>Error Responses</td>
               <td class="conformance">
-                LDM Servers SHOULD provide error responses using OSLC Core defined error formats
+                LDM Servers SHOULD provide error responses using error formats as [[!OSLCCore3]]
               </td>
             </tr>
             <tr>
@@ -457,7 +420,7 @@ <h2>Resource Operations</h2>
 
         <p>
           LDM does not feature any resource operations other than retrieving a service provider catalog. LDM services
-          return results in LDP containers.
+          return incoming link results in LDP containers.
         </p>
       </section>
 
@@ -471,8 +434,8 @@ <h2>Authentication</h2>
         <h2>Error Responses</h2>
 
         <p class="conformance">
-          The following error situations MUST be handled by the LDM-Server. In case the error occurs, the subsequent
-          oslc:error SHALL be returned.
+          The following error situations MUST be handled by an LDM Server. In case the error occurs, the subsequent
+          oslc:error MUST be returned.
         </p>
         <ul>
           <li>
@@ -485,7 +448,7 @@ <h2>Error Responses</h2>
             </p>
           </li>
           <li class="conformance">
-            Too many Object resources requested The LDM-Server MAY limit the amount of Object resources to be requested.
+            Too many Object resources requested An LDM Server MAY limit the amount of Object resources to be requested.
             <p>
               dcterms:identifier = “LimitReached” oslc:message = “Too many Object resources requested. Limit = $1” $1 =
               Maximum amount of Object concept resources
@@ -520,36 +483,41 @@ <h2>Pagination</h2>
       <h2>LDM Service Description</h2>
       <h3>Discover links inquiry</h3>
       <p>
-        LDM clients inquire for links related to a set of resources, typically owned and/or
+        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:
+        the open-API section below. For the links inquiry, the client provides:
       </p>
       <ul>
         <li>
-          Configuration Context [0..1]: URI
+          Configuration Context: An optional URI of an OSLC configuration context for resolving concept URIs to version resources
         </li>
         <li>
-          Resource [0..*]: URI
+          Resources: Zero or more URIs of source resources for which incoming links are being requested
         </li>
         <li>
-          Link predicates [0..*]: URI
+          Link predicates: Zero or more URIs of OSLC link types (or RDF properties) that are being requested
         </li>
         <li>
-          Direction [0..1]: String    
+          Direction: optional parameter indicating incoming or any links should be returned, incominig is the default
         </li>
         <li>
-          AdditionalResourceProprties [0..*]: URI    
+          AdditionalResourceProperties: URIs of additional properties the LDM Client is requesting the LDM Server return
+          about the objects of the incoming links. This is a convenience for LDM Clients who might need additional
+          information like title and icon to for example display incoming links, and avoids additionl resource GET requests.    
         </li>
       </ul>
       <p class="conformance">
-        In case the Configuration Context is specified, any object- or subject-resource shall be specified based on
+        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
-        shall be specified based on unversioned resources. the server MUST respond with a set of triples for the
-        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
+        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". Another possible value "any".
+        </p>
+        <p class="conformance">
+        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.
+        </p>
       </p>
       <p>
         The LDM Server response is a set of link triples consisting of
@@ -577,12 +545,14 @@ <h3>Discover links inquiry</h3>
       </p>
       <p class="conformance">
         In case of AdditionalResouceProperties predicates specified, LDM may return additional triples {subject, predicate, object} 
-        where {subject} needs to be one of the subjects in the link triples, and predicate should be one of the 
-        AdditionalResourceProperties predicates. 
+        where {subject} is one of the subjects in the link triples, and predicate is one of the 
+        AdditionalResourceProperties predicates. LDM Servers MAY support some AdditionalResourceProperties. 
       </p>
-      <p class="conformance">
-        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”), for incoming links. The inquiry MUST be implemented as an HTTP post request,
+      <p>
+        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.</p>
+        <p class="conformance">
+        The inquiry MUST be implemented as an HTTP POST request,
         where the target concept resources and the predicates are provided with the request body.
       </p>
       <p>
@@ -590,10 +560,8 @@ <h3>Discover links inquiry</h3>
         req2 in configuration baseline1 with predicates oslc_cm:tracks and oslc_cm:implements
       </p>
       <pre class="example">
-        POST http://ldm.example.com:8080/
-
+POST http://ldm.example.com:8080/
 Content-Type: text/turtle
-
 Configuration-Context: http://elm.example.com/gcm/baseline1URI
  
 @prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
@@ -613,20 +581,20 @@ <h3>Discover links inquiry</h3>
       </p>
   
       <pre class="example">
-        HTTP/1.1 200 OK
-
-        Content-Type: text/turtle
-         
-        @prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
-        @prefix oslc_am: &lt;http://open-services.net/ns/am# . 
-        @prefix oslc_cm: &lt;http://open-services.net/ns/cm#&gt;.
-        
-          
-          &lt;http://example.com/cm/resource/workitem1URI&gt;
-            oslc_cm:tracks &lt;http://elm.example.com/rm/req1URI&gt;; 
-            oslc_cm:tracks &lt;http://elm.example.com/rm/req2URI&gt;.
-          &lt;http://example.com/am/am1URI&gt;
-            oslc_am:implements &lt;http://elm.example.com/rm/req1URI&gt;.
+HTTP/1.1 200 OK
+
+Content-Type: text/turtle
+  
+@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
+@prefix oslc_am: &lt;http://open-services.net/ns/am# . 
+@prefix oslc_cm: &lt;http://open-services.net/ns/cm#&gt;.
+
+  
+  &lt;http://example.com/cm/resource/workitem1URI&gt;
+    oslc_cm:tracks &lt;http://elm.example.com/rm/req1URI&gt;; 
+    oslc_cm:tracks &lt;http://elm.example.com/rm/req2URI&gt;.
+  &lt;http://example.com/am/am1URI&gt;
+    oslc_am:implements &lt;http://elm.example.com/rm/req1URI&gt;.
        
   </pre>
 
@@ -635,28 +603,26 @@ <h3>Discover links inquiry</h3>
  </p>
   
   <pre class="example">
-  POST http://ldm.example.com:8080/
-  
-  Content-Type: text/turtle
+POST http://ldm.example.com:8080/
+Content-Type: text/turtle
+Configuration-Context: http://elm.example.com/gcm/baseline1URI
   
-  Configuration-Context: http://elm.example.com/gcm/baseline1URI
-   
-  @prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
-  @prefix dcterms: &lt;http://purl.org/dc/terms/>.
-  @prefix oslc_cm: &lt;http://open-services.net/ns/cm#&gt;.
-  @prefix oslc_rm: &lt;http://open-services.net/ns/rm#&gt;.
-  @prefix oslc_ldm: &lt;http://open-services/net/ns/ldm#&gt;.
-   
-  _:b1 oslc_ldm:resources
-      &lt;http://example.org/rm/req1URI &gt;, &lt;http://example.org/rm/req2URI&gt;.
-   
-  _:b2 oslc_ldm:linkPredicates
-      oslc_cm:implementsRequirement, oslc_rm:satisfyRequirement .
+@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
+@prefix dcterms: &lt;http://purl.org/dc/terms/>.
+@prefix oslc_cm: &lt;http://open-services.net/ns/cm#&gt;.
+@prefix oslc_rm: &lt;http://open-services.net/ns/rm#&gt;.
+@prefix oslc_ldm: &lt;http://open-services/net/ns/ldm#&gt;.
   
-  _:b3 oslc_ldm:direction “any”.
+_:b1 oslc_ldm:resources
+    &lt;http://example.org/rm/req1URI &gt;, &lt;http://example.org/rm/req2URI&gt;.
   
-  _:b4 oslc_ldm:additionalProperties  
-    dcterms:title .
+_:b2 oslc_ldm:linkPredicates
+    oslc_cm:implementsRequirement, oslc_rm:satisfyRequirement .
+
+_:b3 oslc_ldm:direction “any”.
+
+_:b4 oslc_ldm:additionalProperties  
+  dcterms:title .
 
   </pre>
   <p>