describe.md

any.describe()

Returns a plain object representing the schema's rules and properties. May contain the following keys:

• type - the base type of the schema object
• flags - properties that affect the behavior of a validation, e.g. insensitive
• description - data set by .description()
  • multiple calls to .description() will overwrite previous data
• notes - array of data set by .notes()
• tags - array of data set by .tags()
• meta - array of data set by .meta()
• examples - array of data set by .example()
• unit - data set by .unit()
  • multiple calls to .unit() will overwrite previous data
• valids - array of specific values allowed, e.g. by .allow() or .valid()
• invalids - array of specific values disallowed, e.g. by .invalid()
• alternatives - array of valid type definitions
• children - object map of schema descriptions for object types
• rules - array of validation rules to be applied
  • takes the form of plain objects with a name and an optional arg
• label - data set by .label() (for localization)
  • multiple calls to .label() will overwrite previous data

flags

This object may contain the following keys:

• presence - presence setting for this validation as specified by any.required(), any.optional(), any.forbidden
  • one of: optional, required, forbidden, ignore
  • ignore is set on a validation when using any.when()
• allowOnly - if true, only values in the valids array are acceptable; enabled when using .valid()
• allowUnknown - if true, object data may contain keys that don't have corresponding validations; set by object.unknown()
• default - the default value for this key as specified by any.default()
• encoding - the expected encoding of a Binary value as specified by binary.encoding()
• insensitive - if true, string comparisons are case insensitive; set by string.insensitive()
• trim - if true, forces or requires the string to have no whitespace before or after; set by string.trim()
• case - if set, forces or requires the string to be the specified case
  • one of: upper, lower

alternatives

When a value can be more than one base type, it is represented as an alternatives type. The data is considered valid if it passes any of the validations listed in the alternatives array. Dependent values such as those created by using .when() may only be represented as an alternatives type.

children

For Object types, a key-value map where each value is a Joi schema:

{
  type: 'object',
  children: {
    foo: <joi schema>
  }
}

.describe() is applied to children recursively.

rules

When additional validations are added to a base type, they are represented here as a set of objects representing the rule and any arguments it needs. A simple example is { name: 'min', arg: 3 }, which applies the minimum-length rule with a value of 3. Some rules will not have an 'arg' property, for example { name: 'integer' }.

dependent rules

Dependent rules are set up by calling any.when() and take the form of an object like this:

{
  ref: 'ref:key',
  is: <joi schema>,
  then: <joi schema>,
  otherwise: <joi schema>
}

references

There are two kinds of references; a normal ref points to a value in the data being validated, while a context ref points to a value in external context data that's passed to the validate function. Ref strings are separated by . (by default) and prefixed with ref: if they're a normal ref and context: if they're a context ref.

description was moved under flags (which is kinda weird).