Skip to main content

Custom Entity File Formats

Jason Liang avatar
Written by Jason Liang
Updated over a year ago

Similar to the Global Entity File Formats, there are four different JSON file formats supported in the brainCloud portal.

  • Raw JSON Object format - highly recommended for backups and data migration.

  • Raw JSON Line format - useful for integration with external tools that support JSON line format. With metadata included.

  • Simplified JSON Object format - very good for integration with external tools.

  • Simplified JSON Line format - useful for integration with external tools that support JSON line format. Limited to a single entity type per file.

Each of the file formats is described in more detail below.

Raw JSON Object Format:

Below is a raw JSON object file. 

{
    "dynamicChannel": [
        {
            "entityId": "d02137df-06de-413e-9ef7-34216de06454",
            "version": 1,
            "acl": {
                "other": 2
            },
            "ownerId": null,
            "expiresAt": null,
            "timeToLive": null,
            "createdAt": 1687874382272,
            "updatedAt": 1687874382272,
            "appId": "13229",
            "data": {
                "id": "13229:dy:dynamic_1",
                "type": "dy",
                "code": "dynamic_1",
                "name": "dynamic_1",
                "desc": "dynamic_1 channel"
            }
        },
        {
            "entityId": "1075946e-6cea-4390-921d-6b43a6c8f636",
            "version": 1,
            "acl": {
                "other": 2
            },
            "ownerId": null,
            "expiresAt": null,
            "timeToLive": null,
            "createdAt": 1687904590872,
            "updatedAt": 1687904590872,
            "appId": "13229",
            "data": {
                "id": "13229:dy:dynamic_1",
                "type": "dy",
                "code": "dynamic_1",
                "name": "dynamic_1",
                "desc": "dynamic_1 channel"
            }
        },
        {
            "entityId": "ccb3cd5f-08f9-4c7b-9915-87a2c330bde0",
            "version": 1,
            "acl": {
                "other": 2
            },
            "ownerId": null,
            "expiresAt": null,
            "timeToLive": null,
            "createdAt": 1710255034434,
            "updatedAt": 1710255034434,
            "appId": "13229",
            "data": {
                "id": "13229:dy:dynamic_1",
                "type": "dy",
                "code": "dynamic_1",
                "name": "dynamic_1",
                "desc": "dynamic_1 channel"
            }
        }
    ]
}

File format specifics:

  • EntityTypes are enclosed in a JSON arrays - and thus multiple entityTypes are supported.

  • brainCloud meta-data is preserved

    • entityId

    • version

    • acl

    • ownerId

    • expiresAt

    • timeToLive

    • createdAt

    • updatedAt

    • appId

Note that although the example below only shows a single entity type -- "dynamicChannel", the file structure does allow multiple types of entities to be present in a single file.

Raw JSON Lines Format:

Raw JSON Lines files are a bit simpler in structure than raw JSON object files - in that they don't require the enclosing object array structure.

{"entityId":"d02137df-06de-413e-9ef7-34216de06454","version":1,"acl":{"other":2},"ownerId":null,"expiresAt":null,"timeToLive":null,"createdAt":1687874382272,"updatedAt":1687874382272,"data":{"id":"13229:dy:dynamic_1","type":"dy","code":"dynamic_1","name":"dynamic_1","desc":"dynamic_1 channel"}}

{"entityId":"1075946e-6cea-4390-921d-6b43a6c8f636","version":1,"acl":{"other":2},"ownerId":null,"expiresAt":null,"timeToLive":null,"createdAt":1687904590872,"updatedAt":1687904590872,"data":{"id":"13229:dy:dynamic_1","type":"dy","code":"dynamic_1","name":"dynamic_1","desc":"dynamic_1 channel"}}

{"entityId":"ccb3cd5f-08f9-4c7b-9915-87a2c330bde0","version":1,"acl":{"other":2},"ownerId":null,"expiresAt":null,"timeToLive":null,"createdAt":1710255034434,"updatedAt":1710255034434,"data":{"id":"13229:dy:dynamic_1","type":"dy","code":"dynamic_1","name":"dynamic_1","desc":"dynamic_1 channel"}}

Each line of the file is considered a separate JSON object.

Because of this, JSON Lines files can only support a single _entityType_ per file.

Note that we are using a simpler example for better readability. Also, note that the file above contains just 3 lines (it looks like more due to word-wrapping - notice the line numbers).

Simplified JSON Object Format:

Simplified JSON is very readable and suitable for round-trip importing and exporting with tools like Google Sheets.

It minimizes the structure and overheads that brainCloud imposes - though that comes with limitations (record-level ACL, ownership, and entityIds are not preserved).

File format specifics:

  • EntityTypes are enclosed in JSON arrays - and thus multiple entityTypes are supported. ← Same as RAW

  • brainCloud meta-data is NOT preserved.

  • The lack of a "data" section makes the object easier to view and understand

{
    "dynamicChannel": [
        {
            "id": "13229:dy:dynamic_1",
            "type": "dy",
            "code": "dynamic_1",
            "name": "dynamic_1",
            "desc": "dynamic_1 channel"
        },
        {
            "id": "13229:dy:dynamic_1",
            "type": "dy",
            "code": "dynamic_1",
            "name": "dynamic_1",
            "desc": "dynamic_1 channel"
        },
        {
            "id": "13229:dy:dynamic_1",
            "type": "dy",
            "code": "dynamic_1",
            "name": "dynamic_1",
            "desc": "dynamic_1 channel"
        }
    ]
}

Note that although the example below only shows a single entity type -- "dynamicChannel", the file structure does allow multiple types of entities to be present in a single file.

Simplified JSON Lines Format:

JSON Lines files are a bit simpler in structure than JSON object files - in that they don't require the enclosing object array structure.

{"id":"13229:dy:dynamic_1","type":"dy","code":"dynamic_1","name":"dynamic_1","desc":"dynamic_1 channel"}

{"id":"13229:dy:dynamic_1","type":"dy","code":"dynamic_1","name":"dynamic_1","desc":"dynamic_1 channel"}

{"id":"13229:dy:dynamic_1","type":"dy","code":"dynamic_1","name":"dynamic_1","desc":"dynamic_1 channel"}

Each line of the file is considered a separate JSON object.

Because of this, JSON Lines files can only support a single _entityType_ per file.

Note that we are using a simpler example for better readability. Also, note that the file below contains just 3 lines (it looks like more due to word-wrapping - notice the line numbers).

Did this answer your question?