Core Concepts

This page is a collection of core concepts that are essential to understanding the Speakeasy Platform. If you rather skip straight to getting started with platform go here.

Workflows

A workflow is how the Speakeasy Platform defines the process of generating a Target from a Source. A workflow is defined in a workflow.yaml file that is stored in the root of a target repository in the .speakeasy directory. A workflow can be run using the speakeasy run command.

Workflow File Syntax, aka workflow.yaml

A workflow file is a YAML file that defines the steps of a workflow. The file is broken down into the following sections:

This syntax allows for 1:1, 1:N, or N:N mapping of sources to targets. A common use case for 1:N mapping is setting up a monorepo of SDKs. See our monorepo guide for details.

Sources

A Source is one or more OpenAPI documents and Overlays merged together to create a single OpenAPI documents. Defined in the workflow.yaml.

Targets

A Target is a SDK, Terraform or other code generated from sources. Defined in the workflow.yaml.

SDK Generation

The following are concpets specific to SDK generation, a specific type of target. Please see our template-sdk (opens in a new tab) for examples of each of the following concepts.

Generation Config, aka gen.yaml

The generation config file which is used by the Speakeasy CLI to generate a Target. The file is stored in the root of a target repository in the .speakeasy directory. For a full reference of the gen.yaml file see here.

Generation State, aka gen.lock

The generation state file which is used by the Speakeasy CLI to track the state of a generation. It includes a generation uuid, management and feature versions and the list of generated files managed through the Speakeasy CLI. The file is stored in the root of a target repository in the .speakeasy directory.

Releases and Versioning

Speakeasy automatically creates releases and versions for your target artifacts. The release and version are defined in the gen.yaml file. The release and version are used to track the state of a generation and to create a release on the target repository. Releases (opens in a new tab) are used synonmously with Github Releases, our primary means of distributing artifacts. For more information on how to manage versioning see our versioning reference.

Github Workflow

The Github Workflow is a set of Github Actions that are used to automate the generation of a target. The Github Workflow is defined in the .github/workflows directory of a target repository. For a complete reference of the Github Workflow see here. These files can be setup through speakeasy configure github CLI command.

OpenAPI Specification (OAS)

The OpenAPI Specification (OAS) is a widely accepted REST specification for building APIs. An OpenAPI document is a JSON or YAML file that defines the structure of an API. The Speakeasy Platform uses OpenAPI documents as the source for generating SDKs and other code.

Overlay

An Overlay is a JSON or YAML file that is used to modify an OpenAPI document. An Overlay is used to add, remove or modify the structure of an OpenAPI document. Overlays are used to customize the generated code. Overlays that are used to alter an OpenAPI document are defined in the workflow.yaml file.

Linting

Linting is the process of checking an OpenAPI document for errors and style issues. The Speakeasy Platform defines linting rules that are used to validate an OpenAPI document. Linting is done using the speakeasy lint command and linting rules are defined in the lint.yaml file.

Validation

Validation is the process of checking if an OpenAPI document is ready for code generation. The Speakeasy Platform defines validation rules that are used to validate an OpenAPI document. Validation is done using the speakeasy validate command and validation rules are defined in the lint.yaml file. By default the validate CLI command will use the speakeasy-default linting rule set if custom rules are not defined.