---
title: "Yaml@1"
description: "Yaml@1 — data in YAML files, and the provider behind every definition in the project file itself"
url: "https://docs.justcat.it/reference/data-sources/providers/yaml-1/"
---
# Yaml@1


## Connects to

YAML files — the project file among them. `Yaml@1` is the provider behind the [implicit list](https://docs.justcat.it/reference/project-file/lists/ "Lists"): every definition written under `Data sources:`, `Queries:` or `Tests:` in the project file is read by this provider, exactly as definitions in a separate YAML file would be. Its primary purpose is loading definitions; testing data in YAML files is the second use.

## Example

A YAML file with data to test, registered as a data source with the friendly name `DepartmentData`:


**Properties**



Name
: DepartmentData

Provider
: Yaml@1

Technology
: Yaml

Connection string
: ./DepartmentData.yaml





**YAML**


```yaml
Data sources:
- Name: DepartmentData
  Provider: Yaml@1
  Technology: Yaml
  Connection string: ./DepartmentData.yaml
```




A test against it names the node to read in `Query`:

```yaml
Tests:
- Name: Check number of generated records
  Data source: DepartmentData
  Query: /Departments # path to the list, with slashes
  Expectation: set row count
  Expected row count: 10
```

### Test definitions

Tests and data sources can be defined in the [project file](https://docs.justcat.it/reference/project-file/introduction/ "Project files") alone. As the project file grows, it can be split: CAT then loads tests from other YAML files through `Yaml@1`.

```yaml
Get list of tests from:
- Provider: Yaml@1
  Name: Smoke tests # a list's name is optional, useful for troubleshooting
  Connection string: ./SmokeTests.yaml # relative paths are resolved against the directory of the project file
  Query: /SmokeTests
- Provider: Yaml@1
  Name: Integrity checks
  Connection string: ./IntegrityChecks.yaml
  Query: /IntegrationChecks
# - ...  abbreviated
```

The same technique splits tests inside the project file: name the project file itself in `Connection string` and point `Query` at a node of your own.

### Hardcoded data

Data to compare against — the expected result of a query on a relational data source, say — can be hardcoded in the project file or any other YAML file and served by `Yaml@1`:

```yaml
Data sources:
- Name: ExpectedData
  Provider: Yaml@1
  Connection string: ./MyCatProject.cat.yaml # the project file, or any other file holding the data

Tests:
- Name:
  Description: Sample dataset contains problems for two invoices, the test should identify them
  First Data Source: Accounting
  First Query: SELECT InvoiceID FROM fn_GetProblematicInvoices();
  Second Data Source: ExpectedData
  Second Query: /Expected data

Expected data:
- InvoiceID: 202000483490
- InvoiceID: 202330409494
```

### JSON inside YAML

YAML is a superset of JSON: JSON written inside a YAML file is valid YAML. JSON is the more concise way of writing hardcoded data and is easier to generate.

```yaml
# an empty array:
Expected Data: []
# an array with data:
Other Data: ["Red", "Green", "Blue"]
# an object in JSON syntax:
Expected Employee: { "First name": "Tereza", "Last name": "Černá", "Department": "Testing" }
```

## Connection string

The path to the YAML file. A relative path is resolved against the directory of the project file. The key is also accepted as `File path`; when neither is present the provider falls back to `Data.yaml` — see [Connection string](https://docs.justcat.it/reference/data-sources/properties/#connection-string "Data source properties") on the data source properties page.

## Settings

None beyond the file path.

## Query

A node path: the keys leading from the root of the document to the list to read, separated by slashes, starting with `/` for the document root — `/Tests`, `/Data sources`, `/Structure/Departments`. The node the path ends at must be a YAML list; every item of the list becomes one row, its keys the columns. `Yaml@1` does not accept SQL.

To read the departments out of this file

```yaml
Date: 2023-05-02
Company: ABC
Structure:
    Departments:
    - Name: Sales
    - Name: Marketing
    - Name: HR
```

the `Query` is `/Structure/Departments`: CAT walks the list and returns a result set with one column (`Name`) and three rows.

## Prerequisites

None. Nothing to install; Windows and Linux alike.

## Limitations

`Yaml@1` reads one list at a time. A row is built from the keys of one item of that list, and nothing else: values from the item's parents or from nested mappings and lists inside the item are not combined into the row. A list directly at the root of the document (a file that starts with `- `) cannot be read — the list must sit under a key. The items of the list must be mappings (`- Name: Sales`), not bare scalars (`- Sales`).

## Serving test and data source definitions

`Yaml@1` is the provider that serves [lists](https://docs.justcat.it/reference/project-file/lists/ "Lists") of definitions from the project file itself, and it serves them from any other YAML file the same way: a node path whose list items carry the keys of a [test](https://docs.justcat.it/reference/tests/properties/ "Test properties"), [data source](https://docs.justcat.it/reference/data-sources/properties/ "Data source properties") or [query](https://docs.justcat.it/reference/queries/properties/ "Query properties") definition. It is also the only provider whose lists can be written back to — CAT Studio saves edited definitions into a YAML-backed list, the implicit one in the project file included; lists served by any other provider are read-only to CAT.

## Related

* [Technologies](https://docs.justcat.it/reference/data-sources/technologies/ "Technologies").
* [Lists — implicit and explicit](https://docs.justcat.it/reference/project-file/lists/ "Lists") — how the project file and external YAML files feed definitions through `Yaml@1`.
* [Project file](https://docs.justcat.it/reference/project-file/introduction/ "Project files").