Skip to content

Commit

Permalink
Updated standalone documentation and add new examples (ajv-validator#…
Browse files Browse the repository at this point in the history 
…1866)

* docs: updated standalone documentation and added new examples ajv-validator#1831

* remove unnecessary line breaks

* remove style changes

* minor corrections

* minor corrections

* Update docs/standalone.md

* Update docs/standalone.md

* Update docs/standalone.md

Co-authored-by: Evgeny Poberezkin <[email protected]>
  • Loading branch information
@rehanvdm @epoberezkin
rehanvdm and epoberezkin authored Jan 15, 2022
1 parent f2e590a commit ec96c87
Showing 1 changed file with 190 additions and 33 deletions.
223 changes: 190 additions & 33 deletions docs/standalone.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,83 +2,241 @@

[[toc]]

Ajv supports generating standalone modules with exported validation function(s), with one default export or multiple named exports, that are pre-compiled and can be used without Ajv. It is useful for several reasons:
Ajv supports generating standalone validation functions from JSON Schemas at compile/build time. These functions can then be used during runtime to do validation without initialising Ajv. It is useful for several reasons:

- to reduce the browser bundle size - Ajv is not included in the bundle (although if you have a large number of schemas the bundle can become bigger - when the total size of generated validation code is bigger than Ajv code).
- to reduce the start-up time - the validation and compilation of schemas will happen during build time.
- to avoid dynamic code evaluation with Function constructor (used for schema compilation) - when it is prohibited by the browser page [Content Security Policy](./security.md#content-security-policy).

This functionality in Ajv v7 supersedes deprecated package ajv-pack that can be used with Ajv v6. All schemas, including those with recursive references, formats and user-defined keywords are supported, with few [limitations](#configuration-and-limitations).
This functionality in Ajv v7 supersedes the deprecated package ajv-pack that can be used with Ajv v6. All schemas, including those with recursive references, formats and user-defined keywords are supported, with few [limitations](#configuration-and-limitations).

## Usage with CLI
## Two-step process

In most cases you would use this functionality via [ajv-cli](https://github.com/ajv-validator/ajv-cli) (>= 4.0.0) to generate module that exports validation function.
The **first step** is to **generate** the standalone validation function code. This is done at compile/build time of your project and the output is a generated JS file. The **second step** is to **use** the generated JS validation function.

There are two methods to generate the code, using either the Ajv CLI or the Ajv JS library. There are also a few different options that can be passed when generating code. Below is just a highlight of a few options:

- Set the `code.source` (JS) value to true or use the `compile` (CLI) command to generate standalone code.
- The standalone code can be generated in either ES5 or ES6, it defaults to ES6. Set the `code.es5` (JS) value to true or pass the `--code-es5` (CLI) flag to true if you want ES5 code.
- The standalone code can be generated in either CJS (module.export & require) or ESM (exports & import), it defaults to CJS. Set the `code.esm` (JS) value to true or pass the `--code-esm` (CLI) flag if you want ESM exported code.

Note that the way the function is exported, differs if you are exporting a single or multiple schemas. See examples below.

### Generating function(s) using CLI

In most cases you would use this functionality via [ajv-cli](https://github.com/ajv-validator/ajv-cli) (>= 4.0.0) to generate the standalone code that exports the validation function. See [ajv-cli](https://github.com/ajv-validator/ajv-cli#compile-schemas) docs and the [cli options](https://github.com/ajv-validator/ajv-cli#ajv-options) for additional information.

#### Using the defaults - ES6 and CJS exports
```sh
npm install -g ajv-cli
ajv compile -s schema.json -o validate_schema.js
```

`validate_schema.js` will contain the module exporting validation function that can be bundled into your application.

See [ajv-cli](https://github.com/ajv-validator/ajv-cli) docs for additional information.

## Usage from code
### Generating using the JS library

Install the package, version >= v7.0.0:
```sh
npm install ajv
```

#### Generating functions(s) for a single schema using the JS library - ES6 and CJS exports

```javascript
const Ajv = require("ajv") // version >= v7.0.0
const ajv = new Ajv({code: {source: true}}) // this option is required to generate standalone code
const fs = require("fs")
const path = require("path")
const Ajv = require("ajv")
const standaloneCode = require("ajv/dist/standalone").default

const schema = {
$id: "https://example.com/object.json",
$id: "https://example.com/bar.json",
$schema: "http://json-schema.org/draft-07/schema#",
type: "object",
properties: {
foo: {
type: "string",
pattern: "^[a-z]+$",
},
bar: {type: "string"},
},
"required": ["bar"]
}

// 1. generate module with a single default export (CommonJS and ESM compatible):
// The generated code will have a default export:
// `module.exports = <validateFunctionCode>;module.exports.default = <validateFunctionCode>;`
const ajv = new Ajv({code: {source: true}})
const validate = ajv.compile(schema)
let moduleCode = standaloneCode(ajv, validate)

// 2. pass map of schema IDs to generate multiple exports,
// it avoids code duplication if schemas are mutually recursive or have some share elements:
let moduleCode = standaloneCode(ajv, {
validateObject: "https://example.com/object.json",
})
// Now you can write the module code to file
fs.writeFileSync(path.join(__dirname, "../consume/validate-cjs.js"), moduleCode)
```

#### Generating functions(s) for multiple schemas using the JS library - ES6 and CJS exports

```javascript
const fs = require("fs")
const path = require("path")
const Ajv = require("ajv")
const standaloneCode = require("ajv/dist/standalone").default

// 3. or generate module with all schemas added to the instance (excluding meta-schemas),
// export names would use schema IDs (or keys passed to addSchema method):
const schemaFoo = {
$id: "#/definitions/Foo",
$schema: "http://json-schema.org/draft-07/schema#",
type: "object",
properties: {
foo: {"$ref": "#/definitions/Bar"}
}
}
const schemaBar = {
$id: "#/definitions/Bar",
$schema: "http://json-schema.org/draft-07/schema#",
type: "object",
properties: {
bar: {type: "string"},
},
"required": ["bar"]
}

// For CJS, it generates an exports array, will generate
// `exports["#/definitions/Foo"] = ...;exports["#/definitions/Bar"] = ... ;`
const ajv = new Ajv({schemas: [schemaFoo, schemaBar], code: {source: true}})
let moduleCode = standaloneCode(ajv)

// now you can
// write module code to file
// Now you can write the module code to file
fs.writeFileSync(path.join(__dirname, "../consume/validate-cjs.js"), moduleCode)
```

#### Generating functions(s) for multiple schemas using the JS library - ES6 and ESM exports

```javascript
const fs = require("fs")
const path = require("path")
fs.writeFileSync(path.join(__dirname, "/validate.js"), moduleCode)
const Ajv = require("ajv")
const standaloneCode = require("ajv/dist/standalone").default

const schemaFoo = {
$id: "#/definitions/Foo",
$schema: "http://json-schema.org/draft-07/schema#",
type: "object",
properties: {
foo: {"$ref": "#/definitions/Bar"}
}
}
const schemaBar = {
$id: "#/definitions/Bar",
$schema: "http://json-schema.org/draft-07/schema#",
type: "object",
properties: {
bar: {type: "string"},
},
"required": ["bar"]
}

// ... or require module from string
const requireFromString = require("require-from-string")
const standaloneValidate = requireFromString(moduleCode) // for a single default export
// For ESM, the export name needs to be a valid export name, it can not be `export const #/definitions/Foo = ...;` so we
// need to provide a mapping between a valid name and the $id field. Below will generate
// `export const Foo = ...;export const Bar = ...;`
// This mapping would not have been needed if the `$ids` was just `Bar` and `Foo` instead of `#/definitions/Foo`
// and `#/definitions/Bar` respectfully
const ajv = new Ajv({schemas: [schemaFoo, schemaBar], code: {source: true, esm: true}})
let moduleCode = standaloneCode(ajv, {
"Foo": "#/definitions/Foo",
"Bar": "#/definitions/Bar"
})

// Now you can write the module code to file
fs.writeFileSync(path.join(__dirname, "../consume/validate-esm.mjs"), moduleCode)
```

::: warning ESM name mapping
The ESM version only requires the mapping if the ids are not valid export names. If the $ids were just the
`Foo` and `Bar` instead of `#/definitions/Foo` and `#/definitions/Bar` then the mapping would not be needed.
:::


## Using the validation function(s)

### Validating a single schemas using the JS library - ES6 and CJS

```javascript
const Bar = require('./validate-cjs')

const barPass = {
bar: "something"
}

const barFail = {
// bar: "something" // <= empty/omitted property that is required
}

let validateBar = Bar
if (!validateBar(barPass))
console.log("ERRORS 1:", validateBar.errors) //Never reaches this because valid

if (!validateBar(barFail))
console.log("ERRORS 2:", validateBar.errors) //Errors array gets logged
```

### Validating multiple schemas using the JS library - ES6 and CJS

```javascript
const validations = require('./validate-cjs')

const fooPass = {
foo: {
bar: "something"
}
}

const fooFail = {
foo: {
// bar: "something" // <= empty/omitted property that is required
}
}

let validateFoo = validations["#/definitions/Foo"];
if (!validateFoo(fooPass))
console.log("ERRORS 1:", validateFoo.errors); //Never reaches this because valid

if (!validateFoo(fooFail))
console.log("ERRORS 2:", validateFoo.errors); //Errors array gets logged

```

### Validating multiple schemas using the JS library - ES6 and ESM

```javascript
import {Foo, Bar} from './validate-multiple-esm.mjs';

const fooPass = {
foo: {
bar: "something"
}
}

const fooFail = {
foo: {
// bar: "something" // bar: "something" <= empty properties
}
}

let validateFoo = Foo;
if (!validateFoo(fooPass))
console.log("ERRORS 1:", validateFoo.errors); //Never reaches here because valid

if (!validateFoo(fooFail))
console.log("ERRORS 2:", validateFoo.errors); //Errors array gets logged
```


### Requirement at runtime

To run the standalone generated functions, the Ajv package should still be a run-time dependency for most schemas, but generated modules can only depend on code in [runtime](https://github.com/ajv-validator/ajv/tree/master/lib/runtime) folder, so the whole Ajv will not be included in the bundle (or executed) if you require the modules with standalone validation code from your application code.
One of the main reason for using the standalone mode is to start applications faster to avoid runtime schema compilation.

The standalone generated functions still has a dependency on the Ajv. Specifically on the code in the [runtime](https://github.com/ajv-validator/ajv/tree/master/lib/runtime) folder of the package.

Completely isolated validation functions can be generated if desired (won't be for most use cases). Run the generated code through a bundler like ES Build to create completely isolated validation functions that can be imported/required without any dependency on Ajv. This is also not needed if your project is already using a bundler.

## Configuration and limitations

To support standalone code generation:

- Ajv option `source.code` must be set to `true`
- Ajv option `code.source` must be set to `true`
- only `code` and `macro` user-defined keywords are supported (see [User defined keywords](./keywords.md)).
- when `code` keywords define variables in shared scope using `gen.scopeValue`, they must provide `code` property with the code snippet. See source code of pre-defined keywords for examples in [vocabularies folder](https://github.com/ajv-validator/ajv/blob/master/lib/vocabularies).
- if formats are used in standalone code, ajv option `code.formats` should contain the code snippet that will evaluate to an object with all used format definitions - it can be a call to `require("...")` with the correct path (relative to the location of saved module):
Expand All @@ -93,6 +251,5 @@ const ajv = new Ajv({
formats: _`require("./my-formats")`,
},
})
```

If you only use formats from [ajv-formats](https://github.com/ajv-validator/ajv-formats) this option will be set by this package automatically.

0 comments on commit ec96c87

Please sign in to comment.