Overview

Enable JSON serialization

JSON serialization is controlled by attributes, starting with json. namespace.

For example, JSON serialization may be enabled for module or type using json.enabled attribute. See Enabling Serialization Format for more details.

See JSON Serialization Attributes for the full list of JSON attributes that are not target-specific.

Warning

JSON imposes limitations on types it can serialize. In particular, dict types can be serialized to JSON only if integer, string and enum types (or other types that have bulit-in or custom string serialization) are used as dict keys.

JSON Data

JSON serialization in generated code is performed from Igor data objects to target-specific JSON data, not to JSON string. It is up to the user to decide how to format JSON to string, and to parse string to JSON data for further deserialization.

Note

That said, in some cases, e.g. for HTTP resources with application/json content type, JSON data <-> string conversion may be performed by generated code.

Modelling Existing JSON Layout

JSON value may belong to one of following types: string, number, object, array, and special values: true, false and null. The following table illustrates which Igor types you can choose when modelling existing JSON layout.

JSON Type	Igor Type	Comment
string	string atom enum	enum may be a prefered choice when string belongs to the fixed set of known values
number	float double int and other integer types	Although JSON standard doesn’t distingush integer and float types, many real world implementations do so. You may use integer types to limit constraints
true false	bool
array	list<T> flags<T>	flags may be used if T is enum
object	dict<K,V> record variant	Use dict if object keys are all of the same type and records if they are of different types, but the set of names if fixed and known. Use variants if there’s a single tag field that defines which set of other fields is used.
null	?T	If null is a valid value, use optional type to denote that.

Unset Values vs null

Optional record fields

For optional record fields there’s no difference if they are not included into JSON object at all or set to null.

When deserializing, optional field value is set to null no matter if JSON object contained null value for the field key, ot the key was absent.

Note

There’s one common scenario when it’s convenient to distinguish between null and absent values - update records, which contain requested changes to some data source. Then absent value would mean lack of update information, and null value would mean reset/removal request. This scenario is not supported at the moment.

Collections

If optional type is used as generic collection type argument (e.g. ?T in list<?T> or ?TValue in dict<TKey,?TValue>) then null value should be present in JSON to be included into collection. null is both properly serialized and deserialized.

Optional dict keys are not supported.