Need to agree on the LDM POST entity request and response body formats

[jamsden]

There a number of options for how to express the LDM entity request and response bodies. This issue explores the options through an example. Resolution of this issue will result in the proposed, reviewed, agreed and voted on option.

Updated LDM example

1. Use example.org to avoid any product biases
2. Use the proper oslc_cm implementsRequirement and tracksRequirement properties
3. Includes the result triples in an LDP container
4. Uses reified RDF statements for the result triples
5. Includes the missing subject URIs for the change requests that are the incoming links
6. Proposes to use text/turtle for the POST entity request body and demonstrates the required vocabulary
7. Added an example of an entity response body that has only link assertions, not LDP container
8. Corrected inconsistent use of example.org URLs in the example
9. Provided comparison of LDPC of reified statements vs. simple graph of incoming link assertions
10. Included an example of a SPQRL result set returned by IBM LDM
11. NEW: Added example content to request additional properties about a link that an LDM server may wish to support.
12. NEW: Included RDF/XML for the simple entity response body format

TLDNR> it appears that LDM entity response bodies do not require LDP containers or reification of statements, and can be returned as simple graphs of incoming link RDF triples.

EXAMPLE 1 - LDM Request

The current specification proposes to use application/x-www-form-urlencoded for the POST parameters:

POST http://ldm.example.com:8080/
Content-Type: application/x-www-form-urlencoded
Configuration-Context: http://elm.example.com/gcm/baseline1URI

objectConceptResources=http://example.org/rm/req1URI,http://example.org/rm/req2URI
predicateFilters=http://open-services.net/ns/cm#implementsRequiremenet,http://open-services.net/ns/cm#tracksRequirement

Using application/x-www-form-urlencoded for the POST entity request body has some issues:

1. It isn't easily extended
2. You can't specify prefixes and use namespaces in the URLs

The example below also shows an additional request property to allow the client to request properties about the link such as its title, and the title of the source resources.

Consider using RDF to specify the POST entity request body:

POST http://example.org/ldm
Content-Type: text/turtle
Configuration-Context: http://example.org/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/rdm#> .

_:b1 oslc_ldm:objectConceptResources
    <http://example.org/rm/req1URI>, <http://example.org/rm/req2URI> .

_:b2 oslc_ldm:predicateFilters
    oslc_cm:implementsRequirement, oslc_cm:tracksRequirement .

_:b3 oslc_ldm:linkProperties
    rdfs:label

_:b4 oslc_ldm:subjectProperties
    dcterms:title, dcterms:identifier

EXAMPLE 2 - LDM Response

HTTP/1.1 200 OK
Content-Type: text/turtle
Configuration-Context: http://example.org/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#> .

