This document describes the SPARQL 1.1 Subscribe Language< used within the SPARQL Event Processing Architecture to describe subscription requests, responses and notifications.
This is a first draft.

Introduction

The SPARQL 1.1 Subscription Language defines the content of the following elements: primitives (i.e., subscribe and unsubscribe), notifications and pings. 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 engine
The server component of the SEPA. It implements the publish-subscribe mechanisms and algorithms. Clients interact with a SEPA engine 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 engine 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]]

Subscribe

Request

A subscribe primitive is expressed as shown in the following example:
{"subscribe" : "select * where {?s ?p ?o}",
"authorization" : "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
"alias" : "All"}

The value of the subscribe 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 the other two 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.

Response

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

{"subscribed" : "sepa://subscription/0d057ca5-cc10-4e8a-a5d9-59d7b36f71d6","alias":"All"}

The value of the subscribed member is an URI [[!RFC3986]]. It is used to identify the corresponding notifications and it MUST be present. The alias member (if present) has the same value of the corresponding alias member of the subscribe request.

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" : "sepa://subscription/0d057ca5-cc10-4e8a-a5d9-59d7b36f71d6",
"authorization" : "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",}

The unsubscribe 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 Engine implementation MUST reply to a unsubscribe request with a message like the following:

{"unsubscribed" : "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:

 {"spuid" : "sepa://subscription/0d057ca5-cc10-4e8a-a5d9-59d7b36f71d6", 		
"sequence" : 0, 
"results" : {
	"head":
		{ "vars" : [ ... ] ,"link" : [ ... ] },
	"addedResults": 
		{"bindings" : [
			{"a" : { ... } ,"b" : { ... }} ,
			{"a" : { ... } ,"b" : { ... }}]} ,
	"removedResults":
		{"bindings" : []}}}

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) and the value of the results member is an object with three keys: head , addedResults and removedResults . With reference to the SPARQL 1.1 Query Results JSON format [[sparql11-results-json]], the head key corresponds to the head member described in the SPARQL 1.1 JSON format [[sparql11-results-json]] document, while both the addedResults and removedResults keys correspond to the results member in the same document [[sparql11-results-json]].

Ping

The default content of a ping message follows:

 {"ping" : "2017-06-06T19:20:07Z"}

The ping member MUST be present and its value is the UTC time on the SEPA Engine represented as described in [[!RFC3339]].

Error responses

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

 { "body" : "Internal Server Error: SPARQL endpoint not found" , "code" : 500}
 

If applies, the use of use of HTTP status codes [[!RFC2616]] is RECOMMENDED. As reference, a list of common HTTP status codes follows:

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
	

Implementation specific error codes MAY also be used.

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).