ata-validator 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 0.16.0 - 2026-05-23
+
+### Added
+
+- `defineSchema` helper and the exported `JSONSchema` type. Wrap a plain schema object in `defineSchema(...)` to author it inline in TypeScript with keyword autocomplete and value checking, no `as const` needed. It is an identity function at runtime, so the returned object drops straight into `Validator`, `toStandaloneModule`, and the rest of the API. Requires TypeScript >= 5.0 for the `const` type parameter.
+- OpenAPI `nullable` keyword. `{ type: 'string', nullable: true }` accepts `null` alongside the declared type, matching OpenAPI 3.0 schemas.
+
+### Fixed
+
+- `coerceTypes` with `type: 'array'` wraps a scalar into a single-element array instead of leaving it unchanged.
+- Codegen resolves a `$defs` entry that carries a fragment `$id` and is reached through a pointer `$ref`.
+- Preprocessing (defaults, coercion, `removeAdditional`) guards against `null` and non-object data instead of throwing.
+
 ## 0.15.1 - 2026-05-23
 
 ### Fixed

package/README.md

@@ -158,6 +158,28 @@ if (result.valid) {
 
 The same pattern works with Zod-from-JSON-Schema, Valibot, or a hand-written `type User = {...}` alongside a JSON Schema literal. `Validator<T>` makes no library-specific assumption.
 
+#### Authoring a schema inline: `defineSchema`
+
+If you would rather write a plain JSON Schema object than reach for a schema library, wrap it in `defineSchema`. It returns the schema untouched at runtime, but in TypeScript it gives you keyword autocomplete and an error when a value has the wrong shape, with no `as const` needed.
+
+```ts
+import { defineSchema, Validator } from 'ata-validator'
+
+const userSchema = defineSchema({
+  type: 'object',
+  properties: {
+    id: { type: 'integer', minimum: 1 },
+    role: { type: 'string', enum: ['admin', 'user'] },
+  },
+  required: ['id'],
+})
+
+// type: 123 or required: 'id' would be a compile error here.
+const v = new Validator(userSchema)
+```
+
+The exported `JSONSchema` type is also available directly if you want to annotate a schema yourself. Custom and vendor keywords are allowed, so exotic schemas still type-check. Requires TypeScript >= 5.0.
+
 ### Cross-Schema `$ref`
 
 ```javascript

package/index.d.ts

@@ -75,6 +75,95 @@ export function renderJSON(errors: RichValidationError[], opts?: JSONRenderOptio
 /** A user-supplied format checker. Receives the candidate value, returns true if valid. */
 export type FormatChecker = (value: string) => boolean;
 
+/** The seven primitive `type` values defined by JSON Schema. */
+export type JSONSchemaTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null';
+
+/**
+ * A hand-written type for authoring JSON Schema (draft 2020-12) objects inline
+ * in TypeScript. Known keywords are typed, so you get autocomplete and an error
+ * when a value has the wrong shape (e.g. `type: 123` or `required: 'id'`).
+ * Unknown keywords are permitted, so custom/vendor keywords do not error.
+ *
+ * Pair it with {@link defineSchema} for inline authoring without `as const`.
+ */
+export interface JSONSchema {
+  $id?: string;
+  $schema?: string;
+  $ref?: string;
+  $defs?: Record<string, JSONSchema>;
+  definitions?: Record<string, JSONSchema>;
+  $comment?: string;
+
+  type?: JSONSchemaTypeName | JSONSchemaTypeName[];
+  enum?: ReadonlyArray<unknown>;
+  const?: unknown;
+
+  title?: string;
+  description?: string;
+  default?: unknown;
+  examples?: ReadonlyArray<unknown>;
+  deprecated?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+
+  // object
+  properties?: Record<string, JSONSchema>;
+  required?: ReadonlyArray<string>;
+  additionalProperties?: boolean | JSONSchema;
+  patternProperties?: Record<string, JSONSchema>;
+  propertyNames?: JSONSchema;
+  minProperties?: number;
+  maxProperties?: number;
+  dependentRequired?: Record<string, ReadonlyArray<string>>;
+  dependentSchemas?: Record<string, JSONSchema>;
+
+  // array
+  items?: JSONSchema | ReadonlyArray<JSONSchema>;
+  prefixItems?: ReadonlyArray<JSONSchema>;
+  additionalItems?: boolean | JSONSchema;
+  contains?: JSONSchema;
+  minContains?: number;
+  maxContains?: number;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+
+  // string
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+
+  // number
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+
+  // composition
+  allOf?: ReadonlyArray<JSONSchema>;
+  anyOf?: ReadonlyArray<JSONSchema>;
+  oneOf?: ReadonlyArray<JSONSchema>;
+  not?: JSONSchema;
+  if?: JSONSchema;
+  then?: JSONSchema;
+  else?: JSONSchema;
+
+  /** OpenAPI compatibility: ata honors `nullable` as a JSON Schema extension. */
+  nullable?: boolean;
+
+  /** Custom and vendor keywords are allowed without error. */
+  [keyword: string]: unknown;
+}
+
 export type ValidationResult<T = unknown> =
   | { valid: true;  data: T;       errors: ValidationError[] }
   | { valid: false; data?: never;  errors: ValidationError[] };
@@ -253,3 +342,25 @@ export const SIMDJSON_PADDING: number;
  * build-time integrations (Vite plugin, custom build steps).
  */
 export function toTypeScript(schema: object, options?: { name?: string }): string;
+
+/**
+ * Authoring helper for writing a JSON Schema inline in TypeScript. Returns the
+ * schema unchanged at runtime; its purpose is to apply the {@link JSONSchema}
+ * type so you get keyword autocomplete and an error on malformed values, while
+ * the `const` type parameter preserves the literal shape (no `as const` needed).
+ *
+ * ```ts
+ * import { defineSchema, Validator } from 'ata-validator';
+ *
+ * const user = defineSchema({
+ *   type: 'object',
+ *   properties: { id: { type: 'integer', minimum: 1 } },
+ *   required: ['id'],
+ * });
+ *
+ * const v = new Validator(user);
+ * ```
+ *
+ * Requires TypeScript >= 5.0 for the `const` type parameter.
+ */
+export declare function defineSchema<const S extends JSONSchema>(schema: S): S;

package/index.js

@@ -8,7 +8,7 @@ const {
   compileToJSCodegenWithErrors,
   compileToJSCombined,
 } = require("./lib/js-compiler");
-const { normalizeDraft7 } = require("./lib/draft7");
+const { normalizeDraft7, normalizeNullable } = require("./lib/draft7");
 const { classify } = require("./lib/shape-classifier");
 const { buildTier0Plan, tier0Validate } = require("./lib/tier0");
 
@@ -242,6 +242,8 @@ function buildPreprocessCodegen(schema, options) {
       } else if (t === 'boolean') {
         lines.push(`if(d[${k}]==='true'||d[${k}]==='1')d[${k}]=true`);
         lines.push(`if(d[${k}]==='false'||d[${k}]==='0')d[${k}]=false`);
+      } else if (t === 'array' && options.coerceTypes === 'array') {
+        lines.push(`if(${k} in d&&d[${k}]!==undefined&&!Array.isArray(d[${k}]))d[${k}]=[d[${k}]]`);
       }
     }
   }
@@ -256,6 +258,9 @@ function buildPreprocessCodegen(schema, options) {
   }
 
   if (lines.length === 0) return null;
+  // Data may legitimately be null or a non-object (e.g. a `['object','null']`
+  // schema), so the per-property mutations must not run on it.
+  lines.unshift(`if(d===null||typeof d!=='object')return`);
   try {
     return new Function('d', lines.join('\n'));
   } catch {
@@ -350,6 +355,7 @@ function buildSchemaMap(schemas) {
   if (Array.isArray(schemas)) {
     for (const s of schemas) {
       normalizeDraft7(s)
+      normalizeNullable(s)
       const id = s.$id
       if (!id) throw new Error('Schema in schemas option must have $id')
       map.set(id, s)
@@ -357,6 +363,7 @@ function buildSchemaMap(schemas) {
   } else {
     for (const [key, s] of Object.entries(schemas)) {
       normalizeDraft7(s)
+      normalizeNullable(s)
       map.set(s.$id || key, s)
     }
   }
@@ -459,6 +466,8 @@ class Validator {
 
     // Draft 7 normalization — convert keywords to 2020-12 equivalents in-place
     normalizeDraft7(schemaObj);
+    // OpenAPI nullable -> type union with 'null'
+    normalizeNullable(schemaObj);
 
     this._schemaStr = null; // lazy: computed on first use
     this._schemaObj = schemaObj;
@@ -1074,6 +1083,7 @@ class Validator {
     }
     // Apply Draft 7 normalization if needed
     normalizeDraft7(schema)
+    normalizeNullable(schema)
     this._schemaMap.set(schema.$id, schema)
   }
 
@@ -1642,6 +1652,14 @@ function attachSuggestions (errors, data) {
   return errors;
 }
 
+// Authoring helper: identity at runtime. Its only job is to attach the
+// JSONSchema type (see index.d.ts) to an inline schema object so TypeScript
+// gives autocomplete and value checking while authoring. Returns the schema
+// untouched so it can be passed straight to Validator, toStandaloneModule, etc.
+function defineSchema (schema) {
+  return schema;
+}
+
 module.exports = {
   Validator,
   compile,
@@ -1651,6 +1669,7 @@ module.exports = {
   SIMDJSON_PADDING,
   parseJSON,
   toTypeScript,
+  defineSchema,
   renderPretty,
   renderCompact,
   renderJSON,

package/index.mjs

@@ -1,3 +1,3 @@
 import mod from './index.js';
-export const { Validator, validate, version, createPaddedBuffer, SIMDJSON_PADDING, renderPretty, renderCompact, renderJSON } = mod;
+export const { Validator, validate, version, createPaddedBuffer, SIMDJSON_PADDING, defineSchema, renderPretty, renderCompact, renderJSON } = mod;
 export default mod;

package/lib/draft7.js

@@ -79,4 +79,51 @@ function _normalize(schema) {
   }
 }
 
-module.exports = { isDraft7, normalizeDraft7 }
+// OpenAPI `nullable: true` is not JSON Schema. Convert it to a union with
+// 'null' (`{ type: 'X', nullable: true }` -> `{ type: ['X', 'null'] }`), the
+// same shape AJV produces under its `nullable` option. Recurses only through
+// schema-bearing keywords so it never touches data values (default, const, etc.).
+function normalizeNullable(schema) {
+  if (typeof schema !== 'object' || schema === null) return schema
+  _normalizeNullable(schema)
+  return schema
+}
+
+function _normalizeNullable(schema) {
+  if (typeof schema !== 'object' || schema === null) return
+
+  if (schema.nullable === true && schema.type !== undefined) {
+    if (Array.isArray(schema.type)) {
+      if (!schema.type.includes('null')) schema.type = schema.type.concat('null')
+    } else {
+      schema.type = [schema.type, 'null']
+    }
+  }
+  if ('nullable' in schema) delete schema.nullable
+
+  const objSubs = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']
+  for (const key of objSubs) {
+    if (schema[key] && typeof schema[key] === 'object') {
+      for (const v of Object.values(schema[key])) {
+        if (typeof v === 'object' && v !== null) _normalizeNullable(v)
+      }
+    }
+  }
+  const arrSubs = ['allOf', 'anyOf', 'oneOf', 'prefixItems']
+  for (const key of arrSubs) {
+    if (Array.isArray(schema[key])) {
+      for (const s of schema[key]) {
+        if (typeof s === 'object' && s !== null) _normalizeNullable(s)
+      }
+    }
+  }
+  const singleSubs = ['items', 'contains', 'not', 'if', 'then', 'else',
+                       'additionalProperties', 'propertyNames', 'unevaluatedItems', 'unevaluatedProperties']
+  for (const key of singleSubs) {
+    if (typeof schema[key] === 'object' && schema[key] !== null) {
+      _normalizeNullable(schema[key])
+    }
+  }
+}
+
+module.exports = { isDraft7, normalizeDraft7, normalizeNullable }

package/lib/js-compiler.js

@@ -690,6 +690,23 @@ function canResolveDynamicRefs(target, callingSchema, schemaMap) {
 
 // Recursively check if a schema can be safely compiled to JS codegen.
 // Returns false if any sub-schema contains features codegen gets wrong.
+// Does the schema (recursively) contain an anchor-style `$ref` equal to anchorId
+// (e.g. `$ref: '#address'`)? Used to keep codegen away from anchor refs it can't
+// resolve in the combined/error paths.
+function schemaHasAnchorRef(node, anchorId) {
+  if (!node || typeof node !== 'object') return false
+  if (Array.isArray(node)) {
+    for (const x of node) if (schemaHasAnchorRef(x, anchorId)) return true
+    return false
+  }
+  if (node.$ref === anchorId) return true
+  for (const k in node) {
+    if (k === '$ref') continue
+    if (schemaHasAnchorRef(node[k], anchorId)) return true
+  }
+  return false
+}
+
 function codegenSafe(schema, schemaMap) {
   if (typeof schema === 'boolean') return true
   if (typeof schema !== 'object' || schema === null) return true
@@ -799,7 +816,15 @@ function codegenSafe(schema, schemaMap) {
       if (/[~/"']/.test(name)) return false // special chars in def name
       if (typeof def === 'boolean') return false
       if (typeof def === 'object' && def !== null) {
-        if (def.$id) return false // $id in $defs creates new resolution scope — bail
+        // A non-fragment $id (e.g. 'sub.json', 'http://...') opens a new base URI
+        // scope — bail. A fragment-only $id ('#name') is a draft-07 anchor; it is
+        // safe to codegen when reached by JSON pointer (#/definitions/name), but the
+        // combined/error codegen paths do not resolve anchor refs (`$ref: '#name'`)
+        // to it, so bail if the schema anchor-references this def.
+        if (def.$id) {
+          if (!def.$id.startsWith('#')) return false
+          if (schemaHasAnchorRef(schema, def.$id)) return false
+        }
         if (def.$ref) return false // nested ref chain — bail
         if (!codegenSafe(def, schemaMap)) return false
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile to per-schema ESM modules with zero validator dependency. Generic Validator<T> for TypeBox/Zod/Valibot composition. Optional runtime API. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
@@ -42,7 +42,7 @@
     "rebuild": "cmake-js rebuild --target ata",
     "prebuild": "pkg-prebuilds-copy --baseDir build/Release --source ata.node --name=ata --strip --napi_version=10",
     "prebuild-all": "npm run prebuild -- --arch x64 && npm run prebuild -- --arch arm64",
-    "test": "node test.js && node tests/test_no_native.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_typed_validator_runner.js && node tests/test_error_codes_lock.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node benchmark/bench_aot_size.mjs",
+    "test": "node test.js && node tests/test_no_native.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_nullable.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node benchmark/bench_aot_size.mjs",
     "bench:size": "node benchmark/bench_aot_size.mjs",
     "test:suite": "node tests/run_suite.js",
     "test:compat": "node tests/test_compat.js",