Version: 0.42

JSON-Cadence Data Interchange Format

Version 0.3.1

JSON-Cadence is a data interchange format used to represent Cadence values as language-independent JSON objects.

This format includes less type information than a complete ABI, and instead promotes the following tenets:

Human-readability - JSON-Cadence is easy to read and comprehend, which speeds up development and debugging.
Compatibility - JSON is a common format with built-in support in most high-level programming languages, making it easy to parse on a variety of platforms.
Portability - JSON-Cadence is self-describing and thus can be transported and decoded without accompanying type definitions (i.e. an ABI).

Values

Void


_10{
_10  "type": "Void"
_10}

Example


_10{
_10  "type": "Void"
_10}

Optional


_10{
_10  "type": "Optional",
_10  "value": null | <value>
_10}

Example


_16// Non-nil
_16
_16{
_16  "type": "Optional",
_16  "value": {
_16    "type": "UInt8",
_16    "value": "123"
_16  }
_16}
_16
_16// Nil
_16
_16{
_16  "type": "Optional",
_16  "value": null
_16}

Bool


_10{
_10  "type": "Bool",
_10  "value": true | false
_10}

Example


_10{
_10  "type": "Bool",
_10  "value": true
_10}

String


_10{
_10  "type": "String",
_10  "value": "..."
_10}

Example


_10{
_10  "type": "String",
_10  "value": "Hello, world!"
_10}

Address


_10{
_10  "type": "Address",
_10  "value": "0x0" // as hex-encoded string with 0x prefix
_10}

Example


_10{
_10  "type": "Address",
_10  "value": "0x1234"
_10}

Integers

[U]Int, [U]Int8, [U]Int16, [U]Int32,[U]Int64,[U]Int128, [U]Int256, Word8, Word16, Word32, or Word64

Although JSON supports integer literals up to 64 bits, all integer types are encoded as strings for consistency.

While the static type is not strictly required for decoding, it is provided to inform client of potential range.


_10{
_10  "type": "<type>",
_10  "value": "<decimal string representation of integer>"
_10}

Example


_10{
_10  "type": "UInt8",
_10  "value": "123"
_10}

Fixed Point Numbers

[U]Fix64

Although fixed point numbers are implemented as integers, JSON-Cadence uses a decimal string representation for readability.


_10{
_10    "type": "[U]Fix64",
_10    "value": "<integer>.<fractional>"
_10}

Example


_10{
_10    "type": "Fix64",
_10    "value": "12.3"
_10}

Array


_10{
_10  "type": "Array",
_10  "value": [
_10    <value at index 0>,
_10    <value at index 1>
_10    // ...
_10  ]
_10}

Example


_17{
_17  "type": "Array",
_17  "value": [
_17    {
_17      "type": "Int16",
_17      "value": "123"
_17    },
_17    {
_17      "type": "String",
_17      "value": "test"
_17    },
_17    {
_17      "type": "Bool",
_17      "value": true
_17    }
_17  ]
_17}

Dictionary

Dictionaries are encoded as a list of key-value pairs to preserve the deterministic ordering implemented by Cadence.


_10{
_10  "type": "Dictionary",
_10  "value": [
_10    {
_10      "key": "<key>",
_10      "value": <value>
_10    },
_10    ...
_10  ]
_10}

Example


_16{
_16  "type": "Dictionary",
_16  "value": [
_16    {
_16      "key": {
_16        "type": "UInt8",
_16        "value": "123"
_16      },
_16      "value": {
_16        "type": "String",
_16        "value": "test"
_16      }
_16    }
_16  ],
_16  // ...
_16}

Composites (Struct, Resource, Event, Contract, Enum)

Composite fields are encoded as a list of name-value pairs in the order in which they appear in the composite type declaration.


_13{
_13  "type": "Struct" | "Resource" | "Event" | "Contract" | "Enum",
_13  "value": {
_13    "id": "<fully qualified type identifier>",
_13    "fields": [
_13      {
_13        "name": "<field name>",
_13        "value": <field value>
_13      },
_13      // ...
_13    ]
_13  }
_13}

Example


_12{
_12  "type": "Resource",
_12  "value": {
_12    "id": "0x3.GreatContract.GreatNFT",
_12    "fields": [
_12      {
_12        "name": "power",
_12        "value": {"type": "Int", "value": "1"}
_12      }
_12    ]
_12  }
_12}

Path


_10{
_10  "type": "Path",
_10  "value": {
_10    "domain": "storage" | "private" | "public",
_10    "identifier": "..."
_10  }
_10}

Example


_10{
_10  "type": "Path",
_10  "value": {
_10    "domain": "storage",
_10    "identifier": "flowTokenVault"
_10  }
_10}

Type Value


_10{
_10  "type": "Type",
_10  "value": {
_10    "staticType": <type>
_10  }
_10}

Example


_10{
_10  "type": "Type",
_10  "value": {
_10    "staticType": {
_10      "kind": "Int",
_10    }
_10  }
_10}

Capability


