npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

json-schema-to-decoders

v0.2.6

Published

A utility for converting JSON schema definition to decoders

Downloads

5,908

Readme

json-schema-to-decoders ci try-it npm

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 the json-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 with items. 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 the anyOf behaviour. This means that the "exactly one" validation is not respected.