Schema

This page documents the JSON schema that DataConfig JSON Asset supports. Note that DcJsonAsset shares most common deserialize handlers from DataConfigCore, which is documented here.

Root $type

The first thing when importing a JSON asset is to determine which class to deserialize into. It's specified by the $type field in the JSON source:

// DcJsonAsset/Tests/DcJsonFixture_Simple.json
{
    "$type" : "DcJsonAssetTestPrimaryDataAsset1",
    "AlphaName" : "Foo",
    "AlphaBool" : true, 
    "AlphaStr" : "Bar"
}

We call all object keys with $ prefix meta fields. $type is one that's used a lot. Under the hood this $type field is handled separately from other fields:

• $type must be the first field in the object. In fact all meta fields are order significant and needs to start as the beginning keys of a object.
• $type values must refers to a UDcImportedDataAsset or UDcPrimaryImportedDataAsset children:
  • If it's a native C++ class, refer to it by the class name without the U prefix. For example: DcJsonAssetTestPrimaryDataAsset1
  • If it's a Blueprint Class, refer to it by the Blueprint asset path. For example: /DcJsonAsset/DcFixture/DcTestBPDataAsset

Scalar Types

Most UE primitive types has pretty straight forward mappings to JSON data types:

We additionally support a few scalar like data types:

Enums

Enum can be deserialized from a string. Enum flags needs to be deserialized from a list of string:

// DcJsonAssetTests/Private/DcTestImports2.h
UCLASS()
class UDcJsonAssetTestDataAsset1_Enum : public UDcImportedDataAsset {
	// ...
	UPROPERTY(EditAnywhere) EDcJsonAssetTestEnum_Simple EnumField;
	UPROPERTY(EditAnywhere) EDcJsonAssetTestEnum_Flag EnumFlagField;
};

// DcJsonAsset/Tests/DcJsonFixture_Enum.json
{
    "$type" : "DcJsonAssetTestDataAsset1_Enum",
    "EnumField" : "Baz",
    "EnumFlagField" : ["Alpha", "Gamma"], 
}

GameplayTags

Gameplay Tag structs FGameplayTag and FGameplayTagContainer are both supported:

// DcJsonAssetTests/Private/DcTestImports2.h 
UCLASS()
class UDcJsonAssetTestDataAsset2_GameplayTag : public UDcImportedDataAsset {
	// ...
	UPROPERTY(EditAnywhere) FGameplayTag GameplayTagField1;
	UPROPERTY(EditAnywhere) FGameplayTag GameplayTagField2;
	UPROPERTY(EditAnywhere) FGameplayTagContainer GameplayTagContainer;
};

// DcJsonAsset/Tests/DcJsonFixture_GameplayTag.json
{
    "$type" : "DcJsonAssetTestDataAsset2_GameplayTag",
    "GameplayTagField1" : "DcJsonAsset.Foo.Bar.Baz",
    "GameplayTagField2" : null,
    "GameplayTagContainer" : [
        "DcJsonAsset.Foo.Bar",
        "DcJsonAsset.Tar.Taz"
    ]
}

FPrimaryAssetId

FPrimaryAssetId is used to soft reference primary data assets. It's serialized into a Type:Name string, and can be loaded from the same string form, or a full object path:

// DcJsonAssetTests/Private/DcTestImports3.h 
class UDcJsonAssetTestAssetTypes1 : public UDcPrimaryImportedDataAsset
{
    // ...
    UPROPERTY(EditAnywhere, Category="DcJsonAsset|Tests") FPrimaryAssetId AssetId1;
    UPROPERTY(EditAnywhere, Category="DcJsonAsset|Tests") FPrimaryAssetId AssetId2;
    UPROPERTY(EditAnywhere, Category="DcJsonAsset|Tests") FPrimaryAssetId AssetId3;
    UPROPERTY(EditAnywhere, Category="DcJsonAsset|Tests") FPrimaryAssetId AssetId4;
};

