Skip to main content
Version: Next

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​

{
"type": "Void"
}

Example​

{
"type": "Void"
}

Optional​

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

Example​

// Non-nil

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

// Nil

{
"type": "Optional",
"value": null
}

Bool​

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

Example​

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

String​

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

Example​

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

Address​

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

Example​

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

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.

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

Example​

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

Fixed Point Numbers​

[U]Fix64

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

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

Example​

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

Array​

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

Example​

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

Dictionary​

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

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

Example​

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

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.

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

Example​

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

Path​

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

Example​

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

Type Value​

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

Example​

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

Capability​

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

Example​

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

Functions​

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

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

Example​

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

Types

Simple Types​

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

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

Example​

{
"kind": "UInt8"
}

Optional Types​

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

Example​

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

Variable Sized Array Types​

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

Example​

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

Constant Sized Array Types​

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

Example​

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

Dictionary Types​

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

Example​

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

Composite Types​

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

Example​

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

Field Types​

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

Example​

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

Parameter Types​

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

Example​

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

Initializer Types​

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

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

Example​

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

Function Types​

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

Example​

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

Reference Types​

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

Example​

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

Intersection Types​

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

Example​

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

Capability Types​

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

Example​

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

Enum Types​

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

Example​

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

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​

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