Skip to main content

Thrift and JSON

The Glean schema is automatically translated into a set of Thrift type definitions by the gen-schema tool (see Workflow). These Thrift definitions can be used to work with Glean data in your client, as native data types in whatever language you're using, either for querying data or for writing facts.

The Thrift types also have a JSON representation, which can be read and written directly. When you perform queries in the shell, the results are printed as JSON-encoded Thrift; when you write data to Glean it can be in the form of JSON-encoded Thrift.

The relationship between schema types and Thrift/JSON is given by the following table:

Schema typeThrift typeJSON
natNat (i64)123
byteByte (i8)123
stringstring"abc"
boolbooltrue or false
[byte]binarybase-64 encoded string *1
[T]list<T>[...]
{
  f₁ : T₁,
  ...,
  fₙ : Tₙ
}		struct Foo {
  1: T₁ f₁;
  ...
  n: Tₙ fₙ;
}		{
  "f₁" : q₁,
  ...
  "fₙ" : qₙ
}
{
  f₁ : T₁ |
  ... |
  fₙ : Tₙ
}		union Foo {
  1: T₁ f₁;
  ...
  n: Tₙ fₙ;
}		{ "f" : t }
for one of the fields f₁..fₙ
maybe TIn a record field:
optional T f		f : t
if the value is present
enum {
  L₁|
  ...|
  Lₙ
}		enum Foo {
  L₁ = 1,
  ...
  Lₙ = n
}		the index of the value,
e.g. 12
predicate P : K -> Vstruct P {
  1: Id id
  2: optional K key
  3: optional V value
}
note*2		refer to fact N:
N or { "id": N }
define a fact:
{ "id" : N,
   "key" : t } or
{ "key": t } or
{ "key": t,
    "value" : v }
type N = Tdepending on T:
struct N { .. }
union N {...}
enum N {...}
typedef T N;		same as type T

  1. The Thrift encoding of a binary field in JSON is a base-64-encoded string. However, not all Thrift implementations respect this. At the time of writing, the Python Thrift implementation doesn't base-64-encode binary values. For this reason we provide an option in the Glean Thrift API to disable base-64 encoding for binary if your client doesn't support it. The Glean Shell also uses this option to make it easier to work with binary.

  2. the key is optional - a nested fact may be expanded in place or represented by a reference to the fact ID only. When querying Glean data the query specifies which nested facts should be expanded in the result, and when writing data to Glean using Thrift or JSON, we can optionally specify the value of nested facts inline.