Protocol Documentation
Table of Contents
grpc.proto
RdfStreamReceived
Acknowledgement of receiving a stream sent by the server to the client.
RdfStreamSubscribe
Subscribe command sent by the client to the server.
| Field | Type | Label | Description |
|---|---|---|---|
| topic | string | The topic to which the client wants to subscribe (UTF-8 encoded). | |
| requested_options | RdfStreamOptions | Optional: the stream options requested by the client. The server should respond with a stream that matches these options. In case that is not possible, the server must respond with the INVALID_ARGUMENT error. |
RdfStreamService
Pub/Sub service for RDF streams, to be implemented by the server.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| SubscribeRdf | RdfStreamSubscribe | RdfStreamFrame stream | Subscribe to an RDF stream. |
| PublishRdf | RdfStreamFrame stream | RdfStreamReceived | Publish an RDF stream. In case the server cannot process the stream, it must respond with the INVALID_ARGUMENT error. |
rdf.proto
RdfDatatypeEntry
Entry in the datatype lookup table
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | 1-based identifier If id=0, it should be interpreted as previous_id + 1. If id=0 appears in the first RdfDatatypeEntry of the stream, it should be interpreted as 1. | |
| value | string | Value of the datatype (UTF-8 encoded) |
RdfDefaultGraph
Empty message indicating the default RDF graph.
RdfGraphEnd
End of a graph in a GRAPHS stream
RdfGraphStart
Start of a graph in a GRAPHS stream
In contrast to RdfQuad, setting the graph oneof to some value is always required. No repeated terms are allowed.
| Field | Type | Label | Description |
|---|---|---|---|
| g_iri | RdfIri | IRI | |
| g_bnode | string | Blank node | |
| g_default_graph | RdfDefaultGraph | Default graph | |
| g_literal | RdfLiteral | Literal – only valid for generalized RDF streams |
RdfIri
RDF IRIs The IRIs are reconstructed by the consumer using the prefix and name lookup tables.
| Field | Type | Label | Description |
|---|---|---|---|
| prefix_id | uint32 | 1-based, refers to an entry in the prefix lookup. 0 signifies "use the same prefix_id as in the previous IRI". For this to work, IRIs must be processed strictly in order: firstly by stream row, then by term (subject, predicate, object, graph). This also applies recursively to RDF-star quoted triples. If 0 appears in the first IRI of the stream (and in any subsequent IRI), this should be interpreted as an empty ("") prefix. This is for example used when the prefix lookup table is disabled. | |
| name_id | uint32 | 1-based, refers to an entry in the name lookup. 0 signifies "use the previous name_id + 1". This requires the same order guarantees as prefixes. If 0 appears in the first IRI of the stream, it should be interpreted as name_id = 1. |
RdfLiteral
RDF literals
| Field | Type | Label | Description |
|---|---|---|---|
| lex | string | The lexical form of the literal (required). | |
| langtag | string | Language-tagged string. | |
| datatype | uint32 | Typed literal. The datatype is a reference to an entry in the datatype lookup. This value is 1-based and the value of 0 is invalid (in contrast to prefix_id and name_id in RdfIri). |
RdfNameEntry
Entry in the name lookup table
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | 1-based identifier If id=0, it should be interpreted as previous_id + 1. If id=0 appears in the first RdfNameEntry of the stream, it should be interpreted as 1. | |
| value | string | Value of the name (UTF-8 encoded) |
RdfPrefixEntry
Entry in the prefix lookup table
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | 1-based identifier If id=0, it should be interpreted as previous_id + 1. If id=0 appears in the first RdfPrefixEntry of the stream, it should be interpreted as 1. | |
| value | string | Value of the prefix (UTF-8 encoded) |
RdfQuad
RDF quad
Fields 1–12 are repeated from RdfTriple for performance reasons.
Similarly to RdfTriple, this message allows for representing generalized RDF quads (for example, with literals as predicates). Whether this is used in the stream is determined by the stream options (see RdfStreamOptions).
If no field in a given oneof is set, the term is interpreted as a repeated term – the same as the term in the same position in the previous quad. In the first quad of the stream, all terms must be set.
| Field | Type | Label | Description |
|---|---|---|---|
| s_iri | RdfIri | IRI | |
| s_bnode | string | Blank node | |
| s_literal | RdfLiteral | Literal Only valid in a generalized RDF stream. | |
| s_triple_term | RdfTriple | RDF-star quoted triple | |
| p_iri | RdfIri | IRI | |
| p_bnode | string | Blank node Only valid in a generalized RDF stream. | |
| p_literal | RdfLiteral | Literal Only valid in a generalized RDF stream. | |
| p_triple_term | RdfTriple | RDF-star quoted triple | |
| o_iri | RdfIri | IRI | |
| o_bnode | string | Blank node | |
| o_literal | RdfLiteral | Literal | |
| o_triple_term | RdfTriple | RDF-star quoted triple | |
| g_iri | RdfIri | IRI | |
| g_bnode | string | Blank node | |
| g_default_graph | RdfDefaultGraph | Default graph | |
| g_literal | RdfLiteral | Literal – only valid for generalized RDF streams |
RdfStreamFrame
RDF stream frame – base message for RDF streams.
| Field | Type | Label | Description |
|---|---|---|---|
| rows | RdfStreamRow | repeated | Stream rows |
RdfStreamOptions
RDF stream options
| Field | Type | Label | Description |
|---|---|---|---|
| stream_name | string | Name of the stream (completely optional). This may be used for, e.g., topic names in a pub/sub system. | |
| physical_type | PhysicalStreamType | Type of the stream (required) | |
| generalized_statements | bool | Whether the stream may contain generalized triples, quads, or datasets | |
| rdf_star | bool | Whether the stream may contain RDF-star statements | |
| max_name_table_size | uint32 | Maximum size of the name lookup table | |
| max_prefix_table_size | uint32 | Maximum size of the prefix lookup table | |
| max_datatype_table_size | uint32 | Maximum size of the datatype lookup table | |
| logical_type | LogicalStreamType | Logical (RDF-STaX-based) stream type In contrast to the physical type, this field is entirely optional. | |
| version | uint32 | Protocol version (required) For Jelly 1.0.x value must be 1. For custom extensions, the value must be 10000 or higher. |
RdfStreamRow
RDF stream row
| Field | Type | Label | Description |
|---|---|---|---|
| options | RdfStreamOptions | Stream options. Must occur at the start of the stream. | |
| triple | RdfTriple | RDF triple statement. Valid in streams of physical type TRIPLES or GRAPHS. | |
| quad | RdfQuad | RDF quad statement. Only valid in streams of physical type QUADS. | |
| graph_start | RdfGraphStart | Graph boundary: ends the currently transmitted graph and starts a new one Only valid in streams of physical type GRAPHS. | |
| graph_end | RdfGraphEnd | Explicit end of a graph. Signals the consumer that the transmitted graph is complete. Only valid in streams of physical type GRAPHS. | |
| name | RdfNameEntry | Entry in the name lookup table. | |
| prefix | RdfPrefixEntry | Entry in the prefix lookup table. | |
| datatype | RdfDatatypeEntry | Entry in the datatype lookup table. |
RdfTriple
RDF triple
For each term (subject, predicate, object), the fields are repeated for performance reasons. This is to avoid the need for boxing each term in a separate message.
Note: this message allows for representing generalized RDF triples (for example, with literals as predicates). Whether this is used in the stream is determined by the stream options (see RdfStreamOptions).
If no field in a given oneof is set, the term is interpreted as a repeated term – the same as the term in the same position in the previous triple. In the first triple of the stream, all terms must be set. All terms must also be set in quoted triples (RDF-star).
| Field | Type | Label | Description |
|---|---|---|---|
| s_iri | RdfIri | IRI | |
| s_bnode | string | Blank node | |
| s_literal | RdfLiteral | Literal Only valid in a generalized RDF stream. | |
| s_triple_term | RdfTriple | RDF-star quoted triple | |
| p_iri | RdfIri | IRI | |
| p_bnode | string | Blank node Only valid in a generalized RDF stream. | |
| p_literal | RdfLiteral | Literal Only valid in a generalized RDF stream. | |
| p_triple_term | RdfTriple | RDF-star quoted triple | |
| o_iri | RdfIri | IRI | |
| o_bnode | string | Blank node | |
| o_literal | RdfLiteral | Literal | |
| o_triple_term | RdfTriple | RDF-star quoted triple |
LogicalStreamType
Logical stream type, according to the RDF Stream Taxonomy (RDF-STaX). Type 0 is reserved for the unspecified stream type. The rest of the type numbers follow the taxonomical structure of RDF-STaX. For example: 1 is a subtype of 0, 13 and 23 are subtypes of 3, 114 is a subtype of 14, etc.
Types 1–4 correspond to the four base concrete stream types. Their subtypes can be in most cases simply processed in the same way as the base types. Therefore, implementations can take the modulo 10 of the stream type to determine the base type of the stream and use this information to select the appropriate processing logic.
RDF-STaX version: 1.1.2 https://w3id.org/stax/1.1.2
^ The above URL is used to automatically determine the version of RDF-STaX in the Jelly protocol specification. Please keep it up-to-date and in the same format.
| Name | Number | Description |
|---|---|---|
| LOGICAL_STREAM_TYPE_UNSPECIFIED | 0 | Unspecified stream type – invalid |
| LOGICAL_STREAM_TYPE_FLAT_TRIPLES | 1 | Flat RDF triple stream https://w3id.org/stax/ontology#flatTripleStream |
| LOGICAL_STREAM_TYPE_FLAT_QUADS | 2 | Flat RDF quad stream https://w3id.org/stax/ontology#flatQuadStream |
| LOGICAL_STREAM_TYPE_GRAPHS | 3 | RDF graph stream https://w3id.org/stax/ontology#graphStream |
| LOGICAL_STREAM_TYPE_DATASETS | 4 | RDF dataset stream https://w3id.org/stax/ontology#datasetStream |
| LOGICAL_STREAM_TYPE_SUBJECT_GRAPHS | 13 | RDF subject graph stream (subtype of RDF graph stream) https://w3id.org/stax/ontology#subjectGraphStream |
| LOGICAL_STREAM_TYPE_NAMED_GRAPHS | 14 | RDF named graph stream (subtype of RDF dataset stream) https://w3id.org/stax/ontology#namedGraphStream |
| LOGICAL_STREAM_TYPE_TIMESTAMPED_NAMED_GRAPHS | 114 | RDF timestamped named graph stream (subtype of RDF dataset stream) https://w3id.org/stax/ontology#timestampedNamedGraphStream |
PhysicalStreamType
Physical stream type This determines how the data is encoded in the stream, not the logical structure of the data. See LogicalStreamType for the latter.
| Name | Number | Description |
|---|---|---|
| PHYSICAL_STREAM_TYPE_UNSPECIFIED | 0 | Unspecified stream type – invalid |
| PHYSICAL_STREAM_TYPE_TRIPLES | 1 | RDF triples |
| PHYSICAL_STREAM_TYPE_QUADS | 2 | RDF quads |
| PHYSICAL_STREAM_TYPE_GRAPHS | 3 | RDF triples grouped in graphs |