---
# System prepended metadata

title: Using Schema
tags: [schema, ytt]

---

---
title: Using Schema
tags: ytt,schema
---

# Using Schema

ytt v0.37.0 (what ever the playground is at this point 1/21/21)
this is before some of the any type bugs were fixed???

- `null` values in a schema or schema overlays are not allowed unless the type is `any`
    - even if a data value is `nullable` in the base schema, 
    - and a schema overlay sets that `nullable` data value to null, 
    - then the schema overlay will not be a valid schema.

- Common ways that you can invoke a schema overlay
  - another schema file in the same library
  - another schema file in a different library with `@library/ref`
  - yaml fragment provided to a library via `library.with_data_values_schema()`
     
- Facts about schema overlays
  - add keys with `@overlay/match missing_ok=True`
  - `@schema` annotations are processed during the individual checks of the schema files, 
  - but are not carried over during the overlay, so they have no lasting effects.
  - values can not be null, even if annotated with `@schema/type any=True`
  - `@schema/type any=True`
    - when the value is `null` ANYTHING can be overlayed into this value from a schema overlay

# `@schema` annotations

### `@schema/nullable`
- allows null value and sets null as default value


### `@schema/type`
- sets type of value for the node it annotates
- `any=True`
    - removes schema checking from this node's value, recursively
    - short circuits schema processing, so any value that is there will be in the data values
    - errors when other schema annotations are nested.
    - good way to add keys in data values under a data value that is any type

### `@schema/default`
- sets the default value for the node it annotates
- accepts a starlark value
- value can be defined by the result of a function
- predominantly used over map items that contain arrays, since arrays by default are empty (remember that arrays append items by default)
- cannot be `None` or `null` unless combined with `@schema/nullable` (which is then redundant)
- otherwise when used with `@schema/nullable`, the `@schema/default` value is the default value

### Documentation annotations
- `@schema/title`
- `@schema/description`
- `@schema/examples`
- `@schema/depreciated`


# Open Questions

- Q: when overlaying Schema, is it possible to redefine a data value (i.e. replace from the "right" over the "left"?)
- Q: if someone cannot edit the schema or write a schema overlay, but they want to provide a new data value, what are their options?