@versionzero/schema / Schema
Class: Schema
Defined in: src/schema.js:33
Schema - allows the definition of structure and rules for data
Essentially acts as a fluent builder; must be compiled by SchemaCompiler for use.
Constructors
Constructor
new Schema(
base?,options?,metadata?):Schema
Defined in: src/schema.js:64
Construct a Schema.
Pass a string name of a registered schema to resolve as the base, or pass a schema-shaped object to extend.
Prefer the fluent setters over passing in options/metadata or attributes.
Parameters
| Parameter | Type | Description |
|---|---|---|
base? | string | ISchema | SchemaData | schema type or base to extend |
options? | any | schema options (also supports "attribute" shorthand syntax, but prefer being explicit) |
metadata? | ISchemaMetadata | schema metadata |
Returns
Schema
Accessors
base
Get Signature
get base():
string|undefined
Defined in: src/schema.js:98
Name of a schema registered in SchemaResolver that this schema extends
Returns
string | undefined
properties
Get Signature
get properties():
SchemaProperties
Defined in: src/schema.js:112
Properties are named child schemas.
Use the property setter rather than direct access to ensure data consistency.
Returns
SchemaProperties
handlers
Get Signature
get handlers():
SchemaHandlers
Defined in: src/schema.js:123
Handlers are grouped lists of value processors.
Assign using the individual value processor setters.
Returns
SchemaHandlers
options
Get Signature
get options():
ISchemaOptions
Defined in: src/schema.js:132
Options are settings that define how the schema behaves.
Returns
metadata
Get Signature
get metadata():
ISchemaMetadata
Defined in: src/schema.js:141
Metadata defines settings that describe how the schema should interact with users.
Returns
unionSchemas
Get Signature
get unionSchemas():
SchemaUnionSchemas
Defined in: src/schema.js:150
Unions are sets of alternative schemas; a discriminator selects which to use.
Returns
SchemaUnionSchemas
Methods
toData()
toData():
SchemaData
Defined in: src/schema.js:159
Extract the contents of this schema and its children as a regular object.
Returns
property()
property(
propertyName,propertySchema):Schema
Defined in: src/schema.js:238
Attach a named child schema
Parameters
| Parameter | Type | Description |
|---|---|---|
propertyName | string | property name |
propertySchema | string | CompiledSchema | Schema | undefined | schema to associate with the property, undefined to delete current |
Returns
Schema
- returns self for fluent chaining
option()
option(
option,value?):Schema
Defined in: src/schema.js:297
Define a schema option
Options are settings that define how the schema behaves.
Parameters
| Parameter | Type | Description |
|---|---|---|
option | string | option |
value? | any | option value |
Returns
Schema
- returns self for fluent chaining
meta()
meta(
meta,value?):Schema
Defined in: src/schema.js:421
Define schema metadata (like options, but for humans and ConfigurationSource hints) - todo: locale-aware
(Note: named "meta" instead of "metadata" to differentiate from the object getter)
Parameters
| Parameter | Type | Description |
|---|---|---|
meta | string | metadata key |
value? | any | option value |
Returns
Schema
- returns self for fluent chaining
unionDiscriminator()
unionDiscriminator(
spec):Schema
Defined in: src/schema.js:468
The discriminator handler returns the key or schema of the union member that should be used. This function appends a single value processor to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | any | - |
Returns
Schema
- returns self for fluent chaining
unionDiscriminators()
unionDiscriminators(
specs,policy?):Schema
Defined in: src/schema.js:481
The discriminator handler returns the key or schema of the union member that should be used. This function applies multiple value processors to the handler pipeline. (Note that it would be highly unusual to want more than one!)
Parameters
| Parameter | Type | Description |
|---|---|---|
specs | any[] | - |
policy? | symbol | - |
Returns
Schema
- returns self for fluent chaining
unionSchema()
unionSchema(
key,unionSchema):Schema
Defined in: src/schema.js:492
Add a schema as an alternative member of this schema's union.
Parameters
| Parameter | Type | Description |
|---|---|---|
key | string | union schema key (used by some discriminators to select this schema) |
unionSchema | CompiledSchema | Schema | schema that the discriminator selects, or true/false override if a group |
Returns
Schema
unionKey()
unionKey(
value?):Schema
Defined in: src/schema.js:533
Mark this schema as containing (and only permitting) storage of union keys.
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
selector()
selector(
value?):Schema
Defined in: src/schema.js:547
Mark this schema as a selector.
Selectors are a convenience wrapper for controlling selection conditions that only are true when the selector contains the correct selection value.
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
selection()
selection(
value?):Schema
Defined in: src/schema.js:564
Mark this schema as a selection.
A selection schema automatically creates a condition that only activates the schema if the corresponding selector has the correct value.
With the default argument, the selection schema condition uses the property name as the selector value.
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | any | - |
Returns
Schema
required()
required(
value?):Schema
Defined in: src/schema.js:598
Mark this schema as defining a required value (or not)
Schema requirements are enforced during validation.
Requirements are shallow; this can be changed via the deep() option.
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
optional()
optional(
value?):Schema
Defined in: src/schema.js:614
Mark this schema as defining an optional value (or not); the default is optional.
(Syntactic sugar to negate required()) Schema requirements are enforced during validation.
Requirements are shallow; this can be changed via the deep() option.
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
default()
default(
value):Schema
Defined in: src/schema.js:628
Define a default value for this schema to use if there is no input.
Defaults are shallow and will not cause children of undefined inputs to populate; this can be changed via the deep() option.
Parameters
| Parameter | Type | Description |
|---|---|---|
value | any | - |
Returns
Schema
deep()
deep(
value?):Schema
Defined in: src/schema.js:640
Indicate that this schema should be deeply traversed even if the input is empty (e.g. to enable deep defaults and requirements)
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
allowEmpty()
allowEmpty(
value?):Schema
Defined in: src/schema.js:651
Mark this array/string as allowing empty values.
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
allowIncremental()
allowIncremental(
value?):Schema
Defined in: src/schema.js:667
Mark this schema as allowing incremental assignment to children.
(The default is true for any schema with children, so most of the time you'd be disabling it.)
Deprecated; use the "opaque" option as it more clearly indicates the actual intent.
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
Deprecated
opaque()
opaque(
value?):Schema
Defined in: src/schema.js:690
Mark this schema as defining a value whose internal structure is hidden after transformation.
This has implications both for assignment processing and validation.
Deep property assignments usually result in any mid-path containers being automatically created (normalized and transformed) and property values are incrementally assigned.
Opaque schemas do not allow incremental assignments, so they only create normalized mid-path containers that are staged until all relevant assignments are complete. The transform is then run, and passed the staged normalized container contents as input.
Validators for opaque schemas only run on the value itself, and do not traverse into any child properties. Opaque schemas thus generally require custom validators that know how to properly handle the value.
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
value? | boolean | true | - |
Returns
Schema
strict()
strict(
value?):Schema
Defined in: src/schema.js:706
Mark this schema as requiring strict enforcement (the default)
Strict mode means that the data cannot have any extra data, and exactly matches the schema definition. Lax mode allows a more "fuzzy" interpretation of the data, but the data still must pass all value processors including the validation phases. (To prevent exceptions during validation, wrap the processors in a $filter, which will just return undefined.)
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
lax()
lax(
value?):Schema
Defined in: src/schema.js:717
Syntactic sugar for the opposite of strict
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
implicit()
implicit(
value?):Schema
Defined in: src/schema.js:728
Mark this schema as implicit in the transformed output (so no need to assign or check)
Parameters
| Parameter | Type | Description |
|---|---|---|
value? | boolean | - |
Returns
Schema
value()
value(
v):Schema
Defined in: src/schema.js:742
Define a legal input value this schema will accept.
Values will be normalized for comparison.
Parameters
| Parameter | Type | Description |
|---|---|---|
v | any | - |
Returns
Schema
values()
values(
va?,policy?):Schema
Defined in: src/schema.js:755
Define a list of one or more legal values this schema will accept
Values will be normalized for comparison.
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
va | any[] | [] | - |
policy? | symbol | SchemaPolicy.APPEND | - |
Returns
Schema
condition()
condition(
spec):Schema
Defined in: src/schema.js:782
The condition handler determines if the schema should be processed at all. This function appends a single value processor to the handler pipeline
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | any | - |
Returns
Schema
conditions()
conditions(
specs,policy?):Schema
Defined in: src/schema.js:794
The condition handler determines if the schema should be processed at all. This call applies one or more value processors to the handler pipeline (default policy = append)
Parameters
| Parameter | Type | Description |
|---|---|---|
specs | any[] | - |
policy? | symbol | - |
Returns
Schema
normalizer()
normalizer(
spec):Schema
Defined in: src/schema.js:805
The normalizer handler ensures input is in a format that the transformer can handle. This call appends a single value processor to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | any | - |
Returns
Schema
normalizers()
normalizers(
specs,policy?):Schema
Defined in: src/schema.js:817
The normalizer handler ensures input is in a format that the transformer can handle. This call applies one or more value processors to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
specs | any[] | - |
policy? | symbol | - |
Returns
Schema
transformer()
transformer(
spec):Schema
Defined in: src/schema.js:828
The transformer handler converts a normalized input value into the final output value for the schema. This call appends a single value processor to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | any | - |
Returns
Schema
transformers()
transformers(
specs,policy?):Schema
Defined in: src/schema.js:840
The transformer handler converts a normalized input value into the final output value for the schema. This call applies one or more value processors to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
specs | any[] | - |
policy? | symbol | - |
Returns
Schema
finalizer()
finalizer(
spec):Schema
Defined in: src/schema.js:850
The finalizer handler performs any required post-processing of a transformed value.
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | any | - |
Returns
Schema
finalizers()
finalizers(
specs,policy?):Schema
Defined in: src/schema.js:862
The finalizer handler does any required post-processing of a transformed value. This call applies one or more value processors to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
specs | any[] | - |
policy? | symbol | - |
Returns
Schema
validator()
validator(
spec):Schema
Defined in: src/schema.js:874
The validator handler ensures an input value matches the schema, and returns a (potentially enhanced) fully validated output value. This call appends a single value processor to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | any | - |
Returns
Schema
validators()
validators(
specs,policy?):Schema
Defined in: src/schema.js:886
The validator handler ensures an input value matches the schema, and returns a (potentially enhanced) fully validated output value. This call applies one or more value processors to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
specs | any[] | - |
policy? | symbol | - |
Returns
Schema
serializer()
serializer(
spec):Schema
Defined in: src/schema.js:897
The serialize handler restores a configuration value to its pre-transform normalized form. This call appends a single value processor to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | any | - |
Returns
Schema
serializers()
serializers(
specs,policy?):Schema
Defined in: src/schema.js:909
The serialize handler restores a configuration value to its pre-transform normalized form. This call applies one or more value processors to the handler pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
specs | any[] | - |
policy? | symbol | - |
Returns
Schema
extend()
extend(
otherSchema,seen?):Schema
Defined in: src/schema.js:921
Use another schema to extend the current one without overwriting.
Parameters
| Parameter | Type | Description |
|---|---|---|
otherSchema | ISchema | SchemaData | source schema |
seen? | Map<any, any> | - |
Returns
Schema
- returns self
clone()
clone():
Schema
Defined in: src/schema.js:950
Make a copy of this schema
Returns
Schema
createFromModel()
staticcreateFromModel(model,seen?):Schema
Defined in: src/schema.js:961
Create a new Schema from something schema-shaped
Parameters
| Parameter | Type | Description |
|---|---|---|
model | string | ISchema | SchemaData | - |
seen? | Map<any, any> | - |
Returns
Schema
create()
staticcreate(base?,options?,metadata?):Schema
Defined in: src/schema.js:988
Static schema factory (useful for aliasing to reduce typing!)
Prefer using fluent setters over passing options/metadata to this call
Parameters
| Parameter | Type | Description |
|---|---|---|
base? | string | CompiledSchema | ISchema | SchemaData | Schema | schema |
options? | any | schema options |
metadata? | ISchemaMetadata | schema metadata |
Returns
Schema
literal()
staticliteral(literalValue,options?,metadata?):Schema
Defined in: src/schema.js:1002
Static schema factory for special schemas that ignore assignments and produce a single defined value
Prefer using fluent setters over passing options/metadata to this call
Parameters
| Parameter | Type | Description |
|---|---|---|
literalValue | any | the value this schema will always emit |
options? | any | additional options |
metadata? | ISchemaMetadata | additional metadata |
Returns
Schema