Sites

These are the docs for 14.1, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.4 is the newest →

# 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 `object`s
`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` `object`s

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" : 
``````

### `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 `object`s 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_event`s (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 `component`s 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": {
"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" :  {...}}
]
``````
{"ft_lang_label":"__label__en","ft_lang_prob":0.7115616,"math_prob":0.7572806,"size":9561,"snap":"2019-51-2020-05","text_gpt3_token_len":2418,"char_repetition_ratio":0.18876216,"word_repetition_ratio":0.15812777,"special_character_ratio":0.2582366,"punctuation_ratio":0.15632184,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.9785714,"pos_list":[0,1,2],"im_url_duplicate_count":[null,null,null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2020-01-27T18:01:27Z\",\"WARC-Record-ID\":\"<urn:uuid:e9595055-13b4-4b6c-8776-9a204aa6bc40>\",\"Content-Length\":\"82014\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:d0ce71ec-b1ed-4fff-a2ea-2541456f90d0>\",\"WARC-Concurrent-To\":\"<urn:uuid:65b978f9-0767-40ba-91df-b887a717a876>\",\"WARC-IP-Address\":\"35.193.224.116\",\"WARC-Target-URI\":\"https://docs.improbable.io/reference/14.1/shared/schema/json\",\"WARC-Payload-Digest\":\"sha1:3FVD4LJVBJ22LIGC4WXQPGXHIEHFHDS5\",\"WARC-Block-Digest\":\"sha1:P6LCFGX55JGAOYMKS3SVQKVTXAC5EHB2\",\"WARC-Identified-Payload-Type\":\"text/html\",\"warc_filename\":\"/cc_download/warc_2020/CC-MAIN-2020-05/CC-MAIN-2020-05_segments_1579251705142.94_warc_CC-MAIN-20200127174507-20200127204507-00544.warc.gz\"}"}