Open 3D Engine AzCore API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
AZ::JsonSerialization Class Referencefinal

#include <JsonSerialization.h>

Static Public Member Functions

static JsonSerializationResult::ResultCode ApplyPatch (rapidjson::Value &target, rapidjson::Document::AllocatorType &allocator, const rapidjson::Value &patch, JsonMergeApproach approach, const JsonApplyPatchSettings &settings=JsonApplyPatchSettings{})
 
static JsonSerializationResult::ResultCode ApplyPatch (rapidjson::Value &target, rapidjson::Document::AllocatorType &allocator, const rapidjson::Value &patch, JsonMergeApproach approach, JsonApplyPatchSettings &settings)
 
static JsonSerializationResult::ResultCode ApplyPatch (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const rapidjson::Value &source, const rapidjson::Value &patch, JsonMergeApproach approach, const JsonApplyPatchSettings &settings=JsonApplyPatchSettings{})
 
static JsonSerializationResult::ResultCode ApplyPatch (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const rapidjson::Value &source, const rapidjson::Value &patch, JsonMergeApproach approach, JsonApplyPatchSettings &settings)
 
static JsonSerializationResult::ResultCode CreatePatch (rapidjson::Value &patch, rapidjson::Document::AllocatorType &allocator, const rapidjson::Value &source, const rapidjson::Value &target, JsonMergeApproach approach, const JsonCreatePatchSettings &settings=JsonCreatePatchSettings{})
 
static JsonSerializationResult::ResultCode CreatePatch (rapidjson::Value &patch, rapidjson::Document::AllocatorType &allocator, const rapidjson::Value &source, const rapidjson::Value &target, JsonMergeApproach approach, JsonCreatePatchSettings &settings)
 
template<typename T >
static JsonSerializationResult::ResultCode Load (T &object, const rapidjson::Value &root, const JsonDeserializerSettings &settings=JsonDeserializerSettings{})
 
template<typename T >
static JsonSerializationResult::ResultCode Load (T &object, const rapidjson::Value &root, JsonDeserializerSettings &settings)
 
static JsonSerializationResult::ResultCode Load (void *object, const Uuid &objectType, const rapidjson::Value &root, const JsonDeserializerSettings &settings=JsonDeserializerSettings{})
 
static JsonSerializationResult::ResultCode Load (void *object, const Uuid &objectType, const rapidjson::Value &root, JsonDeserializerSettings &settings)
 
static JsonSerializationResult::ResultCode LoadTypeId (Uuid &typeId, const rapidjson::Value &input, const Uuid *baseClassTypeId=nullptr, AZStd::string_view jsonPath=AZStd::string_view{}, const JsonDeserializerSettings &settings=JsonDeserializerSettings{})
 
static JsonSerializationResult::ResultCode LoadTypeId (Uuid &typeId, const rapidjson::Value &input, const Uuid *baseClassTypeId, AZStd::string_view jsonPath, JsonDeserializerSettings &settings)
 
template<typename T >
static JsonSerializationResult::ResultCode Store (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const T &object, const JsonSerializerSettings &settings=JsonSerializerSettings{})
 
template<typename T >
static JsonSerializationResult::ResultCode Store (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const T &object, JsonSerializerSettings &settings)
 
template<typename T >
static JsonSerializationResult::ResultCode Store (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const T &object, const T &defaultObject, const JsonSerializerSettings &settings=JsonSerializerSettings{})
 
template<typename T >
static JsonSerializationResult::ResultCode Store (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const T &object, const T &defaultObject, JsonSerializerSettings &settings)
 
static JsonSerializationResult::ResultCode Store (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const void *object, const void *defaultObject, const Uuid &objectType, const JsonSerializerSettings &settings=JsonSerializerSettings{})
 
static JsonSerializationResult::ResultCode Store (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const void *object, const void *defaultObject, const Uuid &objectType, JsonSerializerSettings &settings)
 
static JsonSerializationResult::ResultCode StoreTypeId (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const Uuid &typeId, AZStd::string_view elementPath=AZStd::string_view{}, const JsonSerializerSettings &settings=JsonSerializerSettings{})
 
static JsonSerializationResult::ResultCode StoreTypeId (rapidjson::Value &output, rapidjson::Document::AllocatorType &allocator, const Uuid &typeId, AZStd::string_view elementPath, JsonSerializerSettings &settings)
 
static JsonSerializerCompareResult Compare (const rapidjson::Value &lhs, const rapidjson::Value &rhs)
 
