Announcing Sui Incentivized Testnet: Get ready for the Sui-nami in August. Read more

SuiJSON

Introduction

SuiJSON is a JSON-based format with restrictions that allow Sui to align JSON inputs more closely with Move Call arguments.

This table shows the restrictions placed on JSON types to make them SuiJSON compatible:

JSON SuiJSON Restrictions Move Type Mapping
Number Must be unsigned integer U8

U64

(U128 is encoded as String)

String No restrictions Vector<U8>

Address

ObjectID

TypeTag

Identifier

Unsigned Integer (128 bit max)

Boolean No restrictions Bool
Array Must be homogeneous JSON and of SuiJSON type Vector
Null Not allowed
Object Not allowed
'

Type coercion reasoning

Due to the loosely typed nature of JSON/SuiJSON and the strongly typed nature of Move types, we sometimes need to overload SuiJSON types to represent multiple Move types.
For example SuiJSON::Number can represent both U8 and U64. This means we have to coerce and sometimes convert types.

Which type we coerce depends on the expected Move type. For example, if the Move function expects a U8, we must have received a SuiJSON::Number with a value less than 256. More importantly, we have no way to easily express Move addresses in JSON, so we encode them as hex strings prefixed by 0x.

Additionally, Move supports U128 but JSON doesn't. As a result we allow encoding numbers as strings.

Type coercion rules

Move Type SuiJSON Representations Valid Examples Invalid Examples
Bool Bool true, false
U8 Three formats are supported
  • Unsigned number < 256.

  • Decimal string with value < 256.

  • One byte hex string prefixed with 0x.

7

"70"

"0x43"

-5: negative not allowed

3.9: float now allowed

NaN: not allowed

300: U8 must be less than 256

" 9": Spaces not allowed in string

"9A": Hex num must be prefixed with 0x

"0x09CD": Too large for U8

U64 Similarly to U8, three formats are supported
  • Unsigned number < U64::MAX.

  • Decimal string with value < U64::MAX.

  • Up to 8 byte hex string prefixed with 0x.

Extrapolate above examples Extrapolate above examples
U128

Two formats are supported

  • Decimal string with value < U128::MAX.

  • Up to 16 byte hex string prefixed with 0x.

"74794734937420002470"

"0x2B1A39A1514E1D8A7CE"

34: Although this is a valid u128 number, it must be encoded as a string
Address 20 byte hex string prefixed with 0x "0x2B1A39A1514E1D8A7CE45919CFEB4FEE70B4E011" 0x2B1A39: string too short

2B1A39A1514E1D8A7CE45919CFEB4FEE70B4E011: missing 0x prefix

0xG2B1A39A1514E1D8A7CE45919CFEB4FEE70B4E01: invalid hex char G

ObjectID 16 byte hex string prefixed with 0x "0x2B1A39A1514E1D8A7CE45919CFEB4FEE" Similar to above
Identifier Typically used for module and function names. Encoded as one of the following:
  1. A String whose first character is a letter and the remaining characters are letters, digits or underscore.

  2. A String whose first character is an underscore, and there is at least one further letter, digit or underscore

"function",

"_function",

"some_name",

"____some_name",

"Another"

"_": missing trailing underscore, digit or letter,

"8name": cannot start with digit,

".function": cannot start with period,

" ": cannot be empty space,

"func name": cannot have spaces

Vector<Move Type> Homogeneous vector of aforementioned types including nested vectors [1,2,3,4]: simple U8 vector

[[3,600],[],[0,7,4]]: nested U64 vector

[1,2,3,false]: not homogeneous JSON

[1,2,null,4]: invalid elements

[1,2,"7"]: although we allow encoding numbers as strings meaning this array can evaluate to [1,2,7], the array is still ambiguous so it fails the homogeneity check.

Vector<U8> For convenience, we allow:

U8 vectors represented as UTF-8 (and ASCII) strings.

"√®ˆbo72 √∂†∆˚–œ∑π2ie": UTF-8

"abcdE738-2 _=?": ASCII

'
Last update 4/30/2022, 5:49:35 PM

Contributor(s)