Core Concepts

The core concepts explained on this page are essential to understanding the Speakeasy platform. To skip to getting started with the 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 stored in the root of the target repository in the .speakeasy directory. A workflow is run using the speakeasy run command.

Workflow File Syntax

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

workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  my-source:
    inputs:
      - location: ./openapi.yaml
      - location: ./overlay.yaml
      - location: ./another-openapi.yaml
      - location: ./another-overlay.yaml
      # .... more openapi documents and overlays can be added here
  # more inputs can be added here through `speakeasy configure sources` command
  # ....
  # ....
targets:
  python-sdk:
    target: python
    source: my-source
  # more inputs can be added here through `speakeasy configure targets` command
  # ....
  # ....

The workflow file 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 to create a single OpenAPI document. Sources are defined in the workflow.yaml file.

Targets

A target is an SDK, Terraform provider, or other code generated from sources. Sources are defined in the workflow.yaml file.

SDK Generation

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

The Generation Config File

The Speakeasy CLI uses the gen.yaml generation config file to generate a target. The gen.yaml file is stored in the root of a target repository in the .speakeasy directory. For a full reference of the gen.yaml file, see the reference doc.

The Generation State File

The Speakeasy CLI uses the gen.lock generation state file to track the state of a generation. The gen.lock file 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 and used to track the state of a generation and create a release on the target repository. Releases (opens in a new tab) are used synonymously with GitHub Releases, the primary way Speakeasy distributes artifacts. For more information on how to manage versioning, see our versioning reference.

GitHub Workflow

The GitHub Workflow is a set of GitHub actions 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 the documentation. These files can be set up using the 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 used to add, remove, or modify parts of an OpenAPI document and customize the generated code. Overlays 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 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 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 ruleset if custom rules are not defined.