json-schema-to-decoders
v0.2.6
Published
A utility for converting JSON schema definition to decoders
Downloads
4,748
Maintainers
Readme
json-schema-to-decoders
Generates Typescript/Javascript decoders source code expressions from JSON schema specifications.
You can also try it in your browser with any JSON schema.
Description
This package aims to provide the best possible conversion of a JSON Schema type into it's equivalent decoder function.
It has a wide support of different features from different JSON Schema drafts, check the Support Matrix for more details.
Installation
To use the CLI you can install the package globally:
npm install -g json-schema-to-decoders
To use it as a library in your package, install it locally:
npm install --dev json-schema-to-decoders
# or
yarn add -D json-schema-to-decoders
Usage
To convert a JSON definition file to decoders, use the following command CLI:
json-schema-to-decoders <schema.json>
The package also exports an API that be used for more elaborate integrations:
import Converter from "json-schema-to-decoders";
console.log(await Converter.convertFile("path/to/schema.json"));
API Reference
There are a few functios you can use for invoking the converter:
// Synchronous variations
convertSchema(schema: Schema, options?: ConverterOptions): string;
convertContents(buffer: string, options?: ConverterOptions): string;
// Asynchronous variations
convertFile(file: string, options?: ConverterOptions): Promise<string>;
convert(url: string | Schema, options?: ConverterOptions): Promise<string>;
The ConverterOptions
have the following properties:
nsPrefix
: An optional namespace where to look for decoder functions into.For example, if you are importing the decoders like so:
import * as D from "decoders";
Then you can use:
const code = convertSchema(schema, { nsPrefix: "D.", });
nsLib
: An optional namespace where to look for extra decoder library functions exposed by thejson-schema-to-decoders
package.If not specified, all of the avanced decoders would be disabled.
For example, if you can import the utility library like so:
import * as L from "json-schema-to-decoders/decoders";
Then you can use:
const code = convertSchema(schema, { nsLib: "L.", });
resolveRefPointer
: An optional function to call when a $ref is encountered. The returned value will replace the contents of that ref.For example, given the following logic:
const schema = { type: "array", items: { $ref: "#/components/schema/Item", }, }; const code = convertSchema(schema, { resolveRefPointer: (expr) => { return expr.split("/").pop(); }, });
Will produce the following code:
array(Item);
resolveRefSchema
: An optional function to call when a $ref is encountered and the schema of it is required.In contrast to
resolveRefPointer
, where a variable reference is emitted, this function expects the value of the referred schema to be returned.If missing,
resolveRefPointer
would be used when possible, and if not, an exception would be thrown.
Support Matrix
The following table summarizes the supported conversion between JSON Schema types and decoders.
| Type | Validation / Keyword | Status |
| :------------------ | :----------------------- | :----- |
| All Types | enum
| ✅ |
| | const
| ✅ |
| References | Basic Support | ✅ [1] |
| any
| Basic Support | ✅ |
| string
| Basic Support | ✅ |
| | minLength
| ✅ |
| | maxLength
| ✅ |
| | pattern
| ✅ |
| | format: "date-time
| ✅ |
| | format: "time
| - |
| | format: "date
| - |
| | format: "duration
| - |
| | format: "email
| ✅ |
| | format: "idn-email
| - |
| | format: "hostname
| ✅ |
| | format: "idn-hostname
| - |
| | format: "ipv4
| - |
| | format: "ipv6
| - |
| | format: "uuid
| ✅ |
| | format: "uri
| ✅ |
| | format: "uri-reference
| - |
| | format: "iri
| - |
| | format: "iri-reference
| - |
| integer
| Basic Support | ✅ |
| number
| Basic Support | ✅ |
| | multipleOf
| ✅ |
| | minimum
| ✅ |
| | maximum
| ✅ |
| | exclusiveMinimum
| ✅ |
| | exclusiveMaximum
| ✅ |
| boolean
| Basic Support | ✅ |
| null
| Basic Support | ✅ |
| array
| Basic Support | ✅ |
| | Unevaluated Items | - |
| | items
| ✅ |
| | prefixItems
| 🟨 [2] |
| | contains
| - |
| | minContains
| - |
| | maxContains
| - |
| | minItems
| ✅ |
| | maxItems
| ✅ |
| | uniqueItems
| ✅ |
| object
| Basic Support | ✅ [3] |
| | Unevaluated Properties | - |
| | Extending Closed Schemas | - |
| | properties
| ✅ |
| | additionalProperties
| ✅ |
| | required
| ✅ |
| | patternProperties
| ✅ |
| | propertyNames
| ✅ |
| | minProperties
| ✅ |
| | maxProperties
| ✅ |
| Schema Composition | allOf
| ✅ |
| | oneOf
| 🟨 [4] |
| | anyOf
| ✅ |
| | discriminator
| ✅ |
| Conditional Schemas | dependentRequired
| - |
| | dependentSchemas
| - |
| | if
| - |
| | then
| - |
| | else
| - |
Remarks:
[1] Implemented through a user-provided reference resolution function that returns the variable name of a previously defined decoder.
[2] Currently
prefixItems
cannot be used together withitems
. This means that declaring additional items for arrays is not supported.
[3] Note that while for
type: "object"
the JSON Schema spec indicates that "Using non-strings as keys is invalid JSON", the javascript implementation implicitly converts all properties to strings, so the decoders will always validate even numbers in the object keys.
[4] The
oneOf
is currently polyfilled with theanyOf
behaviour. This means that the "exactly one" validation is not respected.