node-oas-valexp

The node-oas-valexp is a value validator using OAS (OpenAPI Specification) Parameter object. The design is inspired by the RegExp object.

Note that this module is not a OAS syntax validator. Though it actually validates the syntax internally, its purpose is validating a value following the specified OAS Parameter Object.

Dependencies

• Node.js 10 +

Installation

$ cd ~
$ npm install node-oas-valexp

---

Table of Contents

• Quick Start
• ValExp object
  • Creating ValExp object
  • Properties
  • toString() method
  • test() method
  • exec() method
• ValExpExecResult object
• ValExpError object
• Supported keywords
• Release Note
• References
• License

---

Quick Start

In the sample code below, the function howOldAreYou() takes an argument which means your age. It must be an integer in the range of 0 to 120. If 35 is passed to the function, this code will output Thank you.

const ValExp = require('node-oas-valexp');
 
howOldAreYou(35);
 
function howOldAreYou(age) {
  const valexp = new ValExp({
    name: 'age',
    required: true,
    schema: {
      type: 'integer',
      mininum: 0,
      maximum: 120
    }
  });
 
  if (valexp.test(age)) {
    console.log('Thank you.');
  } else {
    console.log(valexp.error.message);
  }
}

As you can see in the code above, a ValExp object (variable valexp) is created using the OAS Parameter Object. Then the value passed to the function (variable age) is checked by the test() method of the ValExp object. The test() method returns true if the value is valid. Otherwise, it returns false.

If 121 is passed to the function, the code above will output the result as follows:

The `age` must be less than or equal to 120.

If the validation check is failed, you can get the Error object from the valexp.error. The object is actually a ValExpError object inherited from the Error object.

If you need not only to check the validity but also to get the validated value, you can use the exec() method of the ValExp object. You might wonder how it is going to help. See the scenario below:

const ValExp = require('node-oas-valexp');
 
tellYourProfile({ age: 35 });
 
function tellYourProfile(profile) {
  const valexp = new ValExp({
    name: 'profile',
    required: true,
    schema: {
      type: 'object',
      properties: {
        age: {
          type: 'integer',
          mininum: 0,
          maximum: 120
        },
        gender: {
          type: 'string',
          enum: ['male', 'female', 'other'],
          default: 'other'
        }
      }
    }
  });
 
  let res = valexp.exec(profile);
  if(res) {
    console.log('Thank you.');
    console.log(res[0]);
  } else {
    console.log(valexp.error.message);
  }
}

In the code above, the function tellYourProfile() expects your age and gender. In the Parameter Object, the default value for the gender is defined. If the gender is not passed to the function, the exec() method will automatically set the default value and returns the complete value set. Besides, the returned value is not the reference of the original value, but a newly created value (object).

If the validity check is passed, the exec() method returns a ValExpExecResult object (the variable res in the code above). Otherwise, it returns null.

---

ValExp object

Creating ValExp object

In order to use this module , you have to get the ValExp constructor loading this module as follows:

const ValExp = require('node-oas-valexp');

In the code snippet above, the variable ValExp is a ValExp constructor.

In order to check the validity of a value, you have to create a ValExp object from the constructor as follows:

const valexp = new ValExp({
  name: 'age',
  schema: { type: 'integer' }
});

The constructor takes a OAS Parameter Object. In the code snippet above, the variable valexp is a ValExp object. If the specified Parameter Object is invalid, the constructor will throw an error. The thrown error is an ValExpError object.

For now, the ValExp constructor does not support JSON/YAML string. You have to parse such string in advance.

Properties

The ValExp object supports some properties as follows:

Property	Type	Description
source	String	JSON string representing the specified OAS Parameter Object
error	Object	ValExpError object or null

const valexp = new ValExp({
  name: 'age',
  schema: { type: 'integer' }
});
console.log(valexp.source);

The code above will output the result as follows:

{"name":"age","required":false,"schema":{"type":"integer"}}

As you can see the result above, the source is not as same as the specified Parameter Object. This module parses the specified Parameter Object and rebuilds an object internally.

The error is set to null initially. When the test() or exec() is called, it will be set to the ValExpError object if an validation error occurred.

toString() method

The toString() method returns a JSON string representing the specified Parameter Object. Actually, calling this method is as same as accessing the source property.

test() method

The test() method validates the specified value following the Parameter Object, then returns the result. If the validation check is passed, it returns true. Otherwise, it returns false.

See the Quick Start for more details.

exec() method

The exec() method validates the specified value following the Parameter Object, then returns the result. If the validation check is passed, it returns a ValExpExecResult object. Otherwise, it returns null.

See the Quick Start for more details.

---

ValExpExecResult object

The ValExpExecResult object has the properties as follows:

Property	Type	Description
0	Any	The value after the validation
input	Any	The value before the validation

This object is similar to the result of the RegExp.prototype.exec() of JavaScript. The ValExpExecResult object is actually an object inherited from the Array.

const valexp = new ValExp({
  name: 'profile',
  required: true,
  schema: {
    type: 'object',
    properties: {
      age: {
        type: 'integer',
        mininum: 0,
        maximum: 120
      },
      gender: {
        type: 'string',
        enum: ['male', 'female', 'other'],
        default: 'other'
      }
    }
  }
});
 
let res = valexp.exec({age: 35});
console.log('- Before: ' + JSON.stringify(res.input));
console.log('- After : ' + JSON.stringify(res[0]));

