Protobuf sources
Below you will find the Protocol Buffers definitions for the Jelly-RDF and Jelly-Patch formats, along with the Jelly gRPC streaming protocol. The original files are hosted on GitHub and all releases can be found here.
Human-readable reference for these definitions can be found here.
The following code is licensed under the Apache License, Version 2.0.
rdf.proto
syntax = "proto3";
package eu.ostrzyciel.jelly.core.proto.v1;
// Jelly RDF serialization with Protocol Buffers.
// Specification document:
// https://w3id.org/jelly/1.1.1/specification/serialization
// Protocol version: 1.1.1
// RDF IRIs
// The IRIs are reconstructed by the consumer using the prefix and name
// lookup tables.
message RdfIri {
// 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.
uint32 prefix_id = 1;
// 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.
uint32 name_id = 2;
}
// RDF literals
message RdfLiteral {
// The lexical form of the literal (required).
string lex = 1;
// Literal kind – at most one of these field may be set.
// If none is set, then it's a simple literal.
oneof literalKind {
// Language-tagged string.
string langtag = 2;
// 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).
uint32 datatype = 3;
}
}
// Empty message indicating the default RDF graph.
message RdfDefaultGraph {
}
// 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).
message RdfTriple {
// Triple subject
oneof subject {
// IRI
RdfIri s_iri = 1;
// Blank node
string s_bnode = 2;
// Literal
// Only valid in a generalized RDF stream.
RdfLiteral s_literal = 3;
// RDF-star quoted triple
RdfTriple s_triple_term = 4;
}
// Triple predicate
oneof predicate {
// IRI
RdfIri p_iri = 5;
// Blank node
// Only valid in a generalized RDF stream.
string p_bnode = 6;
// Literal
// Only valid in a generalized RDF stream.
RdfLiteral p_literal = 7;
// RDF-star quoted triple
RdfTriple p_triple_term = 8;
}
// Triple object
oneof object {
// IRI
RdfIri o_iri = 9;
// Blank node
string o_bnode = 10;
// Literal
RdfLiteral o_literal = 11;
// RDF-star quoted triple
RdfTriple o_triple_term = 12;
}
}
// 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.
message RdfQuad {
// Quad subject
oneof subject {
// IRI
RdfIri s_iri = 1;
// Blank node
string s_bnode = 2;
// Literal
// Only valid in a generalized RDF stream.
RdfLiteral s_literal = 3;
// RDF-star quoted triple
RdfTriple s_triple_term = 4;
}
// Quad predicate
oneof predicate {
// IRI
RdfIri p_iri = 5;
// Blank node
// Only valid in a generalized RDF stream.
string p_bnode = 6;
// Literal
// Only valid in a generalized RDF stream.
RdfLiteral p_literal = 7;
// RDF-star quoted triple
RdfTriple p_triple_term = 8;
}
// Quad object
oneof object {
// IRI
RdfIri o_iri = 9;
// Blank node
string o_bnode = 10;
// Literal
RdfLiteral o_literal = 11;
// RDF-star quoted triple
RdfTriple o_triple_term = 12;
}
// Quad graph
oneof graph {
// IRI
RdfIri g_iri = 13;
// Blank node
string g_bnode = 14;
// Default graph
RdfDefaultGraph g_default_graph = 15;
// Literal – only valid for generalized RDF streams
RdfLiteral g_literal = 16;
}
}
// 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.
message RdfGraphStart {
oneof graph {
// IRI
RdfIri g_iri = 1;
// Blank node
string g_bnode = 2;
// Default graph
RdfDefaultGraph g_default_graph = 3;
// Literal – only valid for generalized RDF streams
RdfLiteral g_literal = 4;
}
}
// End of a graph in a GRAPHS stream
message RdfGraphEnd {
}
// Explicit namespace declaration
//
// This does not correspond to any construct in the RDF Abstract Syntax.
// Rather, it is a hint to the consumer that the given IRI prefix (namespace)
// may be associated with a shorter name, like in Turtle syntax:
// PREFIX ex: <http://example.org/>
//
// These short names (here "ex:") are NOT used in the RDF statement encoding.
// This is a purely cosmetic feature useful in cases where you want to
// preserve the namespace declarations from the original RDF document.
// These declarations have nothing in common with the prefix lookup table.
message RdfNamespaceDeclaration {
// Short name of the namespace (e.g., "ex")
// Do NOT include the colon.
string name = 1;
// IRI of the namespace (e.g., "http://example.org/")
RdfIri value = 2;
}
// Entry in the name lookup table
message RdfNameEntry {
// 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.
uint32 id = 1;
// Value of the name (UTF-8 encoded)
string value = 2;
}
// Entry in the prefix lookup table
//
// Note: the prefixes in the lookup table can be arbitrary strings, and are
// NOT meant to be user-facing. They are only used for IRI compression.
// To transmit user-facing namespace declarations for cosmetic purposes, use
// RdfNamespaceDeclaration.
message RdfPrefixEntry {
// 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.
uint32 id = 1;
// Value of the prefix (UTF-8 encoded)
string value = 2;
}
// Entry in the datatype lookup table
message RdfDatatypeEntry {
// 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.
uint32 id = 1;
// Value of the datatype (UTF-8 encoded)
string value = 2;
}
// RDF stream options
message RdfStreamOptions {
// Name of the stream (completely optional).
// This may be used for, e.g., topic names in a pub/sub system.
string stream_name = 1;
// Type of the stream (required)
PhysicalStreamType physical_type = 2;
// Whether the stream may contain generalized triples, quads, or datasets
bool generalized_statements = 3;
// Whether the stream may contain RDF-star statements
bool rdf_star = 4;
// Maximum size of the name lookup table
// (required, must be >= 8)
uint32 max_name_table_size = 9;
// Maximum size of the prefix lookup table
// (required if the prefix lookup is used)
uint32 max_prefix_table_size = 10;
// Maximum size of the datatype lookup table
// (required if datatype literals are used)
uint32 max_datatype_table_size = 11;
// Logical (RDF-STaX-based) stream type
// In contrast to the physical type, this field is entirely optional.
LogicalStreamType logical_type = 14;
// Protocol version (required)
// For Jelly 1.0.x value must be 1.
// For Jelly 1.1.x value must be 2.
// For custom extensions, the value must be 10000 or higher.
uint32 version = 15;
}
// 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.
enum PhysicalStreamType {
// Unspecified stream type – invalid
PHYSICAL_STREAM_TYPE_UNSPECIFIED = 0;
// RDF triples
PHYSICAL_STREAM_TYPE_TRIPLES = 1;
// RDF quads
PHYSICAL_STREAM_TYPE_QUADS = 2;
// RDF triples grouped in graphs
PHYSICAL_STREAM_TYPE_GRAPHS = 3;
}
// 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.
enum LogicalStreamType {
// Unspecified stream type – invalid
LOGICAL_STREAM_TYPE_UNSPECIFIED = 0;
// Flat RDF triple stream
// https://w3id.org/stax/ontology#flatTripleStream
LOGICAL_STREAM_TYPE_FLAT_TRIPLES = 1;
// Flat RDF quad stream
// https://w3id.org/stax/ontology#flatQuadStream
LOGICAL_STREAM_TYPE_FLAT_QUADS = 2;
// RDF graph stream
// https://w3id.org/stax/ontology#graphStream
LOGICAL_STREAM_TYPE_GRAPHS = 3;
// RDF dataset stream
// https://w3id.org/stax/ontology#datasetStream
LOGICAL_STREAM_TYPE_DATASETS = 4;
// RDF subject graph stream (subtype of RDF graph stream)
// https://w3id.org/stax/ontology#subjectGraphStream
LOGICAL_STREAM_TYPE_SUBJECT_GRAPHS = 13;
// RDF named graph stream (subtype of RDF dataset stream)
// https://w3id.org/stax/ontology#namedGraphStream
LOGICAL_STREAM_TYPE_NAMED_GRAPHS = 14;
// RDF timestamped named graph stream (subtype of RDF dataset stream)
// https://w3id.org/stax/ontology#timestampedNamedGraphStream
LOGICAL_STREAM_TYPE_TIMESTAMPED_NAMED_GRAPHS = 114;
}
// RDF stream row
message RdfStreamRow {
// Exactly one of these fields must be set.
oneof row {
// Stream options. Must occur at the start of the stream.
RdfStreamOptions options = 1;
// RDF triple statement.
// Valid in streams of physical type TRIPLES or GRAPHS.
RdfTriple triple = 2;
// RDF quad statement.
// Only valid in streams of physical type QUADS.
RdfQuad quad = 3;
// Graph boundary: ends the currently transmitted graph and starts a new one
// Only valid in streams of physical type GRAPHS.
RdfGraphStart graph_start = 4;
// Explicit end of a graph.
// Signals the consumer that the transmitted graph is complete.
// Only valid in streams of physical type GRAPHS.
RdfGraphEnd graph_end = 5;
// Explicit namespace declaration.
RdfNamespaceDeclaration namespace = 6;
// Entry in the name lookup table.
RdfNameEntry name = 9;
// Entry in the prefix lookup table.
RdfPrefixEntry prefix = 10;
// Entry in the datatype lookup table.
RdfDatatypeEntry datatype = 11;
}
}
// RDF stream frame – base message for RDF streams.
message RdfStreamFrame {
// Stream rows
repeated RdfStreamRow rows = 1;
// Arbitrary metadata
// The keys are UTF-8 encoded strings, the values are byte arrays.
// This may be used by implementations in any way they see fit.
// The metadata does not affect the RDF data in any way, treat it
// as comments in a text file.
map<string, bytes> metadata = 15;
}
patch.proto
syntax = "proto3";
package eu.ostrzyciel.jelly.core.proto.v1.patch;
// EXPERIMENTAL FEATURE -- the API and format may change.
// RDF Patch implementation based on Jelly
// RDF Patch spec: https://afs.github.io/rdf-delta/rdf-patch.html
// Jelly-Patch spec: https://w3id.org/jelly/1.1.0/specification/patch
import "rdf.proto";
message RdfPatchTransactionStart {
}
message RdfPatchTransactionCommit {
}
message RdfPatchTransactionAbort {
}
message RdfPatchNamespace {
// Short name of the namespace (e.g., "ex")
// Do NOT include the colon.
string name = 1;
// IRI of the namespace (e.g., "http://example.org/").
// Optional in the "prefix delete" (PD) operation,
// but required in the "prefix add" (PA) operation.
RdfIri value = 2;
// Graph name for the namespace declaration.
//
// This is required for the statement type QUADS, and disallowed for
// the statement type TRIPLES.
//
// This is used to achieve full 1:1 replication in systems that associate
// namespaces with specific graphs (e.g., Apache Jena).
//
// Repeated term compression IS supported for this field.
// The repeated terms are shared between the namespace and statement rows.
oneof graph {
// IRI
RdfIri g_iri = 3;
// Blank node
string g_bnode = 4;
// Default graph
RdfDefaultGraph g_default_graph = 5;
// Literal – only valid for generalized RDF streams
RdfLiteral g_literal = 6;
}
}
// Metadata header for RDF Patch.
// Header rows must occur at the start of the patch frame.
message RdfPatchHeader {
// Header key (required)
string key = 1;
// Header value (required)
// Repeated term compression is not supported for header values.
// This oneof must always be set to a valid RDF term.
oneof value {
// IRI
RdfIri h_iri = 2;
// Blank node
string h_bnode = 3;
// Literal
RdfLiteral h_literal = 4;
// RDF-star quoted triple
RdfTriple h_triple_term = 5;
}
}
message RdfPatchPunctuation {
}
// RDF Patch stream options
message RdfPatchOptions {
// Type of statements in the stream (required)
PatchStatementType statement_type = 1;
// Type of the stream (required)
PatchStreamType stream_type = 2;
// Whether the stream may contain generalized triples, quads, or datasets
bool generalized_statements = 3;
// Whether the stream may contain RDF-star statements
bool rdf_star = 4;
// Maximum size of the name lookup table
// (required, must be >= 8)
uint32 max_name_table_size = 9;
// Maximum size of the prefix lookup table
// (required if the prefix lookup is used)
uint32 max_prefix_table_size = 10;
// Maximum size of the datatype lookup table
// (required if datatype literals are used)
uint32 max_datatype_table_size = 11;
// Protocol version (required)
// For Jelly-Patch 1.0.x (based on Jelly-RDF 1.1.x), the value must be 1.
// For custom extensions, the value must be 10000 or higher.
uint32 version = 15;
}
// Type of statements in the stream.
// This determines whether the statements are interpreted as triples or quads.
enum PatchStatementType {
// Unspecified stream type – invalid
PATCH_STATEMENT_TYPE_UNSPECIFIED = 0;
// RDF triples
PATCH_STATEMENT_TYPE_TRIPLES = 1;
// RDF quads
PATCH_STATEMENT_TYPE_QUADS = 2;
}
// Type of the stream.
// This determines whether each RdfPatchFrame is a complete patch by itself,
// or part of a larger patch.
enum PatchStreamType {
// Unspecified stream type – invalid
PATCH_STREAM_TYPE_UNSPECIFIED = 0;
// Each RdfPatchFrame is a complete patch.
// In this case, transactions cannot span multiple frames.
PATCH_STREAM_TYPE_FRAME = 1;
// Entire stream is a single patch.
// Transactions may span multiple frames.
PATCH_STREAM_TYPE_FLAT = 2;
// Stream contains multiple patches separated by punctuation marks.
// Patches and transactions may span multiple frames.
// Each frame must contain at most one patch.
PATCH_STREAM_TYPE_PUNCTUATED = 3;
}
// A row in an RDF Patch stream
message RdfPatchRow {
oneof row {
// Stream options. Must be the first row in the stream.
RdfPatchOptions options = 1;
// Add a triple/quad statement (A)
RdfQuad statement_add = 2;
// Delete a triple/quad statement (D)
RdfQuad statement_delete = 3;
// Add a namespace/prefix declaration (PA)
RdfPatchNamespace namespace_add = 4;
// Delete a namespace/prefix declaration (PD)
RdfPatchNamespace namespace_delete = 5;
// Transaction start (TX)
RdfPatchTransactionStart transaction_start = 6;
// Transaction commit (TC)
RdfPatchTransactionCommit transaction_commit = 7;
// Transaction abort (TA)
RdfPatchTransactionAbort transaction_abort = 8;
// Entry in the name lookup table.
RdfNameEntry name = 11;
// Entry in the prefix lookup table.
RdfPrefixEntry prefix = 12;
// Entry in the datatype lookup table.
RdfDatatypeEntry datatype = 13;
// Header entry (H)
RdfPatchHeader header = 14;
// Punctuation mark, only used in stream type PUNCTUATED
// Indicates the end of a patch.
RdfPatchPunctuation punctuation = 15;
}
}
// A batch of RDF patch rows.
message RdfPatchFrame {
// Patch rows
repeated RdfPatchRow rows = 1;
}
grpc.proto
syntax = "proto3";
package eu.ostrzyciel.jelly.core.proto.v1;
// Jelly gRPC streaming protocol.
// Specification document: https://w3id.org/jelly/1.0.0/specification/streaming
// Protocol version: 1.0.0
import "rdf.proto";
// Subscribe command sent by the client to the server.
message RdfStreamSubscribe {
// The topic to which the client wants to subscribe (UTF-8 encoded).
string topic = 1;
// 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.
RdfStreamOptions requested_options = 2;
}
// Acknowledgement of receiving a stream sent by the server to the client.
message RdfStreamReceived {
}
// Pub/Sub service for RDF streams, to be implemented by the server.
service RdfStreamService {
// Subscribe to an RDF stream.
rpc SubscribeRdf (RdfStreamSubscribe) returns (stream RdfStreamFrame);
// Publish an RDF stream.
// In case the server cannot process the stream, it must respond with
// the INVALID_ARGUMENT error.
rpc PublishRdf (stream RdfStreamFrame) returns (RdfStreamReceived);
}