Schema node can be annotated to allow any type

[pivotaljohn]

Narrative:
As a configuration author
I want to ensure a field exists in my data values, regardless of type
so that tooling can rely on its existence, and we can support multi-typed items like "intOrString"s

---

🟢 Any Type Allowed

Given a document, array item, or map item is annotated with @schema/type any=True
And the value for that node is any value (including null)
When I run ytt that includes that schema
Then that value passes validation

#! schema.yml
#@schema/match data_values=True
---
#@schema/type any=True
foo: "any value"
bar:
#@schema/type any=True
- 0
#@schema/type any=True
baz: {}

#! dv.yml
#@data/values
---
foo: 13.5
bar: ["", 0, True]
baz: ~

#! template.yml
#@ load("@ytt:data", "data")
---
foo: #@ data.values.foo
bar: #@ data.values.bar
baz: #@ data.values.baz

Then the result of ytt -f schema.yml -f dv.yml -f template.yml --enable-experiment-schema is:

---
foo: 13.5
bar: ["", 0, True]
baz: null

(without an error)

🟢 Any Type Not Allowed

Given a document, array item, or map item is annotated with @schema/type any=False
When I run ytt that includes that schema
Then (it should behave exactly as if the annotation were not present)

#! schema.yml

#@schema/match data_values=True
---
#@schema/type any=False
foo: 42

#! dv.yml
#@data/values
---
foo: 0

(success)

#! dv.yml
#@data/values
---
foo: True

(error)

🔴 Keyword argument(s) other than any specified

Given a document, array item, or map item is annotated with @schema/type with any other keyword argument (kwarg) except any=[True,False]
When I run ytt that includes that schema
Then I see an error message which includes line numbers to help point to where the error is, alongside a helpful message that describes the problem and how to fix it (unknown kwarg, fix by removing or using the only currently supported on, any)

#! schema.yml
#@schema/match data_values=True
---
#@schema/type unknown_kwarg=1
foo: 42

  Document on line schema.yml:3:
    Map item (key 'foo') on line schema.yml:5:
      Unknown 'schema/type' annotation keyword argument 'unknown_kwarg'. Supported kwargs are 'any'

🔴 Values for any other than a boolean

Given a document, array item, or map item is annotated with @schema/type with any keyword argument with value except [True,False]
When I run ytt that includes that schema
Then I see an error message which includes line numbers to help point to where the error is, alongside a helpful message that describes the problem and how to fix it (any kwarg must be a boolean, fix by setting to True or False)

#! schema.yml
#@schema/match data_values=True
---
#@schema/type any=3.5
foo: 0

  Document on line schema.yml:3:
    Map item (key 'foo') on line schema.yml:5:
      Expected 'schema/type' annotation keyword argument 'any' to be a boolean, but was '3.5'.

📚 Documentation: Navigation

Given I want to learn how to mark a node in a schema as accepting any type of value
When I navigate through ytt documentation
Then I intuitively find the reference that describes the @schema/type annotation.

🔍 Documentation: Search

Given I want to learn how to mark a node in a schema as accepting any type of value
When I search for the most obvious search terms: "schema", "any", "types"
Then I see results that when I click on them take me to the most relevant reference for this annotation.

---

Implementation Notes

• it would be lovely if we could replace the AnySchema type with a DocumentSchema that contains a Document node of type Any

---

Notes
Adding the any annotation does not relax the constraints of the schema; they must continue to be well-formed. Arrays must have a single item with a type, and nulls aren't permitted as values. (after talking this over with @gcheadle-vmware, we saw no reason to maintain a this limitation, and saw value in allowing it)

[pivotaljohn]

Released: https://github.com/vmware-tanzu/carvel-ytt/releases/tag/v0.34.0