static JsonSerializationResult::ResultCode ResolveImports (rapidjson::Value &jsonDoc, rapidjson::Document::AllocatorType &allocator, JsonImportSettings &settings)
 
static JsonSerializationResult::ResultCode RestoreImports (rapidjson::Value &jsonDoc, rapidjson::Document::AllocatorType &allocator, JsonImportSettings &settings)
 
static RegisteredReflectionContextResult IsTypeSerializable (const AZ::TypeId &typeId, JsonSerializerSettings settings={})
 

Static Public Attributes

static constexpr const char * TypeIdFieldIdentifier = "$type"
 
static constexpr const char * DefaultStringIdentifier = "{}"
 
static constexpr const char * KeyFieldIdentifier = "Key"
 
static constexpr const char * ValueFieldIdentifier = "Value"
 
static constexpr const char * ImportDirectiveIdentifier = "$import"
 

Detailed Description

Core class to handle serialization to and from json documents. The Json Serialization works by taking a default constructed object and then apply the information found in the JSON document on top of that object. This allows the Json Serialization to avoid storing default values and helps guarantee that the final object is in a valid state even if non-fatal issues are encountered. Note on containers: Containers such as vector or map are always considered to be empty even if there's entries in the provided default object. During deserialization entries will be appended to any existing values. A flag is provided to automatically clear containers during deserialization. Note on maps: If the key for map containers such as unordered_map can be interpret as a string the Json Serialization will use a JSON Object to store the data in instead of an array with key/value objects. Note on pointers: The Json Serialization assumes that are always constructed, so a default JSON value of "{}" is interpret as creating a new default instance even if the default value is a null pointer. A JSON Null needs to be explicitly stored in the JSON Document in order to default or explicitly set a pointer to null. Note on pointer memory: Objects created/destroyed by the Json Serialization for pointers require that the AZ_CLASS_ALLOCATOR is declared and the object is created using aznew or memory is allocated using azmalloc. Without these the application may crash if the Json Serialization tries to create or destroy an object pointed to by a pointer.

Member Function Documentation

◆ ApplyPatch() [1/4]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::ApplyPatch ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const rapidjson::Value &  source,
const rapidjson::Value &  patch,
JsonMergeApproach  approach,
const JsonApplyPatchSettings settings = JsonApplyPatchSettings{} 
)
static

Merges two json values together by applying "patch" to a copy of "output" and written to output using the selected merge algorithm. This version of ApplyPatch is non-destructive to "source". If the patch couldn't be fully applied "output" will be left set to an empty (default) object.

Parameters
sourceA copy of source with the patch applied to it or an empty object if the patch couldn't be applied.
allocatorThe allocator associated with the document that holds the source.
targetThe value where the patch will be applied to.
patchThe value holding the patch information.
approachThe merge algorithm that will be used to apply the patch on top of the target.
settingsOptional additional settings to control the way the patch is applied.

◆ ApplyPatch() [2/4]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::ApplyPatch ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const rapidjson::Value &  source,
const rapidjson::Value &  patch,
JsonMergeApproach  approach,
JsonApplyPatchSettings settings 
)
static

Merges two json values together by applying "patch" to a copy of "output" and written to output using the selected merge algorithm. This version of ApplyPatch is non-destructive to "source". If the patch couldn't be fully applied "output" will be left set to an empty (default) object.

Parameters
sourceA copy of source with the patch applied to it or an empty object if the patch couldn't be applied.
allocatorThe allocator associated with the document that holds the source.
targetThe value where the patch will be applied to.
patchThe value holding the patch information.
approachThe merge algorithm that will be used to apply the patch on top of the target.
settingsAdditional settings to control the way the patch is applied.

◆ ApplyPatch() [3/4]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::ApplyPatch ( rapidjson::Value &  target,
rapidjson::Document::AllocatorType &  allocator,
const rapidjson::Value &  patch,
JsonMergeApproach  approach,
const JsonApplyPatchSettings settings = JsonApplyPatchSettings{} 
)
static

Merges two json values together by applying "patch" to "target" using the selected merge algorithm. This version of ApplyPatch is destructive to "target". If the patch can't be correctly applied it will leave target in a partially patched state. Use the other version of ApplyPatch if target should be copied.

Parameters
targetThe value where the patch will be applied to.
allocatorThe allocator associated with the document that holds the target.
patchThe value holding the patch information.
approachThe merge algorithm that will be used to apply the patch on top of the target.
settingsOptional additional settings to control the way the patch is applied.

