ajv-openapi-compile

Given an OpenAPI definition, compile into AJV validation modules to be used in environments (like Cloudflare Workers) where eval is not available, or a single JavaScript file is desired.

Install

The normal way:

1npm install ajv-openapi-compile --save-dev

Build With It

You can use the CLI tool, as part of your build process:

1ajv-openapi-compile --definition=/path/to/openapi.json \
2  --output=/path/to/compiled.js \
3  --tree=/path/to/tree.js

You can also use in your build scripts:

1import { compile } from 'ajv-openapi-compile'
2import { readFile, writeFile } from 'node:fs'
3const definition = JSON.parse(await readFile('/path/to/openapi.json', 'utf8'))
4const { code, tree } = await compile(definition)
5await writeFile('/path/to/compiled.js', code, 'utf8')
6await writeFile('/path/to/tree.js', tree, 'utf8')

The output from the compile function contains the code property, which has all imports/requires resolved and concatenated into the single string.

Use Built Code

The compiled code is an ES string, and exports schema as the default, which is a map of schema identifiers to validation functions.

If you know the fully-resolved schema id, you can access the validation function explicitly:

1import schemas from '/path/to/compiled.js'
2const validate = schemas['#/components/schema/error']
3const valid = validate({ code: 404 })
4if (!valid) console.log(validate.errors)

Note: The schema identifiers are escaped using the JSON Pointer (RFC6901) specs, which turns ~ into ~0 and / into ~1.

If you don't know the fully-resolved schema id, you can use something like pointer-props to navigate the structure and resolve to the correct id:

1import { resolve, toPointer } from 'pointer-props'
2import { readFile } from 'node:fs'
3import schemas from '/path/to/compiled.js'
4const definition = JSON.parse(await readFile('/path/to/openapi.json', 'utf8'))
5// lookup the id
6const id = resolve(definition, '#/path/to/schema') // => '/path/to/fully/resolved/schema'
7// note the relative reference requires "#" as the prefix
8const validate = schemas['#' + id]
9const valid = validate({ code: 404 })
10if (!valid) console.log(validate.errors)

CLI ajv-openapi-compile

The CLI takes the following parameters:

• ---definition, -d (String) - The path to the definition JSON file.
• ---output, -o (String) - The path to write the compiled AJV validation code.

For convenience and compatability with other tooling, the definition parameter also supports importing JavaScript files, and will follow this algorithm:

1. If the file extension is .json read and parse as JSON
2. If the file extension is .yaml or .yml read and parse as YAML (using js-yaml internally)
3. Otherwise, attempt importing * as schema
4. If schema.definition is set, use that
5. Otherwise, try using schema
6. Otherwise, try importing the default as schema and try that

To be considered valid, the imported schema definition must have a paths object, with at least one "Path Object" defined.

API: function(definition: Object) => { code: String }

The function simply takes a valid OpenAPI 3.x object.

It returns an object with the following properties:

• code: String - The compiled code, with all import and require statements resolved and placed inline.

License

Published and released under the Very Open License.

If you need a commercial license, contact me here.