JSON encoding

How RequestScript values are converted to and from JSON.

Scripts exchange data with the outside world as JSON: contract parameters arrive as JSON, and return values leave as JSON.

Return values

A script’s return value is encoded as JSON under the returnValue key:

RequestScript type	JSON
int32	Number
int64	Number, or a string if a number would lose precision
decimal	Number, or a string if a number would lose precision
boolean	true or false
string	String
object	Object
[]T	Array
null	null

Large or very precise numbers are returned as strings so that no digits are lost:

request BigNumbers {
    return {
        small: 42,
        big: 9223372036854775807,
        precise: 12345678901234567.89,
    }
}

{
  "returnValue": {
    "small": 42,
    "big": "9223372036854775807",
    "precise": "12345678901234567.89"
  }
}

If a client needs a consistent type for a field, check whether it’s a string and parse it with an arbitrary-precision library.

Trailing zeros after the decimal point aren’t preserved: a decimal such as 72.00 is returned as 72.

Contract parameters

Contract parameters are converted from JSON to their declared types:

Declared type	Accepted JSON
int32	A whole number within range, or a string containing one
int64	A whole number within range, or a string containing one
decimal, decimal(p, s)	A number, or a string containing one. decimal(p, s) bounds are checked.
boolean	true or false
string	A string
object	An object
[]T	An array whose elements are each accepted as T
Any type	null

Send int64 and decimal values as strings when they have more digits than a JSON number can safely carry. Integer parameters larger than 9,007,199,254,740,991 must be sent as strings:

{ "parameters": { "amount": "12345678901234567.89" } }

Inferred types

Values without a declared type, such as the properties of an object parameter or of an object returned by a resource function, get inferred types:

JSON	Inferred type
Whole number that fits in 32 bits	int32
Larger whole number	int64
Number with a fractional part	decimal
String	string
true, false	boolean
Object	object
Array	A list
null	null