Interfaces

Interfaces

Interfaces are defined in *.sidl.yaml files and describe the complete API contract for a service: the methods it exposes, the attributes it owns, the broadcasts it emits, and the types it uses.

Full Example

serp_idl: 1
package: demo.climate

interfaces:
  - name: IClimateManager
    version:
      major: 1
      minor: 0
    
    methods:
      - name: setTemperature
        in:
          - name: zone
            type: ClimateZone
          - name: temp
            type: Double
        out:
          - name: ok
            type: Boolean
      
      - name: getTemperature
        in:
          - name: zone
            type: ClimateZone
        out:
          - name: temp
            type: Double
    
    attributes:
      - name: driverTemp
        type: Double
        readonly: true
      - name: fanSpeed
        type: Int32
    
    broadcasts:
      - name: climateChanged
        out:
          - name: zone
            type: ClimateZone
          - name: temp
            type: Double
    
    types:
      - kind: enum
        name: ClimateZone
        values: [driver, passenger, all]
      
      - kind: struct
        name: ClimateStatus
        fields:
          - name: zone
            type: ClimateZone
          - name: temperature
            type: Double
          - name: fanSpeed
            type: Int32

Top-Level Fields

Field	Description
serp_idl	Schema version — always 1 for current SerpIDL
package	Dotted namespace for this file's types (e.g. demo.climate)
interfaces	List of interface definitions

Interface Fields

Field	Required	Description
name	Yes	Interface name — by convention starts with I
version.major	Yes	Breaking change version
version.minor	Yes	Backwards-compatible change version
methods	No	RPC calls
attributes	No	Observable state variables
broadcasts	No	Events emitted by the service
types	No	Enums and structs scoped to this interface

Methods

Methods represent RPC calls. The caller sends in parameters and receives out parameters in the reply.

methods:
  - name: setTemperature
    in:
      - name: zone
        type: ClimateZone
      - name: temp
        type: Double
    out:
      - name: ok
        type: Boolean

• in: list of named input parameters. May be empty or omitted.
• out: list of named output parameters. May be empty or omitted.
• Both in and out parameters carry a name and a type.
• Types may be any primitive, collection, or custom type defined in this interface or in a shared common file.

Attributes

Attributes represent state owned by the service. Callers can read (and optionally write) them, and subscribe to change notifications.

attributes:
  - name: driverTemp
    type: Double
    readonly: true
  - name: fanSpeed
    type: Int32

Field	Required	Description
name	Yes	Attribute name
type	Yes	Value type
readonly	No	If true, only the service can set this attribute. Default: false.

serpgen generates typed getter/setter methods and change subscription callbacks for each attribute in the interface and base class.

Broadcasts

Broadcasts are events fired by the service and received by all subscribers. Unlike attributes, they are one-shot notifications with no persistent state.

broadcasts:
  - name: climateChanged
    out:
      - name: zone
        type: ClimateZone
      - name: temp
        type: Double

• out: the payload parameters attached to the event.
• The generated interface exposes a subscription method for each broadcast.

Types

Types defined inside an interface are scoped to that interface. Both enum and struct are supported.

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

For types shared across multiple interfaces, define them in a separate common *.sidl.yaml file and reference the directory in interface_dirs in the workspace root. See Type System for the full type reference.

Multiple Interfaces per File

A single *.sidl.yaml file may define multiple interfaces under the same package. This is useful for grouping closely related contracts.

serp_idl: 1
package: demo.audio

interfaces:
  - name: IAudioManager
    ...
  - name: IAudioPolicy
    ...

Related Pages

• Type System — primitive, collection, and custom type reference
• Service Specs — declaring which interfaces a service implements
• Generated Code Layout — what serpgen produces from an interface file