Sites

Menu

JSON representation of schema data

This page describes the JSON representation of schema data. This representation is designed to make it possible to easily parse, generate, and manipulate SpatialOS component data with a familiar format.

Usage

JSON Representation of Schema_ objects

You can use the Schema_Json_ family of functions in c_schema.h to convert between Schema_ objects and their JSON string representation. For example, you can convert a Schema_ComponentUpdate to a JSON string representation using Schema_Json_DumpComponentUpdate and you can convert a JSON string representation of a component update to a Schema_ComponentUpdate using Schema_Json_LoadComponentUpdate.

JSON Snapshots

You can save and load JSON snapshots using the Worker_SnapshotOutputStream_* and Worker_SnapshotInputStream_* family of functions in the C SDK by setting the Schema_JsonParameters in your Worker_SnapshotParameters.

Please see backwards compatibility properties for a description of the backwards compatibility of JSON snapshots.

JSON representation of schema types

See the table below for an at-a-glance reference of the mapping from schema datatypes to their JSON representation.

Schemalang type JSON type Notes
bool boolean
uint32, uint64, int32, int64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64 number
float, double number string for unrepresentable floating point numbers
EntityID string
enum string
map<K,V> array of objects
list<T> array of the JSON representation of type T
option<T> array containing 0 or 1 entries of the JSON representation of the type T
string string UTF-8 encoded
bytes string base64 encoded
schema type T object
component C object
component update to component C object
entity object
snapshot array of entity objects

The sections below describe in more detail the mapping between schema types and their JSON representations.

bool

The bool schema type is represented as JSON boolean.

For example, a bool field bool_value with the value True would be represented in JSON as:

"bool_value" : true

Integers

The integral schema data types (uint32, uint64, int32, int64, sint32, sint64, fixed32, fixed64, sfixed32, and sfixed64) are all represented as a JSON number.

For example, an int32 field example_integer with the value 123 would be represented in JSON as:

"example_integer": 123 

Note: Numbers outside of the range of (-2^53 + 1, 2^53 - 1) can cause loss of precision in some third-party JSON processors, because they are interpreted as 64-bit floats. The schema JSON processor outputs a warning when writing an integer value outside of this range, and can handle reading integers outside of this range.

Floating point numbers

The floating point schema datatypes (float and double) are represented as a JSON number.

For example, a float field example_float with the value 123.456 would be represented in JSON as:

"example_float" : 123.456

Unrepresentable floating point numbers

JSON numbers do not implement any floating point standard, and certain values are not representable. In the schema JSON representation, replacement strings are used for unrepresentable floating point values. The following table lists the mapping between these values and their JSON representation:

Value JSON representation
Not a number "NaN"
Infinity "Infinity"
Negative infinity "-Infinity"

For example, a float field example_float with the value positive infinity, would be represented in JSON as:

"example_float" : "Infinity"

enum

The enum schema data type is represented as a JSON string. The value of the string is the name of the enum case value that the field is assigned.

For example, given a schema enum definition: enum ExampleEnum { VALUE_1 = 1; VALUE_2 = 2;}, an ExampleEnum field enum_example with the value ExampleEnum.VALUE_1 would be represented in JSON as:

"enum_example" : "VALUE_1"

map<K, V>

The map<K, V> schema data type is represented as an array of JSON objects, one for each entry in the map. Each object contains two properties:

  • "key" contains the JSON representation of the schema type K
  • "value" contains the JSON representation of the schema type V.

For example, a map<string, double> field example_map with a single entry of ("the key", 2.5) would be represented in JSON as:

"example_map" : [{"key" : "the key" , "value" : 2.5}]  

list<T>

The list<T> schema data type is represented as an array of the JSON representation of the schmea type T.

For example, for a list<int32> field example_list which has the set of elements 1, 2, and 3, the JSON representation would be:

"example_list" : [1, 2, 3]

option<T>

The option<T> schema data type is represented as an array containing 0 or 1 entries of the JSON representation of the schema type T.

For example, an option<int32> field example_option that is empty would be represented in JSON as:

"example_option" : []

If the option contains the value 234, the JSON representation would be:

"example_option" : [234]

string