_10{
_10  "type": "Capability",
_10  "value": {
_10    "path": <path>,
_10    "address": "0x0",  // as hex-encoded string with 0x prefix
_10    "borrowType": <type>,
_10  }
_10}

Example


_16{
_16  "type": "Capability",
_16  "value": {
_16    "path": {
_16      "type": "Path",
_16      "value": {
_16        "domain": "public",
_16        "identifier": "someInteger"
_16      }
_16    },
_16    "address": "0x1",
_16    "borrowType": {
_16      "kind": "Int"
_16    }
_16  }
_16}

Functions


_10{
_10  "type": "Function",
_10  "value": {
_10    "functionType": <type>
_10  }
_10}

Function values can only be exported, they cannot be imported.

Example


_13{
_13  "type": "Function",
_13  "value": {
_13    "functionType": {
_13      "kind": "Function",
_13      "typeID": "(():Void)",
_13      "parameters": [],
_13      "return": {
_13        "kind": "Void"
_13      }
_13    }
_13  }
_13}

Types

Simple Types

These are basic types like Int, String, or StoragePath.


_14{
_14  "kind": "Any" | "AnyStruct" | "AnyResource" | "AnyStructAttachment" | "AnyResourceAttachment" | "Type" |
_14    "Void" | "Never" | "Bool" | "String" | "Character" |
_14    "Bytes" | "Address" | "Number" | "SignedNumber" |
_14    "Integer" | "SignedInteger" | "FixedPoint" |
_14    "SignedFixedPoint" | "Int" | "Int8" | "Int16" |
_14    "Int32" | "Int64" | "Int128" | "Int256" | "UInt" |
_14    "UInt8" | "UInt16" | "UInt32" | "UInt64" | "UInt128" |
_14    "UInt256" | "Word8" | "Word16" | "Word32" | "Word64" |
_14    "Fix64" | "UFix64" | "Path" | "CapabilityPath" | "StoragePath" |
_14    "PublicPath" | "PrivatePath" | "AuthAccount" | "PublicAccount" |
_14    "AuthAccount.Keys" | "PublicAccount.Keys" | "AuthAccount.Contracts" |
_14    "PublicAccount.Contracts" | "DeployedContract" | "AccountKey" | "Block"
_14}

Example


_10{
_10  "kind": "UInt8"
_10}

Optional Types


_10{
_10  "kind": "Optional",
_10  "type": <type>
_10}

Example


_10{
_10  "kind": "Optional",
_10  "type": {
_10    "kind": "String"
_10  }
_10}

Variable Sized Array Types


_10{
_10  "kind": "VariableSizedArray",
_10  "type": <type>
_10}

Example


_10{
_10  "kind": "VariableSizedArray",
_10  "type": {
_10    "kind": "String"
_10  }
_10}

Constant Sized Array Types


_10{
_10  "kind": "ConstantSizedArray",
_10  "type": <type>,
_10  "size": <length of array>,
_10}

Example


_10{
_10  "kind": "ConstantSizedArray",
_10  "type": {
_10    "kind": "String"
_10  },
_10  "size":3
_10}

Dictionary Types


_10{
_10  "kind": "Dictionary",
_10  "key": <type>,
_10  "value": <type>
_10}

Example


_10{
_10  "kind": "Dictionary",
_10  "key": {
_10    "kind": "String"
_10  },
_10  "value": {
_10    "kind": "UInt16"
_10  },
_10}

Composite Types


_15{
_15  "kind": "Struct" | "Resource" | "Event" | "Contract" | "StructInterface" | "ResourceInterface" | "ContractInterface",
_15  "type": "", // this field exists only to keep parity with the enum structure below; the value must be the empty string
_15  "typeID": "<fully qualified type ID>",
_15  "initializers": [
_15    <initializer at index 0>,
_15    <initializer at index 1>
_15    // ...
_15  ],
_15  "fields": [
_15    <field at index 0>,
_15    <field at index 1>
_15    // ...
_15  ],
_15}

Example


_24{
_24  "kind": "Resource",
_24  "type": "",
_24  "typeID": "0x3.GreatContract.GreatNFT",
_24  "initializers":[
_24    [
_24      {
_24        "label": "foo",
_24        "id": "bar",
_24        "type": {
_24          "kind": "String"
_24        }
_24      }
_24    ]
_24  ],
_24  "fields": [
_24    {
_24      "id": "foo",
_24      "type": {
_24        "kind": "String"
_24      }
_24    }
_24  ]
_24}

Field Types


_10{
_10  "id": "<name of field>",
_10  "type": <type>
_10}

Example


_10{
_10  "id": "foo",
_10  "type": {
_10    "kind": "String"
_10  }
_10}

Parameter Types


_10{
_10  "label": "<label>",
_10  "id": "<identifier>",
_10  "type": <type>
_10}

Example


_10{
_10  "label": "foo",
_10  "id": "bar",
_10  "type": {
_10    "kind": "String"
_10  }
_10}

Initializer Types

Initializer types are encoded a list of parameters to the initializer.


_10[
_10  <parameter at index 0>,
_10  <parameter at index 1>,
_10  // ...
_10]

Example


_10[
_10  {
_10    "label": "foo",
_10    "id": "bar",
_10    "type": {
_10      "kind": "String"
_10    }
_10  }
_10]

Function Types


_10{
_10  "kind": "Function",
_10  "typeID": "<function name>",
_10  "parameters": [
_10    <parameter at index 0>,
_10    <parameter at index 1>,
_10    // ...
_10  ],
_10  "return": <type>
_10}

Example


_16{
_16  "kind": "Function",
_16  "typeID": "foo",
_16  "parameters": [
_16    {
_16      "label": "foo",
_16      "id": "bar",
_16      "type": {
_16        "kind": "String"
_16      }
_16    }
_16  ],
_16  "return": {
_16    "kind": "String"
_16  }
_16}

Reference Types


_10{
_10  "kind": "Reference",
_10  "authorized": true | false,
_10  "type": <type>
_10}

Example


_10{
_10  "kind": "Reference",
_10  "authorized": true,
_10  "type": {
_10    "kind": "String"
_10  }
_10}

Restricted Types


_10{
_10  "kind": "Restriction",
_10  "typeID": "<fully qualified type ID>",
_10  "type": <type>,
_10  "restrictions": [
_10    <type at index 0>,
_10    <type at index 1>,
_10    //...
_10  ]
_10}

Example


_23{
_23  "kind": "Restriction",
_23  "typeID": "0x3.GreatContract.GreatNFT",
_23  "type": {
_23    "kind": "AnyResource",
_23  },
_23  "restrictions": [
_23    {
_23        "kind": "ResourceInterface",
_23        "typeID": "0x1.FungibleToken.Receiver",
_23        "fields": [
_23            {
_23                "id": "uuid",
_23                "type": {
_23                    "kind": "UInt64"
_23                }
_23            }
_23        ],
_23        "initializers": [],
_23        "type": ""
_23    }
_23  ]
_23}

Capability Types


_10{
_10  "kind": "Capability",
_10  "type": <type>
_10}

Example


_10{
_10  "kind": "Capability",
_10  "type": {
_10    "kind": "Reference",
_10    "authorized": true,
_10    "type": {
_10      "kind": "String"
_10    }
_10  }
_10}

Enum Types


_12{
_12  "kind": "Enum",
_12  "type": <type>,
_12  "typeID": "<fully qualified type ID>",
_12  "initializers":[],
_12  "fields": [
_12    {
_12      "id": "rawValue",
_12      "type": <type>
_12    }
_12  ]
_12}

Example


_16{
_16  "kind": "Enum",
_16  "type": {
_16    "kind": "String"
_16  },
_16  "typeID": "0x3.GreatContract.GreatEnum",
_16  "initializers":[],
_16  "fields": [
_16    {
_16      "id": "rawValue",
_16      "type": {
_16        "kind": "String"
_16      }
_16    }
_16  ]
_16}

Repeated Types

When a composite type appears more than once within the same JSON type encoding, either because it is recursive or because it is repeated (e.g. in a composite field), the composite is instead represented by its type ID.

Example


_19{
_19  "type":"Type",
_19  "value": {
_19    "staticType": {
_19      "kind":"Resource",
_19      "typeID":"0x3.GreatContract.NFT",
_19      "fields":[
_19        {"id":"foo",
_19        "type": {
_19          "kind":"Optional",
_19          "type":"0x3.GreatContract.NFT" // recursive NFT resource type is instead encoded as an ID
_19          }
_19        }
_19      ],
_19      "initializers":[],
_19      "type":""
_19    }
_19  }
_19}

JSON-Cadence Data Interchange Format

Values

Void​

Example​

Optional​

Example​

Bool​

Example​

String​

Example​

Address​

Example​

Integers​

Example​

Fixed Point Numbers​

Example​

Array​

Example​

Dictionary​

Example​

Composites (Struct, Resource, Event, Contract, Enum)​

Example​

Path​

Example​

Type Value​

Example​

Capability​

Example​

Functions​

Example​

Types

Simple Types​

Example​

Optional Types​

Example​

Variable Sized Array Types​

Example​

Constant Sized Array Types​

Example​

Dictionary Types​

Example​

Composite Types​

Example​

Field Types​

Example​

Parameter Types​

Example​

Initializer Types​

Example​

Function Types​

Example​

Reference Types​

Example​

Restricted Types​

Example​

Capability Types​

Example​

Enum Types​

Example​

Repeated Types​

Example​

Void

Example

Optional

Example

Bool

Example

String

Example

Address

Example

Integers

Example

Fixed Point Numbers

Example

Array

Example

Dictionary

Example

Composites (Struct, Resource, Event, Contract, Enum)

Example

Path

Example

Type Value

Example

Capability

Example

Functions

Example

Simple Types

Example

Optional Types

Example

Variable Sized Array Types

Example

Constant Sized Array Types

Example

Dictionary Types

Example

Composite Types

Example

Field Types

Example

Parameter Types

Example

Initializer Types

Example

Function Types

Example

Reference Types

Example

Restricted Types

Example

Capability Types

Example

Enum Types

Example

Repeated Types

Example