Syntax Reference

The .sia schema language defines data structures and RPC plugins. It is parsed by a Chevrotain-based lexer and parser, producing an intermediate representation (IR) that feeds into language-specific code generators.

Schema Definitions

A schema defines a data structure with named, typed fields:

schema Person {
  name    string8
  age     uint8
  email   string16
  active  bool
}

The generated code will produce an encode function that calls addString8, addUInt8, addString16, and addBool in order, and a decode function that calls the corresponding read* methods.

Field Types

Integers

Strings

Byte Arrays

Boolean

Custom Types

Any identifier that matches a declared schema name is treated as a custom type. The generated code will call the corresponding encode/decode function for that type:

schema Address {
  street  string8
  city    string8
  zip     int32
}

schema Person {
  name    string8
  address Address
}

Optional Fields

Append ? to a field name to mark it as optional:

schema Config {
  host     string8
  port?    uint16
  debug?   bool
}

In TypeScript, optional fields become fieldName?: type. In Go, optional fields with defaults use inline conditionals. In Python, optional fields appear as keyword arguments with default values of None.

Default Values

Assign default values with =:

schema Settings {
  theme?    string8 = "dark"
  retries?  uint8 = 3
  verbose?  bool = false
}

Default values are applied in the generated code when the field is not provided.

Arrays

Append [] to a type to make it an array:

schema Document {
  title   string8
  tags    string8[]
  scores  uint32[]
}

Arrays are serialized using addArray8 / readArray8 (with a 1-byte length prefix). The array variant matches the implicit default of 8-bit length prefix.

Type Options

Type options are key-value pairs in parentheses after the type:

schema Message {
  id       byteN(length = 32)
  sender   string8(encoding = "ascii")
  data     byte64
}

Available Options

Plugin methods also support timeout, fee, and currency options. See the Plugins page.

Cross-Schema References

Schemas can reference other schemas as field types:

schema Coordinate {
  x  int32
  y  int32
}

schema Shape {
  name    string8
  origin  Coordinate
  points  Coordinate[]
}

The generated code calls the referenced type's encode/decode function inline.

Comments

Both single-line and block comments are supported:

// This is a single-line comment

/* This is a
   block comment */

schema Example {
  name  string8   // inline comment
}

Keyword Contextuality

Inside schema {} and method {} blocks, all keywords (schema, plugin, method, as, returns) are treated as identifiers. This means you can use keywords as field names:

schema Meta {
  schema   string8
  method   string8
  returns  bool
}

Complete Example

Here is a schema demonstrating all constructs:

schema Address {
  street?  string8 = "Unknown"
  city     string8
  zip      int32
}

schema Person {
  name     string8
  age?     int32
  email?   string8(encoding = "ascii")[]
  tags     string8[]
  avatar   byteN(length = 32)
  photo    byte64
  address  Address
}

This schema defines two types. Person has required fields, optional fields with defaults, arrays, fixed-length byte fields, variable-length byte fields, and a nested Address reference.