HTTP REQUEST ACCESS

Abstract

In [RML-IO] source and target access descriptions are complemented with external (existing or custom) vocabulary.

The [RML-IO] specification includes several examples of modelling access to web resources with an external vocabulary (DCAT dataset, SPARQL endpoint, WoT...). Because the [RML-IO] specification only includes examples, it does not specify the expected shape per access description or other guidelines to secure an unambiguous implementation by RML processors.

This specification specifies an access description to a web resource, modelled as a simplified HTTP request with optional authentication. The configuration options are intentionally minimized to secure a straightforward implementation by RML processors.

This specification is use-case driven. It was developed to support to access to resources on a Solid pod [Solid], but supports also access to other web resources without having the ambition to cover all cases. It can be extended to cover other use cases, e.g., with additional authentication descriptions.

Prefix	Namespace
`rml:`	http://w3id.org/rml/
`rmle:`	https://rml.io/ns/extensions#
`htv:`	http://www.w3.org/2011/http#
`formats:`	https://www.w3.org/ns/formats/
`ex:`	http://example.org/
`foaf:`	http://xmlns.com/foaf/0.1/

This specification describes the [RML-IO] access to a web resource, modelled as a simplified HTTP request with optional authentication. The configuration of the HTTP request is restricted to the properties defined in this specification, to limit the needed implementation by an RML processor. The specification reuses the HTTP Vocabulary in RDF 1.0, defines defaults and adds custom vocabulary for access to auxiliary resources and for authentication. The access description complements the description of a source (rml:source) or a target (rml:target).

An HTTP request (rmle:HttpRequest) an abstract construct describing how a web resource must be accessed by an RML processor, both for source and target.

A HTTP request is a subclass of a request (htv:Request) as specified in the HTTP Vocabulary in RDF 1.0, represented by a resource that MUST contain:

