SPARQL 1.1 Incremental Protocol

Living Document,

Previous Versions:
Issue Tracking:
GitHub
Inline In Spec
Editor:
(Ghent University - imec)

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 1 December 2025, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

Abstract

This document defines an extension to the SPARQL 1.1 Protocol that enables incremental delivery of SPARQL query results over Server-Sent Events. Instead of a single response, the service emits a stream of events that convey an initial query results followed by incremental updates and explicit "up-to-date" signals. This extension is intended for use by incremental view maintenance (IVM) engines and other systems that require low-latency maintenance of SPARQL query results under updates.

1. Introduction

The SPARQL Protocol defines how clients issue SPARQL queries and receive results over HTTP. In its standard form, each query produces a single response containing the query results, serialized using formats such as SPARQL Results JSON or SPARQL Results XML.

For applications that maintain long-lived queries over changing data, repeatedly reissuing queries and re-fetching full results is inefficient and adds latency.

This specification defines an extension to the SPARQL Protocol that allows a SPARQL Protocol service to deliver results as an Incremental Result Stream using server-sent events. Instead of returning a single result document, the service emits:

This version of the specification normatively defines different serializations for query results over server-sent events.

1.1. Terminology

We use the terms specified in the SPARQL Protocol and SPARQL Query specifications, and additionally define:

1.2. Namespaces

The following namespace prefixes are used throughout this document.
Prefix      IRI
sip: https://www.w3.org/ns/sparql-incremental#
sd: http://www.w3.org/ns/sparql-service-description#
xsd: http://www.w3.org/2001/XMLSchema#
rdfs: http://www.w3.org/2000/01/rdf-schema#
rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
owl: http://www.w3.org/2002/07/owl#

The http://www.w3.org/ns/sparql-incremental# namespace needs to be registered.

2. SPARQL Incremental Protocol

This protocol only changes three aspects of the SPARQL Protocol:

  1. Content negotiation to select the server-sent events-based incremental result format.

  2. The body of the success response format itself, which is now a server-sent events stream.

  3. The service description to advertise support for this protocol extension.

2.1. Content Negotiation

To request incremental results over server-sent events, the client MUST include the text/event-stream media type in the Accept header as per the requirements for server-sent events in [HTML]. By default, the the Incremental SPARQL Service MUST respond with the JSON-based serialization (see § 2.3 Events JSON) for binding and boolean results and the RDF serialization (see § 2.6 Events RDF) for graph results. This is to have the best compatibility with the EventSource API in web browsers, where JSON is the most commonly supported format. To support other serializations, the client MAY add the Accept header string to a accept HTTP query string parameter of the request. In case of a URL-encoded POST requests, the accept parameter MUST be included in the body of the request. This parameter is not part of HTTP content negotiation; it is interpreted exclusively by SPARQL 1.1 Incremental Protocol services.

2.2. Events Semantics

The server-sent events stream consists of the following event types. Implementations MUST support these event types, but MAY emit additional event types not defined in this specification. The id field defined by the server-sent events specification MAY be supported by the implementation.
initial

This event conveys the initial state of the query results. It MUST be the first event emitted by the Incremental SPARQL Service upon successfully establishing the stream. The data payload contains the complete results, serialized according to the negotiated format.

processing

This event MUST be emmited when the Incremental SPARQL Service is processing updates to the underlying data. The payload MAY contain a timestamp representing the latest data change being processed. This event does not guarantee that an update event will follow (e.g., if the processed changes do not affect the query result).

update

This event conveys incremental changes to the query results since the last initial or update event. The payload describes the additions and/or deletions to the query results. The head with variable names and the optional link array SHOULD NOT be included in these events. The Incremental SPARQL Service MAY emit multiple update events before an up-to-date event to batch changes.

NOTE: When processing updates, the additions should be applied before deletions to avoid transient inconsistencies in the results.

up-to-date

This event signals that the Incremental SPARQL Service has processed all changes to the underlying data. It indicates that all changes known up to the included timestamp have been processed and any resulting update events have been emitted. The payload MUST include a timestamp indicating this consistency point.

error

This event indicates a terminal failure in the stream generation. After emitting this event, the Incremental SPARQL Service MUST close the connection. The payload MUST include an error code and a description. This event is reserved for errors occurring after the stream has started; initial request errors (like SPARQL syntax errors) MUST be handled via standard HTTP status codes.

2.3. Events JSON

