swagger-enforcer
Advanced tools
Automatically validate a value against the swagger schema while you build it. Alternatively you can validate the final value.
Automatically validate a value against the swagger schema while you build it. Alternatively you can validate the final value.
To validate while building (enforce), this package requires support of the native Proxy interface. For NodeJS that means version 6.0.0 and newer. If your node version is lower than that you can still validate the final value (validate) but will be unable to enforce while building.
Validate While Building (enforce)
const Enforcer = require('swagger-enforcer');
// a schema to enforce
const schema = {
type: 'object',
properties: {
num: {
type: 'number',
minimum: 0
},
str: {
type: 'string',
enum: ['foo', 'bar', 'baz'],
default: 'foo'
}
}
};
// define swagger schema definitions
const definitions = {};
// define enforcer options
const options = { useDefaults: true };
// create enforcer instance that defines which rules to enforce
const enforcer = Enforcer(schema, definitions, options);
// build an object that enforces the schema
const obj = enforcer.enforce();
console.log(obj); // { str: 'foo' } - this is because 'str' had a default value:
obj.num = 5; // validates successfully and value is set
obj.str = 'abc'; // throws an error because 'abc' is not in enum
Validate the Final Value (validate)
const Enforcer = require('swagger-enforcer');
// a schema to enforce
const schema = {
type: 'object',
properties: {
num: {
type: 'number',
minimum: 0
},
str: {
type: 'string',
enum: ['foo', 'bar', 'baz'],
default: 'foo'
}
}
};
// create enforcer instance that defines which rules to enforce
const enforcer = Enforcer(schema, {}, { useDefaults: true });
// build the object
const obj = {
num: 5,
str: 'abc'
};
// validate the object
enforcer.validate(schema, obj); // throws an error because 'abc' is not in enum
Produce an enforcer instance that can enforce a swagger schema while you build the object and/or that validates the object after it is built.
Signature: Enforcer (schema [, definitions [, options ] ]) : Enforcer
Parameters:
schema - The swagger schema to use for enforcement of values.
definitions - An object containing definitions by name. Definitions are only necessary if using discriminators.
{
Pet: {
type: 'object',
discriminator: 'petType',
properties: {
name: {
type: 'string'
},
petType: {
type: 'string'
}
},
required: ['name', 'petType']
},
Cat: {
type: 'object',
allOf: [
{
$ref: '#/definitions/Pet'
},
{
type: 'object',
properties: {
name: {
type: 'string'
},
petType: {
type: 'string'
},
huntingSkill: {
type: string
}
}
}
]
}
}
options - Enforcement options. Defaults to:
{
autoFormat: false,
enforce: {
enum: true,
maxItems: true,
minItems: false,
uniqueItems: true,
multipleOf: true,
maximum: true,
minimum: true,
maxLength: true,
minLength: true,
pattern: true,
additionalProperties: true,
maxProperties: true,
minProperties: false,
required: false
},
useDefaults: false
}
Returns - An enforcer instance with the following prototype methods: Enforcer.prototype.enforce and Enforcer.prototype.validate.
Validate an object while you build it.
This method requires that your running a version of JavaScript that supports the native Proxy interface.
Signature: .enforce ( [ initial ]) : *
Parameters:
Returns - A proxied object or array if the schema is for an object or an array. Any modifications to the object or array will automatically be run through a performance optimized validation sequence. If the schema is for a non-object or non-array then the value cannot be proxied.
Example - See Example 1
Validate a value as if it were fully built. An array is returned with any errors that were encountered.
Signature: .errors ( value ) : Error[]
Parameters:
Returns - An array of Error objects.
Validate a value as if it were fully built. If validation fails then an error will be thrown.
Signature: .validate ( value ) : undefined
Parameters:
Returns - Undefined. If validation fails then an error will be thrown.
Example - See Example 2
Build an unenforced object from a schema's x-template definitions, applying parameters to the templates to to generate valid values.
Signature: Enforcer.applyTemplate ( schema, definitions, params [, options, [, initialValue ] ] ) : object
Parameters:
schema - The schema to build objects from.
definitions - The swagger definitions object. This is necessary if using discriminators, otherwise it can safely be set to an empty object {} or null.
params - An object defining key value pairs for parameter enforcement.
options - The options to use while building the object:
defaultsUseParams - If applying useDefaults is set to true and this property is set to true then parameter replacement will also be set for defaults.
replacement - Set the parameter replacement style to one of colon, doubleHandlebar, handlebar, or a custom Function. Defaults to handlebar.
useDefaults - Set to true to use default property in addition to x-template property to generate templates. Defaults to true.
useTemplates - Set to true to use the x-template property to produce replacements
initialValue - An optional value to start building the object from. If provided it must match the schema's type.
Returns - An unenforced object with the template applied.
Example
const schema = {
type: 'object',
properties: {
firstName: {
type: 'string',
'x-template': '{firstName}'
},
fullName: {
type: 'string',
'x-template': '{firstName} {lastName}'
},
lastName: {
type: 'string',
'x-template': '{lastName}'
},
roles: {
type: 'array',
items: {
type: 'string'
},
default: []
}
}
};
const params = {
firstName: 'Bob',
lastName: 'Smith'
};
const x = Enforcer.applyTemplate(schema, null, params);
console.log(x); // {
// firstName: 'Bob',
// fullName: 'Bob Smith',
// lastName: 'Smith',
// roles: []
// }
An object that has the defaults to use for the applyTemplate. The defaults can be overwritten for this object and those changes may affect any future calls to Enforcer.applyTemplate.
Enforcer.applyTemplate.defaults = {
autoFormat: true,
defaultsUseParams: true,
useDefaults: true,
useTemplates: true,
useVariables: true,
replacement: 'handlebar'
};
A static method that will find and replace string parameters with new values.
Signature: Enforcer.injectParameters( value, parameters [, options ]) : undefined
Parameters:
value - The value to begin traversing and looking for strings to replace.
parameters - An object with keys and values that represent what to replace in each string.
options - Configuration options:
mutate - Set to true to mutate the passed in object, otherwise generate a copy. Defaults to false.
replacement - The replacement method to use. This can be one of colon, doubleHandlebar, handlebar, or a custom Function. Defaults to handlebar.
Returns the value after parameter injection.
Example
const o = {
foo: '{name} is {age} years old {when}'
};
const params = {
name: 'Bob',
age: 25,
when: 'today'
};
const x = Enforcer.injectParameters(o, params);
console.log(x.foo); // 'Bob is 25 years old today'
An object that has the defaults to use for the parameterInjection. The defaults can be overwritten for this object and those changes may affect any future calls to Enforcer.injectParameters.
Enforcer.injectParameters.defaults = {
mutate: false,
replacement: 'handlebar'
};
A group of static methods that determine if a value falls into one of several categories.
Check to see if a string is an 8-bit binary string consisting only of 0 and 1.
Signature: Enforcer.is.binary( value ) : boolean
Parameters:
Returns: true if a binary string, otherwise false.
Enforcer.is.binary('00101000'); // true
Check to see if a string equals 'true' or 'false'.
Signature: Enforcer.is.boolean( value ) : boolean
Parameters:
Returns: true if 'true' or 'false', otherwise false.
Enforcer.is.boolean('true'); // true
Check to see if a string is a base64 encoded string.
Signature: Enforcer.is.base64( value ) : boolean
Parameters:
Returns: true if a base64 encoded string, otherwise false.
Enforcer.is.byte('aGVsbG8='); // true
Check to see if a string is a date string.
Signature: Enforcer.is.date( value ) : boolean
Parameters:
Returns: true if a string in the date format YYYY-MM-DD, otherwise false.
Enforcer.is.date('2000-01-01'); // true
Check to see if a string is a date-time encoded string.
Signature: Enforcer.is.dateTime( value ) : boolean
Parameters:
Returns: true if a date in ISO string format YYYY-MM-DDTHH:mm:ss:uuuZ, otherwise false.
Enforcer.is.dateTime('2000-01-01T00:00:00.000Z'); // true
Check to see if a string is an integer encoded string.
Signature: Enforcer.is.integer( value ) : boolean
Parameters:
Returns: true if the string is an encoded integer, otherwise false.
Enforcer.is.integer('15'); // true
Check to see if a string is an number encoded string.
Signature: Enforcer.is.number( value ) : boolean
Parameters:
Returns: true if the string is an encoded number, otherwise false.
Enforcer.is.number('15.27'); // true
Take an enforced object and get it's equivalent non-enforced object.
Signature: Enforcer.release( value ) : *
Parameters:
Returns: The released value.
const Enforcer = require('swagger-enforcer');
const enforcer = Enforcer();
const schema = {
type: 'array',
items: {
type: 'number'
}
};
const array = enforcer.enforce(schema, []);
try {
// throws an error because the item is not a string
array.push('a');
} catch (e) {
console.error(e.stack);
}
// release the enforcement
const released = Enforcer.release(array);
// no error thrown
released.push('a');
Check to see if two values are similar, including the evaluation of objects and arrays.
Signature: Enforcer.is.same( value1, value2 ) : boolean
Parameters:
value1 - The first value to compare.
value2 - The second value to compare.
Returns: true if both values are similar, otherwise false.
Enforcer.same({ a: 1, b: 2 }, { b: 2, a: 1 }); // true
A group of static methods that can be used to convert values into their acceptable swagger type equivalents.
Convert a value into an 8-bit binary string.
Signature: Enforcer.to.binary( value ) : string
Parameters:
Returns: An 8-bit binary string.
Enforcer.to.binary(1); // '00000001'
Convert a value into a boolean.
Signature: Enforcer.to.boolean( value ) : string
Parameters:
Returns: A boolean.
Enforcer.to.boolean('hello'); // true
Convert a value into an base64 encoded string.
Signature: Enforcer.to.byte( value ) : string
Parameters:
Returns: A base64 encoded string.
Enforcer.to.byte('hello'); // 'aGVsbG8='
Convert a value into a date encoded string.
Signature: Enforcer.to.date( value ) : string
Parameters:
Returns: A date encoded string of the format YYYY-MM-DD.
Enforcer.to.date(new Date(2000, 0, 1, 0, 0, 0, 0)); // '2000-01-01'
Convert a value into a date encoded string.
Signature: Enforcer.to.dateTime( value ) : string
Parameters:
Returns: A date encoded string of the format YYYY-MM-DDTHH:mm:ss:uuuZ.
Enforcer.to.dateTime(new Date(2000, 0, 1, 0, 0, 0, 0)); // '2000-01-01T00:00:00.000Z'
Convert a value into an integer.
Signature: Enforcer.to.integer( value ) : string
Parameters:
Returns: A number that is an integer.
Enforcer.to.integer('15'); // 15
Convert a value into an number.
Signature: Enforcer.to.number( value ) : string
Parameters:
Returns: A number.
Enforcer.to.number('1.23'); // 1.23
The following object shows the defaults for enforcement:
{
autoFormat: false,
enforce: {
enum: true,
maxItems: true,
minItems: false,
uniqueItems: true,
multipleOf: true,
maximum: true,
minimum: true,
maxLength: true,
minLength: true,
pattern: true,
additionalProperties: true,
maxProperties: true,
minProperties: false,
required: false
},
useDefaults: false
}
Below is an explanation of each option:
autoFormat - Whether to attempt to convert any values being set to their appropriate types. For example, if a schema expects a string of format date-time and this option is set to true then you can set the schema using a Date object and that object will automatically be converted to a string in date-time format. The advantage of using this is that it means you can skip to explicit use of the conversion to api but the disadvantage is that it may obscure some errors if the conversion shouldn't have happened. Defaults to false.
enforce - An object specifying the validation rules to enforce while building or validating a schema. If this value is set to true then all enforcement properties will be set to true. Conversely, if this value is set to false then all enforcement properties will be set to false. Some properties default to being disabled (false) because they would make it hard to build an object that is under active enforcement.
General Enforcement
true.Array Enforcement
maxItems - Enforce that the array is not populated above its maxItems threshold. Defaults to true.
minItems - Enforce that the array is never smaller than its minItems threshold. Defaults to false.
uniqueItems - Enforce that each item in the array is always unique. Enabling this option may significantly increase processing time (more so for nested objects and arrays). Defaults to true.
Number and Integer Enforcement
multipleOf - Enforce multipleOf validation for numbers and integers. Defaults to true.
maximum - Enforce maximum validation for numbers and integers. Defaults to true.
minimum - Enforce minimum validation for numbers and integers. Defaults to true.
String Enforcement
maxLength - Enforce maxLength validation. Defaults to true.
minLength - Enforce minLength validation for numbers and integers. Defaults to true.
pattern - Enforce pattern matching. Defaults to true.
Object Enforcement
additionalProperties - Enforce additional property validation. Defaults to true.
maxProperties - Enforce maxProperties validation. Defaults to true.
minProperties - Enforce minProperties validation for numbers and integers. Defaults to false.
required - Enforce that required properties are set. Defaults to false.
useDefaults - Whether to use default values to build out the swagger response object automatically, as much as possible. Defaults to false.
FAQs
Automatically validate a value against the swagger schema while you build it. Alternatively you can validate the final value.
The npm package swagger-enforcer receives a total of 92 weekly downloads. As such, swagger-enforcer popularity was classified as not popular.
We found that swagger-enforcer demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.