@empyria/common 0.2.0 → 0.3.1

package/README.md

@@ -41,14 +41,14 @@ import { defineSchema } from '@empyria/common/lib/Ata.js'
 
 ## Modules
 
-| Module                                 | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [index.js](./index.js)                 | Package entry point; re-exports every module below plus Moleculer meta helpers (`moleculerMeta`, `moleculerEmpyriaMeta`) and workflow ID helpers (`workflowName`, `workflowId`, `identifyWorkflow`).                                                                                                                                                                                                                                              |
-| [lib/Errors.js](./lib/Errors.js)       | `EmpyriaError`, the `ErrorCreator` factory, and `BaseErrors` — Empyria's catalog of pre-built, templated errors.                                                                                                                                                                                                                                                                                                                                  |
-| [lib/Env.js](./lib/Env.js)             | `createEnv` — builds a service's environment-variable JSON schema from Empyria-wide defaults; pass `{ closed: true }` to reject undeclared vars and bind `{ coerceTypes, removeAdditional }` to the schema.                                                                                                                                                                                                                                       |
-| [lib/Ata.js](./lib/Ata.js)             | JSON schema building blocks (`string`, `number`, `bool`, `enumType`, `email`, `password`, `ip4`, `ip6`, ...) and validation — throwing (`defineSchema`, `createValidator`, `validate`), transform-intent aliases (`parse`, `createParser`), or non-throwing/structured (`createChecker`, `checkSchema`, now returning the parsed `data`) — built on [ata-validator](https://www.npmjs.com/package/ata-validator). See _Validation options_ below. |
-| [lib/Codogram.js](./lib/Codogram.js)   | `generateCodogram` — one-time challenge codes (PIN, alphanumeric, alphabetic) for SMS/TOTP-style verification flows.                                                                                                                                                                                                                                                                                                                              |
-| [lib/Defaulter.js](./lib/Defaulter.js) | `defaultsFromSchema` — builds a fully-populated default object for a JSON schema.                                                                                                                                                                                                                                                                                                                                                                 |
+| Module                                 | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [index.js](./index.js)                 | Package entry point; re-exports every module below plus Moleculer meta helpers (`moleculerMeta`, `moleculerEmpyriaMeta`) and workflow ID helpers (`workflowName`, `workflowId`, `identifyWorkflow`).                                                                                                                                                                                                                                                                                                                      |
+| [lib/Errors.js](./lib/Errors.js)       | `EmpyriaError`, the `ErrorCreator` factory, and `BaseErrors` — Empyria's catalog of pre-built, templated errors.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| [lib/Env.js](./lib/Env.js)             | `createEnv` — builds a service's environment-variable JSON schema from Empyria-wide defaults; pass `{ closed: true }` to reject undeclared vars and bind `{ coerceTypes, removeAdditional }` to the schema.                                                                                                                                                                                                                                                                                                               |
+| [lib/Ata.js](./lib/Ata.js)             | JSON schema building blocks (`string`, `number`, `integer`, `bool`, `enumType`, `constant`, `nullable`, `array`, `discriminated`, `email`, `isoDateTime`, ...) and validation — throwing (`defineSchema`, `createValidator`, `validate`), transform-intent aliases (`parse`, `createParser`), or non-throwing/structured (`createChecker`, `checkSchema`, now returning the parsed `data`) — built on [ata-validator](https://www.npmjs.com/package/ata-validator). See _Schema builders_ and _Validation options_ below. |
+| [lib/Codogram.js](./lib/Codogram.js)   | `generateCodogram` — one-time challenge codes (PIN, alphanumeric, alphabetic) for SMS/TOTP-style verification flows.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [lib/Defaulter.js](./lib/Defaulter.js) | `defaultsFromSchema` — builds a fully-populated default object for a JSON schema.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 Every exported function is documented with JSDoc directly in its source file — hovering
 a function in VSCode or Zed shows its parameters and return type without any extra
@@ -90,6 +90,37 @@ copy when the caller must keep its input pristine (as the `env.js` files do with
 intent is to transform rather than merely assert. `createChecker` / `checkSchema` now also
 return `data` (the parsed value on success, `undefined` on failure).
 
+## Schema builders
+
+Each returns a plain JSON Schema fragment; compose them in `defineSchema(map, opts)`.
+
+| Builder                                                                                 | Produces                                                                                    |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `bool(default?)`                                                                        | `{ type: 'boolean' }`                                                                       |
+| `string(default?, minLength \| { minLength, maxLength, pattern, format, description })` | `{ type: 'string', … }`                                                                     |
+| `number(default?, { min, max, exclusiveMin, exclusiveMax, multipleOf, description })`   | `{ type: 'number', … }`                                                                     |
+| `integer(default?, …)`                                                                  | `{ type: 'integer', … }` — use for ports/counts; rejects `3.5`                              |
+| `enumType(list, default?, { type, description })`                                       | `{ enum, type? }`                                                                           |
+| `constant(value, { description })`                                                      | `{ const: value }`                                                                          |
+| `nullable(schema)`                                                                      | `type: [t, 'null']`, or `{ anyOf: [schema, { type: 'null' }] }`                             |
+| `array(items?, { minItems, maxItems, uniqueItems, default, description })`              | `{ type: 'array', … }`                                                                      |
+| `email() / password() / ip4() / ip6()`                                                  | `{ type: 'string', format: 'empyria-*' }` (see `EMPYRIA_FORMATS`)                           |
+| `isoDateTime() / isoDate() / isoTime() / duration() / uri() / uuid()`                   | `{ type: 'string', format: … }` (ata built-in formats)                                      |
+| `logLevel() / nodeEnv() / tmpFile() / logFile()`                                        | domain presets                                                                              |
+| `discriminated(prop, { value: schema, … }, { description })`                            | JSON Schema **v1** `propertyDependencies` — an object whose shape depends on `prop`'s value |
+
+### Dialect
+
+`defineSchema(map, { dialect: 'v1' \| '2020-12' \| 'draft-07' \| <uri> })` stamps `$schema`
+(`ata-validator` reads it to pick the dialect). `setDefaultDialect('v1')` / `getDefaultDialect()`
+set a process-wide default a per-call `dialect` overrides. v1 differs from 2020-12 only in
+`$dynamicRef` scoping and unlocks `propertyDependencies`; `discriminated()` works on any
+dialect (ata supports the keyword as an extension) but `dialect: 'v1'` makes it spec-legitimate.
+
+`defineSchema(map, { strict: 'unevaluated' })` sets `unevaluatedProperties: false` while
+leaving `additionalProperties` open — the composable form of strict, for schemas meant to be
+`allOf`-combined.
+
 ## Scripts
 
 ```bash

package/lib/Ata.js

@@ -63,6 +63,42 @@ export const EMPYRIA_FORMATS = {
 /** Non-enumerable key under which {@link defineSchema} stashes a schema's bound options. */
 const SCHEMA_OPTIONS = Symbol('ataOptions')
 
+/**
+ * Known JSON Schema dialect URIs, keyed by short name. `defineSchema({ dialect })` accepts a
+ * short name or a raw URI and stamps it as the schema's `$schema`. `ata-validator` reads
+ * `$schema` to pick the dialect; `'v1'` (the forthcoming IETF standard) differs from
+ * `'2020-12'` only in `$dynamicRef` scoping and unlocks `propertyDependencies` (see
+ * {@link discriminated}).
+ */
+export const DIALECTS = {
+	'2020-12': 'https://json-schema.org/draft/2020-12/schema',
+	'draft-07': 'http://json-schema.org/draft-07/schema#',
+	v1: 'https://json-schema.org/v1',
+}
+
+/** Process-wide default dialect for {@link defineSchema}; `null` = emit no `$schema`. */
+let defaultDialect = null
+
+/**
+ * Sets the process-wide default dialect for {@link defineSchema} — the `$schema` it stamps
+ * when a call passes no `dialect` of its own. Call once at startup to move a service to a
+ * dialect (e.g. `'v1'`) without touching every schema.
+ * @param {('2020-12'|'draft-07'|'v1'|string|null)} [dialect=null] - Short name, raw URI, or
+ *   `null` to go back to emitting no `$schema`.
+ * @returns {void}
+ */
+export function setDefaultDialect(dialect = null) {
+	defaultDialect = dialect
+}
+
+/**
+ * Returns the process-wide default dialect (see {@link setDefaultDialect}).
+ * @returns {string|null}
+ */
+export function getDefaultDialect() {
+	return defaultDialect
+}
+
 /** Process-wide default `ata-validator` options; the base layer for every call here. */
 let libraryDefaults = {}
 
@@ -137,12 +173,17 @@ export function cloneBySchema(schema) {
  * Builds a JSON schema object from a flat map of property schemas.
  * @param {Object} schemaDef - Map of property name to its JSON schema.
  * @param {Object} [options={}]
- * @param {boolean} [options.strict] - If true, disallows properties not listed in `schemaDef`
- *   (`additionalProperties: false`). Combine with `validation: { removeAdditional: true }` to
- *   *strip* unknown keys instead of rejecting them. Ignored when `options.additionalProperties`
- *   is given.
+ * @param {(boolean|'unevaluated')} [options.strict] - `true` disallows properties not listed
+ *   in `schemaDef` (`additionalProperties: false`); combine with
+ *   `validation: { removeAdditional: true }` to *strip* unknown keys instead of rejecting
+ *   them. `'unevaluated'` sets `unevaluatedProperties: false` and leaves `additionalProperties`
+ *   open — the composable form of strict, for a schema meant to be `allOf`-combined. Ignored
+ *   when `options.additionalProperties` is given.
  * @param {boolean|Object} [options.additionalProperties] - Explicit `additionalProperties`
  *   value (a boolean, or a sub-schema for the extra keys). Overrides `options.strict`.
+ * @param {('2020-12'|'draft-07'|'v1'|string)} [options.dialect] - Stamp this dialect as the
+ *   schema's `$schema` (short name from {@link DIALECTS}, or a raw URI). Defaults to
+ *   {@link getDefaultDialect}; when both are unset no `$schema` is emitted.
  * @param {boolean} [options.optional] - If true, a property whose own schema carries
  *   `optional: true` is excluded from `required` (that marker is then stripped from the
  *   property itself — never leaked into the resulting schema, since it isn't a real JSON
@@ -168,14 +209,19 @@ export function defineSchema(schemaDef, options = {}) {
 			required.push(key)
 		}
 	}
+	const unevaluated = options.strict === 'unevaluated'
 	const schema = {
 		type: 'object',
 		properties,
 		required,
 		additionalProperties: defined(options.additionalProperties)
 			? options.additionalProperties
-			: !options.strict,
+			: !options.strict || unevaluated,
 	}
+	if (unevaluated) schema.unevaluatedProperties = false
+
+	const dialect = options.dialect ?? defaultDialect
+	if (dialect) schema.$schema = DIALECTS[dialect] ?? dialect
 
 	if (options.validation) {
 		Object.defineProperty(schema, SCHEMA_OPTIONS, {
@@ -327,15 +373,26 @@ export function bool(defaultValue) {
 /**
  * JSON schema for a string property.
  * @param {string} [defaultValue] - Default value, if any.
- * @param {number} [minLength] - Minimum string length, if greater than 0.
- * @returns {Object} `{ type: 'string', default?, minLength? }`.
+ * @param {number|Object} [opts] - A bare number is shorthand for `{ minLength }` (kept for
+ *   back-compat). As an object:
+ * @param {number} [opts.minLength] - Minimum length (`0` is honoured, unlike the old
+ *   number-shorthand which dropped non-positive values).
+ * @param {number} [opts.maxLength] - Maximum length.
+ * @param {string} [opts.pattern] - `pattern` regex (string form, unanchored per JSON Schema).
+ * @param {string} [opts.format] - `format` name (e.g. an {@link EMPYRIA_FORMATS} key or a
+ *   built-in like `'uri'`; see {@link isoDateTime} & co. for ready-made wrappers).
+ * @param {string} [opts.description]
+ * @returns {Object} `{ type: 'string', default?, minLength?, maxLength?, pattern?, format?, description? }`.
  */
-export function string(defaultValue, minLength) {
-	const schema = {
-		type: 'string',
-	}
+export function string(defaultValue, opts) {
+	const o = typeof opts === 'number' ? { minLength: opts } : (opts ?? {})
+	const schema = { type: 'string' }
 	if (defined(defaultValue)) schema.default = `${defaultValue}`
-	if (minLength > 0) schema.minLength = minLength
+	if (defined(o.minLength) && o.minLength >= 0) schema.minLength = o.minLength
+	if (defined(o.maxLength)) schema.maxLength = o.maxLength
+	if (defined(o.pattern)) schema.pattern = o.pattern
+	if (defined(o.format)) schema.format = o.format
+	if (defined(o.description)) schema.description = o.description
 	return schema
 }
 
@@ -343,13 +400,19 @@ export function string(defaultValue, minLength) {
  * JSON schema for an enumerated property.
  * @param {Array} list - Allowed values.
  * @param {*} [defaultValue] - Default value, if any.
- * @returns {Object} `{ enum: list, default? }`.
+ * @param {Object} [opts]
+ * @param {string} [opts.type] - Optional `type` alongside `enum` (helps tooling / type
+ *   inference; validation is unchanged since `enum` already pins the values).
+ * @param {string} [opts.description]
+ * @returns {Object} `{ enum: list, type?, default?, description? }`.
  */
-export function enumType(list, defaultValue) {
+export function enumType(list, defaultValue, opts = {}) {
 	const schema = {
 		enum: list,
 	}
+	if (defined(opts.type)) schema.type = opts.type
 	if (defined(defaultValue)) schema.default = defaultValue
+	if (defined(opts.description)) schema.description = opts.description
 	return schema
 }
 
@@ -389,18 +452,151 @@ export function nodeEnv() {
 }
 
 /**
- * JSON schema for a numeric property.
+ * @param {'number'|'integer'} type
+ * @param {number} [defaultValue]
+ * @param {Object} [opts] - `min`/`max` (inclusive → `minimum`/`maximum`),
+ *   `exclusiveMin`/`exclusiveMax`, `multipleOf`, `description`.
+ * @returns {Object}
+ */
+function numeric(type, defaultValue, opts = {}) {
+	const schema = { type }
+	if (defined(defaultValue)) schema.default = Number(defaultValue)
+	if (defined(opts.min)) schema.minimum = opts.min
+	if (defined(opts.max)) schema.maximum = opts.max
+	if (defined(opts.exclusiveMin)) schema.exclusiveMinimum = opts.exclusiveMin
+	if (defined(opts.exclusiveMax)) schema.exclusiveMaximum = opts.exclusiveMax
+	if (defined(opts.multipleOf)) schema.multipleOf = opts.multipleOf
+	if (defined(opts.description)) schema.description = opts.description
+	return schema
+}
+
+/**
+ * JSON schema for a numeric property (`type: 'number'` — accepts integers and reals).
  * @param {number} [defaultValue] - Default value, if any.
- * @returns {Object} `{ type: 'number', default? }`.
+ * @param {Object} [opts] - `min`, `max`, `exclusiveMin`, `exclusiveMax`, `multipleOf`,
+ *   `description` (see {@link numeric}).
+ * @returns {Object} `{ type: 'number', default?, minimum?, maximum?, ... }`.
  */
-export function number(defaultValue) {
+export function number(defaultValue, opts) {
+	return numeric('number', defaultValue, opts)
+}
+
+/**
+ * JSON schema for an integer property (`type: 'integer'` — rejects `3.5`, and with
+ * `coerceTypes` rejects `"3.5"`). Prefer this over {@link number} for ports, counts, lengths.
+ * @param {number} [defaultValue] - Default value, if any.
+ * @param {Object} [opts] - Same as {@link number}.
+ * @returns {Object} `{ type: 'integer', default?, minimum?, maximum?, ... }`.
+ */
+export function integer(defaultValue, opts) {
+	return numeric('integer', defaultValue, opts)
+}
+
+/**
+ * JSON schema for a constant value (`const`). Useful as a discriminator tag or a pinned
+ * config value.
+ * @param {*} value - The only accepted value (compared structurally).
+ * @param {Object} [opts] - `description`.
+ * @returns {Object} `{ const: value, description? }`.
+ */
+export function constant(value, opts = {}) {
+	const schema = { const: value }
+	if (defined(opts.description)) schema.description = opts.description
+	return schema
+}
+
+/**
+ * Wraps a schema so `null` is also accepted. A schema with a single string `type` gets
+ * `type: [t, 'null']`; anything else (an `enum`, a `$ref`, a composed schema) is wrapped as
+ * `{ anyOf: [schema, { type: 'null' }] }`.
+ * @param {Object} schema - The schema to make nullable.
+ * @returns {Object}
+ */
+export function nullable(schema) {
+	if (schema && typeof schema.type === 'string') {
+		return { ...schema, type: [schema.type, 'null'] }
+	}
+	return { anyOf: [schema, { type: 'null' }] }
+}
+
+/**
+ * JSON schema for an array property.
+ * @param {Object} [items] - Schema every element must satisfy. Omit for "any element".
+ * @param {Object} [opts] - `minItems`, `maxItems`, `uniqueItems` (boolean), `default`,
+ *   `description`.
+ * @returns {Object} `{ type: 'array', items?, minItems?, maxItems?, uniqueItems?, default?, description? }`.
+ */
+export function array(items, opts = {}) {
+	const schema = { type: 'array' }
+	if (defined(items)) schema.items = items
+	if (defined(opts.minItems)) schema.minItems = opts.minItems
+	if (defined(opts.maxItems)) schema.maxItems = opts.maxItems
+	if (opts.uniqueItems) schema.uniqueItems = true
+	if (defined(opts.default)) schema.default = opts.default
+	if (defined(opts.description)) schema.description = opts.description
+	return schema
+}
+
+/**
+ * JSON Schema v1 `propertyDependencies`: an object that takes a different shape depending on
+ * the value of a discriminator property. Replaces the `oneOf` + `if`/`then`/`const` pattern.
+ * Validates on every `ata-validator` engine (supported since 1.5.0); pair with
+ * `defineSchema`'s `dialect: 'v1'` — or `setDefaultDialect('v1')` — for a spec-legitimate
+ * `$schema`.
+ * The result is open (`additionalProperties` unset): `additionalProperties: false` cannot be
+ * used alongside `propertyDependencies` — it does not see through the branches and would
+ * reject every branch key. For a closed union, give each branch schema its own
+ * `unevaluatedProperties: false` and add one at this level too.
+ * @param {string} property - The discriminator property name.
+ * @param {Record<string, Object>} mapping - Discriminator value → the schema the rest of the
+ *   object must then satisfy.
+ * @param {Object} [opts]
+ * @param {string} [opts.description]
+ * @returns {Object} `{ type: 'object', properties: { [property]: { enum } }, required, propertyDependencies }`.
+ */
+export function discriminated(property, mapping, opts = {}) {
 	const schema = {
-		type: 'number',
+		type: 'object',
+		properties: { [property]: { enum: Object.keys(mapping) } },
+		required: [property],
+		propertyDependencies: { [property]: mapping },
 	}
-	if (defined(defaultValue)) schema.default = Number(defaultValue)
+	if (defined(opts.description)) schema.description = opts.description
 	return schema
 }
 
+const stringFormat = (format, description) => ({ type: 'string', format, description })
+
+/** JSON schema for an RFC 3339 date-time string (`format: 'date-time'`). */
+export function isoDateTime() {
+	return stringFormat('date-time', 'ISO 8601 / RFC 3339 date-time')
+}
+
+/** JSON schema for an RFC 3339 full-date string (`format: 'date'`). */
+export function isoDate() {
+	return stringFormat('date', 'ISO 8601 / RFC 3339 date')
+}
+
+/** JSON schema for an RFC 3339 full-time string (`format: 'time'`). */
+export function isoTime() {
+	return stringFormat('time', 'ISO 8601 / RFC 3339 time')
+}
+
+/** JSON schema for an ISO 8601 duration string (`format: 'duration'`, e.g. `P1DT2H`). */
+export function duration() {
+	return stringFormat('duration', 'ISO 8601 duration')
+}
+
+/** JSON schema for a URI string (`format: 'uri'`). */
+export function uri() {
+	return stringFormat('uri', 'URI')
+}
+
+/** JSON schema for a UUID string (`format: 'uuid'`). */
+export function uuid() {
+	return stringFormat('uuid', 'UUID')
+}
+
 /**
  * JSON schema for an email-address string, checked against the `email` format
  * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_EMAIL}).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/common",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"description": "Shared backend goodies for Empyria",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -20,7 +20,7 @@
 	},
 	"dependencies": {
 		"@empyria/classification": "0.1.6",
-		"ata-validator": "1.14.1",
+		"ata-validator": "1.18.0",
 		"clerobee": "1.0.8",
 		"ms": "2.1.3"
 	},

package/test/Ata.test.js

@@ -15,6 +15,9 @@ import {
 	schemaOptions,
 	setAtaDefaults,
 	getAtaDefaults,
+	setDefaultDialect,
+	getDefaultDialect,
+	DIALECTS,
 	EMPYRIA_FORMATS,
 	bool,
 	string,
@@ -24,6 +27,17 @@ import {
 	logFile,
 	nodeEnv,
 	number,
+	integer,
+	constant,
+	nullable,
+	array,
+	discriminated,
+	isoDateTime,
+	isoDate,
+	isoTime,
+	duration,
+	uri,
+	uuid,
 	email,
 	password,
 	ip4,
@@ -329,3 +343,145 @@ describe('parse / createParser', () => {
 		expect(typeof createValidator).toBe('function')
 	})
 })
+
+describe('scalar builders — constraints', () => {
+	test('string accepts a number shorthand or an options object', () => {
+		expect(string('x', 3)).toEqual({ type: 'string', default: 'x', minLength: 3 })
+		expect(
+			string(undefined, { minLength: 0, maxLength: 8, pattern: '^a', format: 'uri' }),
+		).toEqual({
+			type: 'string',
+			minLength: 0,
+			maxLength: 8,
+			pattern: '^a',
+			format: 'uri',
+		})
+	})
+
+	test('number/integer carry bounds; integer types as integer', () => {
+		expect(number(5)).toEqual({ type: 'number', default: 5 })
+		expect(integer(8100, { min: 1, max: 65535 })).toEqual({
+			type: 'integer',
+			default: 8100,
+			minimum: 1,
+			maximum: 65535,
+		})
+		expect(integer(undefined, { exclusiveMin: 0, multipleOf: 2 })).toEqual({
+			type: 'integer',
+			exclusiveMinimum: 0,
+			multipleOf: 2,
+		})
+	})
+
+	test('an integer schema rejects a real (and, coerced, a non-integer string)', () => {
+		const schema = defineSchema({ port: integer() })
+		expect(() => validate(schema, { port: 3.5 })).toThrow(EmpyriaError)
+		expect(() => validate(schema, { port: '3.5' }, { coerceTypes: true })).toThrow(EmpyriaError)
+		expect(validate(schema, { port: '3000' }, { coerceTypes: true })).toEqual({ port: 3000 })
+	})
+
+	test('enumType can carry a type alongside enum', () => {
+		expect(enumType(['a', 'b'], 'a')).toEqual({ enum: ['a', 'b'], default: 'a' })
+		expect(enumType(['a', 'b'], undefined, { type: 'string' })).toEqual({
+			type: 'string',
+			enum: ['a', 'b'],
+		})
+	})
+
+	test('constant / nullable', () => {
+		expect(constant('circle')).toEqual({ const: 'circle' })
+		expect(nullable(string('x'))).toEqual({ type: ['string', 'null'], default: 'x' })
+		expect(nullable(enumType(['a']))).toEqual({ anyOf: [{ enum: ['a'] }, { type: 'null' }] })
+		const schema = defineSchema({ note: nullable(string()) })
+		expect(validate(schema, { note: null })).toEqual({ note: null })
+		expect(validate(schema, { note: 'hi' })).toEqual({ note: 'hi' })
+		expect(() => validate(schema, { note: 3 })).toThrow(EmpyriaError)
+	})
+
+	test('array builder', () => {
+		expect(array(string(), { minItems: 1, uniqueItems: true })).toEqual({
+			type: 'array',
+			items: { type: 'string' },
+			minItems: 1,
+			uniqueItems: true,
+		})
+		const schema = defineSchema({ tags: array(string()) })
+		expect(validate(schema, { tags: ['a', 'b'] })).toEqual({ tags: ['a', 'b'] })
+		expect(() => validate(schema, { tags: ['a', 2] })).toThrow(EmpyriaError)
+	})
+
+	test('format wrappers', () => {
+		expect(isoDateTime()).toEqual({
+			type: 'string',
+			format: 'date-time',
+			description: expect.any(String),
+		})
+		expect([isoDate(), isoTime(), duration(), uri(), uuid()].map((s) => s.format)).toEqual([
+			'date',
+			'time',
+			'duration',
+			'uri',
+			'uuid',
+		])
+		const schema = defineSchema({ at: isoDateTime() })
+		expect(validate(schema, { at: '2026-09-10T09:28:09Z' })).toEqual({
+			at: '2026-09-10T09:28:09Z',
+		})
+		expect(() => validate(schema, { at: 'not-a-date' })).toThrow(EmpyriaError)
+	})
+})
+
+describe('defineSchema — dialect & unevaluated strict', () => {
+	test('dialect stamps $schema from a short name or a raw URI', () => {
+		expect(defineSchema({ a: string() }, { dialect: 'v1' }).$schema).toBe(
+			'https://json-schema.org/v1',
+		)
+		expect(defineSchema({ a: string() }, { dialect: 'https://example.test/s' }).$schema).toBe(
+			'https://example.test/s',
+		)
+		expect(defineSchema({ a: string() }).$schema).toBeUndefined()
+	})
+
+	test('setDefaultDialect applies when a call passes no dialect', () => {
+		expect(getDefaultDialect()).toBeNull()
+		setDefaultDialect('v1')
+		try {
+			expect(defineSchema({ a: string() }).$schema).toBe('https://json-schema.org/v1')
+			expect(defineSchema({ a: string() }, { dialect: '2020-12' }).$schema).toBe(
+				'https://json-schema.org/draft/2020-12/schema',
+			)
+		} finally {
+			setDefaultDialect()
+		}
+		expect(getDefaultDialect()).toBeNull()
+		expect(defineSchema({ a: string() }).$schema).toBeUndefined()
+	})
+
+	test("strict: 'unevaluated' keeps additionalProperties open but sets unevaluatedProperties:false", () => {
+		const schema = defineSchema({ a: string() }, { strict: 'unevaluated' })
+		expect(schema.additionalProperties).toBe(true)
+		expect(schema.unevaluatedProperties).toBe(false)
+	})
+})
+
+describe('discriminated (propertyDependencies)', () => {
+	const shape = discriminated('kind', {
+		circle: defineSchema({ radius: number() }),
+		square: defineSchema({ side: number() }),
+	})
+
+	test('selects the branch by the discriminator value', () => {
+		expect(validate(shape, { kind: 'circle', radius: 2 })).toEqual({
+			kind: 'circle',
+			radius: 2,
+		})
+		expect(validate(shape, { kind: 'square', side: 3 })).toEqual({ kind: 'square', side: 3 })
+		expect(() => validate(shape, { kind: 'circle', side: 3 })).toThrow(EmpyriaError)
+		expect(() => validate(shape, { kind: 'triangle' })).toThrow(EmpyriaError)
+	})
+
+	test('pairs with a v1 $schema via dialect', () => {
+		const v1shape = { ...shape, $schema: DIALECTS.v1 }
+		expect(validate(v1shape, { kind: 'square', side: 3 })).toEqual({ kind: 'square', side: 3 })
+	})
+})