<http://example.org/ldm>
	a ldp:BasicContainer;
	ldp:contains 
		[ a rdf:Statement ;
		  rdf:subject <http://example.org/cm/changeRequest1> ;
		  rdf:predicate oslc_cm:tracksRequirement ;
		  rdf:object <http://example.org/rm/req1URI>],
		[ a rdf:Statement ;
		  rdf:subject <http://example/cm/changeRequest2> ;
		  rdf:predicate oslc_cm:tracksRequirement ;
		  rdf:object <http://example.org/rm/req1URI>],
		[ a rdf:Statement ;
		  rdf:subject <http://example.org/cm/changeRequest3> ;
		  rdf:predicate oslc_cm:implementsRequirement ;
		  rdf:object <http://example.org/rm/req2URI> ;
		  rdfs:label "Impalements Requirement" ;
		  dcterms:title "Change Request number 3" ;
		  dcterms:identifier "3"].

Or more generally:

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix oslc_cm: <http://open-services.net/ns/cm#> .
@prefix ex: <http://example.org/>.

<#s1> a rdf:Statement ;
    rdf:subject <http://example.org/cm/changeRequest1> ;
    rdf:predicate oslc_cm:tracksRequirement ;
    rdf:object <http://example.org/rm/req1URI> .

<#s2> a rdf:Statement ;
    rdf:subject <http://example.org/cm/changeRequest2> ;
    rdf:predicate oslc_cm:tracksRequirement ;
    rdf:object <http://example.org/rm/req1URI> .

<#s3> a rdf:Statement ;
    rdf:subject <http://example.org/cm/changeRequest3> ;
    rdf:predicate oslc_cm:implementsRequirement ;
    rdf:object <http://example.org/rm/req2URI> ;
    rdfs:label "Impalements Requirement" ;
    dcterms:title "Change Request number 3" ;
    dcterms:identifier "3" .

<http://example.com/ldm>
   a ldp:BasicContainer;
   ldp:contains <#s1>, <#s2>, <#s3> .

Or returning simple triples:

@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> .
oslc_cm:implementsRequirement   rdfs:label "Impalements Requirement" .
<http://example.org/cm/changeRequest3>  dcterms:title "Change Request number 3" .
<http://example.org/cm/changeRequest3>  dcterms:identifier "3" .

And in RDF/XML:

<?xml version="1.0" encoding="utf-8"?>
<rdf:RDF
	xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
	xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
	xmlns:dcterms="http://purl.org/dc/terms/"
	xmlns:oslc_cm="http://open-services.net/ns/cm#">

	<rdf:Description rdf:about="http://example.org/cm/changeRequest1">
		<oslc_cm:tracksRequirement rdf:resource="http://example.org/rm/req1URI"/>
	</rdf:Description>

	<rdf:Description rdf:about="http://example.org/cm/changeRequest2">
		<oslc_cm:tracksRequirement rdf:resource="http://example.org/rm/req1URI"/>
	</rdf:Description>

	<rdf:Description rdf:about="http://example.org/cm/changeRequest3">
		<oslc_cm:implementsRequirement rdf:resource="http://example.org/rm/req2URI"/>
		<dcterms:title>Change Request number 3</dcterms:title>
		<dcterms:identifier>3</dcterms:identifier>
	</rdf:Description>

	<rdf:Description rdf:about="http://open-services.net/ns/cm#implementsRequirement">
		<rdfs:label>Impalements Requirement</rdfs:label>
	</rdf:Description>
</rdf:RDF>

Note, you can see that the additional properties about the subject can be added to the statements, but the dcterms:title property is actually a property of the subject URL, not the statement. That is, these additional properties are not about the statement, they are about the link properties and subjects in the statement. The simpler assertions in. this case are actually more correct as they are asserting properties about the right subjects.

Representing a set of RDF assertions as an LDP (Linked Data Platform) collection of reified statements versus just using a graph of assertions depends on the specific requirements and goals of the data management and usage scenario Here are some considerations:

Using a Graph of Assertions
Preferred When:

Simplicity and Readability:

• The dataset is relatively straightforward, and the relationships between entities can be easily understood without additional metadata.
• Direct RDF assertions (triples) are sufficient to convey the necessary information.

Performance:

• You need to minimize complexity and overhead in data processing.
• Graph operations like querying, updating, and reasoning are more efficient with simple assertions.

Interoperability:

• The primary goal is to ensure broad compatibility with existing RDF tools and standards.
• Most RDF-based systems and applications readily support and understand simple RDF graphs.

No Need for Statement Metadata:

• There's no requirement to attach metadata (like provenance, confidence, or source) to individual statements.

Using LDP Collection of Reified Statements

Reification involves making statements about statements, which introduces additional complexity. LDP collections can help manage this complexity in a structured manner.

Preferred When:

Metadata on Statements:

• You need to attach metadata to individual RDF assertions. For example, stating who made the assertion, when it was made, or the confidence level of the assertion.
• Reification allows you to provide this extra layer of information, which is crucial for applications like data provenance, trust management, and data auditing.

Versioning and Tracking Changes:

• Managing changes over time requires tracking the history of assertions and their modifications.
• An LDP collection of reified statements can help organize and manage these historical records effectively.

Complex Query Requirements:

• Complex queries that involve not just the data but also its metadata (e.g., querying assertions by their provenance or source) can be better managed with reified statements.
• LDP provides a framework for organizing these reified statements, making it easier to construct and execute such queries.

Integration with LDP Services:

• If you are using or planning to use LDP services for managing linked data resources, representing RDF assertions as LDP collections aligns with the LDP standards.
• This allows leveraging LDP’s capabilities for resource creation, modification, and deletion, and its support for various interaction patterns.

Summary

• Graph of Assertions: Best for simpler datasets where direct assertions suffice, focusing on performance and interoperability.
• LDP Collection of Reified Statements: Suitable for complex scenarios requiring metadata on assertions, detailed provenance, versioning, and integration with LDP services.

In essence, if your application demands detailed metadata about individual statements or requires advanced data management features provided by LDP, using a collection of reified statements is preferred. For straightforward datasets where simplicity and performance are paramount, a simple graph of assertions is more appropriate.

Neither of these are required by LDM entity response bodies. So the simple graph of incoming triples seems sufficient for the LDM entity response body

IBM Link Discovery Index (LDX)

IBM LDX LinkQueryResults.java is an array of LinkTriples that are returned in a JSON array that is not the same as reified RDF statements in an LDP container, but it is conceptually similar. The format is a SPARQL result set in JSON.

Result JSON” {
  "head": {
    "vars": [
      "sURL",
      "linkType",
      "tURL"
    ]
  },
  "results": {
    "bindings": [
      {
        "sURL": {
          "type": "uri",
          "value": " https://localhost:9443/qm/oslc_qm/contexts/_dZylobPvEe6OrPSlucpNjQ/resources/com.ibm.rqm.planning.VersionedTestCase/_3xFFobPzEe6OrPSlucpNjQ"
        },
        "linkType": {
          "type": "uri",
          "value": " http://open-services.net/ns/qm#validatesRequirement"
        },
        "tURL": {
          "type": "uri",
          "value": " https://localhost:9443/rm/resources/TX_B7TawbPwEe6NWuFoI0l_YA"
        }
      },
      {
        "sURL": {
          "type": "uri",
          "value": " https://localhost:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/145"
        },
        "linkType": {
          "type": "uri",
          "value": " http://open-services.net/ns/cm#implementsRequirement"
        },
        "tURL": {
          "type": "uri",
          "value": " https://localhost:9443/rm/resources/TX_B7TawbPwEe6NWuFoI0l_YA"
        }
      }
    ]
  }
 }