yaml-reference-specs

This repository is a Gherkin specification suite for the behavior of a modular YAML reference compilation CLI called yaml-reference-cli.

Some of the projects which conform to this specification include:

Project	Compliance status	Link
yaml-reference (Python)	✅	Github | PyPI
yaml-reference-ts (TypeScript)	✅	Github | npm

Tags supported include:

• !reference: "Import" another YAML document from another file into the current node.
  • Shorthand: !reference "path/to/file.yaml" (string scalar used as path)
  • path: Relative path to the YAML file to "import."
  • anchor (optional): Name of an anchor defined in the target file to extract instead of the whole document. Raises an error if the anchor does not exist.
• !reference-all: "Import" all YAML documents using a specific glob pattern into a sequence node.
  • Shorthand: !reference-all "glob/pattern/*.yaml" (string scalar used as glob)
  • glob: Relative glob pattern matching YAML files to "import."
  • anchor (optional): Name of an anchor defined in each matched file to extract instead of the whole document. Raises an error if the anchor does not exist in any matched file.
• !merge: Merge a multiple objects into a single object, using a shallow merge.
• !flatten: "Flatten" a nested sequence of sequences into a one-dimensional sequence.
• !ignore: Suppress a node from the output while preserving any anchors defined within it for use elsewhere in the document.

Purpose

The CLI provides a language-agnostic framework for being able to assess the functionality of client libraries which implement the behavior of resolving YAML files which reference other YAML files (using !reference, !reference-all, !merge, !flatten and !ignore syntax).

• Describe the expected behavior of yaml-reference-cli using human-readable feature files under features/.
• Drive regression tests for the CLI implementation via Go tests that use the godog framework.

The specification has a basic README describing the responsibilities of YAML reference resolution.

Repository layout

• features/ — Gherkin feature files exercising scenarios (input modes, file references, nested references, etc.).
• main.go - CLI entrypoint that runs the godog test suite against a specified yaml-reference-cli implementation supplied with the YAML_REFERENCE_CLI_EXECUTABLE environment variable.

Running the tests

1. Build or make available the yaml-reference-cli CLI binary you want to verify.
2. Set the environment variable YAML_REFERENCE_CLI_EXECUTABLE to the absolute path of that binary.

If you have this project cloned on your machine, you can run the tests from this project directory with:

export YAML_REFERENCE_CLI_EXECUTABLE=/absolute/path/to/yaml-reference-cli
go run .

Alternatively, you can run the test suite by installing it directly with go install and then running the yaml-reference-specs binary:

go install github.com/dsillman2000/yaml-reference-specs@latest
export YAML_REFERENCE_CLI_EXECUTABLE=/absolute/path/to/yaml-reference-cli
yaml-reference-specs

Notes

• Each scenario runs in an isolated temporary directory; file-creation steps place files in that temp directory so tests do not modify your working tree.

Contributing

• Add feature files under features/ to describe new behaviors.
• Add corresponding step implementations or extend existing steps in the test file when needed.

Acknowledgments

Author(s):

• David Sillman dsillman2000@gmail.com
• Ryan Johnson github@ryodine.com