Documentation for version v0.40.0 is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.
Data Values Schema Reference
This reference covers details of Data Values Schema: supported types and annotations.
For an introduction of Data Values, see Using Data Values.
For details on writing Schema, see Writing Schema.
The Schema Document ¶
Schema is written in YAML.
#@data/values-schema --- ...
- the document must be annotated as
- each item in the document declares a Data Value (i.e. an item in the data.values struct).
- (optionally) types and default values can be explicitly specified through annotations.
- a file containing a Schema document must not contain any other kind of document.
Multiple Schema Documents ¶
In some cases, it is useful to separate Schema into multiple YAML documents (typically in separate files).
When doing so, it becomes relevant to know that Schema Documents are
- they merge in the same order as overlays, and
- one controls that merge via overlay annotations.
Data Value Declarations ¶
Each item in a Schema Document declares a Data Value.
A Data Value declaration has three (3) parts:
- the name of the data value,
- its default value, and
- the type of the value.
A Data Value is referred to by its name (aka “key” or “attribute”).
A Data Value name must be a string.
When using multi-word names, it is recommended to employ snake-case (e.g.
database_connection). This principally because:
- the underlying programming language in
ytt— Starlark — is Pythonic in which identifiers are snake-cased, by convention
- as in most modern languages, the dash (i.e.
-) is not allowed for identifier names in Starlark (allow characters are: Unicode letters, decimal digits, and underscores
_, per the Starlark spec).
Where disallowed characters in names cannot be avoided, references will need to employ either:
- the Starlark built-in
secure: #@ getattr(data.values, "db-conn").secure
- (as of v0.31.0) or index notation:
secure: #@ data.values["db-conn"].secure
Default Values ¶
The default value for a Data Value is specified in schema, directly:
- the default value for a scalar is the value given;
- the default value for a map are all of the items specified in the schema (with their defaults, recursively);
- the default value for an array is an empty list (i.e.
- the default value for an item in an array are the contents of the item specified in schema (with their defaults, recursively).
Default values can be overridden using the @schema/default annotation.
Defaults for Scalars ¶
When a scalar value is specified, the default is merely that value.
#@data/values-schema --- system_domain: "" load_balancer: enabled: true databases: - name: "" adapter: postgresql
""(i.e. an empty string), by default.
databases.adapteris the string
"postgres", by default.
Defaults for Mappings ¶
The set of items of a map are its default: any missing item will be automatically added with its defaults.
#@data/values-schema --- load_balancer: enabled: true static_ip: ""
load_balancer were omitted from supplied Data Values, entirely, it would default to:
load_balancer is partially specified…
#@data/values --- load_balancer: static_ip: 10.0.101.1
the missing item (here,
enabled) is defaulted:
Defaults for Arrays ¶
The default value for all arrays is, by default, an empty array.
This is different from all other types where the default value is literally what is specified in schema. For arrays, it is
 (i.e. an empty array).
This means that the value given for the element is only used to infer the type of the array’s elements.
#@data/values-schema --- app_domains: - "" databases: - name: "" adapter: postgresql host: "" port: 5432 user: admin secretRef: name: ""
by default. Each item in the array must be a string.
by default. Each item in the array must be a map. When an item is added to the array:
- its key must be one of those named in this schema:
- if it lacks any of the six keys, they will be added with their default values.
- its key must be one of those named in this schema:
The default value of an array itself can be overridden using the @schema/default annotation.
ytt Schema can infer the type of the Data Value from the following…
Types of Scalars ¶
ytt recognizes the following scalar types:
- strings — e.g.
- integers — e.g.
- booleans —
false(and when not strict,
- floats — e.g.
Types of Maps ¶
A map is a collection of map items, each a key/value pair.
The schema of a map is inferred from that collection. Each item declares a nested Data Value of the type inferred from the given map item’s value.
load_balancer: enabled: true static_ip: ""
load_balancerhas a type of a map that has two items:
- one item has a key
enabledwhose type is a boolean.
- the other item has a key of
static_ipand is a string.
- one item has a key
Types of Arrays ¶
An array is a sequence of array items.
The schema of an array must contain exactly one (1) item. The type inferred from that item becomes the type of all items in that array. That is, arrays in
ytt are homogenous.
app_domains: - ""
app_domainshas a type of an array. Each element in that array will be a string.
- note that the default value for
app_domainsis an empty list as explained in Defaults for Arrays, above.
null Type ¶
null value means the absence of a value.
ytt schema, a default value is not permitted to be
null (with one exception described in
any Type, below). This is because no useful type can be inferred from the value
Instead, one provides a non-null default value and annotates the Data Value as “nullable”.
This results in a Data Value whose default value is
null, but when set to a non-null value has an explicit type. See
@schema/nullable for details.
any Type ¶
In certain cases, it may be necessary to relax all restrictions on the type or shape of a Data Value:
- the Data Value is a pass-through, where template(s) using it merely insert its value, but care not about the actual contents;
- a heterogeneous array is required;
- there are multiple possible allowed types for a given Data Value.
This is done by annotating the Data Value as having “any” type. See
@schema/type for details.
ytt determines the type of each Data Value by inferring it from the value specified in the schema file (as described in Types, above). Currently, there is no way to explicitly set the type of a Data Value.
Configuration Authors can explicit specify the type of a Data Value in two cases that are not inferrable:
- overriding the default value (via the @schema/default annotation);
- also allowing null (via the @schema/nullable annotation);
- allowing any type (via the @schema/type annotation).
Overrides the default value for the annotated node.
default_value— the value to set as the default for the annotated node.
- this value must be of the same type as the value given on the node.
(as of v0.38.0)
Example 1: Default value for an array of scalars
#@data/values-schema --- #@schema/default ["apps.example.com", "gateway.example.com"] app_domains: - ""
… yields the default:
app_domains: - apps.example.com - gateway.example.com
Example 2: Default value for an array of maps
When specifying values for an array of maps, it can quickly become unwieldy to keep on a single line.
To handle these situations, enclose those values in a Fragment function and invoke that function as the value for
#! For best results, declare functions *before* the schema document. #@ def default_dbs(): - name: core host: coredb user: app1 - name: audit host: metrics.svc.local user: observer #@ end #@data/values-schema --- #@schema/default default_dbs() databases: - name: "" adapter: postgresql host: "" port: 5432 user: admin secretRef: name: ""
Yields the default:
databases: - name: core adapter: postgresql host: coredb port: 5432 user: app1 secretRef: name: "" - name: audit adapter: postgresql host: metrics.svc.local port: 5432 user: observer secretRef: name: ""
Note: as the comment in the example schema indicates, it is best to declare the function prior to starting the schema document itself (see https://github.com/vmware-tanzu/carvel-ytt/issues/526 for details).
Extends the type of the Data Value to also allow
null and sets the default value to be
Unset value for strings
The preferred way to express “unset value” for a string-type is not to mark it as “nullable” but to provide the empty value:
"". Empty values in Starlark are falsey (details in the Starlark Spec > Booleans).
When empty string is a useful/valid value for a given Data Value, then marking it as “nullable” is appropriate. In this case, one must take care to explicitly check if that Data Value is not
Example: Nullable map
#@data/values-schema --- #@schema/nullable aws: username: admin password: "1234" name: ""
Without other Data Value settings,
null by default:
aws: null name: ""
However, if a Data Value is set:
$ ytt ... --data-value aws.username=sa ...
That effectively sets
aws to be non-null:
username is set to the custom value and
password is defaulted.
aws: username: sa password: "1234" name: ""
Explicitly configures the type of the annotated node. Currently, the only supported configuration is whether to allow the “any” type or not.
bool) — whether or not any and all types are permitted on this node and its children.
The annotated node and its nested children are not checked by schema, and has no schema defaulting behavior.
However, (as of v0.39.0) any nested
@schema annotation that alters type or value of a child would conflict with the fragment’s “any” type, resulting in an error.
Otherwise, the annotated node and its children are simply passed-through as a data value.
Example: Using any=True to avoid schema restrictions on an array
#@data/values-schema --- #@schema/type any=True app_domains: - "carvel.dev" - 8080
Example: Error case when setting schema within an any type fragment
#@data/values-schema --- #@schema/type any=True app_domains: #@schema/default "localhost" #@schema/type any=False - "carvel.dev"
ytt: Error: Invalid schema ============== Schema was specified within an "any type" fragment schema.yml: | 5 | #@schema/default "localhost" 6 | #@schema/type any=False 7 | - "carvel.dev" | = found: @schema/type, @schema/default annotation(s) = expected: no '@schema/...' on nodes within a node annotated '@schema/type any=True'
(Help improve our docs: edit this page on GitHub)