Language reference

NOTE: This page explains the Glue syntax in pseudo EBNF form. It is not a formal specification, but rather a reference guide to the language features and syntax, so that it's easier to grok. If you are interested in the exact grammar, Glue uses pest and you can check out the Pest file in the Glue codebase.

The Glue IDL is designed to be simple and intuitive, with a syntax that is easy to read and write. Below is a reference of the language features and syntax.

#Primitive types

Glue supports the following primitive types:

• string
• int
• uint
• i8, i16, i32, i64
• u8, u16, u32, u64
• float
• any
• bool

#Compound types

• model (a structured type with named fields)
• enum (enumeration of string values)
• type alias declarations (e.g., type UserID = string)
• const declarations (e.g., const MAX_PAGE_SIZE: int = 100)
• T[] (an array/list of type T)
• (T, U) (a fixed-length tuple)
• Record<T, U> (a map/dictionary type with keys of type T and values of type U)
• A | B (a union type)
• endpoint (an API endpoint definition with method, path, parameters, and responses)
• service (a Protobuf service definition with RPC methods)

#Block member separators

Model, anonymous model, endpoint, service, and RPC blocks accept either whitespace/newlines or commas between members. Commas are useful for compact one-line shapes:

#Type aliases

Glue supports type aliases, which let you define reusable names for existing types.

Notes:

• Aliases declared inside a model are scoped to that model.
• Alias targets can be any valid type expression.

#Constants

Glue supports top-level and model-scoped constants for reusable literal values.

Notes:

• Constant types are inferred from folded values. Optional annotations can be integer primitives, string, or bool.
• Int expressions support +, *, parentheses, and references to int constants.
• String expressions support +, parentheses, and references to string constants.
• Bool expressions support literals and references only.
• Constants can be referenced before they are declared. Cycles are rejected.
• Constants declared inside a model are scoped to that model. Public model constants can be referenced as Model.CONSTANT; nested model constants can be referenced as Outer.Inner.CONSTANT.
• Names should use CONSTANT_CASE. A leading _ marks a constant as private in generated language targets. Private model constants cannot be referenced from outside their owning model as Model._CONSTANT.
• Constants can be used in field defaults and decorator arguments, including @field(alias=...) and @field(proto_tag=...).
• TypeScript, Python, Rust, and Go emit standalone constants. Model-scoped constants are emitted with model-path prefixes. OpenAPI, JSON Schema, and Protobuf only consume folded constant values.

#Models

Models are the foundation of Glue data models. They are defined using the model keyword, followed by the model name and a block of fields.

For example:

Fields can also use anonymous structs for one-off inline shapes:

#Model decorators

Fields can be decorated with the @field decorator, which allows you to specify additional metadata for the field that can be used by code generators.

For Protobuf generation, fields can use @field(proto_tag=<number>) to set stable field tags. If one field in a model has proto_tag, every field in that model must have one.

#Enums

Enums are defined using the enum keyword, followed by the enum name and pipe-separated primitive string values.

For example:

Enums can be nested inside models as well:

#Imports

Glue supports explicit imports, which must appear at the top of the file (before any const, type, model, endpoint, service, or enum declarations).

Notes:

• Import sources are string literals.
• Imports are supported for both local files and HTTP(S) URLs (for URL-based inputs).

#Endpoints

Endpoints are defined using the endpoint keyword, followed by the HTTP method and path, endpoint name, and a block of parameters and responses. They mostly follow what you expect from the OpenAPI specification, with defaults such that typing out endpoints is as frictionless as possible.

For example:

#Services

Services are defined using the service keyword. They are currently used by Protobuf generation.

For example:

#Current limitations

Below is a non-exhaustive list of features that are commonly requested or expected in an IDL like Glue, but are not currently supported. If Glue gains some traction, these will be managed as issues and prioritized accordingly, however for now this acts as a reference for common features you may expect to see in Glue but are not yet implemented:

• Endpoints - proper typing of query/path parameters, authentication/authorization schemes, and some other common API features are not yet supported
• Services - RPC body and returns currently support message types only
• Intersections of types (e.g., type A = B & C)
• Generics (e.g., model Response<T> { data: T })

If you would like to see any of these supported in Glue, please open (or upvote) a feature request in the Glue GitHub repo.