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
• any
• bool

#Compound types

• model (a structured type with named fields)
• enum (enumeration of string values)
• T[] (an array/list of type T)
• Record<T, U> (a map/dictionary type with keys of type T and values of type U)
• endpoint (an API endpoint definition with method, path, parameters, and responses)

#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:

#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.

#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 model, endpoint, 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:

#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
• Type aliasing (e.g., type UserID = string)
• 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.