The IDL is a type system, not just a wire format.

The types don't stop at the boundary

The moment two systems share an interface, they share its types. But the generated types are ordinary types as in C++ or Rust — so they don't stay penned at the edge of the program. They are used directly by the code that never marshals anything, which means there is no second set of "domain" types to translate to and from. And because the same machinery that marshals a call can serialise a value to bytes, the very same definitions can describe how data is stored. One schema ends up governing how a system talks, computes, and persists.

This is the long game. The further the same definitions reach — past the wire, into the logic, down into the database — the more the IDL stops being "the marshalling format" and becomes the canonical type system the whole system is built on.

Coming soon

A language-independent surface for the same wire type system.

Canopy's current IDL deliberately resembles C++. The next IDL surface will use language-independent, Rust- and Protocol Buffers-like type spelling while preserving Canopy's canonical wire type system, contract identities, and compatibility rules. It is a clearer way to express the same boundary contract, not a second RPC protocol.

Explicit numbered namespaces such as v1 remain strongly recommended. The surface syntax may evolve, but wire-version and contract identity should always remain visible.

Imperative code, functional-grade plumbing

C++ is an imperative language, and hand-written boundary glue is imperative at its most error-prone: mutable buffers, manual ordering, lifetimes juggled by hand — and subtly different on every boundary. It is exactly the code most likely to hide a bug that surfaces on one transport and not another.

The IDL is declarative. You state the contract — the methods, the types, the direction of each parameter — and nothing about how it is carried. Declarative definitions remove boilerplate by construction, and generating the boundary from one means the whole path from proxy call to stub dispatch is produced for you: serialise the arguments, move the bytes, deserialise them, invoke your implementation. Because that path is generated rather than typed out by hand, it carries guarantees that functional programming usually needs a dedicated language to enforce — while your runtime stays plain imperative C++:

• Deterministic. The same contract generates the same path every time — no drift between boundaries, no marshalling bug on one transport but not another.
• Referentially transparent. Given the same inputs the boundary behaves the same way, whichever transport or serialiser sits underneath it.
• Free of incidental state. The generated layer does one thing — call your implementation correctly — and keeps no hidden state of its own.
• Total. Every declared method and type is handled exhaustively; there is no half-written case left to be forgotten.

It borrows the principle behind functional core, imperative shell — separate the deterministic part from the effectful part — and bakes it into the boundary itself: a generated, deterministic contract layer kept cleanly apart from the imperative implementation it wraps. You write your business logic the way you always have; the plumbing earns the discipline.

Only two things are allowed to break that determinism, and both are deliberate: logging and telemetry layered into the generated path for observability, and the expected failures of an unreliable wire — a dropped connection, a timeout — which the contract surfaces as errors rather than hiding. Everything else is the same code, doing the same thing, on every boundary.

The anatomy of an interface definition

The current Canopy IDL reads like trimmed-down C++ with a few RPC-specific attributes in square brackets. Here is each construct used by the current format, building from data types up through interfaces and remote references.

These examples use C++-flavoured spellings such as std::string and std::vector. The language-independent surface described above will retain the same wire type system while making language-specific native types explicit overrides.

Namespaces and versioning

Namespaces group interfaces and structs, and can nest. We strongly recommend putting every durable contract inside an explicit numbered namespace such as v1, and using that version in the fully qualified type name. Callers then state exactly which contract they were built against, while v1 and v2 can coexist during migration.

Explicit version names make compatibility boundaries visible in code, generated bindings, fingerprints, diagnostics, and policy. They also prevent a new default version from silently changing the meaning of an existing unqualified interface name.

namespace calculator
{
    namespace v1
    {
        interface i_calculator
        {
            error_code add(int a, int b, [out] int& result);
        };
    }
}

Enums

Enums carry an explicit underlying type, keeping their numeric domain consistent across generated bindings and serialisers. Enum values are also how [tag=…] method routing is declared.

enum encoding : uint64_t
{
    yas_binary = 1,
    yas_json = 8,
    protocol_buffers = 16
};

Structs

Structs are plain data: members, defaults, vectors and maps, and nesting. They are ordinary generated C++ types, so the same definition is used directly in your in-process code — there is no separate DTO layer to translate to and from.

struct config
{
    std::string name = "default";
    int timeout = 30;
    std::vector<std::string> tags;
    std::map<std::string, int> name_to_id;
};

Optional and variant

Some types use Canopy's own wrappers, rpc::optional<T> and rpc::variant<Ts…>. The generator deliberately rejects std::optional and std::variant so that YAS binary, Protobuf, Nanopb, and JSON all agree on one wire shape. In JSON an absent optional is simply omitted, and an explicit null loads back as empty.

struct request_options
{
    rpc::optional<std::string> label;
    rpc::variant<int32_t, std::string> selector;
};

Interfaces

Interfaces are the RPC contracts: methods returning an error_code (a typedef you define, conventionally 0 = OK), with parameter direction in brackets. They can inherit — including multiple inheritance — carry [description] and [status] documentation, and mark one-way methods with [post]. The full attribute set is listed under the annotation vocabulary below.

[status=production, description="Calculator interface"]
interface i_calculator
{
    error_code add(int a, int b, [out] int& result);

    // fire-and-forget: returns immediately, ordered, no [out] params
    [post] error_code log_event(const std::string& message);
};

Remote references: shared_ptr vs optimistic_ptr

An interface can be passed as a parameter or returned — that is how one runtime component hands another a callable object across a boundary. Two pointer types express the ownership:

interface i_host
{
    // hand back an owning reference to a created object
    error_code create_example([out] rpc::shared_ptr<i_example>& target);

    // accept an object owned by the caller
    error_code set_app(const std::string& name,
                       [in] const rpc::shared_ptr<i_example> app);
};

Smart-pointer parameters are [in] or [out], never [in, out]; and [post] methods cannot pass interface pointers at all. Raw C++ pointers are rejected too — an address has no meaning in another address space.

Composing across files — #import vs #include

Almost always reach for #import: it makes the generator aware of types defined elsewhere and reuses their marshalling, without regenerating them. #include copy-pastes the file like the C preprocessor — handy for shared #defines, but a source of duplicate-symbol errors if the same types land twice.

#import "shared/types.idl"   // preferred: reference, don't regenerate
#include "macros.idl"        // copy-paste; use sparingly (#defines etc.)

What gets generated

Use explicit versioned namespaces such as v1 from the first published contract. Add v2 beside it when a breaking change is needed, keep both callable during migration, and retire the old version deliberately.

The annotation vocabulary

Attributes in square brackets add RPC-specific meaning to a declaration without changing the types themselves. They are how an interface carries documentation, lifecycle, dispatch behaviour, and parameter direction — all of which the generator and the reflection metadata pick up.

One definition also powers your tools

Beyond proxy and stub code, the same IDL emits machine-readable metadata: reflection schemas that let a running component describe its interfaces, and configuration schemas that bind exchanged interfaces to transports and addresses. Both are derived from the one source of truth, so the tools that consume them are never out of step with the running system.

CMake integration

The CanopyGenerate CMake command takes an IDL file and produces C++ proxy, stub, and serialisation glue for each requested format. Multiple formats from the same IDL are supported.

CanopyGenerate(
  foo
  foo/foo.idl
  ${CMAKE_CURRENT_SOURCE_DIR}
  ${CMAKE_BINARY_DIR}/generated
  ""
  yas_binary
  yas_json
  protocol_buffers
  include_paths ${CMAKE_CURRENT_SOURCE_DIR}/.
  install_dir   ${GENERATED_INSTALL_DIR})