---
title: Story Scratchpad
---

## Proto Personas and Identified Needs

As a Package Consumer
I want to provide my Data Values in plain YAML
So that I don't have to be concerned about the underlying template engine when installing a package.

As a Tools Integrator
I want to be able to invoke `ytt`, passing in plain YAML for Data Values
So that my users (e.g. the Package Author) can abstract away implementation detail of which templating engine they use from _their_ users (e.g. Package Consumer).

As a Configuration Consumer (`ytt` user using someone else's library)
I want to provide my Data Values in plain YAML
So that I don't have to understand fancy `ytt` features like overlays to just use `ytt`.

### Sample Interactions

Package Consumer:

apiVersion: install.package.carvel.dev/v1alpha1
kind: InstalledPackage
metadata:
  name: fluent-bit
  namespace: my-ns
spec:
  serviceAccountName: fluent-bit-sa
  packageRef:
    publicName: fluent-bit
    version: 1.5.3
  values:
  - secretRef:
      name: fluent-bit-values
---
apiVersion: ...
kind: Secret
metadata:
  name: fluent-bit-values
data:
  

Configuration Consumer and Tool Integration:

$ ytt -f config/ --data-values-file staging/values.yml

## Stories

### Core Functionality

Accept DVs in a single plain YAML file/document as the only source of Data Values
- Validate that scalar value only within yaml doc works
- Validate empty file does nothing
- Document presence of flag (keeping Data Values Overlays as the prominent feature, for now)
(see examples in proposal)

Accept DVs in multiple plain YAML files/documents that merge into the only source of Data Values
- multiple yaml docs across multiple files
- multiple yaml docs in a single file
- Validate that plain YAML overwrites & appends data values provided in the config file
- Document that flag can be used multiple times and can contain multiple documents
(see examples in proposal)

Accept DVs from a plain YAML file in a library containing Data Values Overlays
- Document the library reference notation

Accept DVs from a plain YAML file targeting a private library

Reject Data Values Overlays when supplied as a Data Values File
- Create additional page specifically calling out the difference between Data Values Overlays and Data Values File (see proposal for details)

Support filename rename notation (like `--file` does)
- Document

Assumptions:
- most of the heavy lifting is done with very permissive overlays.
- all of the interesting plumbing there are examples in the other `--data-value...` flag implementations.

### Updates to Documentation

#### Minimal
_(focused on _only_ Tools Integrator proto-persona)_

- add section to "data values" page that describes this flag. (S)

#### Replacing @data/values with `--data-values-file` as _the_ way to provide Data Values

_(lots of stories around moving Data Values Overlays stuff into an "advanced" section, etc.)_

### Updates to the Playground

- Update the Playground to support --data-values (provide an editor to accept this file)
- Update bulk-in/bulk-out to be able to include flags in the payload (nominally, to allow --data-values-files)
- Q: how does one include a "--data-values-file" via a gist?

If we don't update the playground, we risk users getting confused by the docs saying one thing, and the examples looking differently.
- factors:
- most users begin learning `ytt` through the examples (making it more probable that new users will have to reconcile the diff between docs and playground)
-

ytt -f config/ --data-values-file @libby:values.yml --data-values-file @other_lib:values.yml

# Currently, all files are treated a plain YAML.
$ ytt -f contour.yml -f plain-yaml-dvs.yml    

# Provide Data Values using the --files flag (like all other files)
$ ytt -f contour.yml -f my-template.yml -f plain-yaml-dvs.ytt.data.yml
$ ytt -f contour.yml -f my-template.yml -f plain-yaml-dvs.yml --file-mark "plain-yaml-dvs.yml:type=plain-yaml-data-values"


# Currently proposed:
$ ytt -f contour.yml -f my-template.yml --data-values-file plain-yaml-dvs.yml

Why not use file-marks?
- this would result in two kinds of Data Values files supplied in a `--files` parameter
- @data/values (overlays)
- evaluate in the order provided through the `-f` flag
- _appends_ its array items to any existing array
- potentially result in overlay errors
- (plain YAML Data Values file)
- evaluate in the order provided through the `-f` flag
- _replaces_ any existing array value with its own
-
- by using a separate flag, `--data-values-file` — this input

# values.yml
foo: 14
bar: meek

$ ytt -f config/ --data-value-yaml foo+=14 --data-value-yaml bar+=meek

$ ytt -f config/ --data-values-file values.yml