# File Structure

## Speakeasy Version

The version of the Speakeasy CLI to use to run the workflow. The `speakeasyVersion` field accepts three types of values:

- **`latest`**: The Speakeasy CLI will perform a blue/green attempted upgrade to the latest version of the CLI. If there is a failure in generation, it will always re-run on the last successful version. This is the default and always tries to bring in generator upgrades (for example, to dependencies) where those changes compile, lint successfully, and pass tests successfully.

- **`pinned`**: The Speakeasy CLI will always execute on the installed version and won't attempt to change versions. This can be useful for teams with alternative automation to control the Speakeasy CLI version (for example, using [mise](https://mise.jdx.dev/)).

- **A specific version** (for example, `1.493.1`): The Speakeasy CLI will always run on this exact version. This can be useful for teams with stringent change management procedures. Available versions correspond to [Speakeasy CLI releases](https://github.com/speakeasy-api/speakeasy/releases).

```yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
```

```yaml
workflowVersion: 1.0.0
speakeasyVersion: pinned
```

```yaml
workflowVersion: 1.0.0
speakeasyVersion: 1.493.1
```

## Sources

Sources can be added to a workflow programmatically `speakeasy configure sources` or manually by editing the workflow file.

### Sources

Sources are the inputs to the workflow. A single Source is one or more OpenAPI documents and Overlays that are merged together to create a single OpenAPI document.

```yaml
sources:
  my-source:
    inputs:
      - location: ./openapi.yaml
      - location: ./another-openapi.yaml
      # .... more openapi documents can be added here
    overlays:
      - location: ./overlay.yaml
      - location: ./another-overlay.yaml
      # .... more openapi overlays can be added here
    transformations:
```

### SourceName

Each Source is given a name. In this example the name is `my-source`. This name is used to reference the source in the workflow file.

```yaml
  my-source:
```

### Inputs

Each Source has a list of inputs. Each input is an OpenAPI document or Overlay. The OpenAPI documents and Overlays are merged together to create a single OpenAPI document.

```yaml
    inputs:
      - location: ./openapi.yaml
      - location: ./another-openapi.yaml
      # .... more openapi documents can be added here
```

### Location

Each input has a location. The location is the path to the OpenAPI document or Overlay. The path can be a local reference or a remote URL. If a URL is a used
authentication may need to be provided.

```yaml
      - location: ./openapi.yaml
      - location: ./another-openapi.yaml
      # .... more openapi documents can be added here
```

### Model namespace

When merging multiple OpenAPI documents, schema components with the same name can cause naming conflicts in generated code. The `modelNamespace` option allows each input document to specify a namespace for its schema components, ensuring unique names in the merged output.

```yaml
sources:
  merged-api:
    inputs:
      - location: service-a.yaml
        modelNamespace: serviceA
      - location: service-b.yaml
        modelNamespace: serviceB
```

When `modelNamespace` is specified, the merge process automatically adds `x-speakeasy-name-override` and `x-speakeasy-model-namespace` extensions to each schema component from that input. This preserves the original schema name for serialization while placing the generated model in a separate namespace to avoid conflicts.

For example, if both `service-a.yaml` and `service-b.yaml` define a `Pet` schema:

```yaml