Format Overview

This page overviews spec format

Basics

Spec format is based on YAML. Each spec file is a YAML file. In many aspects spec format resembles to OpenAPI. Main purpose of spec is to provide more compact (then OpenAPI) way of defining API and also limit some capabilities of OpenAPI.

Spec Structure

Here's an example of simplest spec:

spec: 2.1                    #  Meta information
name: example
version: 1

http:                        #  HTTP Endpoints
  sample:                    #  API
    get_sample:              #  Endpoint
      endpoint: GET /sample
      response:
        ok: Sample

models:                      #  Models
  Sample:                    #  Model name
    object:                  #  This model is object model
      field1: string
      field2: int

Spec YAML file consists of following sections:

• Meta information

• HTTP

• Models

Meta Information

Meta information is presented in form for keys at the top level of the YAML file. In the example above spec, name and version are meta information fields.

Here's the list of supported meta information fields:

Name	Description
spec	Version of spec format, current latest format is 2.1
name	Name of the specification
version	Version of the specification

HTTP Endpoints

HTTP endpoints are defined in http section of the spec. Endpoints are grouped in APIs. APIs are used in code generation and should bundle together related endpoints. Read more about endpoints in the HTTP Endpoints section.

Models

Models are defined in models section of the spec. This section allows to define custom user types, including object models, enums, and tagged unions. These user-defined models can be used in endpoints where needed by their names.

Read more about endpoints in the Models section.