JSON format

This document provides an overview of the JSON serializer format. For an overview of how to use the JSON serializer API, see the JSON addon documentation.

Value kinds

This section describes value kinds that are used by the JSON serializers.

Name

A name field returns the name of an entity as returned by ecs_get_name or flecs::entity::name.

Example:

"Earth"

Path

A path field returns the path identifier of an entity as returned by ecs_get_fullpath or flecs::entity::path. The path contains the entity's name and the names of its parent and grandparents separated by a dot (.).

Example:

"SolarSystem.Sun.Earth"

Label

A label field returns the doc name of the entity as returned by ecs_doc_get_name or flecs::entity::doc_name. The doc name is a user-friendly name for the entity that does not need to be unique and may contain any character.

Serializing labels requires the doc addon.

Example:

"The Earth"

Id

An id field returns a component id or pair. It is formatted as an array of at least one and at most three elements where the elements have the following meaning:

• Component or First element of pair
• Second element of pair
• Type flag

Each element is formatted as a Path.

Example:

["transform.Position"]
["Likes", "Apples"]
["Movement", 0, "SWITCH"]

Id**

Same as Id but with Label's instead of paths.

Example:

["Entity position"]
["Located in", "San Francisco"]

Value

A JSON object or scalar representing the value of a component. Component values can only be serialized if the component is described in the reflection framework (see the meta addon).

When a component has no value (e.g. a tag) or is not described by the reflection framework, 0 will be used as placeholder.

Example:

{"x": 10, "y": 20}

Type**

A JSON object that represents the structure of a component type.

Example:

{
    "type_info": [{
        "x": ["float"],
        "y": ["float"]
    }, 0, 0]
}

Entity

The entity kind is an object that contains metadata and data of a single serialized entity, and is returned by the Entity serializer.

The following sections describe the fields that an object of the entity kind may contain:

"path

The entity path.

Type: Path, optional

"label

The entity doc name.

Type: Label, optional

"brief

Brief description (as returned by ecs_doc_get_brief).

Type: string, optional

"link

Link to URL (as returned by ecs_doc_get_link).

Type: string, optional

"is_a

Base entities.

Type: Array(Entity), optional

"ids

Component ids.

Type: Array(Id)

"id_labels

Component labels.

Type: Array(Id label), optional

"hidden

Array indicating whether a component is hidden. Only applies to components of base entities (in the ["is_a"](is_a) array).

A base component is hidden when it is overridden by an entity higher in the inheritance hierarchy.

Type: Array(bool), optional

"values

Component values.

Type: Array(Value), optional

"type_info

Array with objects that describe the component types of the terms.

Type: Array(Type info), optional

Example

Default serializer options:

{
    "path":"Sun.Earth",
    "ids":[
        ["Position"],
        ["flecs.core.ChildOf", "Sun"],
        ["flecs.core.Identifier", "flecs.core.Name"]
    ]
}

This example shows an entity with a base (an IsA relationship) with default serializer options:

{
    "path":"Sun.Earth",
    "is_a": [{
        "path":"planets.RockyPlanet",
        "ids": [
            ["planets.HasRocks"]
        ]
    }],
    "ids":[
        ["Position"],
        ["flecs.core.ChildOf", "Sun"],
        ["flecs.core.Identifier", "flecs.core.Name"]
    ]
}

This example shows an entity with a base with all serializer options enabled:

{
    "path":"Sun.Earth",
    "label": "The Earth",
    "brief": "The planet you call home",
    "link": "www.earth.com",
    "is_a": [{
        "path":"planets.RockyPlanet",
        "label":"A rocky planet",
        "ids": [
            ["Position"],
            ["planets.HasRocks"]
        ],
        "id_labels": [
            ["Position"],
            ["HasRocks"]
        ],
        "values":[0, 0],
        "hidden":[true, false]
    }],
    "ids":[
        ["Position"],
        ["flecs.core.ChildOf", "Sun"],
        ["flecs.core.Identifier", "flecs.core.Name"]
    ],
    "ids_labels":[
        ["Position"],
        ["ChildOf", "Sun"],
        ["Identifier", "Name"]
    ],
    "values":[
        {"x": 10, "y": 20},
        0, 0
    ],
    "type_info": [{
        "x": ["float"],
        "y": ["float"]
    }, 0, 0]
}

Result

The result kind is an object that contains the metadata and data of a single result returned by an iterator (see Iterator).

The following sections describe the fields that an object of the entity kind may contain:

parent

Parent of the entity in current result.

Type: Array(Path), optional

entities

Array with paths of the returned entities.

Type: Array(Name), optional

entity_labels

Same as entities, but with Label's instead of paths.

Type: Array(Label), optional

entity_ids

Same as entities, but with numerical ids instead of paths.

Type: Array(Number), optional

sources

Array with paths of sources for each term. A subject indicates the actual entity on which a component is stored. If this is the matched entity (default) the array will contain a 0 element.

Type: Array(Path), optional

variables

Array with variable values for current result (see query variables).

Type: Array(Path), optional

variable_labels

Same as variables, but with Label's instead of paths.

Type: Array(Label), optional

variable_ids

Same as variables, but with numerical ids instead of paths.

Type: Array(Number), optional

ids

Array with component ids. This list is more specific than the ids array provided by the top-level iterator object. The arrays can be different in the case of terms with an Or operator, or terms with wildcard ids.

Type: Array(string), optional

is_set

Array with booleans that can be used to determine whether terms with the Optional operator are set.

Type: Array(bool), optional

values

Array with component values. The array contains an element for each term. If a component has no value, or no value could be serialized for the component a [] element is added.

Each element in the array can be either an array with component values when the component is from the matched entity, or a single component value when the component is from another entity (like a parent, prefab, singleton).

