Developer API
The types a field can have, and how a value of each is written in a document.
| Type | Holds | Written as | Examples |
|---|---|---|---|
string | Text. | A YAML string. Quote one that would otherwise read as a number, a boolean or a date. |
|
integer | A whole number. | A YAML integer, with no quotes and no fraction. |
|
number | A number that may have a fraction. | A YAML number. |
|
boolean | True or false. | true or false. |
|
path | A file or directory path. | A string, with forward slashes on every platform. What a relative path is relative to is the field's to say. |
|
uri | A URI. | A string holding the whole URI, its scheme included. |
|
type | A schema type itself, rather than a value of one. | A string naming a definition the way a field's type names one: a definition of the same document, or <alias>.<definition> through one of the document's externalSchemas. | |
any | Any value. Nothing about it is checked. | Any YAML value: a scalar, a sequence or a mapping. |
|
enum | One of a fixed set of strings. | One of the strings the field lists as its values, as listed. | |
duration | A length of time. | A string of one or more amounts, each a whole number and a unit, largest unit first: yr years, mo months, wk weeks, d days, h hours, min minutes, s seconds, ms milliseconds. A bare integer is a count of microseconds, which is how a value is written back. |
|
currency | A currency. | A string: the currency's ISO 4217 code, in either case, or its symbol. It is written back as the upper-case code. |
|
currencyValue | An amount of money in a currency. | A string holding the amount and its currency, as a symbol before the amount or a code after it. A bare number is an amount in the default currency, USD unless the application sets another. |
|
date | A calendar date. | A string, YYYY-MM-DD, quoted so that it is read as written. |
|
time | A time of day. | A string, HH:MM:SS with an optional fraction of a second, optionally followed by an offset from UTC or by a space and a timezone's name. |
|
timezone | A timezone. | A string: a name from the IANA timezone database, or a fixed offset from UTC. |
|
datetime | An instant: a date and a time of day in a timezone. | A string in ISO 8601 with its offset from UTC, optionally followed by the timezone's name in square brackets. The offset fixes the instant; the name keeps a conversion right across a daylight-time change. |
|
list | An ordered sequence of values of one type, spelled list[T]. | A YAML sequence, each item written as a value of T is. | |
dict | A mapping from keys of one type to values of another, spelled dict[K, V]. | A YAML mapping, each key written as a value of K is and each value as a value of V is. | |
union | A value of any one of several types, spelled A | B. | A value written as any one of the types named is. |
Forms
The ways a type is put together from others.
list[T]
An ordered sequence of values of the type T.
- Written as
- A YAML sequence. An empty one is
[]. - Declared as
{"type": {"base": "list", "item": "path"}}- Examples
["packages/app", "packages/lib"][]
dict[string, T]
A mapping from a name to a value of the type T.
- Written as
- A YAML mapping. An empty one is
{}. - Declared as
{"type": {"base": "dict", "key": "string", "item": "integer"}}- Examples
{"unit": 12, "integration": 3}{}
enum
One of the strings the field lists as its values.
- Written as
- The string, exactly as the field lists it.
- Declared as
{"type": {"base": "enum", "enumValues": ["public", "hidden", "internal"]}}- Examples
"public""internal"
an optional field
A field a document may leave out. Left out, it takes the default its schema declares, and has no value where the schema declares none. A field that is not optional is required, and a document leaving it out is refused.
- Written as
- The key is left out of the document, or written with a value.
- Declared as
{"type": "duration", "optional": true}- Examples
"30d"