feat: support draft2020 correctly (#9)

close ajv-validator/json-schema-migrate#7

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: JounQin

.changeset/seven-gifts-fold.md

@@ -0,0 +1,5 @@
+---
+"@unts/json-schema-migrate": minor
+---
+
+feat: support `draft2020` correctly - close [#7](https://github.com/ajv-validator/json-schema-migrate/issues/7)

package.json

@@ -88,7 +88,7 @@
     "prettier": "^3.5.3"
   },
   "typeCoverage": {
-    "atLeast": 91.75,
+    "atLeast": 92.1,
     "cache": true,
     "detail": true,
     "ignoreAsAssertion": true,

src/ajv.ts

@@ -0,0 +1,203 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+
+import { Ajv2019 } from 'ajv/dist/2019.js'
+import { Ajv2020 } from 'ajv/dist/2020.js'
+import type AjvCore from 'ajv/dist/core.js'
+import type {
+  AnySchema,
+  AnySchemaObject,
+  DataValidationCxt,
+} from 'ajv/dist/types/index.js'
+
+import { constantResultSchema, metaSchema } from './common.js'
+import type { SchemaVersion } from './types.js'
+
+const ajvCache: Partial<Record<'default' | 'draft2020', AjvCore.default>> = {}
+
+/**
+ * Retrieves an Ajv validator instance for a specified JSON Schema draft version.
+ *
+ * This function returns a cached Ajv instance if available, or creates a new one configured for either
+ * 'draft2019' (default) or 'draft2020'. The created instance is enhanced with a custom "migrateSchema" keyword
+ * that transforms JSON Schemas to be compatible with different specification drafts by adjusting properties
+ * such as "id", "$schema", "constant", "enum", and various numeric constraints.
+ *
+ * @param version - The target JSON Schema version (defaults to 'draft2019').
+ * @returns An Ajv instance configured for JSON Schema validation and migration.
+ *
+ * @remark The custom "migrateSchema" keyword may throw a TypeError if a schema's "id" is not a string, or an Error
+ * if the "id" format is invalid for the given version during the migration process.
+ */
+export function getAjv(version: SchemaVersion = 'draft2019') {
+  const isDraft2020 = version === 'draft2020'
+
+  const cacheKey = isDraft2020 ? 'draft2020' : 'default'
+
+  let ajv = ajvCache[cacheKey]
+
+  if (ajv) {
+    return ajv
+  }
+
+  ajv = new (isDraft2020 ? Ajv2020 : Ajv2019)({ allErrors: true })
+
+  ajv.addKeyword({
+    keyword: 'migrateSchema',
+    schemaType: 'string',
+    modifying: true,
+    metaSchema: { enum: ['draft7', 'draft2019', 'draft2020'] },
+    // eslint-disable-next-line sonarjs/cognitive-complexity
+    validate(
+      version: SchemaVersion,
+      schema: AnySchema,
+      _parentSchema?: AnySchemaObject,
+      dataCxt?: DataValidationCxt,
+    ) {
+      if (typeof schema != 'object') {
+        return true
+      }
+
+      if (dataCxt) {
+        const { parentData, parentDataProperty } = dataCxt
+        const valid = constantResultSchema(schema)
+        if (typeof valid == 'boolean') {
+          parentData[parentDataProperty] = valid
+          return true
+        }
+      }
+
+      const dsCopy = { ...schema }
+
+      for (const key in dsCopy) {
+        delete schema[key]
+        switch (key) {
+          case 'id': {
+            const { id } = dsCopy
+            if (typeof id !== 'string') {
+              throw new TypeError(
+                `json-schema-migrate: schema id must be string`,
+              )
+            }
+            if ((version === 'draft2019' || isDraft2020) && id.includes('#')) {
+              const [$id, $anchor, ...rest] = id.split('#')
+              if (rest.length > 0) {
+                throw new Error(`json-schema-migrate: invalid schema id ${id}`)
+              }
+              if ($id) {
+                schema.$id = $id
+              }
+              if ($anchor && $anchor !== '/') {
+                schema.$anchor = $anchor
+              }
+            } else {
+              schema.$id = id
+            }
+            break
+          }
+          case '$schema': {
+            schema.$schema = metaSchema(version)
+            break
+          }
+          case 'constant': {
+            schema.const = dsCopy.constant
+            break
+          }
+          case 'enum': {
+            if (
+              Array.isArray(dsCopy.enum) &&
+              dsCopy.enum.length === 1 &&
+              dsCopy.constant === undefined &&
+              dsCopy.const === undefined
+            ) {
+              schema.const = dsCopy.enum[0]
+            } else {
+              schema.enum = dsCopy.enum
+            }
+            break
+          }
+          case 'exclusiveMaximum': {
+            migrateExclusive(schema, key, 'maximum')
+            break
+          }
+          case 'exclusiveMinimum': {
+            migrateExclusive(schema, key, 'minimum')
+            break
+          }
+          case 'maximum': {
+            if (dsCopy.exclusiveMaximum !== true) {
+              schema.maximum = dsCopy.maximum
+            }
+            break
+          }
+          case 'minimum': {
+            if (dsCopy.exclusiveMinimum !== true) {
+              schema.minimum = dsCopy.minimum
+            }
+            break
+          }
+          case 'dependencies': {
+            const deps = dsCopy.dependencies as Record<string, unknown>
+            if (version === 'draft7') {
+              schema.dependencies = deps
+            } else {
+              for (const prop in deps) {
+                const kwd = Array.isArray(deps[prop])
+                  ? 'dependentRequired'
+                  : 'dependentSchemas'
+                schema[kwd] ||= {}
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                schema[kwd][prop] = deps[prop]
+              }
+            }
+            break
+          }
+          case 'items': {
+            if (isDraft2020 && Array.isArray(dsCopy.items)) {
+              schema.prefixItems = dsCopy.items
+              if (dsCopy.additionalItems !== undefined) {
+                schema.items = dsCopy.additionalItems
+              }
+            } else {
+              schema.items = dsCopy.items
+            }
+            break
+          }
+          case 'additionalItems': {
+            if (!isDraft2020) {
+              schema.additionalItems = dsCopy.additionalItems
+            }
+            break
+          }
+          case '$recursiveAnchor': {
+            if (isDraft2020) {
+              schema.$dynamicAnchor = 'meta'
+            } else {
+              schema.$recursiveAnchor = dsCopy.$recursiveAnchor
+            }
+            break
+          }
+          default: {
+            schema[key] = dsCopy[key]
+          }
+        }
+      }
+      return true
+
+      function migrateExclusive(
+        schema: AnySchemaObject,
+        key: string,
+        limit: string,
+      ): void {
+        if (dsCopy[key] === true) {
+          schema[key] = dsCopy[limit]
+        } else if (dsCopy[key] !== false && dsCopy[key] !== undefined) {
+          ajv!.logger.warn(`${key} is not boolean`)
+        }
+      }
+    },
+  })
+
+  ajvCache[cacheKey] = ajv
+
+  return ajv
+}

src/common.ts

@@ -0,0 +1,58 @@
+import type { AnySchemaObject } from 'ajv'
+
+import {
+  DRAFT_7_SCHEMA,
+  DRAFT_2019_SCHEMA,
+  DRAFT_2020_SCHEMA,
+} from './constants.js'
+import type { SchemaVersion } from './types.js'
+
+/**
+ * Recursively evaluates a JSON schema to determine if it reduces to a constant boolean value.
+ *
+ * An empty schema (i.e., an object with no keys) is considered to be a constant true schema.
+ * If the schema has only the "not" property, the function evaluates the value of "not" recursively
+ * and returns its logical negation when it resolves to a boolean.
+ *
+ * @param schema - The JSON schema object to evaluate.
+ * @returns A boolean indicating the constant result if determinable, or undefined if the schema's
+ *          boolean value cannot be established.
+ */
+export function constantResultSchema(
+  schema: AnySchemaObject,
+): boolean | undefined {
+  const keys = Object.keys(schema)
+  if (keys.length === 0) {
+    return true
+  }
+  if (keys.length === 1 && keys[0] === 'not') {
+    const valid = constantResultSchema(schema.not as AnySchemaObject)
+    if (typeof valid == 'boolean') {
+      return !valid
+    }
+  }
+}
+
+/**
+ * Returns the JSON meta-schema corresponding to the specified schema version.
+ *
+ * This function selects the appropriate meta-schema constant based on the provided version,
+ * mapping 'draft7', 'draft2019', and 'draft2020' to their respective meta-schema definitions.
+ * If an unrecognized version is provided, the function returns undefined.
+ *
+ * @param version - The JSON Schema version (e.g., 'draft7', 'draft2019', 'draft2020').
+ * @returns The meta-schema constant for the specified version, or undefined if the version is not supported.
+ */
+export function metaSchema(version: SchemaVersion) {
+  switch (version) {
+    case 'draft7': {
+      return DRAFT_7_SCHEMA
+    }
+    case 'draft2019': {
+      return DRAFT_2019_SCHEMA
+    }
+    case 'draft2020': {
+      return DRAFT_2020_SCHEMA
+    }
+  }
+}

src/constants.ts

@@ -0,0 +1,8 @@
+export const DRAFT_4_SCHEMA = 'http://json-schema.org/draft-04/schema'
+export const DRAFT_4_SCHEMA_ = 'http://json-schema.org/draft-04/schema#'
+
+export const DRAFT_7_SCHEMA = 'http://json-schema.org/draft-07/schema'
+export const DRAFT_7_SCHEMA_ = 'http://json-schema.org/draft-07/schema#'
+
+export const DRAFT_2019_SCHEMA = 'https://json-schema.org/draft/2019-09/schema'
+export const DRAFT_2020_SCHEMA = 'https://json-schema.org/draft/2020-12/schema'

src/helpers.ts

@@ -0,0 +1,48 @@
+import type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv'
+
+import { getAjv } from './ajv.js'
+import { metaSchema } from './common.js'
+import { DRAFT_2020_SCHEMA, DRAFT_2019_SCHEMA } from './constants.js'
+import type { SchemaVersion } from './types.js'
+
+/**
+ * Generates a migration schema object based on the specified version.
+ *
+ * This function constructs a schema object used for validating schema migrations. It selects between
+ * two draft schemas depending on whether the provided version is 'draft2020' or not, and returns an object
+ * with a unique `$id`, the chosen schema, and an `allOf` array that combines migration metadata with a reference
+ * to the base schema. For the 'draft2020' version, a `$dynamicAnchor` is added, whereas for other versions a
+ * `$recursiveAnchor` property is set.
+ *
+ * @param version - The migration schema version (e.g., 'draft2020').
+ * @returns The migration schema object configured for the supplied version.
+ */
+export function getMigrateSchema(version: SchemaVersion): SchemaObject {
+  const isDraft2020 = version === 'draft2020'
+  const schema = isDraft2020 ? DRAFT_2020_SCHEMA : DRAFT_2019_SCHEMA
+  return {
+    $id: `migrateSchema-${version}`,
+    $schema: schema,
+    allOf: [{ migrateSchema: version }, { $ref: schema }],
+    ...(isDraft2020 ? { $dynamicAnchor: 'meta' } : { $recursiveAnchor: true }),
+  }
+}
+
+/**
+ * Returns a schema migration function for the specified version.
+ *
+ * The returned function validates a provided schema against a migration schema and ensures its "$schema"
+ * property is set to the correct meta-schema for the given version. The migration validator is compiled
+ * on the first invocation and reused for subsequent validations.
+ *
+ * @param version - The schema version specifying which migration rules and meta-schema to use.
+ * @returns A function that, when given a schema object, validates it for migration and updates its "$schema" property.
+ */
+export function getMigrate(version: SchemaVersion) {
+  let migrate: ValidateFunction | undefined
+  return (schema: AnySchemaObject) => {
+    migrate ||= getAjv(version).compile(getMigrateSchema(version))
+    migrate(schema)
+    schema.$schema ||= metaSchema(version)
+  }
+}