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. |
|
regex | A regular expression, in the dialect of Python's re. Whether it must match a whole value or may be found inside one is the field's to say. | A string holding the pattern as re reads it, quoted where YAML would read it otherwise. A flag is written inline, as (?i) at its start. A pattern that does not compile is refused where it is read. |
|
glob | A path pattern, read the way a line of an ignore file is: it names the files and directories it matches and everything beneath a directory it matches. What a path is relative to is the field's to say. | A string of segments separated by /. A leading / roots it; without one it matches at any depth. Within a segment * matches any run of characters, ? any one and [...] any one of a set, none of them across a /, with case kept; a segment that is exactly ** matches any number of segments. A trailing / is not read. A pattern that names nothing, ** inside a segment and a [ never closed are refused where it is read. |
|
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. It is written back the same way, the definition spelled as its schema declares it. | |
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. |
|
coordinate | A reference to a package, which may pin one version of it or float to whichever is highest where it is looked up. | A string, <namespace>:<name>, followed by @<major>.<minor>.<patch> to pin a version, or by nothing or @latest to float. A version is written whole. |
|
pinnedCoordinate | A reference to one version of a package. | A string, <namespace>:<name>@<major>.<minor>.<patch>. The version is required and written whole; @latest is refused. |
|
floatingCoordinate | A reference to a package that names no one version: whichever is highest where it is looked up. | A string, <namespace>:<name>, optionally followed by @latest, which says the same thing out loud. A version is refused. |
|
versionSegment | Which of a version's three numbers a change moves: the segment a release earns, or the one a new version is counted on by. | major, minor or patch, as <major>.<minor>.<patch> names them. |
|
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. It is written back as the amount, with two decimal places and any more the value carries, then the code: 5.00 USD, 0.0042 USD. |
|
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. |
|
integerRange | A contiguous run of whole numbers. Both ends are in it: 3..9 holds 3 and 9. | A string, the first and last number with .. between them. Either may be left off for a range open at that end. A range whose end comes before its start is refused. One with an end left out of it is written with [ or ( before it and ] or ) after it, a square bracket holding the end beside it and a round one leaving it out: [3..9) holds 3 to 8. A mapping with start, end, startInclusive and endInclusive is read too. |
|
datespan | A run of days. Both ends are in it: 2026-10-01..2026-10-31 holds the 1st and the 31st. | A string, the first and last day as dates with .. between them. Either may be left off for a span open at that end. A span whose last day is before its first is refused. One with an end left out of it is written with [ or ( before it and ] or ) after it, a square bracket holding the end beside it and a round one leaving it out. A mapping with start, end, startInclusive and endInclusive is read too. |
|
timespan | A stretch of the day. The start is in it and the end is not: 09:00:00..17:30:00 holds 09:00 and stops short of 17:30. An end earlier than the start crosses midnight. | A string, the start and end as times with .. between them. Either may be left off for a span open at that end. A span from a time to the same time is refused. One whose ends are held otherwise is written with [ or ( before it and ] or ) after it, a square bracket holding the end beside it and a round one leaving it out: [09:00:00..17:30:00] holds 17:30. A mapping with start, end, startInclusive and endInclusive is read too. |
|
datetimespan | A stretch of time between two instants. The start is in it and the end is not. Each end carries its own timezone. | A string, the start and end as datetimes with .. between them. Either may be left off for a span open at that end. A span whose end is an earlier instant than its start is refused. One whose ends are held otherwise is written with [ or ( before it and ] or ) after it, a square bracket holding the end beside it and a round one leaving it out. A mapping with start, end, startInclusive and endInclusive is read too. |
|
list | An ordered sequence of values of one type, spelled list[T]. | A YAML sequence, each item written as a value of T is. | |
set | Values of one type with no order and no repeats, spelled set[T]. | A YAML sequence, each item written as a value of T is, no value twice. | |
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, each item written as a value of
Tis. An empty one is[]. - Declared as
{"type": {"base": "list", "item": "path"}}- Examples
["packages/app", "packages/lib"][]
set[T]
Values of the type T, each held once, in no order. A value is one scalar, so T is one of string, integer, number, boolean, uri, regex, glob, duration, coordinate, pinnedCoordinate, floatingCoordinate, versionSegment, currency, date, time, timezone and datetime, an enum -- a field's own base: enum or a definition declared as one -- or a definition whose shorthand declares a format, which is written as one string. Any other item type is refused where the schema declares it. A document that writes a value twice is refused where it loads, naming the value.
- Written as
- A YAML sequence, since YAML has no set, each item written as a value of
Tis and none twice. An empty one is[]. The order it is written in means nothing: a tool writing one back puts an enum's values in the order the enum declares them and any other values in sorted order. - Declared as
{"type": {"base": "set", "item": "string"}}- Examples
["lint", "test"][]
dict[K, V]
A mapping from keys of the type K to values of the type V. A key is one scalar, so K is one of string, integer, number, boolean, uri, regex, glob, duration, coordinate, pinnedCoordinate, floatingCoordinate, versionSegment, currency, date, time, timezone and datetime, or an enum: a field's own base: enum or a definition declared as one. Any other key type is refused where the schema declares it. A mapping declared with no key is keyed by strings.
- Written as
- A YAML mapping, each key written as a value of
Kis and each value as a value ofVis. An empty one is{}. - Declared as
{"type": {"base": "dict", "key": "date", "item": "integer"}}- Examples
{"2026-10-01": 12, "2026-10-02": 3}{}
A | B
A value of any one of the types named, here A or B.
- Written as
- A value written as any one of the types named is.
- Declared as
{"type": {"base": "union", "anyOf": ["integer", "date"]}}- Examples
3"2026-10-01"
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"