// DcJsonAsset/Tests/DcJsonFixture_PrimaryAssetId.json
{
    "$type" : "DcJsonAssetTestAssetTypes1",
    "AssetId1" : null,
    "AssetId2" : "/DcJsonAsset/DcFixture/DcTestBPDataAssetInstance",
    "AssetId3" :
    {
        "$type" : "DcTestBPDataAsset",
        "$name" : "DcTestBPDataAssetInstance"
    }
}

Containers and Aggregates

UE containers mapping to JSON is also pretty unsurprising:

Object References

UE provides a few options when referencing UObject instances:

All of these are supported for completeness sake. The recommendation is:

• Use direct or soft object reference for common object references. It's the usual way to referencing objects.
• Use soft object reference when pointing to UDcImportedDataAsset/UDcPrimaryImportedDataAsset derived classes. It's specially handled that it won't load the object to deserialize. This means we can batch import a set of JSON assets that references each other, without the need to resolve the mutual dependencies among them. The downside is that we don't check that the object actually exist at import time.

We allow a few options when referencing an object. Below is a example of object references:

// DcJsonAssetTests/Private/DcTestImports2.h
UCLASS()
class UDcJsonAssetTestDataAsset3_References : public UDcImportedDataAsset {
	// ...	
	UPROPERTY(EditAnywhere) UObject* DirectRef1;
	UPROPERTY(EditAnywhere) UObject* DirectRef2;
	UPROPERTY(EditAnywhere) UObject* DirectRef3;
	UPROPERTY(EditAnywhere) TSoftObjectPtr<UDcPrimaryImportedDataAsset> DcSoftImported1;
	UPROPERTY(EditAnywhere) TSoftObjectPtr<UDcPrimaryImportedDataAsset> DcSoftImported2;
};

// DcJsonAsset/Tests/DcJsonFixture_Refs.json
{
    "$type" : "DcJsonAssetTestDataAsset3_References",
    "DirectRef1" : "Blueprint'/DcJsonAsset/DcFixture/DcTestBPDataAsset.DcTestBPDataAsset'",
    "DirectRef2" : "/DcJsonAsset/DcFixture/DcTestBPDataAsset",
    "DirectRef3" : {
        "$type" : "Blueprint",
        "$path" : "/DcJsonAsset/DcFixture/DcTestBPDataAsset"
    },
    "DcSoftImported1" : "/DcJsonAsset/DcFixture/DcTestBPDataAssetInstance",
    "DcSoftImported2" : null
}

Note that:

1. DirectRef1/2/3 are deserialized into identical references to the same object.
2. DcSoftImported1/2 are specially handled and /Path/To/Content are the only format that's supported.

Blueprint classes can use FSoftObjectPath/FSoftClassPath to replace the templated C++ equivelent. It looks like this in the Blueprint editor:

Inline Sub Objects

UE already supports "Inline Sub Objects", that is UCLASS marked with DefaultToInstanced specifier. Editor would try to create new sub objects inline for these classes' references, rather than points to a existing one. It's also a way of doing data polymorphism in UE.

Given a simple class hierarchy like this:

// DcJsonAssetTests/Private/DcTestImports2.h
UCLASS(BlueprintType, EditInlineNew, DefaultToInstanced)
class UDcJsonAsset_BaseShape : public UObject 
	// ...
    UPROPERTY(EditAnywhere) FName ShapeName;
};

UCLASS()
class UDcJsonAsset_ShapeBox : public UDcJsonAsset_BaseShape 
	// ...
    UPROPERTY(EditAnywhere) float Height;
	UPROPERTY(EditAnywhere) float Width;
};

UCLASS()
class UDcJsonAsset_ShapeSquare : public UDcJsonAsset_BaseShape 
    // ...
	UPROPERTY(EditAnywhere) float Radius;
};

An asset can be loaded from a JSON like this:

