The description is what schema() puts under the JSON Schema
"description" key – the pydantic-style docstring for a field. It must be
the outermost wrapper in a chain (applied after [n], [expr], opt()/
| and %default%), the same implicit rule %default% already has,
because an outer combinator builds its own schema fragment and would
otherwise discard it. A description added this way replaces, rather than
duplicates, one .refined() wrote automatically.
Arguments
- t
A type, or anything
as_type()accepts.- description
A single string.
Details
A struct's own top-level description is set with struct(.description = )
instead: desc() on a whole struct builds a new, unregistered constructor,
so a ref() to that struct's name would still see the undescribed one.
Multiline descriptions are dedented: blank first and last lines and the
indentation shared by every nonblank line are removed. This makes raw
strings (r"(...)") convenient for long prose. Use describe() to keep
all of a struct's longer descriptions together after its declaration.
Examples
age <- int[1][. > 0] %doc% "Age in years."
schema(age)$description
#> [1] "Age in years."
Person <- struct("Person",
name = chr[1] %doc% "Full name of the person.",
occupation = opt(chr[1]) %doc% "Current job title, or null if unknown."
)
schema(Person)$properties$occupation
#> $type
#> [1] "string" "null"
#>
#> $description
#> [1] "Current job title, or null if unknown."
#>