◆ ApplyPatch() [4/4]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::ApplyPatch ( rapidjson::Value &  target,
rapidjson::Document::AllocatorType &  allocator,
const rapidjson::Value &  patch,
JsonMergeApproach  approach,
JsonApplyPatchSettings settings 
)
static

Merges two json values together by applying "patch" to "target" using the selected merge algorithm. This version of ApplyPatch is destructive to "target". If the patch can't be correctly applied it will leave target in a partially patched state. Use the other version of ApplyPatch if target should be copied.

Parameters
targetThe value where the patch will be applied to.
allocatorThe allocator associated with the document that holds the target.
patchThe value holding the patch information.
approachThe merge algorithm that will be used to apply the patch on top of the target.
settingsAdditional settings to control the way the patch is applied.

◆ Compare()

static JsonSerializerCompareResult AZ::JsonSerialization::Compare ( const rapidjson::Value &  lhs,
const rapidjson::Value &  rhs 
)
static

Compares two json values of any type and determines if the left is less, equal or greater than the right.

Parameters
lhsThe left hand side value for the compare.
rhsThe right hand side value for the compare.
Returns
An enum containing less, equal or greater. In case of an error, the value for the enum will "error".

◆ CreatePatch() [1/2]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::CreatePatch ( rapidjson::Value &  patch,
rapidjson::Document::AllocatorType &  allocator,
const rapidjson::Value &  source,
const rapidjson::Value &  target,
JsonMergeApproach  approach,
const JsonCreatePatchSettings settings = JsonCreatePatchSettings{} 
)
static

Creates a patch using the selected merge algorithm such that when applied to source it results in target.

Parameters
patchThe value containing the differences between source and target.
allocatorThe allocator associated with the document that will hold the patch.
sourceThe value used as a starting point.
targetThe value that will result if the patch is applied to the source.
approachThe algorithm that will be used when the patch is applied to the source.
settingsOptional additional settings to control the way the patch is created.

◆ CreatePatch() [2/2]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::CreatePatch ( rapidjson::Value &  patch,
rapidjson::Document::AllocatorType &  allocator,
const rapidjson::Value &  source,
const rapidjson::Value &  target,
JsonMergeApproach  approach,
JsonCreatePatchSettings settings 
)
static

Creates a patch using the selected merge algorithm such that when applied to source it results in target.

Parameters
patchThe value containing the differences between source and target.
allocatorThe allocator associated with the document that will hold the patch.
sourceThe value used as a starting point.
targetThe value that will result if the patch is applied to the source.
approachThe algorithm that will be used when the patch is applied to the source.
settingsAdditional settings to control the way the patch is created.

◆ IsTypeSerializable()

static RegisteredReflectionContextResult AZ::JsonSerialization::IsTypeSerializable ( const AZ::TypeId typeId,
JsonSerializerSettings  settings = {} 
)
static

Returns an result structure indicating if the type is reflected using either the SerializeContext or JsonRegistrationContext If the type is reflected in both contexts, then the JsonRegistrationContext is given preference in that case

Parameters
typeIdAZ TypeInfo to query in the SerializeContext or JSON RegistrationContext
Returns
result structure which is convertible to bool. If the type is either reflected in SerializeContext or JsonRegistrationContext then it converts to true, otherwise the result structure converts to false

◆ Load() [1/4]

template<typename T >
JsonSerializationResult::ResultCode AZ::JsonSerialization::Load ( T &  object,
const rapidjson::Value &  root,
const JsonDeserializerSettings settings = JsonDeserializerSettings{} 
)
static

Loads the data from the provided json value into the supplied object. The object is expected to be created before calling load.

Parameters
objectObject where the data will be loaded into.
rootThe Value or Document where the deserializer will start reading data from.
settingsOptional additional settings to control the way document is deserialized.

◆ Load() [2/4]

template<typename T >
JsonSerializationResult::ResultCode AZ::JsonSerialization::Load ( T &  object,
const rapidjson::Value &  root,
JsonDeserializerSettings settings 
)
static

Loads the data from the provided json value into the supplied object. The object is expected to be created before calling load.

Parameters
objectObject where the data will be loaded into.
rootThe Value or Document where the deserializer will start reading data from.
settingsAdditional settings to control the way document is deserialized.

◆ Load() [3/4]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::Load ( void *  object,
const Uuid objectType,
const rapidjson::Value &  root,
const JsonDeserializerSettings settings = JsonDeserializerSettings{} 
)
static

Loads the data from the provided json value into the supplied object. The object is expected to be created before calling load.