This section defines the JSON serialization for the incremental events. The event field of the server-sent events message corresponds to the event type defined in § 2.2 Events Semantics. The data field contains the JSON payload.

2.3.1. initial Event

The initial event payload follows the SPARQL Results JSON format.

event: initial
data: {
data:   "head": { "vars": [ "book", "title" ] },
data:   "results": {
data:     "bindings": [
data:       {
data:         "book": { "type": "uri", "value": "http://example.org/book/book1" },
data:         "title": { "type": "literal", "value": "SPARQL Tutorial" }
data:       }
data:     ]
data:   }
data: }

2.3.2. processing Event

The processing event payload is a JSON object that MAY contain a timestamp property (xsd:dateTime) indicating the time of the latest processed change.

event: processing
data: { "timestamp": "2024-11-24T10:00:00Z" }

2.3.3. update Event

The update event payload is a JSON object containing additions and deletions arrays. Each array contains bindings formatted exactly as the bindings array in SPARQL Results JSON.

event: update
data: {
data:   "additions": [
data:     {
data:       "book": { "type": "uri", "value": "http://example.org/book/book2" },
data:       "title": { "type": "literal", "value": "The Semantic Web" }
data:     }
data:   ],
data:   "deletions": [
data:     {
data:       "book": { "type": "uri", "value": "http://example.org/book/book1" },
data:       "title": { "type": "literal", "value": "SPARQL Tutorial" }
data:     }
data:   ]
data: }

2.3.4. up-to-date Event

The up-to-date event payload is a JSON object that MUST contain a timestamp property (xsd:dateTime) indicating the consistency point.

event: up-to-date
data: { "timestamp": "2024-11-24T10:05:00Z" }

2.3.5. error Event

The error event payload is a JSON object containing status (integer) and statusText (string) properties.

event: error
data: {
data:   "status": 500,
data:   "statusText": "Internal Server Error: Query execution timeout"
data: }

2.4. Events XML

This section defines the XML serialization for the incremental events. The event field of the server-sent events message corresponds to the event type defined in § 2.2 Events Semantics. The data field contains the XML payload. The incremental protocol elements are defined in the namespace http://www.w3.org/ns/sparql-incremental#. Standard SPARQL results elements are used within this wrapper in the http://www.w3.org/2005/sparql-results# namespace.

2.4.1. initial Event

The initial event payload follows the SPARQL Results XML format. It uses the standard SPARQL results namespace.

event: initial
data: <?xml version="1.0"?>
data: <sparql xmlns="http://www.w3.org/2005/sparql-results#">
data:   <head>
data:     <variable name="book"/>
data:     <variable name="title"/>
data:   </head>
data:   <results>
data:     <result>
data:       <binding name="book"><uri>http://example.org/book/book1</uri></binding>
data:       <binding name="title"><literal>SPARQL Tutorial</literal></binding>
data:     </result>
data:   </results>
data: </sparql>

2.4.2. processing Event

The processing event payload is an XML element processing in the incremental namespace that MAY contain a timestamp attribute (xsd:dateTime).

event: processing
data: <processing xmlns="http://www.w3.org/ns/sparql-incremental#" timestamp="2024-11-24T10:00:00Z"/>

2.4.3. update Event

The update event payload is an XML element update in the incremental namespace containing additions and deletions child elements. These elements contain result elements formatted exactly as in SPARQL Results XML, using the standard SPARQL results namespace.

event: update
data: <update xmlns="http://www.w3.org/ns/sparql-incremental#">
data:   <additions>
data:     <result xmlns="http://www.w3.org/2005/sparql-results#">
data:       <binding name="book"><uri>http://example.org/book/book2</uri></binding>
data:       <binding name="title"><literal>The Semantic Web</literal></binding>
data:     </result>
data:   </additions>
data:   <deletions>
data:     <result xmlns="http://www.w3.org/2005/sparql-results#">
data:       <binding name="book"><uri>http://example.org/book/book1</uri></binding>
data:       <binding name="title"><literal>SPARQL Tutorial</literal></binding>
data:     </result>
data:   </deletions>
data: </update>

2.4.4. up-to-date Event

The up-to-date event payload is an XML element up-to-date in the incremental namespace that MUST contain a timestamp attribute (xsd:dateTime).

event: up-to-date
data: <up-to-date xmlns="http://www.w3.org/ns/sparql-incremental#" timestamp="2024-11-24T10:05:00Z"/>

2.4.5. error Event

