Events Query with Linked Data

1. Introduction

This section is non-normative.

Events Query [EVENTS-QUERY] is a minimal event notifications protocol built on top of HTTP. Events Query with Linked Data (EQ-LD) defines representation and semantics for using linked data to request and transmit event notifications directly from HTTP resources with the Events Query protocol.

1.1. Audience

This section is non-normative.

This specification is for:

• Server developers who wish to enable clients to listen for updates to HTTP resources.

• Application developers who wish to implement a client to listen for updates to HTTP resources.

1.2. Namespaces

This specification uses the following RDF vocabularies and corresponding namespace prefix bindings:

1.3. Conformance

1.3.1. Document Conventions

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

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" and "MAY" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The above-mentioned keywords are used exclusively in the normative parts of this document and appear only in all capitals.

1.3.2. Specification Category

The Events Query with Linked Data identifies the following Specification Categories [SPEC-VARIABILITY] to distinguish the types of conformance:

• API,

• Notation/syntax,

• Set of events,

• Protocol.

1.3.3. Classes of Products

The Events Query with Linked Data identifies the following Classes of Products [SPEC-VARIABILITY] for conforming implementations. These products are referenced throughout this specification.

Server

A server that builds on HTTP server [RFC9110] and [RFC9112] by defining methods,media types and behaviour of resources.

Client

A client that builds on a HTTP client [RFC9110], [RFC9112] and [FETCH] by defining behaviour in terms of fetching across the platform.

1.3.4. Interoperability

Interoperability occurs between Client—Server as defined by Events Query with Linked Data.

Client—Server Interoperability

Interoperability of implementations for clients and servers is tested by evaluating an implementation’s ability to transmit and receive event notifications that conform to Events Query with Linked Data.

2. Discovery

A client can discover support for event notifications using Events Query with Linked Data by examining if a server is able to accept a query request on a resource using a suitable RDF serialization with content consistent with the Request Format.

A server that provides event notifications using Events Query with Linked Data on a resource MUST advertize application/ld+json [JSON-LD11] as an acceptable representation for a request with the QUERY method ([HTTP-QUERY]), using the Accept-Query ([HTTP-QUERY] § 3) header field of a response. A server MUST further set the value of the profile parameter of the application/ld+json media type to indicate a preferred JSON-LD context http://www.w3.org/ns/json-ld#context with http://cxres.github.io/eq-ld/ns/context.jsonld as the URI.

HEAD /missing/John_Doe HTTP/1.1Host: example.org

HTTP/1.1 200 OKAccept-Query: application/ld+json;  profile="http://www.w3.org/ns/json-ld#context http://cxres.github.io/eq-ld/ns/context.jsonld"

3. Request

3.1. Data Model

A request for event notifications using the Events Query with Linked Data builds on the abstract data model defined by the HTTP Events Query protocol [EVENTS-QUERY].

3.2. Vocabulary

The request data is expressed with the HTTP Vocabulary in RDF 1.0 [HTTP-in-RDF10] and the Events Query with Linked Data vocabulary.

Events Query with Linked Data defines the following RDF properties that a client MAY use in a request:

eq-ld:events <http:headers>

Header fields to negotiate event notifications in an Events Query.

eq-ld:state <http:headers>

Header fields to negotiate the representation of resource state in an Events Query.

3.3. Extended Content

A server MAY admit an extended request based on an augmented JSON-LD Context [JSON-LD11] definition.

3.4. Format

A server implementing Events Query with Linked Data MUST accept a request using the QUERY method ([HTTP-QUERY] § 2) when the content-type of the request is application/ld+json [JSON-LD11], and includes http://cxres.github.io/eq-ld/ns/context.jsonld as a URI for the JSON-LD context.

A server MAY support additional RDF representations for an Events Query.

QUERY /missing/John_Doe HTTP/1.1Host: example.orgContent-Type: application/ld+json{  "@context": "http://cxres.github.io/eq-ld/ns/context.jsonld",  "eq-ld:events":[    {      "@type":"http:RequestHeader",      "http:hdrName":"http-headers:accept",      "http:headerElements":[        {          "@type":"http:HeaderElement",          "http:elementName":"application/ld+json"        }      ]    }  ]}ㅤ