Parameters
objectPointer to the object where the data will be loaded into.
objectTypeType id of the object passed in.
rootThe Value or Document from where the deserializer will start reading data.
settingsOptional additional settings to control the way document is deserialized.

◆ Load() [4/4]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::Load ( void *  object,
const Uuid objectType,
const rapidjson::Value &  root,
JsonDeserializerSettings settings 
)
static

Loads the data from the provided json value into the supplied object. The object is expected to be created before calling load.

Parameters
objectPointer to the object where the data will be loaded into.
objectTypeType id of the object passed in.
rootThe Value or Document from where the deserializer will start reading data.
settingsAdditional settings to control the way document is deserialized.

◆ LoadTypeId() [1/2]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::LoadTypeId ( Uuid typeId,
const rapidjson::Value &  input,
const Uuid baseClassTypeId,
AZStd::string_view  jsonPath,
JsonDeserializerSettings settings 
)
static

Loads the type id from the provided input. Note: it's not recommended to use this function (frequently) as it requires users of the json file to have knowledge of the internal type structure and is therefore harder to use.

Parameters
typeIdThe uuid where the loaded data will be written to. If loading fails this will be a null uuid.
inputThe json node to load from. The node is expected to contain a string.
baseClassTypeId.An optional type id for the base class, if known. If a type name is stored in the string which references multiple types then the baseClassTypeId will be used to disambiguate between the different types by looking if exactly one of the types inherits from the base class that baseClassTypeId points to.
jsonPathAn optional path to the json node. This will be used for reporting.
settingsSettings object to change where this function collects information from. This can be same settings as used for the other Load functions.

◆ LoadTypeId() [2/2]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::LoadTypeId ( Uuid typeId,
const rapidjson::Value &  input,
const Uuid baseClassTypeId = nullptr,
AZStd::string_view  jsonPath = AZStd::string_view{},
const JsonDeserializerSettings settings = JsonDeserializerSettings{} 
)
static

Loads the type id from the provided input. Note: it's not recommended to use this function (frequently) as it requires users of the json file to have knowledge of the internal type structure and is therefore harder to use.

Parameters
typeIdThe uuid where the loaded data will be written to. If loading fails this will be a null uuid.
inputThe json node to load from. The node is expected to contain a string.
baseClassTypeId.An optional type id for the base class, if known. If a type name is stored in the string which references multiple types then the baseClassTypeId will be used to disambiguate between the different types by looking if exactly one of the types inherits from the base class that baseClassTypeId points to.
jsonPathAn optional path to the json node. This will be used for reporting.
settingsOptional settings object to change where this function collects information from. This can be same settings as used for the other Load functions.

◆ ResolveImports()

static JsonSerializationResult::ResultCode AZ::JsonSerialization::ResolveImports ( rapidjson::Value &  jsonDoc,
rapidjson::Document::AllocatorType &  allocator,
JsonImportSettings settings 
)
static

Resolves all import directives, including nested imports, in the given document. An importer object needs to be passed in through the settings.

Parameters
jsonDocThe json document in which to resolve imports.
allocatorThe allocator associated with the json document.
settingsAdditional settings that control the way the imports are resolved.

◆ RestoreImports()

static JsonSerializationResult::ResultCode AZ::JsonSerialization::RestoreImports ( rapidjson::Value &  jsonDoc,
rapidjson::Document::AllocatorType &  allocator,
JsonImportSettings settings 
)
static

Restores all import directives that were present in the json document. The same importer object that was passed into ResolveImports through the settings needs to be passed here through settings as well.

Parameters
jsonDocThe json document in which to restore imports.
allocatorThe allocator associated with the json document.
settingsAdditional settings that control the way the imports are restored.

◆ Store() [1/6]

template<typename T >
JsonSerializationResult::ResultCode AZ::JsonSerialization::Store ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const T &  object,
const JsonSerializerSettings settings = JsonSerializerSettings{} 
)
static

Stores the data in the provided object as json values starting at the provided value.

Parameters
outputThe Value or Document where the converted data will start writing to.
allocatorThe memory allocator used by RapidJSON to create the json document.
objectThe object that will be read from for values to convert.
settingsOptional additional settings to control the way document is serialized.

◆ Store() [2/6]

template<typename T >
JsonSerializationResult::ResultCode AZ::JsonSerialization::Store ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const T &  object,
const T &  defaultObject,
const JsonSerializerSettings settings = JsonSerializerSettings{} 
)
static

Stores the data in the provided object as json values starting at the provided value.