The error event payload is an XML element error in the incremental namespace containing status and statusText attributes.

event: error
data: <error xmlns="http://www.w3.org/ns/sparql-incremental#" status="500" statusText="Internal Server Error: Query execution timeout"/>

2.5. Events CSV and TSV

This section defines the CSV and TSV serializations for the incremental events. The event field of the server-sent events message corresponds to the event type defined in § 2.2 Events Semantics. The data field contains the payload formatted according to SPARQL Results CSV or SPARQL Results TSV. For TSV, the values MUST be encoded as defined in SPARQL Results TSV (e.g., IRIs enclosed in <>).

2.5.1. initial Event

The initial event payload follows the standard SPARQL Results CSV or SPARQL Results TSV format.

event: initial
data: book,title
data: http://example.org/book/book1,"SPARQL Tutorial"

2.5.2. processing Event

The processing event payload is a CSV/TSV document with a single column timestamp.

event: processing
data: timestamp
data: 2024-11-24T10:00:00Z

2.5.3. update Event

The update event payload is a CSV/TSV document. To distinguish between additions and deletions, the payload MUST include a special column named _op as the first column. The values in this column MUST be add for additions and del for deletions. The remaining columns correspond to the variables in the query results.

event: update
data: _op,book,title
data: add,http://example.org/book/book2,"The Semantic Web"
data: del,http://example.org/book/book1,"SPARQL Tutorial"

NOTE: This serialization does not allow to update the head information (variable names).

2.5.4. up-to-date Event

The up-to-date event payload is a CSV/TSV document with a single column timestamp.

event: up-to-date
data: timestamp
data: 2024-11-24T10:05:00Z

2.5.5. error Event

The error event payload is a CSV/TSV document with columns status and statusText.

event: error
data: status,statusText
data: 500,"Internal Server Error: Query execution timeout"

2.6. Events RDF

This section defines the RDF serialization for the incremental events. This serialization is used when the client negotiates an RDF media type (e.g., text/turtle, application/trig, application/ld+json). It is applicable only to CONSTRUCT and DESCRIBE queries, which return an RDF Graph. The event field of the server-sent events message corresponds to the event type defined in § 2.2 Events Semantics. The data field contains the RDF payload serialized in the negotiated format.

The incremental protocol terms are defined in the namespace http://www.w3.org/ns/sparql-incremental# (prefix sip).

2.6.1. initial Event

The initial event payload contains the complete RDF Graph result.

event: initial
data: @prefix : <http://example.org/> .
data: :book1 :title "SPARQL Tutorial" .

2.6.2. processing Event

The processing event payload contains an instance of sip:Processing.

event: processing
data: @prefix sip: <http://www.w3.org/ns/sparql-incremental#> .
data: @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
data:
data: [] a sip:Processing ;
data:    sip:timestamp "2024-11-24T10:00:00Z"^^xsd:dateTime .

2.6.3. update Event

The update event payload conveys additions and deletions. The additions and deletions MUST be described using standard RDF Reification. The sip:Update instance links to the reified statements via sip:additions and sip:deletions.

event: update
data: @prefix sip: <http://www.w3.org/ns/sparql-incremental#> .
data: @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
data: @prefix : <http://example.org/> .
data:
data: [] a sip:Update ;
data:    sip:additions [
data:      a rdf:Statement ;
data:      rdf:subject :book2 ; rdf:predicate :title ; rdf:object "The Semantic Web"
data:    ] ;
data:    sip:deletions [
data:      a rdf:Statement ;
data:      rdf:subject :book1 ; rdf:predicate :title ; rdf:object "SPARQL Tutorial"
data:    ] .

NOTE: A future version of this specification will adopt the RDF 1.2 terminology of RDF terms and will use RDF 1.2 quoted triples for describing additions and deletions.

2.6.4. up-to-date Event

The up-to-date event payload contains an instance of sip:UpToDate.

event: up-to-date
data: @prefix sip: <http://www.w3.org/ns/sparql-incremental#> .
data: @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
data:
data: [] a sip:UpToDate ;
data:    sip:timestamp "2024-11-24T10:05:00Z"^^xsd:dateTime .

2.6.5. error Event

The error event payload contains an instance of sip:Error.

event: error
data: @prefix sip: <http://www.w3.org/ns/sparql-incremental#> .
data:
data: [] a sip:Error ;
data:    sip:status 500 ;
data:    sip:statusText "Internal Server Error: Query execution timeout" .

