> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataharbor.co/llms.txt
> Use this file to discover all available pages before exploring further.

# YAML Reference

> Complete reference for the current v0.3 Virtual API Configuration.

# YAML Reference

This page documents the current v0.3 Virtual API Configuration that the runtime executes for Data Control and Data Transform behavior.

## Virtual API Configuration Structure

```yaml theme={null}
version: "0.3"
input_format: json
default_output_format: markdown
failOnUnmatchedObject: false
useStrictNameMatching: true

objects:
  customers:
    controls:
      - type: redact
        fields: [ssn, date_of_birth]
      - type: combine
        fields: [first_name, last_name]
        into: full_name
        separator: " "

  _default:
    controls:
      - type: redact
        fields: [createdBy]
```

| Key                       | Type    | Description                                                                                             |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `version`                 | string  | Use `"0.3"` for the current controls pipeline                                                           |
| `input_format`            | string  | Optional. Expected upstream format. Values: `json`, `csv`, `yaml`, `markdown`. Auto-detected if omitted |
| `default_output_format`   | string  | Optional. Desired response format. Values: `json`, `markdown`, `csv`, `yaml`. Returns JSON if omitted   |
| `objects`                 | mapping | Named object definitions keyed by route segment                                                         |
| `objects.<name>.controls` | array   | Ordered list of control blocks for that object                                                          |
| `objects._default`        | object  | Catch-all object definition used only when no named object matches                                      |
| `failOnUnmatchedObject`   | boolean | Fail the request if no object definition matches                                                        |
| `useStrictNameMatching`   | boolean | When `false`, field matching is case-insensitive                                                        |

## Object Definitions

Object definition keys are matched against the last path segment, then the second-to-last path segment of the request URL.

```yaml theme={null}
version: "0.3"
objects:
  addresses:
    controls:
      - type: redact
        fields: [name]
  users:
    controls:
      - type: redact
        fields: [metadata.tag]
  _default:
    controls:
      - type: redact
        fields: [description]
```

`_default` is a fallback. It is used only when no named object matches.

## Common Control Options

| Option          | Applies to            | Required | Description                                                          |
| --------------- | --------------------- | -------- | -------------------------------------------------------------------- |
| `fields`        | All controls          | Yes      | Field paths to operate on                                            |
| `required`      | All controls          | No       | When `true`, missing referenced fields fail instead of being skipped |
| `into`          | `combine`, `coalesce` | Yes      | Target field for the transformed value                               |
| `separator`     | `combine`             | No       | Separator inserted between combined string values. Default: `""`     |
| `remove_source` | `combine`, `coalesce` | No       | Remove source fields after the transform completes. Default: `false` |

## Control Blocks

Control blocks live inside `objects.<objectName>.controls`, not in a top-level `controls` array.

### Redact

```yaml theme={null}
- type: redact
  fields:
    - field_name
    - nested.field
    - "[array].field"
  required: false
```

### Tokenize

```yaml theme={null}
- type: tokenize
  fields:
    - field_name
  required: false
```

### Anonymize

```yaml theme={null}
- type: anonymize
  fields:
    - field_name
  required: false
```

### Mask

```yaml theme={null}
- type: mask
  fields:
    - field_name
  required: false
```

### Hash

```yaml theme={null}
- type: hash
  fields:
    - field_name
  required: false
```

### Allow

```yaml theme={null}
- type: allow
  fields:
    - field_name
  required: false
```

### Combine

```yaml theme={null}
- type: combine
  fields:
    - first_field
    - second_field
  into: new_field_name
  separator: ""
  remove_source: false
  required: false
```

### Coalesce

```yaml theme={null}
- type: coalesce
  fields:
    - primary_field
    - fallback_field
  into: new_field_name
  remove_source: false
  required: false
```

## Path Syntax

Use dot notation in v0.3:

```yaml theme={null}
fields:
  - metadata.tag
  - billing.address.street
  - "[addresses].city"
  - "[orders].[items].sku"
```

Slash notation like `metadata/tag` is not supported in v0.3.

## Execution Notes

* Controls execute top-to-bottom.
* Filter controls target scalar values only: strings, numbers, and booleans.
* If the matched payload is a root array, controls apply to each object element automatically.
* When you use nested transform paths, every entry in `fields` plus `into` must share the same parent path.
* `combine` fails if `into` already exists. `coalesce` also fails if `into` already exists.