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

@bscotch/schema-builder

v0.1.0-dev.2

Published

Tools for creating and managing JSON Schemas.

Downloads

1

Readme

SchemaBuilder (@bscotch/schema-builder)

SchemaBuilder is built on top of TypeBox to make it easier to build self-contained, complex schemas and reusable schema libraries, with complete Typescript support along the way.

⚠ In early development. Unstable, incomplete, and subject to dramatic change. ⚠

⚡ Quick Start

See the TypeBox docs for the core concepts and features, since SchemaBuilder builds upon those. In particular, this package provides a SchemaBuilder class which extends the TypeBuilder class from TypeBox (the Type export from TypeBox is a TypeBuilder instance.)

Install: npm install @bscotch/schema-builder

Then build your schema:

import {
  SchemaBuilder,
  Static,
  StaticDefs
} from '@bscotch/schema-builder';

// SchemaBuilder makes heavy use of chaining, and of using callback
// functions to provide Schemas, so that your `this` type stays
// up to date as you change your SchemaBuilder instance.

// Create a definitions library for re-usability. Related or cross-
// referencing definitions can be collected by a single `SchemaBuilder`
// instance for convenience.
const lib = new SchemaBuilder().addDefinition('aString', function () {
  // By using a callback function, `this` refers to the current
  // SchemaBuilder instance.
  return this.String();
});

// Create a complex schema, starting by importing the definitions
// stored by the `lib` SchemaBuilder instance we just made.
const mySchema = new SchemaBuilder({ lib })
  .use(function () {
    // Using a callback via the `.use()` method lets
    // you use the `this` keyword to refer to the current SchemaBuilder
    // instance, with full type support for any definitions or other
    // changes made to the instance.
    return this.addDefinition('nums', this.LiteralUnion([1, 2, 3]))
      .addDefinition('moreNums', this.Array(this.Number()))
      .addDefinition('deeper', function () {
        return this.Object({
          deepArray: this.Array(this.DefRef('nums')),
          libRef: this.Array(this.DefRef('aString')),
        });
      });
  })
  // Most function return an updated `this`, so that the return type
  // includes changes made to the SchemaBuilder instance.
  .setRoot('deeper');

// Get the root schema as a Typescript interface, which can
// be used for static validation and intellisense.
type MySchema = Static<typeof mySchema>;
// {
//     deepArray: (1|2|3)[];
//     libRef: string[];
// }

// Get the defs library as a Typescript interface
type MySchemaDefs = StaticDefs<typeof mySchema>;
// {
//     aString: string;
//     nums: 2 | 1 | 3;
//     moreNums: StaticArray<TNumber>;
//     deeper: {
//         deepArray: StaticArray<TRef<TLiteralUnion<[1, 2, 3]>>>;
//         libRef: StaticArray<...>;
//     };
// }

// Validate data against the schema
const data: MySchema = {
  deepArray: [2, 3],
  libRef: ['hello']
};

mySchema.assertIsValid(data);

// Save the schema to disk
mySchema.writeSchemaSync('mySchema.json');

What is JSON Schema?

JSON Schema is a specification for describing data structures, and it is incredibly useful for solving several problems simultaneously:

  • Data structure description (machine-readable, allows for use of generic solutions for specific data problems)
  • Data description/documentation (human-readable)
  • Data validation (machine-readable, reduces need for additional test-writing)

By solving this all at the same time, in one place, developers can dramatically reduce the amount of code they need to write and thus reduce errors and increase productivity.

What problems does SchemaBuilder solve?

Schema authoring is hard and error-prone

JSON Schema is a pain to write since any given schema is itself a complex data structure, and JSON Schema has strict rules that schema authors must follow to create valid, useful schemas.

Various tools exist to help with this, including using YAML instead of JSON for better human-readability, intellisense in editors like Visual Studio Code, and various libraries in the JavaScript ecosystem for programmatically creating schemas with varying amounts of Typescript support.

Prior Art

Typescript + JSON Schema

Typescript tries to solve many of the same problems that JSON Schema does, at least for JSON-compatible data structures. There are a few libraries that try to use Typescript to infer Schemas or vice versa:

  • TypeBox: Create a Schema and corresponding Typescript types at the same time. This reduces duplicate effort, and is the basis for SchemaBuilder.
  • typescript-json-schema: Create a Schema from Typescript types.
  • json-schema-to-typescript: Exactly the opposite! Create a Typescript interface from a JSON Schema.

Validators

The primary use case for JSON Schema is in building data validators. As such, there are many libraries/modules providing related functionality:

  • ajv: Easily the most popular validator. Well tested, with plenty of extended functionality on top of canonical JSON Schema.
  • jsonschema: A popular validator that still offers significant flexibility for feature extension, including mutation of data during parsing, but is less feature-rich than ajv.
  • z-schema: Robust and popular validator. Appears to be restricted to JSON Schema spec.
  • json-schema-faker: Generates fake data based on a schema. Useful for testing.

Parsers & Serializers

JSON Schemas describe data, and so can be used to programmatically parse and serialize corresponding data.

  • fast-json-stringify: A JSON stringifier that makes use of a corresponding JSON Schema to precompile a stringifier that is much faster than the general JSON.stringify function.

Misc. Schema tools

JSON Schemas can be difficult to create and understand, and there are various tools out there for simplifying their use:

  • json-schema-traverse: Call functions on each subschema of a JSON Schema.
  • json-schema-ref-parser: Utilities for de-referencing $refs in JSON Schemas, including the ability to convert such a schema into one with internal references.