Syntax Overview

IonPath uses a concise IDL (Interface Definition Language) to declare types, services, and contracts. Files use the .ion extension.

File Structure

An .ion file consists of directives at the top, followed by type and service declarations in any order:

// directives
#use "common.ion"
#feature "std"

// custom attribute declaration
attribute @deprecated(version: string, reason: string);

// message (data structure)
msg User {
    id: u4;
    name: string;
    email: string?;    // optional
    tags: string[];    // array
}

// enum
enum Status: u1 {
    Active,
    Inactive = 2
}

// flags (bitwise)
flags Permissions: u4 {
    Read = 1 << 0,
    Write = 1 << 1,
    Admin = 1 << 2
}

// typedef (type alias)
typedef UserId = u4;

// union (discriminated)
union Result {
    Success(data: User),
    Error(code: i4, message: string)
}

// service (RPC)
service UserService(spaceId: u4) {
    GetUser(id: u4): User;
    stream WatchUsers(): User;
}

Language Constructs

Keyword Description

msg Data structure with indexed fields — like a struct or record

service RPC interface with methods — generates client and server code

union Discriminated union — tagged variant type

enum Enumeration with named constants (single value)

flags Bitfield enumeration (combinable values)

typedef Type alias — give a name to an existing type

attribute Custom annotation declaration

#use Import another .ion module

#feature Enable a feature module (std, vector, orleans)

Type Modifiers

Types can be modified with suffixes:

Modifier Description

T? Optional — wraps in Maybe<T>. Null on the wire when absent.

T[] Array — wraps in Array<T>. Variable-length sequence.

~T Partial — wraps in Partial<T>. Sparse update (only modified fields sent).

Method Modifiers

Service methods support these modifiers:

Modifier Description

unary Request-response (default). One request, one response over HTTP.

stream Streaming response or bidirectional streaming over WebSocket.

internal Hidden/internal method — not exposed in public API.

Comments

Single-line comments with //:

// This is a documentation comment for the User message.
// It can span multiple lines.
msg User {
    // The unique user identifier
    id: u4;
}

Deep Dive

Each construct has its own detailed guide:

Primitive Types

All 27+ built-in types with wire sizes.

Messages

Data structures with field indexing.

Services

RPC definitions and method types.

Unions

Discriminated unions and shared fields.

Enums & Flags

Enumerations and bitfield types.

Generics

Parameterized types and constraints.