Contract Shape
A .lirath file declares exactly one service. A service can advertise one or more versions:
The first version is emitted as service.version; all versions are emitted as service.versions.
service ServiceName v1, v2 { auth bearer auth apiKey XApiKey header type MessageName { field: Type, other: Type } type Validated { email: String required max_length 255 format email } type UserDTO = vti User GET "/path/{param}" method_name(param: Type) -> ReturnType POST "/path" create(input: RequestType) body RequestType -> 201 ReturnType error 400 ErrorType POST "/examples" example_method(input: RequestType) -> 201 ReturnType example request "{\"name\":\"Ada\"}" response "{\"id\":\"u1\"}" GET "/private/{param}" private_method(param: Type) -> ReturnType auth bearer @deprecated GET "/old/{param}" old_method(param: Type) -> ReturnType}Built-in Types
The v0.4 compiler recognizes these scalar type names:
All other type references must name a message type or VTI-backed type alias declared in the same service.
- String
- Uuid
- Bool
- Int
- Float
- Bytes
VTI Type Aliases
Use type LocalName = vti EntityName to reuse an entity type from a VTI package. The compiler validates those aliases when a VTI JSON file is supplied:
Without --vti, VTI aliases are reported as validation errors. Unknown VTI entity names are also reported as validation errors.
lirath check api.lirath --vti family.vti.jsonlirath emit api.lirath --vti family.vti.jsonDeprecation
Place @deprecated immediately before a method:
Contract JSON emits "deprecated": true for that method. Non-deprecated methods emit "deprecated": false.
Auth
Declare service-wide auth at service scope:
Declare method auth after the response clauses:
Supported auth schemes are:
- auth bearer
- auth apiKey NAME header
- auth apiKey NAME query
- auth apiKey NAME cookie
service Billing v1 { auth bearer auth apiKey XApiKey header}Examples
Attach one request and/or response example to a method:
Examples are stored as deterministic strings in contract JSON under the method's example object. OpenAPI 3.1 emits request examples under the JSON request body media type and response examples under the primary response media type.
Method Bodies, Status Codes, and Errors
The v0.2 method form remains valid:
It is interpreted as a 200 JSON response. The first non-path parameter is also treated as a JSON request body for SDK and contract emission, preserving the v0.2 SDK behavior.
v0.3+ methods can declare the request body type explicitly and attach HTTP status codes:
Field Validation
Field validation rules are written after the field type:
Contract JSON emits these under each field's validation object. OpenAPI 3.1 maps them to schema required, maxLength, and format.
- required
- max_length N
- format NAME
type CreateUser { email: String required max_length 255 format email, display_name: String max_length 80}Validation
Validation reports diagnostics as file:line:col: message.
- referenced field, parameter, and return types must exist
- VTI aliases require a supplied VTI JSON package
- VTI entity references must exist in the supplied package
- method names must be unique
- every {name} segment in a path must have a method parameter named name
- type names must be unique
- method response and error status codes must be in the HTTP range 100..599
- auth schemes must be bearer or apiKey
Download
Lirath is in active development and has no public downloads or releases yet.
No public download artifacts are available yet for this language.
Looking for everything in one place? See the downloads index.