Skip to content

Protocol Documentation

Table of Contents

Top

java/dev/enola/thing/thing.proto

CompactThing

Field Type Label Description
properties CompactThing.PropertiesEntry repeated TODO bytes, really?

CompactThing.PropertiesEntry

Field Type Label Description
key uint64
value bytes

CompactThings

Field Type Label Description
id uint64
things CompactThings.ThingsEntry repeated
links CompactThings.LinksEntry repeated

CompactThings.LinksEntry

Field Type Label Description
key uint64
value string

CompactThings.ThingsEntry

Field Type Label Description
key uint64
value CompactThing

LinksMetadata

Field Type Label Description
metadata LinksMetadata.MetadataEntry repeated Map key is IRI.

LinksMetadata.MetadataEntry

Field Type Label Description
key string
value ThingMetadata

TextThing

Field Type Label Description
properties TextThing.PropertiesEntry repeated

TextThing.PropertiesEntry

Field Type Label Description
key string
value string

TextThings

Field Type Label Description
imports string repeated
prefixes TextThings.PrefixesEntry repeated
things TextThings.ThingsEntry repeated

TextThings.PrefixesEntry

Field Type Label Description
key string
value string

TextThings.ThingsEntry

Field Type Label Description
key string
value TextThing

Thing

Thing is a generic datastructure for Linked Data.

It is inspired by the Resource Description Framework (RDF) and its Subject / Predicate / Object "Triples". It's however not "flat", but represents "Blank Nodes" as "Unlabeled Nested" sub-structures, which makes it resemble regular ProtoBuf / JSON / YAML.

This is also very close to (essentially really just a Protocol Buffer representation of) the "Expanded Term Definition" of the W3C's JSON-LD format.

This obviously also looks a bit similar to Proto's Struct (see google/protobuf/struct.proto), with additional explicit Links.

Cap’n Proto's interface types, which are passed by reference instead of value over its RPC protocol, also somewhat resemble the explicit links used here.

Field Type Label Description
iri string The IRI is often only set on the "top outer most", and may well be unset for things "contained" in other things (RDF calls this "blank nodes"). It's not even mandatory required for the "top outer most" one either. (TODO Why do we even need this?! Why not just use an https://schema.org/identifier field/attribute?)
properties Thing.PropertiesEntry repeated Key string is an IRI (of a "property"). Nota Bene: This is never a “name” (or even a “label”), but really an IRI. In theory such a Property IRI could be unique to only this single Thing; more typically, it is shared among things of the same type. Crucially though, it could also be an IRI of a property that is common among attributes of different types! Classic examples are e.g. https://schema.org/name (rdfs:label 🏷️) or rdf:type.

Thing.PropertiesEntry

Field Type Label Description
key string
value Value

ThingMetadata

Field Type Label Description
id string
label string
description_html string
image_html string

Things

Things are repeated things. TODO Keep Things? Or (better…) replace with "streaming" gRPC, only?

Field Type Label Description
things Thing repeated

Value

Value is the stuff that Thing's fields are made of.

Field Type Label Description
link string
string string
literal Value.Literal
lang_string Value.LangString TODO Keep or remove this? See https://github.com/enola-dev/enola/pull/540
struct Thing Sub-structure (contained) Thing.
list Value.List List of Values.

Value.LangString

TODO Keep or remove this? See https://github.com/enola-dev/enola/pull/540

Field Type Label Description
text string Text, for humans.
lang string BCP 47 “language tag” (e.g. “de-ch”) of the text.

Value.List

TODO Rename to Collection

Field Type Label Description
ordered bool
values Value repeated

Value.Literal

Field Type Label Description
value string Value of the literal. This is "encoded" by the datatype, below. (RDF calls this the "label", but to us that sounds wrong, because it evokes "something to show human users" too much.)
datatype string This is an IRI.

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)