Type: Array(Array(Value)), optional

Iterator

The iterator kind is an object that contains metadata and data of all the entities yielded by an iterator.

"ids

Array with ids for each term.

Type: Array(string), optional

"variables

Array with variable names (see query variables).

Type: Array(string), optional

"results

Array with elements for each returned result.

Type: Array(Result)

"eval_duration

Time it took to serialize the iterator.

Type: Number

"type_info

Array with objects that describe the component types of the terms.

Type: Array(Type info), optional

Example

{
  "ids": ["Position", "Jedi"],
  "results": [{
    "entities": ["Luke", "Yoda"],
    "values": [
      [{ "x": 10, "y": 20 },
       { "x": 20, "y": 30 }],
      0
    ]
  }]
}

Entity serializer

The entity serializer returns a JSON string of the Entity type. This format is returned by ecs_entity_to_json and flecs::entity::to_json.

Serializer options

The following options (found in ecs_entity_to_json_desc_t) customize the output of the entity serializer:

serialize_path

Serialize the "path" member.

Default: true

Example:

{"path": "SolarSystem.Sun.Earth"}

serialize_label

Serialize the "label" member.

Default: false

Example:

{"label": "Rocky planet"}

serialize_brief

Serialize the "brief" member.

Default: false

Example:

{"brief": "A rocky planet"}

serialize_link

Serialize the "link" member.

Default: false

Example:

{"brief": "www.rocky-planet.com"}

serialize_id_labels

Serializes the "id_labels" member.

Default: false

Example:

{"id_labels": [["A Rocky Planet"], ["Has surface water"]]}

serialize_base

Serializes the "is_a" member.

Default: true

Example:

{"is_a": [{
    "path":"planets.RockyPlanet",
    "ids": [
        ["planets.HasRocks"]
    ]
}]}

serialize_private

Serialize private components. Private components are regular components with the EcsPrivate (or flecs::Private) tag. When serialize_private is false, private components will be hidden from all arrays.

Example:

{"ids": ["Position", "PrivateComponent"]}

Default: false

serialize_hidden

Serializes the "hidden" member.

Example:

{"hidden":[true, false]}

Full example:

{
    "path":"Sun.Earth",
    "is_a": [{
        "path":"planets.RockyPlanet",
        "ids": [
            ["Position"],
            ["planets.HasRocks"]
        ],
        "hidden":[true, false]
    }],
    "ids":[
        ["Position"],
        ["flecs.core.ChildOf", "Sun"],
        ["flecs.core.Identifier", "flecs.core.Name"]
    ]
}

Note that hidden[0] is true in this example, because the Position component from planets.RockyPlanet is overridden by the entity.

Default: false

serialize_values

Serializes the "values" member.

Example:

{"values":[{"x":10, "y": 20}, 0]}

Default: false

serialize_type_info

Serialize the "type_info" member.

Example:

{
    "type_info": [{
        "x": ["float"],
        "y": ["float"]
    }, 0, 0]
}

Iterator serializer

The entity serializer returns a JSON string of the Iterator type. This format is returned by ecs_iter_to_json.

Serializer options

serialize_term_ids

Serialize the top level "ids" member.

Default: true

Example:

Example result for query Position, Jedi

{
  "ids": ["Position", "Jedi"],
  "results": [ ]
}

serialize_ids

Serialize the result specific "ids" member.

If the iterated query does not contain variable ids (either an Or term or a term with a wildcard id) the result specific ids member will exactly match the top-level ids member.

Default: true

Example:

Example result for query Position, (Likes, *)

{
  "ids": ["Position", "(Likes,*)"],
  "results": [{
    "ids": ["Position", "(Likes,Apples)"]
  }]
}

serialize_sources

Serialize the "sources" member.

Default: true

Example:

Example result for query Position, Position(parent)

{
  "ids": ["Position", "Position"],
  "results": [{
    "entities": ["Parent.A", "Parent.B"],
        "sources": [0, "Parent"]
  }]
}

serialize_variables

Serialize the "variables" member.

Default: true

Example:

Example result for query Position, (Likes, _Food)

{
  "variables": ["Food"],
  "results": [{
    "ids": ["Position", "(Likes,Apples)"],
        "variables": ["Apples"],
  }]
}

serialize_is_set

Serialize the "is_set" member.

Default: true

Example:

Example result for query Position, ?Velocity

{
    "ids": ["Position", "Velocity"],
  "results": [{
        "is_set": [true, false]
  }]
}

serialize_values

Serialize the "values" member.

Default: true

Example:

Example result for query Position

{
  "ids": ["Position"],
  "results": [{
    "values": [
      [{
        "x": 10,
        "y": 20
      }]
    ]
  }]
}

serialize_entities

Serialize the "entities" member.

Default: true

Example:

{
  "results": [{
    "entities": ["MyEntity"]
  }]
}

serialize_entity_labels

Serialize the "entity_labels" member.

Default: false

Example:

{
  "results": [{
    "entities": ["Parent.MyEntity"],
        "entity_labels": ["My entity"]
  }]
}

serialize_variable_labels

Serialize the "variable_labels" member.

Default: false

Example:

{
  "results": [{
    "variables": ["GrannySmith"],
    "variable_labels": ["Granny smith"]
  }]
}

measure_eval_duration

Serialize the "eval_duration" member.

Default: false

Example:

{
  "eval_duration": 0.001
}

serialize_type_info

Serialize the "type_info" member.

Default: false

Example:

{
  "ids": ["Position", "Jedi"],
  "type_info": [{
      "x": ["float"],
      "y": ["float"]
  }, 0],
  "results": [{
  }]
}