Type System

Type System

SerpIDL has a complete type system covering primitives, collections, and user-defined types. Types appear in method parameters, attribute types, broadcast payloads, and struct fields.

Primitive Types

Type	Description
String	UTF-8 string
Boolean	true / false
Int8	Signed 8-bit integer
Int16	Signed 16-bit integer
Int32	Signed 32-bit integer
Int64	Signed 64-bit integer
UInt8	Unsigned 8-bit integer
UInt16	Unsigned 16-bit integer
UInt32	Unsigned 32-bit integer
UInt64	Unsigned 64-bit integer
Float	32-bit IEEE 754 floating-point
Double	64-bit IEEE 754 floating-point
Byte	Raw byte

Collection Types

Type	Example	Description
list<T>	list<String>	Variable-length ordered array
map<K, V>	map<String, Int32>	Key-value map
optional<T>	optional<Double>	Nullable (may be absent) value
T[]	String[]	Array shorthand — equivalent to list<T>

Collection types can be nested:

- name: tags
  type: list<String>

- name: metadata
  type: map<String, String>

- name: maybeSpeed
  type: optional<Double>

- name: history
  type: list<TrackInfo>

Custom Types

Custom types are defined in the types section of an interface or in a shared common file. Two kinds are supported: enum and struct.

Enum

An enum defines a closed set of named values.

- kind: enum
  name: PlaybackState
  values: [stopped, playing, paused, buffering]

values is a list of strings. serpgen maps these to a C++ enum class.

Struct

A struct groups named fields into a composite value type.

- kind: struct
  name: TrackInfo
  fields:
    - name: id
      type: String
    - name: title
      type: String
    - name: durationSec
      type: Int32

Each field has a name and a type. Field types may be:

• Any primitive
• Any collection (list<T>, map<K,V>, optional<T>)
• Another struct or enum defined in the same interface or in an imported common file

Nested Types

Structs can reference other structs and enums freely, as long as the referenced type is defined in the same interface or in a common file included via interface_dirs.

types:
  - kind: enum
    name: ClimateZone
    values: [driver, passenger, all]
  
  - kind: struct
    name: ClimateStatus
    fields:
      - name: zone
        type: ClimateZone      # references the enum above
      - name: temperature
        type: Double
      - name: fanSpeed
        type: Int32

Shared Common Types

Types used across multiple interfaces should be defined in a dedicated common *.sidl.yaml file rather than repeating them in each interface.

serp_idl: 1
package: demo.common

types:
  - kind: enum
    name: ErrorCode
    values: [ok, not_found, permission_denied, invalid_argument, internal_error]
  
  - kind: struct
    name: ServiceStatus
    fields:
      - name: ok
        type: Boolean
      - name: error
        type: ErrorCode

Place this file in one of the directories listed under interface_dirs in serp.sidl. Any interface in the workspace can then reference ErrorCode or ServiceStatus by name.

Type Naming Conventions

Category	Convention	Example
Primitives	PascalCase	Int32, String
Enums	PascalCase	PlaybackState
Structs	PascalCase	TrackInfo
Collection wrappers	lowercase keyword	list<T>, map<K,V>, optional<T>

Related Pages

• Interfaces — where types appear in method, attribute, and broadcast definitions
• Generator Overview — how types are mapped to C++ in generated code