// DcJsonAssetTests/Private/DcTestImports2.h
UCLASS()
class UDcJsonAssetTestDataAsset4_SubObjects : public UDcImportedDataAsset {
	UPROPERTY(EditAnywhere) UDcJsonAsset_BaseShape* ShapeField1;
	UPROPERTY(EditAnywhere) UDcJsonAsset_BaseShape* ShapeField2;
	UPROPERTY(EditAnywhere) UDcJsonAsset_BaseShape* ShapeField3;
};

// DcJsonAsset/Tests/DcJsonFixture_SubObjects.json
{
    "$type" : "DcJsonAssetTestDataAsset4_SubObjects",
    "ShapeField1" : {
        "$type" : "DcJsonAsset_ShapeBox",
        "ShapeName" : "MyBox",
        "Height" : 43,
        "Width" : 25
    },
    "ShapeField2" : {
        "$type" : "DcJsonAsset_ShapeSquare",
        "Radius" : 16
    },
    "ShapeField3" : null
}

Instanced Struct

UE introduced FInstancedStruct with StructUtils plugin since 5.0 which implements lightweight polymorphic serialization. Given a struct hierarchy like this:

// DcJsonAssetTests/Private/DcTestImports3.h
USTRUCT(BlueprintType)
struct FDcJsonAssetTestStructShapeBase
{
    // ...
    UPROPERTY(EditAnywhere) FName ShapeName;
};

USTRUCT(BlueprintType)
struct FDcJsonAssetTestStructShapeRectangle : public FDcJsonAssetTestStructShapeBase
{
    // ...
    UPROPERTY(EditAnywhere) float Height;
    UPROPERTY(EditAnywhere) float Width;
};

USTRUCT(BlueprintType)
struct FDcJsonAssetTestStructShapeCircle : public FDcJsonAssetTestStructShapeBase
{
    // ...
    UPROPERTY(EditAnywhere) float Radius;
};

An asset can be loaded from a JSON like this:

// DcJsonAssetTests/Private/DcTestImports3.h
UCLASS()
class UDcJsonAssetTestAssetInstancedStruct : public UDcPrimaryImportedDataAsset
{
    GENERATED_BODY()
public:
    UPROPERTY(EditAnywhere) FInstancedStruct Instanced1;
    UPROPERTY(EditAnywhere) FInstancedStruct Instanced2;
    UPROPERTY(EditAnywhere) FInstancedStruct Instanced3;
};

// DcJsonAsset/Tests/DcJsonFixture_InstancedStruct.json
{
    "$type" : "DcJsonAssetTestAssetInstancedStruct",
    "Instanced1" : null,
    "Instanced2" :
    {
        "$type" : "DcJsonAssetTestStructShapeRectangle",
        "ShapeName" : "MyBox",
        "Height" : 3,
        "Width" : 4
    },
    "Instanced3" :
    {
        "$type" : "DcJsonAssetTestStructShapeCircle",
        "ShapeName" : "MyCircle",
        "Radius" : 5
    }
}

Other Root Meta Fields

In the root JSON object we now check for some other $meta fields.

$reimport-keep-instance

By default imported UDcImportedDataAsset object is destroyed and recreated on every import. Now $reimport-keep-instance changes the behavior and it would reuse the existing object. This is mostly for more advanced setups.

The main reason we create a new object on every import is that one can hardly reset the values of the dirty object. Consider the example below:

// DcJsonAsset/Tests/DcJsonFixture_Simple.json
{
    "$type" : "DcJsonAssetTestPrimaryDataAsset1",
    "AlphaName" : "Foo",
    "AlphaBool" : true, 
    "AlphaStr" : "Bar"
}

// reimport with the new content below
// DcJsonAsset/Tests/DcJsonFixture_Simple_ReimportKeepInstance.json
{
    "$type" : "DcJsonAssetTestPrimaryDataAsset1",
    "$reimport-keep-instance" : true,
    "AlphaStr" : "Changed"
}

After reimport the resulting object would be like this:

{
    "AlphaName" : "Foo",    // dirty value from last time
    "AlphaBool" : true,     // dirty value from last time
    "AlphaStr" : "Changed"  // new value in reimport
}