4. Notification

4.1. Data Model

An Events Query with Linked Data notification message specializes the Activity object defined by Activity Streams 2.0 [ACTIVITYSTREAMS-CORE].

4.2. Vocabulary

The core notification data is expressed with the Activity Streams vocabulary [ACTIVITYSTREAMS-VOCABULARY].

An event notification transmitted using the Events Query with Linked Data protocol MUST have the following properties:

as:type <as:Activity>

the type of activity that triggered the notification.

as:published <xs:dateTime>

the date and time of the notification.

4.3. Activity Mapping

A server sending an event notification with the Events Query with Linked Data protocol as a result of some activity on a resource MUST set the type property as the type of activity that triggered the notification as specified by the Activity Streams vocabulary [ACTIVITYSTREAMS-VOCABULARY].

4.4. Extended Content

A server MAY augment the JSON-LD Context [JSON-LD11] definition and extend the content of an event notification.

NOTE: See examples of using multiple vocabularies in the Activity Streams [ACTIVITYSTREAMS-CORE] specification.

4.5. Format

A server implementing Events Query with Linked Data on a resource MUST be able to transmit event notifications using the application/ld+json [JSON-LD11] media-type.

A server MAY additionally support other RDF serializations to transmit event notifications.

HTTP/1.1 200 OKContent-Type: application/ld+jsonContent-Length: 180{  "@context": "https://www.w3.org/ns/activitystreams",  "published": "2024-11-10T11:12:13Z",  "type": "Update",  "object": "https://example.org/missing/John_Doe"}

Considerations

This section is non-normative.

References within this specification point to documents with a Living Standard or Draft status, meaning their contents can still change over time. It is advised to monitor these documents, as such changes might have implications.

Security Considerations

This section is non-normative.

Since Events Query with Linked Data uses Events Query to transmit notifications, it follows that the Events Query with Linked Data inherits security considerations from Events Query, as discussed in [EVENTS-QUERY] § Security Considerations.

Servers are strongly discouraged from exposing information beyond the minimum amount necessary in a notification. Clients are strongly discouraged from exposing information beyond the minimum amount necessary to receive notifications from particular resources.

Clients are discouraged from sending requests for notifications to untrusted servers, including localhost or any other loopback IP address, in order to avoid making arbitrary requests.

Example

This section is non-normative.

The following uses the example of a resource with a missing persons' report to illustrate the request and response for representation and event notifications using Events Query with Linked Data.

QUERY /missing/John_Doe HTTP/1.1Host: example.orgContent-Type: application/ld+json{  "@context": "http://cxres.github.io/eq-ld/ns/context.jsonld",  "eq-ld:state":[    {      "@type":"http:RequestHeader",      "http:hdrName":"http-headers:accept",      "http:headerElements":[        {          "@type":"http:HeaderElement",          "http:elementName":"text/html"        }      ]    }  ],  "eq-ld:events":[    {      "@type":"http:RequestHeader",      "http:hdrName":"http-headers:accept",      "http:headerElements":[        {          "@type":"http:HeaderElement",          "http:elementName":"application/ld+json"        }      ]    }  ]}ㅤ

HTTP/1.1 200 OKAccept-Query: application/ld+json;  profile="http://www.w3.org/ns/json-ld#context http://cxres.github.io/eq-ld/ns/context.jsonld"Content-Type: application/httpEvents: duration=1200Incremental: ?1

HTTP/1.1 200 OKContent-Type: application/ld+jsonContent-Length: 139{  "@context": "https://json-ld.org/contexts/person.jsonld",  "@id": "http://dbpedia.org/resource/John_Doe",  "name": "John Doe"}

HTTP/1.1 200 OKContent-Type: application/ld+jsonContent-Length: 180{  "@context": "https://www.w3.org/ns/activitystreams",  "published": "2024-11-10T11:12:13Z",  "type": "Update",  "object": "https://example.org/missing/John_Doe"}

HTTP/1.1 200 OKContent-Type: application/ld+jsonContent-Length: 180{  "@context": "https://www.w3.org/ns/activitystreams",  "published": "2024-11-10T14:15:16Z",  "type": "Delete",  "object": "https://example.org/missing/John_Doe"}