HTTP Request Access in YARRRML

Abstract

This extension of [YARRRML] applies the semantics specified by the RML extension for [RML-HTTP-REQUEST-ACCESS], describing the access to a web resource (both as source and as target), modelled as a simplified HTTP request with optional authentication.

This section is non-normative.

We assume readers have basic familiarity with [RDF], [RML] and [YARRRML] concepts.

In this document, examples assume the following namespace prefix bindings unless otherwise stated:

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

The examples are contained in color-coded boxes. We use the Turtle syntax [Turtle] to write RDF.

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.

HTTP requests can define the access for a data source or a target in resp. the sources or the targets collections of a [YARRRML] document.

To describe an HTTP request access, [YARRRML] is extended with following keys for the sources and targets collection:

methodName: HTTP method name of the HTTP request.
Datatype: string.
headers: Headers of the HTTP request.
Datatype: collection or sequence of collections.
rel: Link relation in the Link header for retrieving the URI of a Linked HTTP Request.
Datatype: string.
authentication: The key of an authentication, defined in the authentications collection.
Datatype: string.

The following values extend the supported values for the key type for data sources and targets:

Data source type or target type	Value
Direct HTTP Request	`directhttprequest`
Linked HTTP Request	`linkedhttprequest`

This key's value describes one or more headers, as a collection or sequence of collections. A collection describing one header has following keys:

name: The name of the header.
Datatype: string.
value: The value of the header.
Datatype: string.

If unspecified, the value of the key methodName is by default "GET".

If unspecified, the accept header is by default derived from the reference formulation of the data source, following the table below:

referenceFormulation	accept
`csv`	`text/plain`
`jsonpath`	`application/json`
`xpath`	`application/xml`
`xquery`	`application/xml`

If unspecified, the value of the key methodName is by default PUT.

If unspecified, the content-type header is by default derived from the serialization of the target, following the table below:

serialization	contentType
`jsonld`	`application/ld+json`
`n3`	`text/n3`
`ntriples`	`application/n-triples`
`nquads`	`application/n-quads`
`turtle`	`text/turtle`
`trig`	`application/trig`

A authentication is defined in the authentications collection in the root of the YARRRML document. Each authentication is added to this collection via a key-value pair. The key has to be unique for every authentication. The key's value is a collection with the keys described below.

type: The type of the authentication.
Datatype: string.
email: Email for the authentication.
Datatype: string.
password: Password for the authentication.
Datatype: string.
oidcIssuer: OIDC issuer for the authentication.
Datatype: string.
webId: WebID for the authentication.
Datatype: string.

This key's value describes what type of authentication is used, so that the correct way of authenticating be determined. The following values are supported:

Authentication type	Value
CSS Client Credentials Authentication	`cssclientcredentials`

In the following example a data source is defined using a direct HTTP request.

sources:
  ls_persons:
    type: directhttprequest
    access: "https://w3id.org/imec/rml/specs/rml-target/Friends.json"
    methodName: GET
    headers: 
      name: Accept
      value: application/json
    referenceFormulation: jsonpath
    iterator: "$[*]"

<#ls_persons> a rml:LogicalSource ; 
  rml:source [
    a rml:Source, rmle:HttpRequest ;
    htv:absoluteURI "https://w3id.org/imec/rml/specs/rml-target/Friends.json" ;
    htv:methodeName "GET" ; 
    htv:headers ([
      a htv:RequestHeader ; 
      htv:fieldName "Accept" ; 
      htv:fieldValue "application/json" ; 
    )] ;  
  ] ;
  rml:referenceFormulation rml:JSONPath ; 
  rml:iterator "$[*]" ;
.

The above example can be shortened, counting on the defaults defined in the RML HTTP Request Access specification.

sources:
  ls_persons:
    type: directhttprequest
    access: "https://w3id.org/imec/rml/specs/rml-target/Friends.json"
    referenceFormulation: jsonpath
    iterator: "$[*]"

<#ls_persons> a rml:LogicalSource ; 
  rml:source [
    a rml:Source, rmle:HttpRequest ;
    htv:absoluteURI "https://w3id.org/imec/rml/specs/rml-target/Friends.json" ;
  ] ;
  rml:referenceFormulation rml:JSONPath ; 
  rml:iterator "$[*]" ;
.

In the following example two targets are defined: lt_persons using a direct HTTP request and lt_persons_acl uses a linked HTTP request using rel relation acl. Both targets require authentication, using the same email, password, webId, and oidcIssuer parameters.

targets:
  lt_persons:
    type: directhttprequest
    access: "https://pod.playground.solidlab.be/user1/persons"
    referenceFormulation: turtle
    authentication: auth
  lt_persons_acl:
    type: linkedhttprequest
    access: "https://pod.playground.solidlab.be/user1/persons"
    rel: acl
    referenceFormulation: turtle
    authentication: auth

authentications:
  auth:
    type: cssclientcredentials
    email: user1@pod.playground.solidlab.be
    password: user1
    webId: "https://pod.playground.solidlab.be/user1/profile/card#me"
    oidcIssuer: "https://pod.playground.solidlab.be/"

<#lt_persons> a rml:LogicalTarget ;
  rml:serialization formats:Turtle ;
  rml:target [
    a rml:Target, rmle:HttpRequest ;
    htv:absoluteURI "https://pod.playground.solidlab.be/user1/persons" ;
    rmle:userAuthentication <#auth> ; 
  ] ;
. 

<#lt_persons_acl> a rml:LogicalTarget ;
  rml:serialization formats:Turtle ;
  rml:target [
    a rml:Target, rmle:LinkedHttpRequest ;
    rmle:linkingAbsoluteURI "https://pod.playground.solidlab.be/user1/persons" ;
    rmle:linkRelation "acl" ;
    rmle:userAuthentication <#auth> ; 
  ] ;
. 

<#auth> a rmle:CssClientCredentialsAuthentication ;
  rmle:authEmail "user1@pod.playground.solidlab.be" ;
  rmle:authPassword "user1" ;
  rmle:authWebId <https://pod.playground.solidlab.be/user1/profile/card#me> ;
  rmle:authOidcIssuer <https://pod.playground.solidlab.be/> ;
.

HTTP Request Access in YARRRML

Abstract

1. Overview

1.1 Document conventions

1.2 Conformance

2. HTTP Requests

2.1 Headers

2.2 Default values for HTTP requests as data source

2.3 Default values for HTTP requests as target

2.4 Authentications

2.4.1 Type

3. Examples

3.1 Direct HTTP request as data source

3.2 Direct HTTP request as data source, with defaults

3.3 Direct HTTP request and linked HTTP request as target, with authentication

A. References

A.1 Normative references

A.2 Informative references