The code above will output the result as follows:

- Before: {"age":35}
- After : {"age":35,"gender":"other"}

---

ValExpError object

The ValExpError is an object inherited from the Error object. The ValExpError supports the additional properties as follows:

Property	Type	Description
valExpName	String	Target name whose value has a validation error
valExpCode	String	Error code representing what type of error was found.

const ValExp = require('node-oas-valexp');
const valexp = new ValExp({
  name: 'age',
  required: true,
  schema: {
    type: 'integer',
    mininum: 0,
    maximum: 120
  }
});
 
valexp.test(121); // This couses an validation error
 
console.log('- valExpName: ' + valexp.error.valExpName);
console.log('- valExpCode: ' + valexp.error.valExpCode);
console.log('- messsage  : ' + valexp.error.message);

The code above will output the result as follows:

- valExpName: age
- valExpCode: ERR_VALUE_INTEGER_MAXIMUM
- messsage  : The `age` must be less than or equal to 120.

The valExpCode and the corresponding message are pre-defined in this module. See the lib/errors/en.json for details.

For now, this module also supports Japanese error message. If you want to change to Japanese, set the environment variable process.env.NODE_OAS_VALEXP_LANG to "ja" before loading this module calling the require():

process.env.NODE_OAS_VALEXP_LANG = 'ja';
const ValExp = require('node-oas-valexp');
...

The code above will output the result as follows:

- valExpName: age
- valExpCode: ERR_VALUE_INTEGER_MAXIMUM
- messsage  : `age` は 120 以下でなければいけません。

---

Supported keywords

Parameter object

Property	Type	Required	Description
name	String	Required	Parameter name
required	Boolean	Optional	true: Required, false: Optional (Default)
schema	Object	Optional	Schema object

Schema object

Common keywords

Property	Type	Required	Description
oneOf	Array	Optional	List of Schema object
anyOf	Array	Optional	List of Schema object
allOf	Array	Optional	List of Schema object
type	String	Required	"string", "number", "integer", "boolean", "array", or "object"
nullable	Boolean	Optional	true: null is acceptable, false: null is not acceptable (default)

Note that if oneOf, anyOf, or allOf is set, other keywords must not be set.

Keywords for "string"

Property	Type	Required	Description
default	String	Optional	Default value
minLength	Integer	Optional	It must be grater than 0.
maxLength	Integer	Optional	It must be grater than 0.
format	String	Optional	"date-time", "date", "time", or "byte"
pattern	String	Optional	Regular expression
	RegExp

The format example:

format	Expected values
date-time	"2020-04-05T08:30:00.000Z", "2020-04-05T08:30:00.000+09:00"
date	"2020-04-05"
time	"08:30:00", "08:30:00.000"

The date-time and date check if the date actually exists. For example, "2021-02-29" will be rejected.

The format does not support "binary" for now. If the format is "byte", it is expected that the validated value is a base64 string.

The pattern allows both of a Regular expression string and a RegExp object. The two codes are identical:

pattern: '^\\d{3}\\-\\d{4}$'

pattern: /^\d{3}\-\d{4}$/

Keywords for "number"

Property	Type	Required	Description
default	Number	Optional	Default value
minimum	Number	Optional
exclusiveMinimum	Boolean	Optional	The default value is false
maximum	Number	Optional
exclusiveMaximum	Boolean	Optional	The default value is false
multipleOf	Number	Optional	It must be grater than 0.

Keywords for "integer"

Property	Type	Required	Description
default	Integer	Optional	Default value
minimum	Number	Optional
exclusiveMinimum	Boolean	Optional	The default value is false
maximum	Number	Optional
exclusiveMaximum	Boolean	Optional	The default value is false
multipleOf	Number	Optional	It must be grater than 0.
format	String	Optional	"int32" or "int64"

If the format is "int32", it is expected that the validated value is in the range of -2147483648 to 2147483647.

If the format is "int64", it is expected that the validated value is in the range of Number.MIN_SAFE_INTEGER (-9007199254740991) to Number.MAX_SAFE_INTEGER (9007199254740991). This module does not support the BigInt for now.

Keywords for "boolean"

Property	Type	Required	Description
default	Boolean	Optional	Default value

Keywords for "array"

Property	Type	Required	Description
default	Array	Optional	Default value
minItems	Integer	Optional	It must be equal to or greater than 0.
maxItems	Integer	Optional	It must be equal to or greater than 0.
uniqueItems	Boolean	Optional	The default value is false.
items	Object	Required	Schema object for elements in the array.

Keywords for "object"

Property	Type	Required	Description
default	Object	Optional	Default value
minProperties	Integer	Optional	It must be grater than 0.
maxProperties	Integer	Optional	It must be grater than 0.
required	Array	Optional	The number of elements must be grater than 0.
properties	Object	Optional
additionalProperties	Boolean	Optional
	Object

---

Release Note

• v0.0.4 (2020-04-10)
  • Fixed the repository url in the package.json
• v0.0.3 (2020-04-09)
  • Fixed a bug that the value undefined was determined to be invalid even though the required in the Parameter Object is set to false or not specified
• v0.0.2 (2020-04-05)
  • First public release

---

References

• OpenAPI Specification
• Swagger Data Models (Schemas)
• JSON Schema Validation

---

License

The MIT License (MIT)

Copyright (c) 2020 Futomi Hatano

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.