Parameters
outputThe Value or Document where the converted data will start writing to.
allocatorThe memory allocator used by RapidJSON to create the json document.
objectThe object that will be read from for values to convert.
defaultObjectDefault object used to compare the object to in order to determine if values are defaulted or not. If this is argument is provided m_keepDefaults in the settings will automatically be set to true.
settingsOptional additional settings to control the way document is serialized.

◆ Store() [3/6]

template<typename T >
JsonSerializationResult::ResultCode AZ::JsonSerialization::Store ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const T &  object,
const T &  defaultObject,
JsonSerializerSettings settings 
)
static

Stores the data in the provided object as json values starting at the provided value.

Parameters
outputThe Value or Document where the converted data will start writing to.
allocatorThe memory allocator used by RapidJSON to create the json document.
objectThe object that will be read from for values to convert.
defaultObjectDefault object used to compare the object to in order to determine if values are defaulted or not. If this is argument is provided m_keepDefaults in the settings will automatically be set to true.
settingsAdditional settings to control the way document is serialized.

◆ Store() [4/6]

template<typename T >
JsonSerializationResult::ResultCode AZ::JsonSerialization::Store ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const T &  object,
JsonSerializerSettings settings 
)
static

Stores the data in the provided object as json values starting at the provided value.

Parameters
outputThe Value or Document where the converted data will start writing to.
allocatorThe memory allocator used by RapidJSON to create the json document.
objectThe object that will be read from for values to convert.
settingsAdditional settings to control the way document is serialized.

◆ Store() [5/6]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::Store ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const void *  object,
const void *  defaultObject,
const Uuid objectType,
const JsonSerializerSettings settings = JsonSerializerSettings{} 
)
static

Stores the data in the provided object as json values starting at the provided value.

Parameters
outputThe Value or Document where the converted data will start writing to.
allocatorThe memory allocator used by RapidJSON to create the json document.
objectPointer to the object that will be read from for values to convert.
defaultObjectPointer to a default object used to compare the object to in order to determine if values are defaulted or not. This argument can be null, in which case a temporary default may be created if required by the settings. If this is argument is provided m_keepDefaults in the settings will automatically be set to true.
objectTypeThe type id of the object and default object.
settingsOptional additional settings to control the way document is serialized.

◆ Store() [6/6]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::Store ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const void *  object,
const void *  defaultObject,
const Uuid objectType,
JsonSerializerSettings settings 
)
static

Stores the data in the provided object as json values starting at the provided value.

Parameters
outputThe Value or Document where the converted data will start writing to.
allocatorThe memory allocator used by RapidJSON to create the json document.
objectPointer to the object that will be read from for values to convert.
defaultObjectPointer to a default object used to compare the object to in order to determine if values are defaulted or not. This argument can be null, in which case a temporary default may be created if required by the settings. If this is argument is provided m_keepDefaults in the settings will automatically be set to true.
objectTypeThe type id of the object and default object.
settingsAdditional settings to control the way document is serialized.

◆ StoreTypeId() [1/2]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::StoreTypeId ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const Uuid typeId,
AZStd::string_view  elementPath,
JsonSerializerSettings settings 
)
static

Stores a name for the type id in the provided output. The name can be safely used to reference a type such as a class during loading. Note: it's not recommended to use this function (frequently) as it requires users of the json file to have knowledge of the internal type structure and is therefore harder to use.

Parameters
outputThe json value the result will be written to. If successful this will contain a string object otherwise a default object.
allocatorThe allocator associated with the document that will or already holds the output.
typeIdThe type id to store.
elementPathThe path to the element. This will be used for reporting.
settingsSettings to change where this function collects information from. This can be the same settings as used for the other Store functions.

◆ StoreTypeId() [2/2]

static JsonSerializationResult::ResultCode AZ::JsonSerialization::StoreTypeId ( rapidjson::Value &  output,
rapidjson::Document::AllocatorType &  allocator,
const Uuid typeId,
AZStd::string_view  elementPath = AZStd::string_view{},
const JsonSerializerSettings settings = JsonSerializerSettings{} 
)
static

Stores a name for the type id in the provided output. The name can be safely used to reference a type such as a class during loading. Note: it's not recommended to use this function (frequently) as it requires users of the json file to have knowledge of the internal type structure and is therefore harder to use.

Parameters
outputThe json value the result will be written to. If successful this will contain a string object otherwise a default object.
allocatorThe allocator associated with the document that will or already holds the output.
typeIdThe type id to store.
elementPathAn optional path to the element. This will be used for reporting.
settingsOptional settings to change where this function collects information from. This can be the same settings as used for the other Store functions.

The documentation for this class was generated from the following file: