SPARQL 1.1 Subscribe Language

This document describes the SPARQL 1.1 Subscribe Language used within the SPARQL Event Processing Architecture to describe subscription requests and notifications.

This is a first draft.

Introduction

The SPARQL 1.1 Subscribe Language defines the content of the following elements: primitives (i.e., subscribe and unsubscribe) and notifications. Every SEPA implementation MUST provide a JSON serialization [[!RFC7159]] of the all these elements. Other kinds of serialization formats MAY be provided. This document refers to the REQUIRED JSON serialization.

The SPARQL 1.1 Subscribe Language is framed within W3C Recommendations as shown in the following figure.

Fig. 1 - The SPARQL Event Processing Architecture (SEPA)

Document conventions

When this document uses the words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and RECOMMENDED, and the words appear as emphasized text, they must be interpreted as described in RFC 2119 [[!RFC2119]].

Terminology

SEPA: SPARQL Event Processing Architecture
SEPA broker: The server component of the SEPA. It implements the publish-subscribe mechanisms and algorithms. Clients interact with a SEPA broker with the SPARQL 1.1 SE Protocol
SPARQL 1.1 Subscribe Language: The subscription language introduced by the SEPA
SPARQL 1.1 SE Protocol: The protocol implemented by a SEPA broker and defined in this document
SPARQL 1.1 Update Language: As defined by [[sparql11-update]]
SPARQL 1.1 Query Language: As defined by [[sparql11-query]]

Request

A subscribe primitive is expressed as shown in the following example:

{"subscribe" : {
   "sparql" : "select * where {?vaimee ?deda ?didi}",
   "authorization" : "Bearer xabtQWoH8RJJk1FyKJ78J8h8i2PcWmAugfJ4J6nMd+1jVSoiipV4Pcv8bH+8wJLJ2yRaVage8/TzdZJiz2jdRP8bhkuNzFhGx6N1/1mgmvfKihLheMmcU0pLj5uKOYWFb+TB98n1IpNO4G69lia2YoR15LScBzibBPpmKWF+XAr5TeDDHDZQK4N3VBS/e3tFL/yOhkfC9Mw45s3mz83oyeoFFePUX8MQIuqd3TIcjOhoPgYWd0E+L/EN5wItL5/n78pX/8mVZcpxdyNNqr3bVvrCi0I84mIAefwQ0GyPxFhUHu9PtVNQnXchZuFgppX/YDtOesZSxfIoffUpHFPBY3u4FRIYwpSZX96Knnp0J22RQm+0l8yobik3z6jftw0jbF5+/YC6PnfZT3Wzb6PRJPuVkDzpo+BTC9eKx87GEj8VjtfXjbYRTeZNumD+59wL5kV/OrntNqNQD+IzAYoIZk4rlRbNouNnvT0laEhV012tSD1uAfNUxAlZjSbSMTp5bPNp7PoutMr5q6zPYfAC1PTKnVdkD1CDNqZnhB838WDeISfVzXsf7dsZ0+SkNPtx2kMUYCOYsxNJxyzza3lmaCuvxfnDT3g5F41/p/zX1tXYy6emVfdOWSkJNm1z0FJB/ZIUES0WAA5UEM3kejND++vvIQr38ar72HdFzRvP2V29CsaE5PMRRRZIE5ru9Zwgdb5lfMdwDi4sZkQdNRGHiOfRCT9D92mFVps6s6kv7HKojx05R9WKMDG8bEmSgMYSYQlQzLm93Ardw/hpDoB1/DfNRxbc/GVNZEVOoRVMye8/vICZtxvVeKmu4QawWKSBtrXelWUT8AHTG6v/c88pZjtJWDzy6YIIXLDQ2eJPu30mt3gLfS2ukIV4Tl5Oqu3T1IIghmNgek8vwWNeuG/JGeKrfUp6X6mMH9hdmj5+naOIr8V5rUKCjXnlWLAsrGdOvV8vuYYbx2IFQScZQJD/sTKj3gs6yeYpOwQ2iEs9asA=",
   "alias" : "All",
   "default-graph-uri" : ["http://example/uri_of_the_default_graph"],
   "named-graph-uri" : ["http://example/uri_of_a_named_graph"]
 }}

The value of the sparql member MUST be a SPARQL 1.1 Query [[sparql11-query]], the value of the authorization member (if present) MUST be a Bearer JSON Web Token [[!RFC7519]] and the value of the alias member (if present ) is a string representing a friendly name of the subscription.

The first member is REQUIRED, while all the other are optional.

The authorization member is only REQUIRED for secure operations.

The value of the alias member, if present, it will be included in the subscribe response. The use of the alias member is RECOMMENDED if the SEPA client sends multiple subscribe requests. If needed, the SEPA client MAY store the subscription alias and link it with the subscription URI [[!RFC3986]] contained in the subscribe response message.

The value of the default-graph-uri and of the named-graph-uri (if present) have the same meaning and content of the corresponding parameters defined in the SPARQL 1.1 Protocol [[sparql11-protocol]]

Response

If the subscribe request is successfully processed, every SEPA implementation MUST respond with a message like the following:

{"notification":{
   "spuid" : "sepa://subscription/0d057ca5-cc10-4e8a-a5d9-59d7b36f71d6",
   "sequence" : 0,
   "alias" : "All",
   "addedResults" :{ 
     "head": { "vars": ["vaimee","deda","didi"] },
     "results": {
       "bindings": [{ 
        "vaimee": {"type": "uri", "value" : "http://wot.arces.unibo.it/example#Subject"}, 
        "deda": {"type": "uri", "value": "http://wot.arces.unibo.it/example#Predicate"}, 
        "didi": {"type": "literal","value": "ვაიმეე"} }]}},
   "removedResults":{}}}

The value of the spuid member is an URI [[!RFC3986]], while the sequence member is a number and it will be always 0. Both members MUST be present. The sequence member will be incremented by one on each following notification.

The alias member (if present) has the same value of the corresponding alias member of the subscribe request.

Eventually, the value of the addedResults member corresponds to the results of the SPARQL query according to the SPARQL 1.1 Query Results JSON format [[sparql11-results-json]], while the value of the removedResults will be always an empty object.

In case of error, it is RECOMMENDED to reply as shown here

Unsubscribe

Request

A client MAY request to remove a specific subscription. This can be done by sending a message like the following:

{"unsubscribe":{
   "spuid":"sepa://subscription/0d057ca5-cc10-4e8a-a5d9-59d7b36f71d6",
   "authorization" :"Bearer eyJhbGciOiJIUzI....ONFh7HgQ"}}

The spuid member value is the subscription URI [[!RFC3986]] provided by the subscribe response message.

The value of the authorization member (if present) MUST be a Bearer JSON Web Token [[!RFC7519]].

The former member is REQUIRED, while the latter is only REQUIRED for secure primitives.

Response

A SEPA broker implementation MUST reply to a unsubscribe request with a message like the following:

{"unsubscribed":{
   "spuid":"sepa://subscription/0d057ca5-cc10-4e8a-a5d9-59d7b36f71d6"}}

In case of error, it is RECOMMENDED to reply as shown here

Notification

An example of a content notification follows:

{"notification":{
   "spuid" : "sepa://subscription/0d057ca5-cc10-4e8a-a5d9-59d7b36f71d6",
   "sequence" : 1,
   "alias" : "All",
   "addedResults" :{ 
     "head": { "vars": ["vaimee","deda","didi"] },
     "results": {
       "bindings": [{  
        "didi": {"type": "literal","value": "ზბკლვვ"} }]}},
   "removedResults":{ 
     "head": { "vars": ["vaimee","deda","didi"] },
     "results": {
       "bindings": [{ 
        "didi": {"type": "literal","value": "ვაიმეე"} }]}}}

The value of spuid member is the URI [[!RFC3986]] of the subscription who generates the notification.

The value of the sequence member is a number (incremented by one at every new notification of the same SPUID).

The addedResults and removedResults are two JSON objects whose content conform with the SPARQL 1.1 Query Results JSON format .

Error responses

In case of error, a SEPA broker implementation SHOULD reply with a JSON object like the following:

 {
   "error":"unauthorized_client",
   "error_description" : "Client is not authorized",
   "status_code" : 401
 }

The error member is a string representing the error. Refer to [[!RFC6749]] for all OAuth related errors. Otherwise it would be a SPARQL 1.1 SE Protocol specific error string.

The error_description member is optional and if present it provides a human readable description of the error.

The status_code member is an integer representing the error. The use of use of HTTP status codes [[!RFC2616]] is RECOMMENDED. As reference, a list of common HTTP status codes follows. Implementation specific error codes MAY also be used.

400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
407 Proxy Authentication Required
408 Request Timeout
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
413 Request Entity Too Large
414 Request-URI Too Long
415 Unsupported Media Type
416 Requested Range Not Satisfiable
417 Expectation Failed

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported

Acknowledgements

Editors would like to thanks the Advanced Research Center on Electronic Systems "Ercole De Castro" (ARCES) and the Computer Science and Engineering Department (DISI) of the University of Bologna, the European Commission and all the partners of the ARTEMIS projects who inspired the SPARQL Event Processing Architecture (SEPA).