Why Ajv?

[alecmev]

It's a good validator, but the ergonomics leave a bit to be desired. Just to demonstrate, here's the default graph schema for **/package.json rewritten with Zod:

Zod

import isSemVer from 'validator/lib/isSemVer';
import z from 'zod';

const PUBLIC = {
  version: z.string().refine(isSemVer, {
    message: 'Version must be a valid semantic version',
  }),
  main: z.string(),
  typings: z.never({
    invalid_type_error: '"typings" must only be set within the "publishConfig"',
  }),
  publishConfig: z
    .object({
      registry: z.string().optional(),
      main: z.string().optional(),
      module: z.string().optional(),
      typings: z.string().optional(),
      bin: z.union([z.string(), z.object({})]).optional(),
    })
    .optional(),
};

z.intersection(
  z.object({ name: z.string() }),
  z.discriminatedUnion('private', [
    z.object({
      private: z.literal(true),
      version: z.never({
        invalid_type_error: 'Private packages must not have version numbers',
      }),
    }),
    z.object({ private: z.literal(false) }).extend(PUBLIC),
    z.object({ private: z.undefined() }).extend(PUBLIC),
  ]),
)

And here's the original:

JSON Schema

{
  type: "object",
  $required: true,
  properties: {
    name: { type: "string" },
    main: { type: "string" },
  },
  required: ["name"],
  if: {
    properties: {
      private: { type: "boolean", enum: [true] },
    },
    required: ["private"],
    errorMessage: {},
  },
  then: {
    properties: {
      version: {
        not: {},
        errorMessage: {
          _: "Private packages must not have version numbers.",
        },
      },
      typings: { type: "string" },
    },
  },
  else: {
    properties: {
      typings: {
        not: {},
        errorMessage: '"typings" must only be set withing the "publishConfig"',
      },
      publishConfig: {
        type: "object",
        properties: {
          registry: { type: "string" },
          main: { type: "string" },
          module: { type: "string" },
          typings: { type: "string" },
          bin: { oneOf: [{ type: "string" }, { type: "object" }] },
        },
      },
      version: {
        type: "string",
        // Official semver regex https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
        pattern:
          "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
        errorMessage: {
          pattern: "Version must be a valid semantic version.",
        },
      },
    },
    required: ["version", "main"],
  },
}

The Zod version is actually not much more concise, and I was disappointed to find out that discriminatedUnion doesn't accept unions as discriminators (hence the PUBLIC stuff; union works but produces worse errors). However, it's arguably easier to read (as it's closer to what a TypeScript type would look like), and, most importantly to me, personally, it's much easier to author, as it's typed through and through.

There are many alternatives. If performance is a concern, there's at least TypeBox.

What are your thoughts?

Edit:

Using this for now:

import type { PartialSchema } from 'ajv/dist/types/json-schema';
import type { GraphSchemaValidators } from 'onerepo';
import type { PackageJson } from 'type-fest';

export default {
  '**': {
    'package.json': {
      // ...
    } satisfies PartialSchema<PackageJson>,
  },
} satisfies GraphSchemaValidators;

Not perfect, as it has [keyword: string]: any in its signature, unfortunately (probably to accommodate ajv-errors and such), but at least some code completion.

[paularmstrong]

I love zod! AJV was chosen many years ago before zod was ever a thing and because it uses an actual standard.

I'd be happy to re-evaluate this with some more discussion, but either:

1. It would have to wait for a major release (which is not planned for a long time yet)
2. (or) There would need to be a way to signal whether to use AJV or Zod for validation.

[alecmev]

I finished porting the package.json part of our Yarn constraints to JSON Schema, and it's actually not that bad. Sharing the end result, maybe it'll inspire somebody:

graph-schema.ts

/* eslint-disable unicorn/no-thenable */

import type { PartialSchema } from 'ajv/dist/types/json-schema';
import type { GraphSchemaValidators } from 'onerepo';
import type { PackageJson } from 'type-fest';

export default {
  '**': {
    'package.json': {
      type: 'object',
      $required: true,
      properties: {
        name: { type: 'string' },
        private: { const: true },
        version: { type: 'string' },
        type: { const: 'module' },
        exports: { const: './dist/index.js' },
        types: { const: './dist/index.d.ts' },
        bin: { type: 'string' },
        files: {
          type: 'array',
          items: [
            { const: 'dist' },
            { const: 'src/**/*.ts' },
            { const: 'src/**/*.tsx' },
            { const: '!dist/.tsbuildinfo' },
            { const: '!**/*.test*' },
            { const: '!**/test-*' },
          ],
          minItems: 6,
          additionalItems: false,
        },
        sideEffects: { const: false },
        repository: { const: 'orangelv/blocks' },
        main: { not: {} },
        typings: { not: {} },
        publishConfig: { not: {} },
        scripts: { not: {} },
      },
      required: ['name'],
      if: { properties: { name: { const: '@orangelv/blocks' } } },
      then: { required: ['private'] },
      else: {
        allOf: [
          {
            if: { required: ['private'] },
            then: {
              properties: {
                version: { not: {} },
                files: { not: {} },
                repository: { not: {} },
              },
            },
            else: { required: ['version', 'files', 'repository'] },
          },
          {
            if: { required: ['type'] },
            then: { anyOf: [{ required: ['exports'] }, { required: ['bin'] }] },
            else: { properties: { exports: { not: {} }, bin: { not: {} } } },
          },
          {
            if: { required: ['exports'] },
            then: { required: ['types', 'sideEffects'] },
            else: {
              properties: { types: { not: {} }, sideEffects: { not: {} } },
            },
          },
        ],
      },
    } satisfies PartialSchema<PackageJson>,
  },
} satisfies GraphSchemaValidators;

[paularmstrong]

Nice! Thanks for sharing… I also have quite a few of these, but haven't figured out a good way to share them yet. Maybe a section in the docs?

[alecmev]

I would definitely appreciate more links to "prior art" throughout the docs, I think studying real-world usage is the best way to learn. However, dedicated isolated examples is probably the way to go, since real-world requirements tend to drift 😛 But yeah, once oneRepo catches on, a "Used by" section would be awesome. My main documentation for Turbo was this sheet, for example 😄 And this search. Same for Yarn constraints.

[alecmev]

Re JSON Schema - one small wish I have is for JSONSchema7 from @types/json-schema to be combined with ajv-errors and used as the schema type. It isn't possible without copy-paste right now, but could probably be done if the types were adjusted to use this | boolean in place of JSONSchema7Definition. Then, I think, it's just a simple extends.