2.7. Service Description

Endpoints implementing this extension SHOULD advertise their support for the SPARQL 1.1 Incremental Protocol through the SPARQL Service Description vocabulary. Concretely, an endpoint MAY assert the feature sip:incrementalProtocol on its sd:Service description, MAY type the service as a sip:IncrementalService (making it an Incremental SPARQL Service), and MAY provide the incremental metadata defined in § 3 Vocabulary. 
@prefix sd:  <http://www.w3.org/ns/sparql-service-description#> .
@prefix sip: <https://www.w3.org/ns/sparql-incremental#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

[] a sd:Service, sip:IncrementalService ;
   sd:endpoint <https://example.org/sparql> ;

   # Advertise incremental protocol support
   sd:feature sip:incrementalProtocol ;

   # Additional incremental metadata
   sip:streamingEndpoint <https://example.org/sparql/stream> ;
   sip:resultFormat "text/event-stream+sparql-results+json" ;
   sip:supportsLastEventID true .

3. Vocabulary

The SPARQL 1.1 Incremental Protocol vocabulary is defined in the sip: namespace (https://www.w3.org/ns/sparql-incremental#). The following terms are used in this specification.

3.1. Classes

3.1.1. sip:IncrementalService

An instance of sip:IncrementalService indicates that the service supports the SPARQL 1.1 Incremental Protocol.

type: rdfs:Class

3.1.2. sip:Processing

The class of resources signalling that the Incremental SPARQL Service is processing updates to the underlying data.

type: rdfs:Class

3.1.3. sip:Update

The class of resources that describe incremental changes to the results via additions and deletions.

type: rdfs:Class

3.1.4. sip:UpToDate

The class of resources indicating that the Incremental SPARQL Service has processed all updates to the underlying data.

type: rdfs:Class

3.1.5. sip:Error

The class of resources conveying terminal stream errors emitted after a stream has started.

type: rdfs:Class

3.2. Properties

3.2.1. sip:incrementalProtocol

Feature IRI advertised on a sd:Service to signal support for the SPARQL 1.1 Incremental Protocol.

type: rdf:Property
domain: sd:Service

3.2.2. sip:streamingEndpoint

Relates a sd:Service to the IRI of the streaming endpoint that serves incremental results using the SPARQL 1.1 Incremental Protocol.

type: owl:InverseFunctionalProperty
domain: sd:Service

3.2.3. sip:resultFormat

Relates a sd:Service to the serialization used for incremental results (e.g., text/event-stream+sparql-results+json).

type: rdf:Property
domain: sd:Service
range: http://www.w3.org/ns/formats/Format

3.2.4. sip:supportsLastEventID

Relates a sd:Service to a boolean value indicating whether the Incremental SPARQL Service supports the Last-Event-ID mechanism of Server-Sent Events for resuming streams.

type: rdf:Property
domain: sd:Service
range: xsd:boolean

3.2.5. sip:additions

Relates a sip:Update instance to reified statements describing triples that were added to the result.

type: rdf:Property

3.2.6. sip:deletions

Relates a sip:Update instance to reified statements describing triples that were removed from the result.

type: rdf:Property

3.2.7. sip:timestamp

Records the xsd:dateTime at which the Incremental SPARQL Service is up to date or processing a specific change, used on sip:Processing and sip:UpToDate.

type: rdf:Property

3.2.8. sip:status

Captures the HTTP status code associated with a sip:Error event payload.

type: rdf:Property

3.2.9. sip:statusText

Provides a textual explanation associated with a sip:Error status code.

type: rdf:Property

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SPARQL11-PROTOCOL]
Lee Feigenbaum; et al. SPARQL 1.1 Protocol. URL: https://w3c.github.io/sparql-protocol/spec/
[SPARQL11-QUERY]
Steven Harris; Andy Seaborne. SPARQL 1.1 Query Language. URL: https://w3c.github.io/sparql-query/spec/
[SPARQL11-RESULTS-CSV-TSV]
Andy Seaborne. SPARQL 1.1 Query Results CSV and TSV Formats. URL: https://w3c.github.io/sparql-results-csv-tsv/spec/
[SPARQL11-RESULTS-JSON]
Andy Seaborne. SPARQL 1.1 Query Results JSON Format. URL: https://w3c.github.io/sparql-results-json/spec/

Issues Index

The http://www.w3.org/ns/sparql-incremental# namespace needs to be registered. ↵