# YAML

> Source: https://docs.clonepartner.com/connectors/yaml/

<!-- sources: src/connectors/yaml.ts, src/connectors/file-storage.ts, references/envoy/connectors.md -->

# YAML

The `yaml` connector reads and writes YAML files under a base directory on the local filesystem.

## When to use it

Use `yaml` for lookup tables, fixtures, and small configuration datasets that are convenient to keep as files — for example a directory of mapping records a task reads at startup. For large or continuously growing datasets, prefer a database connector such as [SQLite](/connectors/sqlite/).

## Configuration

| Key | Type | Required | Default | Description |
|---|---|---|---|---|
| `directory` | string | Yes | — | Base directory for YAML files |

## Methods

| Method | Arguments | Returns | Behavior |
|---|---|---|---|
| `read` | `resource` (required), `file` | array | Without `file`: reads every `.yaml`/`.yml` file in the `resource` directory (sorted by filename) into an array. With `file`: reads that single file and returns one object. |
| `write` | `resource` (required), `data` (required) | object | Serializes `data` as YAML to `resource` (appending `.yaml` if no extension), creating parent directories as needed |

## Example

```yaml
name: load_field_mappings
connectors:
  mapping_store:
    type: yaml
steps:
  - name: read_mappings
    type: call_method
    config: |
      { "connector": "mapping_store", "method": "read", "args": { "resource": "mappings" } }
```

The matching `connectors.yaml` entry for CLI runs:

```yaml
mapping_store:
  type: yaml
  config:
    directory: /path/to/data
```

## Behavior notes

- Directory reads buffer all matching files into one array — keep the directory bounded in size.
- Each record from a directory read gains two extra fields: `_file` (the filename) and `_path` (the absolute path). `write` returns the same two fields for the file it created.
- When reading a single file, the connector resolves `resource` (or `resource` + `file`) and tries the exact path, then the path with `.yaml`, then `.yml`, before failing with `YAML file not found`.
- The connector supports file uploads from the connector editor; only `.yaml` and `.yml` files are accepted, and upload paths are validated to stay inside `directory`.

## Related

- [Connectors overview](/connectors/) — all compiled connector types
- [CSV](/connectors/csv/) — the equivalent for flat files
- [Reading and writing data](/building/reading-and-writing-data/) — calling connector methods from steps