SerpIDL Overview

SerpIDL Overview

SerpIDL is the language for describing the architecture of a SERP system. When you write a spec, you're not just defining method signatures — you're specifying service boundaries, ownership, dependencies, and deployment topology. Everything else in the SERP pipeline — generated code, transport adapters, process configurations, AI session scopes — derives from this description.

Technically, SerpIDL is a YAML-based Interface Definition Language. It defines service contracts — methods, attributes, broadcasts, and types — in a format that serpgen reads to produce C++ code, build files, and deployment configurations.

File Types

Extension	Purpose
*.sidl.yaml / *.sidl.yml	Interface contracts — methods, attributes, broadcasts, types
serp.sidl	Workspace root — project entry point for serpgen
*.sidl (in services/)	Service specs — implements/uses declarations
*.sidl (in deployments/)	Deployment specs — process topology and transport config

Directory Layout Convention

specs/
  serp.sidl                  # workspace root
  interfaces/
    IMyService.sidl.yaml     # interface contracts
  services/
    MyService.sidl           # service declarations
  deployments/
    monolith.sidl            # deployment configs

This layout is a convention, not a requirement. The serp.sidl workspace root tells serpgen where to find each file type via interface_dirs, service_dirs, and deployments fields.

Key Concepts

Interface

An interface is the contract for a service — the set of methods callers can invoke, attributes they can observe, and broadcasts they can subscribe to. Interfaces are defined in *.sidl.yaml files and form the canonical API surface that both producers and consumers are generated from.

Service Spec

A service spec declares what a service provides (implements) and what it depends on (uses). serpgen uses this to generate the appropriate base classes, stubs, and dependency injection wiring.

Workspace Root

The serp.sidl file names the project, declares where interfaces and services live, and lists the deployments to generate. It is the single entry point passed to all serpgen commands.

Deployment Spec

A deployment spec defines how services are distributed into processes, which transport backend to use, how processes depend on each other, and how the supervisor (systemd, init.d, etc.) should manage them.

Legacy FIDL Support

FIDL (Franca IDL) is supported as a legacy alternative via the serp_idl_fidl plugin. If your project has existing .fidl files, serpgen can parse them through this plugin. New projects should use SerpIDL.

Related Pages

• Interfaces — interface contract syntax
• Type System — all supported types
• Workspace Root — serp.sidl reference
• Service Specs — service declaration syntax
• Deployment Specs — deployment and process config
• Generator Overview — how serpgen processes specs