zero or one method name properties (htv:methodName), whose value is a literal denoting the HTTP method name,
zero or one user authentication properties (rmle:userAuthentication), whose value is an user authentication,
zero or one accept header properties (rmle:acceptHeader), whose value is a literal denoting the value for the Accept` header,
zero or one content-type header properties (rmle:contentTypeHeader), whose value is a literal denoting the value for the Content-Type header.

The accept header and the content-type header properties are shortcuts for the nested header description in HTTP Vocabulary in RDF 1.0, as exemplified below.

<#request1> rmle:acceptHeader "text/plain".
# is a shortcut for
<#request1> htv:headers [
  a htv:RequestHeader ;
  htv:fieldName "Accept" ;
  htv:fieldValue "text/plain" ;
  htv:hdrName <http://www.w3.org/2011/http-headers#accept> ;
 ] .

<#request2> rmle:contentTypeHeader "text/turtle".
# is a shortcut for
<#request2> htv:headers [
  a htv:RequestHeader ;
  htv:fieldName "Content-type" ;
  htv:fieldValue "text/turtle" ;
  htv:hdrName <http://www.w3.org/2011/http-headers#content-type> ;
 ] .

When the HTTP request complements the description of a source, the body of the response after its execution contains the data for the source.

If unspecified, the method name is by default "GET".

If unspecified, the accept header is by default derived from the reference formulation (rml:referenceFormulation) of the logical source (rml:LogicalSource) in which it is contained, following the table below:

reference formulation	accept header
`rml:CSV`	`text/plain`
`rml:JSONPath`	`application/json`
`rml:XPath`	`application/xml`
`rml:XPathReferenceFormulation`	`application/xml`
`formats:SPARQL_Results_CSV`	`text/plain`
`formats:SPARQL_Results_TSV`	`text/plain`
`formats:SPARQL_Results_JSON`	`application/json`
`formats:SPARQL_Results_XML`	`application/xml`

When the HTTP request is used to complement the description of a target, the body of the HTTP request contains the generated RDF.

If unspecified, the method name is by default "PUT".

If unspecified, the content-type header is by default derived from the serialization format (rml:serialization) of the logical target (rml:LogicalTarget) in which it is contained, following the table below:

serialization format	content-type header
`formats:N-Triples`	`application/n-triples`
`formats:Turtle`	`text/turtle`
`formats:JSON-LD`	`application/ld+json`
`formats:TriG`	`application/trig`
`formats:N-Quads`	`application/n-quads`

A direct HTTP request (rmle:DirectHttpRequest) is an HTTP request (rmle:HttpRequest) that MUST contain:

exactly one absolute URI property (htv:absoluteURI), whose value is a literal denoting the absolute URI to access the resource.

In the example below generated RDF triples are exported using an HTTP PUT request to URI https://mypod/persons, with the generated RDF triples as body and with application/n-triples as content-type.

<#lt_persons> a rml:LogicalTarget;
  rml:serialization formats:N-Triples;
  rml:target [
    a rml:Target, rmle:directHttpRequest;
    htv:absoluteURI "https://mypod/persons";
    rmle:userAuthentication [
      a rmle:CssAuthInfo;
      rmle:authEmail "hello@mypod.com";
      rmle:authPassword "abc123";
      rmle:authWebId <https://mypod/profile/card#me>;
      rmle:authOidcIssuer <https://mypod/>;
    ];
  ];
.

A linked HTTP request (rmle:LinkedHttpRequest) describes how to access a web resource linked from another web resource, via the HTTP Link header with a specified relation. We refer to the web resource that links to that linked web resource as linking web resource.

One use case for a linked HTTP request is access to ACL resources. Clients discover the ACL resource associated with a resource by making an HTTP request on the URI of the linking web resource to which the ACL resource applies. The URI of the ACL resource is exposed with relation acl in the HTTP Link header.

A linked HTTP request is an HTTP request (rmle:HttpRequest) that MUST contain:

exactly one linking absolute URI property (rmle:linkingAbsoluteURI), whose value is a literal denoting the absolute URI of the linking web resource.
exactly one link relation property (rmle:linkRelation), whose value is a literal denoting the link relation.

A linked HTTP request MUST NOT contain an explicit absolute URI property (htv:absoluteURI). The absolute URI is by default discovered by making an HTTP HEAD request on the linking web resource absolute URI, and checking the HTTP Link header whose relation property equals the specified link relation.

The following example shows a Solid ACL target that exports RDF triples to an ACL file for a linking web resource with URI https://mypod/persons.

In the example below, the absolute URI for the linked HTTP request is discovered by making an HTTP HEAD request on https://mypod/persons, and extracting the value of the HTTP Link header with relation acl. The generated RDF triples are exported using a HTTP PUT request to the discovered URI, with the generated RDF triples as body and with text/turtle as content-type.

<#lt_persons_acl> a rml:LogicalTarget ;
  rml:serialization formats:Turtle ;
  rml:target [
    a rml:Target, rmle:LinkedHttpRequest ;
    rmle:linkingAbsoluteURI "https://mypod/persons" ;
    rmle:linkRelation "acl" ;
    rmle:userAuthentication [
      a rmle:CssAuthInfo ;
      rmle:authEmail "hello@mypod.com" ;
      rmle:authPassword "abc123" ;
      rmle:authWebId <https://mypod/profile/card#me> ;
      rmle:authOidcIssuer <https://mypod/> ;
    ] ;
  ] ;
.

A resource of the type user authentication (rmle:UserAuthentication) describes authentication details. The required authentication information depends on the authentication type. This terminology is aligned with the International Data Spaces Information Model.

This specification specifies following types of user authentication:

the CSS client credentials authentication (rmle:CssClientCredentialsAuthentication), describing the information required for authentication using client credentials as specified in the documentation of the Solid Community Server version v7.

A CSS client credentials authentication is represented by a resource that MUST contain:

exactly one authentication email property (rmle:authEmail), whose value is a string denoting the email for the authentication.
exactly one authentication password property (rmle:authPassword), whose value is a string denoting the password for the authentication.
exactly one authentication webID property (rmle:authWebId), whose value is named node denoting the webID for the authentication.
exactly one authentication OIDC issuer property (rmle:authOidcIssuer), whose value is a named node denoting the OpenID Connect issuer for the authentication.

In this example the content of a web resource are used as source data. The generate RDF triples are exported resp. to a Solid resource with URI https://mypod/profile/persons and to the ACL resource linked to this resource. User you gets read access to https://mypod/profile/persons, the owner of the POD, i.e., me, gets read, write, and control access. It is important that the owner rights are added, because the ACL resources (and consequently any existing access rights) are overwritten.

[
  {
    "id": 0,
    "name": "Monica Geller",
    "age": 33
  },
  {
    "id": 1,
    "name": "Rachel Green",
    "age": 34
  },
  {
    "id": 2,
    "name": "Joey Tribbiani",
    "age": 35
  },
  {
    "id": 3,
    "name": "Chandler Bing",
    "age": 36
  },
  {
    "id": 4,
    "name": "Ross Geller",
    "age": 37
  }
]

user,webid,access_mode
me,https://mypod/profile/card#me,Read
me,https://mypod/profile/card#me,Write
me,https://mypod/profile/card#me,Control
you,https://yourpod/profile/card#me,Read

<#ls_persons> a rml:LogicalSource ;
  rml:source [
   a rml:Source, rmle:HttpRequest ;
   htv:absoluteURI "https://rml.io/specs/rml-target/Friends.json" ;
  ] ;
.

<#ls_persons_acl> a rml:LogicalSource ;
  rml:source [
   a rml:Source, a rml:RelativePathSource ;
   rml:root rml:CurrentWorkingDirectory ;
   rml:path "./persons_acl.csv" ;
  ] ;
.

<#lt_persons> a rml:LogicalTarget ;
  rml:serialization formats:N-Triples ;
  rml:target [
    a rml:Target, rmle:HttpRequest ;
    htv:absoluteURI "https://mypod/persons" ;
    rmle:userAuthentication <#auth> ;
  ] ;
.

<#lt_persons_acl> a rml:LogicalTarget ;
  rml:serialization formats:N-Triples ;
  rml:target [
    a rml:Target, rmle:LinkedHttpRequest ;
    rmle:linkingAbsoluteURI "https://mypod/persons" ;
    rmle:linkRelation "acl" ;
    rmle:userAuthentication <#auth> ;
  ] ;
.

<#auth> a rmle:CssClientCredentialsAuthentication ;
  rmle:authEmail "hello@mypod.com" ;
  rmle:authPassword "abc123" ;
  rmle:authWebId <https://mypod/profile/card#me> ;
  rmle:authOidcIssuer <https://mypod/> ;
.

<#tm_persons> a rml:TriplesMap ;
  rml:logicalSource <#ls_persons> ;
  rml:subjectMap [
    a rml:SubjectMap ;
    rml:template "http://example.org/{id}" ;
    rml:logicalTarget <#lt_persons> ;
  ] ;
  rml:predicateObjectMap [
    a rml:PredicateObjectMap ;
    rml:predicate foaf:name ;
    rml:objectMap [
      a rml:ObjectMap ;
      rml:reference "name" ;
    ] ;
  ] ;
  rml:predicateObjectMap [
    a rml:PredicateObjectMap ;
    rml:predicate foaf:age ;
    rml:objectMap [
      a rml:ObjectMap ;
      rml:reference "age" ;
    ] ;
  ] ;
.

<#tm_persons_acl> a rml:TriplesMap ;
  rml:logicalSource <#ls_persons_acl> ;
  rml:subjectMap [
    a rml:SubjectMap ;
    rml:template "http://example.org/{user}_acl" ;
    rml:class acl:Authorization ;
    rml:logicalTarget <#lt_persons_acl> ;
  ] ;
  rml:predicateObjectMap [
    a rml:PredicateObjectMap ;
    rml:predicate acl:Mode ;
    rml:objectMap [
      a rml:ObjectMap ;
      rml:template "http://www.w3.org/ns/auth/acl#{access_mode}" ;
    ] ;
  ] ;
  rml:predicateObjectMap [
    a rml:PredicateObjectMap ;
    rml:predicate acl:agent ;
    rml:objectMap [
      a rml:ObjectMap ;
      rml:reference "webid" ;
    ] ;
  ] ;
  rml:predicateObjectMap [
    a rml:PredicateObjectMap ;
    rml:predicate acl:accessTo ;
    rml:object <https://mypod/persons> ;
  ] ;
.

# https://mypod/persons
<http://example.org/0> <http://xmlns.com/foaf/0.1/name> "Monica Geller" .
<http://example.org/0> <http://xmlns.com/foaf/0.1/age> "33" .
<http://example.org/1> <http://xmlns.com/foaf/0.1/name> "Rachel Green" .
<http://example.org/1> <http://xmlns.com/foaf/0.1/age> "34" .
<http://example.org/2> <http://xmlns.com/foaf/0.1/name> "Joey Tribbiani" .
<http://example.org/2> <http://xmlns.com/foaf/0.1/age> "35" .
<http://example.org/3> <http://xmlns.com/foaf/0.1/name> "Chandler Bing" .
<http://example.org/3> <http://xmlns.com/foaf/0.1/age> "36" .
<http://example.org/4> <http://xmlns.com/foaf/0.1/name> "Ross Geller" .
<http://example.org/4> <http://xmlns.com/foaf/0.1/age> "37" .
<http://example.org/0> <http://xmlns.com/foaf/0.1/name> "Monica Geller" .
<http://example.org/0> <http://xmlns.com/foaf/0.1/age> "33" .

# ACL file for https://mypod/persons
<http://example.org/me_acl> a <http://www.w3.org/ns/auth/acl#Authorization> .
<http://example.org/me_acl> <http://www.w3.org/ns/auth/acl#agent> <https://mypod/profile/card#me> .
<http://example.org/me_acl> <http://www.w3.org/ns/auth/acl#accessTo> <https://mypod/profile/persons> .
<http://example.org/me_acl> <http://www.w3.org/ns/auth/acl#mode> <http://www.w3.org/ns/auth/acl#Read> .
<http://example.org/me_acl> <http://www.w3.org/ns/auth/acl#mode> <http://www.w3.org/ns/auth/acl#Write> .
<http://example.org/me_acl> <http://www.w3.org/ns/auth/acl#mode> <http://www.w3.org/ns/auth/acl#Control> .
<http://example.org/you_acl> a <http://www.w3.org/ns/auth/acl#Authorization> .
<http://example.org/you_acl> <http://www.w3.org/ns/auth/acl#agent> <https://yourpod/profile/card#me> .
<http://example.org/you_acl> <http://www.w3.org/ns/auth/acl#accessTo> <https://mypod/profile/persons> .
<http://example.org/you_acl> <http://www.w3.org/ns/auth/acl#mode> <http://www.w3.org/ns/auth/acl#Read> .

HTTP REQUEST ACCESS

Abstract

1. Overview

1.1 Document conventions

1.2 Conformance

2. HTTP request access

2.1 HTTP request

2.1.1 HTTP request as source

2.1.2 HTTP request as target

2.2 Direct HTTP request

2.3 Linked HTTP request

2.4 User Authentication

2.4.1 CSS Client Credentials Authentication

3. Example

A. References

A.1 Normative references

A.2 Informative references