Protobuf sources
Below you will find the Protocol Buffers definitions for the Jelly serialization format and 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.
// Protocol version: 1.0.0
// 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 {
}
// 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
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
uint32 max_name_table_size = 9;
// Maximum size of the prefix lookup table
uint32 max_prefix_table_size = 10;
// Maximum size of the datatype lookup table
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 custom extensions, the value must be 1000 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.0
// https://w3id.org/stax/1.1.0
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;
// 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;
}
grpc.proto
syntax = "proto3";
package eu.ostrzyciel.jelly.core.proto.v1;
// gRPC service specifications for RDF 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);
}