SATN JSON Format
The Spacetime Algebraic Type Notation JSON format defines how Spacetime AlgebraicType
s and AlgebraicValue
s are encoded as JSON. Algebraic types and values are JSON-encoded for transport via the HTTP Databases API and the WebSocket text protocol.
Values
At a glance
Type | Description |
---|---|
AlgebraicValue |
A value whose type may be any AlgebraicType . |
SumValue |
A value whose type is a SumType . |
ProductValue |
A value whose type is a ProductType . |
BuiltinValue |
A value whose type is a BuiltinType . |
`AlgebraicValue`
SumValue | ProductValue | BuiltinValue
`SumValue`
An instance of a SumType
. SumValue
s are encoded as a JSON object with a single key, a non-negative integer tag which identifies the variant. The value associated with this key is the variant data. Variants which hold no data will have an empty array as their value.
The tag is an index into the SumType.variants
array of the value's SumType
.
{
"<tag>": AlgebraicValue
}
`ProductValue`
An instance of a ProductType
. ProductValue
s are encoded as JSON arrays. Each element of the ProductValue
array is of the type of the corresponding index in the ProductType.elements
array of the value's ProductType
.
array<AlgebraicValue>
`BuiltinValue`
An instance of a BuiltinType
. BuiltinValue
s are encoded as JSON values of corresponding types.
boolean | number | string | array<AlgebraicValue> | map<AlgebraicValue, AlgebraicValue>
BuiltinType |
JSON type |
---|---|
Bool |
boolean |
Integer types | number |
Float types | number |
String |
string |
Array types | array<AlgebraicValue> |
Map types | map<AlgebraicValue, AlgebraicValue> |
All SATS integer types are encoded as JSON number
s, so values of 64-bit and 128-bit integer types may lose precision when encoding values larger than 2⁵².
Types
All SATS types are JSON-encoded by converting them to an AlgebraicValue
, then JSON-encoding that meta-value.
At a glance
Type | Description |
---|---|
AlgebraicType |
Any SATS type. |
SumType |
Sum types, i.e. tagged unions. |
ProductType |
Product types, i.e. structures. |
BuiltinType |
Built-in and primitive types, including booleans, numbers, strings, arrays and maps. |
AlgebraicTypeRef |
An indirect reference to a type, used to implement recursive types. |
`AlgebraicType`
AlgebraicType
is the most general meta-type in the Spacetime Algebraic Type System. Any SATS type can be represented as an AlgebraicType
. AlgebraicType
is encoded as a tagged union, with variants for SumType
, ProductType
, BuiltinType
and AlgebraicTypeRef
.
{ "Sum": SumType }
| { "Product": ProductType }
| { "Builtin": BuiltinType }
| { "Ref": AlgebraicTypeRef }
`SumType`
The meta-type SumType
represents sum types, also called tagged unions or Rust enum
s. A sum type has some number of variants, each of which has an AlgebraicType
of variant data, and an optional string discriminant. For each instance, exactly one variant will be active. The instance will contain only that variant's data.
A SumType
with zero variants is called an empty type or never type because it is impossible to construct an instance.
Instances of SumType
s are SumValue
s, and store a tag which identifies the active variant.
// SumType:
{
"variants": array<SumTypeVariant>,
}
// SumTypeVariant:
{
"algebraic_type": AlgebraicType,
"name": { "some": string } | { "none": [] }
}
`ProductType`
The meta-type ProductType
represents product types, also called structs or tuples. A product type has some number of fields, each of which has an AlgebraicType
of field data, and an optional string field name. Each instance will contain data for all of the product type's fields.
A ProductType
with zero fields is called a unit type because it has a single instance, the unit, which is empty.
Instances of ProductType
s are ProductValue
s, and store an array of field data.
// ProductType:
{
"elements": array<ProductTypeElement>,
}
// ProductTypeElement:
{
"algebraic_type": AlgebraicType,
"name": { "some": string } | { "none": [] }
}
`BuiltinType`
The meta-type BuiltinType
represents SATS primitive types: booleans, integers, floating-point numbers, strings, arrays and maps. BuiltinType
is encoded as a tagged union, with a variant for each SATS primitive type.
SATS integer types are identified by their signedness and width in bits. SATS supports the same set of integer types as Rust, i.e. 8, 16, 32, 64 and 128-bit signed and unsigned integers.
SATS floating-point number types are identified by their width in bits. SATS supports 32 and 64-bit floats, which correspond to IEEE 754 single- and double-precision binary floats, respectively.
SATS array and map types are homogeneous, meaning that each array has a single element type to which all its elements must conform, and each map has a key type and a value type to which all of its keys and values must conform.
{ "Bool": [] }
| { "I8": [] }
| { "U8": [] }
| { "I16": [] }
| { "U16": [] }
| { "I32": [] }
| { "U32": [] }
| { "I64": [] }
| { "U64": [] }
| { "I128": [] }
| { "U128": [] }
| { "F32": [] }
| { "F64": [] }
| { "String": [] }
| { "Array": AlgebraicType }
| { "Map": {
"key_ty": AlgebraicType,
"ty": AlgebraicType,
} }
`AlgebraicTypeRef`
AlgebraicTypeRef
s are JSON-encoded as non-negative integers. These are indices into a typespace, like the one returned by the /database/schema/:name_or_address GET
HTTP endpoint.