The string schema data type is represented as a JSON string. This string is UTF-8 encoded.

Note: Some byte sequences cannot be represented in UTF-8. In this case they are replaced with a UTF-8 replacement character (U+FFFD). This means that the original byte sequence containing the non-valid UTF-8 character cannot be obtained back from the JSON encoding. If you want to represent arbitrary bytes in your schema, you should use a bytes field instead.

For example, a string field example_string which has been assigned the value "Hello, 你好, Привет, مرحبا"“ would be represented in JSON as:

"example_string" : "Hello, 你好, Привет, مرحبا"

bytes

The bytes schema data type is represented as a JSON string. This byte string is encoded using Base64 encoding.

For example, a bytes field example_bytes which has been assigned the values {0x22, 0x33, 0x34, 0x72, 0x12} would be represented in JSON as:

"example_bytes" : "IjM0chI="

type T

An instance of a schema type T is represented as a JSON object. The object contains one property for each field in T. The name of each property is the corresponding field name and the value of each property is the JSON encoding of the corresponding field.

For example, given a schema type definition:

type ExampleType {
    double x = 1;
    list<int> y = 2;
    option<string> z = 3;
}

An instance of ExampleType where x = 123.456, y = {1, 2, 3} and z = "string value" would be represented in JSON as:

{
    "x" : 123.456,
    "y" : [1, 2, 3],
    "z" : ["string value"]
}

component C

The JSON encoding of a component C is the same as the representation of its underlying type T.

Component update to component C

Similarly to a component C, a component update is represented as a JSON object, where the properties of the object are the field names of the component as defined in the schema definition, and the corresponding values of the properties are the JSON encoding of the component’s fields.

However, an update differs from a component in the following ways:

  • A field is included in the JSON encoding if and only if it is contained in the update.
  • Cleared collection fields are represented as an empty JSON array.
  • Events are represented as an array containing JSON objects encoding the event’s type. Events are present only if the update contains at least one event.

For example, given a schema component definition:

type EventType {
    string message = 1;
}

component ExampleComponent {
    double x = 1;
    list<int> y = 2;
    option<string> z = 3;
    event EventType example_event; 
}

An ExampleComponent component update which updates the value of x to 10, clears the value of y, does not change the value of z, and contains 2 example_events (containing the message values "event 1!" and "event 2!", respectively) would be represented in JSON as:

{
    "x" : 10,
    "y" : [],
    "example_event" : [{"message" : "event 1!"}, {"message" : "event 2!"}]
}

Entity

An instance of an entity is encoded as a JSON object, where the properties of the object are the fully-qualified names of the components of the entity and the corresponding values of the properties are the JSON encoding of the components. Entities have an additional optional property, __entity_id, which is set only if the JSON entity is part of a JSON snapshot; the value of this property is a number containing the ID of the entity.

For example, given an entity with an ID of 100, which contains the standard library components improbable.Position (with the value coords = {1, 2, 3}) and improbable.EntityAcl, as well as the component ExampleComponent defined here:

package improbable.example;

component ExampleComponent {
    double x = 1;
    list<int> y = 2;
    option<string> z = 3;
}

If our entity’s ExampleComponent component is assigned the values x = 123.456, y = {1, 2, 3}, and z = "string value", the entity would be represented in JSON as:

{
    "__entity_id": 100,
    "improbable.Position": {
        "coords": {
            "x": 1,
            "y": 2,
            "z": 3
        }
    },
    "improbable.EntityAcl": {
        "read_acl": {
            "attribute_set": ["example_attribute"]
        },
        "write_acl": ["example_attribute"]
    },
    "improbable.example.ExampleComponent": {
        "x": 123.456,
        "y": [1, 2, 3],
        "z": ["string value"]
    }
}

Snapshot

A snapshot is encoded as a JSON array containing the object encoding of the entities in the snapshot.

For example, a snapshot containing three entities would be represented in JSON as:

[ 
    {"__entity_id" :  1, "package_name.ComponentName" :  {...}}, 
    {"__entity_id" :  2, "other_package.DifferentComponentName" :  {...}, "package_name.ComponentName" :  {...}},
    {"__entity_id" :  3, "other_package.ExampleComponent" :  {...}} 
]

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums