---
# System prepended metadata

title: Story Scratchpad

---

---
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:
```yaml=
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:
```console
$ 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)
    - 

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


```console
# 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 


```yaml=
# values.yml
foo: 14
bar: meek
```

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

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