@empyria/common 0.1.9 → 0.3.0

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.                                                                                                                                                                                                                               |
-| [lib/Ata.js](./lib/Ata.js)             | JSON schema building blocks (`string`, `number`, `bool`, `enumType`, `email`, `password`, `ip4`, `ip6`, ...) and validation — throwing (`defineSchema`, `createValidator`, `validate`) or non-throwing/structured (`createChecker`, `checkSchema`) — built on [ata-validator](https://www.npmjs.com/package/ata-validator). |
-| [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
@@ -56,6 +56,71 @@ tooling, since both editors read JSDoc from plain `.js` files automatically.
 
 Tests live under [test/](./test/), one file per module, separate from the `lib/` sources.
 
+## Validation options
+
+`createValidator` / `validate` / `parse` / `createChecker` / `checkSchema` forward
+[`ata-validator`'s options](https://www.npmjs.com/package/ata-validator) to the underlying
+`Validator`. Options are resolved in three layers, **last wins**:
+
+1. **library defaults** — `setAtaDefaults({ ... })`, called once at startup for a
+   deployment-wide policy; `getAtaDefaults()` reads it back, `setAtaDefaults()` clears it.
+2. **schema-bound** — `defineSchema(map, { validation: { ... } })` stores options on a
+   non-enumerable key, so a schema carries its own parsing policy (`schemaOptions(schema)`
+   reads it). The schema still serialises and compares as plain JSON Schema.
+3. **per-call** — the `options` argument to any of the functions above.
+
+`formats` is merged one level deep, with `EMPYRIA_FORMATS` always underneath.
+
+| Option             | What it does (Empyria relevance)                                                                                                              |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `coerceTypes`      | `"4040"` → `4040` before validation. The reason `env.js` files work — every `process.env` value is a string.                                  |
+| `useDefaults`      | Fill missing props from their schema `default`. **On by default**; every `string()/number()/bool()/enumType()` emits one.                     |
+| `removeAdditional` | Strip keys not covered by the schema. Only visible with `additionalProperties: false` (i.e. `defineSchema({ strict: true })`).                |
+| `assertFormat`     | Whether a `format` mismatch is a hard error. On by default.                                                                                   |
+| `abortEarly`       | Stop at the first error, skip enrichment. For hot verdict-only paths (pair with `createChecker`, not the throwing path).                      |
+| `richErrors`       | Keep `ATA####` codes / doc URLs / hints that `renderPretty` & co. consume. On by default; leave it on.                                        |
+| `verbose`          | Add `parentSchema` to each error (ajv's `verbose`).                                                                                           |
+| `formats`          | Custom `format` checkers. `EMPYRIA_FORMATS` (`empyria-email`, `empyria-password`, `empyria-ipv4`, `empyria-ipv6`) is folded in automatically. |
+
+**Return value / mutation.** `createValidator` & `validate` return `ata-validator`'s
+`result.data` — the same object as the input unless `coerceTypes` / `removeAdditional` /
+`useDefaults` applied. Those passes also **mutate the input object in place**, so hand them a
+copy when the caller must keep its input pristine (as the `env.js` files do with
+`{ ...process.env }`). `parse` / `createParser` are behavioural aliases for call sites whose
+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

@@ -31,6 +31,134 @@ export const P_IPv6 = `
 	.replace(/\n/g, '')
 	.trim()
 
+const RE_EMAIL = new RegExp(`^${P_EMAIL}`, 'i')
+const RE_PASS = new RegExp(P_PASS)
+const RE_IPv4 = new RegExp(`^${P_IPv4}`)
+const RE_IPv6 = new RegExp(`^${P_IPv6}`)
+
+/**
+ * Empyria's custom `format` checkers, keyed by the `format` name a schema references.
+ * Registered automatically on every validator this module builds (see `resolveOptions`), so
+ * a schema carrying `{ type: 'string', format: 'empyria-email' }` — as produced by
+ * {@link email}, {@link password}, {@link ip4}, {@link ip6} — is enforced with no per-call
+ * wiring.
+ *
+ * The names are deliberately prefixed rather than reusing `email` / `ipv4` / `ipv6`:
+ * `ata-validator`'s compiled path only lets a custom `formats` entry override a *built-in*
+ * name at the schema root, not on a nested property, whereas an unknown name is honoured
+ * everywhere. A caller's own `options.formats` entry for the same key still wins.
+ *
+ * A schema from {@link email} & co. is only enforced when validated through this module (or
+ * through a validator the caller seeded with this map); a bare `new Validator(schema)` sees
+ * these as unknown (ignored) formats.
+ * @type {Record<string, (value: unknown) => boolean>}
+ */
+export const EMPYRIA_FORMATS = {
+	'empyria-email': (s) => typeof s === 'string' && RE_EMAIL.test(s),
+	'empyria-password': (s) => typeof s === 'string' && RE_PASS.test(s),
+	'empyria-ipv4': (s) => typeof s === 'string' && RE_IPv4.test(s),
+	'empyria-ipv6': (s) => typeof s === 'string' && RE_IPv6.test(s),
+}
+
+/** 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 = {}
+
+/**
+ * Sets this module's process-wide default `ata-validator` options — the base layer every
+ * {@link createValidator} / {@link validate} / {@link parse} / {@link createChecker} call in
+ * this process starts from. Meant to be called once at startup to express a deployment-wide
+ * policy (e.g. `{ coerceTypes: true }`). Individual calls stay free to override any key, and
+ * a schema built by {@link defineSchema} with a `validation` bag overrides these too.
+ *
+ * Merge order, lowest to highest precedence: **library defaults → schema-bound → per-call**.
+ * `formats` is merged one level deep, with {@link EMPYRIA_FORMATS} always underneath.
+ * @param {import('ata-validator').ValidatorOptions} [options={}] - Replaces the current
+ *   defaults wholesale. Pass `{}` (or call with no argument) to clear them.
+ * @returns {void}
+ */
+export function setAtaDefaults(options = {}) {
+	libraryDefaults = { ...options }
+}
+
+/**
+ * Returns a shallow copy of the current process-wide default options (see {@link setAtaDefaults}).
+ * @returns {import('ata-validator').ValidatorOptions}
+ */
+export function getAtaDefaults() {
+	return { ...libraryDefaults }
+}
+
+/**
+ * Returns a shallow copy of the `ata-validator` options bound to `schema` by
+ * {@link defineSchema}'s `validation` option, or `{}` if none were bound.
+ * @param {Object} schema
+ * @returns {import('ata-validator').ValidatorOptions}
+ */
+export function schemaOptions(schema) {
+	const bound = schema?.[SCHEMA_OPTIONS]
+	return bound ? { ...bound } : {}
+}
+
+/**
+ * Merges the three option layers for a single call and folds in {@link EMPYRIA_FORMATS}.
+ * @param {Object} schema - Schema being validated (may carry bound options).
+ * @param {import('ata-validator').ValidatorOptions} [perCall] - Options passed to this call.
+ * @returns {import('ata-validator').ValidatorOptions}
+ */
+function resolveOptions(schema, perCall) {
+	const bound = schema?.[SCHEMA_OPTIONS] ?? {}
+	return {
+		...libraryDefaults,
+		...bound,
+		...perCall,
+		formats: {
+			...EMPYRIA_FORMATS,
+			...libraryDefaults.formats,
+			...bound.formats,
+			...(perCall && perCall.formats),
+		},
+	}
+}
+
 /**
  * Builds a function that clones only the keys declared on a schema's `properties`.
  * @param {Object} schema - JSON schema with a `properties` map.
@@ -45,12 +173,27 @@ 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`.
+ * @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
  *   Schema keyword). Off by default: every declared property is required, exactly as before —
  *   a caller that never sets `optional: true` on any property sees no difference either way.
+ * @param {import('ata-validator').ValidatorOptions} [options.validation] - `ata-validator`
+ *   options bound to the returned schema: every {@link createValidator} / {@link validate} /
+ *   {@link parse} / {@link createChecker} call for it starts from these (below per-call
+ *   options, above {@link setAtaDefaults}). Stored on a non-enumerable key, so the schema
+ *   still serialises and compares as a plain JSON Schema.
  * @returns {Object} A JSON schema: `{ type: 'object', properties, required, additionalProperties }`.
  */
 export function defineSchema(schemaDef, options = {}) {
@@ -66,11 +209,25 @@ export function defineSchema(schemaDef, options = {}) {
 			required.push(key)
 		}
 	}
+	const unevaluated = options.strict === 'unevaluated'
 	const schema = {
 		type: 'object',
 		properties,
 		required,
-		additionalProperties: !options.strict,
+		additionalProperties: defined(options.additionalProperties)
+			? options.additionalProperties
+			: !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, {
+			value: { ...options.validation },
+			enumerable: false,
+		})
 	}
 
 	return schema
@@ -78,17 +235,26 @@ export function defineSchema(schemaDef, options = {}) {
 
 /**
  * Builds a validating function for a JSON schema.
+ *
+ * Options are resolved in three layers — {@link setAtaDefaults} → the schema's bound
+ * `validation` (see {@link defineSchema}) → the `options` argument here — with the last
+ * winning, and {@link EMPYRIA_FORMATS} always folded into `formats`.
+ *
+ * The returned function returns the schema-shaped value: `ata-validator`'s `result.data`,
+ * which is `data` itself unless `coerceTypes` / `removeAdditional` / `useDefaults` (the last
+ * on by default) applied. Those passes also mutate `data` in place, so pass a copy when the
+ * caller must keep its input pristine (see `createEnv` / the `env.js` files).
  * @param {Object} schema - JSON schema to validate against.
- * @param {Object} [options] - Forwarded to `ata-validator`'s `Validator` constructor
- *   (`coerceTypes`, `removeAdditional`, `useDefaults`, ...). Left unset, validation is
- *   strict: a schema expecting `type: 'number'` rejects `"32"`. Pass `{ coerceTypes: true }`
- *   for input that's inherently string-typed, such as `process.env` (see `createEnv`).
- * @returns {(data: *) => *} Function that returns `data` unchanged if valid.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Per-call options (see above):
+ *   `coerceTypes`, `removeAdditional`, `useDefaults`, `assertFormat`, `abortEarly`,
+ *   `richErrors`, `verbose`, `formats`, ... Left unset, validation is strict: a schema
+ *   expecting `type: 'number'` rejects `"32"`.
+ * @returns {(data: *) => *} Function that returns the (possibly coerced/defaulted) value.
  * @throws {EmpyriaError} `BaseErrors.ValidationError` (with a pretty-rendered violation list
  *   in its `validation` param) if `data` doesn't satisfy the schema.
  */
 export function createValidator(schema, options) {
-	const v = new Validator(schema, options)
+	const v = new Validator(schema, resolveOptions(schema, options))
 
 	return (data) => {
 		const result = v.validate(data)
@@ -99,7 +265,7 @@ export function createValidator(schema, options) {
 				validation: renderPretty(result.errors),
 			})
 		}
-		return data
+		return result.data ?? data
 	}
 }
 
@@ -107,8 +273,8 @@ export function createValidator(schema, options) {
  * Validates `input` against `schema` in one call.
  * @param {Object} schema - JSON schema to validate against.
  * @param {*} input - Value to validate.
- * @param {Object} [options] - Forwarded to {@link createValidator} (see its docs).
- * @returns {*} `input` unchanged, if valid.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Forwarded to {@link createValidator}.
+ * @returns {*} `input` — coerced/defaulted/stripped per the resolved options — if valid.
  * @throws {EmpyriaError} `BaseErrors.ValidationError` if `input` doesn't satisfy the schema.
  */
 export function validate(schema, input, options) {
@@ -118,25 +284,57 @@ export function validate(schema, input, options) {
 	return validatedInput
 }
 
+/**
+ * {@link createValidator} under an intent-revealing name, for call sites whose purpose is to
+ * *transform* input — coerce string-typed values, strip unknown keys, apply schema defaults —
+ * rather than merely assert its shape. Behaviour is identical; the name documents that the
+ * returned value is expected to differ from the input.
+ * @param {Object} schema - JSON schema to validate/parse against.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Typically `{ coerceTypes: true }`
+ *   and/or `{ removeAdditional: true }` (with a closed schema).
+ * @returns {(data: *) => *} Function returning the parsed value.
+ * @throws {EmpyriaError} `BaseErrors.ValidationError` on invalid input.
+ */
+export function createParser(schema, options) {
+	return createValidator(schema, options)
+}
+
+/**
+ * {@link validate} under an intent-revealing name — see {@link createParser}.
+ * @param {Object} schema - JSON schema to parse against.
+ * @param {*} input - Value to parse.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Forwarded to {@link createParser}.
+ * @returns {*} The parsed (coerced/defaulted/stripped) value, if valid.
+ * @throws {EmpyriaError} `BaseErrors.ValidationError` on invalid input.
+ */
+export function parse(schema, input, options) {
+	return createParser(schema, options)(input)
+}
+
 /**
  * Builds a non-throwing checking function for a JSON schema — the structured-result
  * counterpart to {@link createValidator}. Use it when a caller needs `ata-validator`'s own
  * error list (to build its own error type, count violations, or render them itself with
  * {@link renderCompact} / {@link renderJSON}) rather than a `BaseErrors.ValidationError`
- * carrying a pre-rendered string.
+ * carrying a pre-rendered string, or when it wants the parsed value without a `try`/`catch`.
  * @param {Object} schema - JSON schema to validate against.
- * @param {Object} [options] - Forwarded to `ata-validator`'s `Validator` constructor
- *   (see {@link createValidator} for the common flags).
- * @returns {(data: *) => { valid: boolean, errors: Array<Object> }} Function that returns the
- *   verdict and, when invalid, `ata-validator`'s raw error objects (empty array when valid).
- *   Never throws on a validation failure.
+ * @param {import('ata-validator').ValidatorOptions} [options] - Resolved the same way as for
+ *   {@link createValidator} (see its docs for the layers and the common flags).
+ * @returns {(data: *) => { valid: boolean, data: *, errors: Array<Object> }} Function that
+ *   returns the verdict, the parsed value (`data` when valid — coerced/defaulted/stripped per
+ *   the resolved options; `undefined` when invalid), and, when invalid, `ata-validator`'s raw
+ *   error objects (empty array when valid). Never throws on a validation failure.
  */
 export function createChecker(schema, options) {
-	const v = new Validator(schema, options)
+	const v = new Validator(schema, resolveOptions(schema, options))
 
 	return (data) => {
 		const result = v.validate(data)
-		return { valid: result.valid, errors: result.valid ? [] : result.errors }
+		return {
+			valid: result.valid,
+			data: result.valid ? (result.data ?? data) : undefined,
+			errors: result.valid ? [] : result.errors,
+		}
 	}
 }
 
@@ -144,9 +342,9 @@ export function createChecker(schema, options) {
  * Checks `input` against `schema` in one call, without throwing.
  * @param {Object} schema - JSON schema to validate against.
  * @param {*} input - Value to validate.
- * @param {Object} [options] - Forwarded to {@link createChecker} (see its docs).
- * @returns {{ valid: boolean, errors: Array<Object> }} The verdict, plus `ata-validator`'s raw
- *   error objects when invalid (empty array when valid).
+ * @param {import('ata-validator').ValidatorOptions} [options] - Forwarded to {@link createChecker}.
+ * @returns {{ valid: boolean, data: *, errors: Array<Object> }} The verdict, the parsed value
+ *   (when valid), plus `ata-validator`'s raw error objects when invalid.
  */
 export function checkSchema(schema, input, options) {
 	return createChecker(schema, options)(input)
@@ -175,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
 }
 
@@ -191,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
 }
 
@@ -237,63 +452,200 @@ 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, pattern-matched against {@link P_EMAIL}.
- * @returns {Object} String schema with `pattern` and `description` set.
+ * JSON schema for an email-address string, checked against the `email` format
+ * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_EMAIL}).
+ * @returns {Object} String schema with `format` and `description` set.
  */
 export function email() {
 	return {
 		type: 'string',
-		pattern: P_EMAIL,
+		format: 'empyria-email',
 		description: 'Email address',
 	}
 }
 
 /**
- * JSON schema for a password string, pattern-matched against {@link P_PASS}
- * (requires lower-case, upper-case, a digit, and at least 8 characters).
- * @returns {Object} String schema with `pattern` and `description` set.
+ * JSON schema for a password string, checked against the `password` format
+ * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_PASS}: lower-case, upper-case, a digit,
+ * and at least 8 characters).
+ * @returns {Object} String schema with `format` and `description` set.
  */
 export function password() {
 	return {
 		type: 'string',
-		pattern: P_PASS,
+		format: 'empyria-password',
 		description: 'password',
 	}
 }
 
 /**
- * JSON schema for an IPv4-address string, pattern-matched against {@link P_IPv4}.
- * @returns {Object} String schema with `pattern` and `description` set.
+ * JSON schema for an IPv4-address string, checked against the `ipv4` format
+ * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_IPv4}).
+ * @returns {Object} String schema with `format` and `description` set.
  */
 export function ip4() {
 	return {
 		type: 'string',
-		pattern: P_IPv4,
+		format: 'empyria-ipv4',
 		description: 'IP address v4',
 	}
 }
 
 /**
- * JSON schema for an IPv6-address string, pattern-matched against {@link P_IPv6}.
- * @returns {Object} String schema with `pattern` and `description` set.
+ * JSON schema for an IPv6-address string, checked against the `ipv6` format
+ * ({@link EMPYRIA_FORMATS}, which mirrors {@link P_IPv6}).
+ * @returns {Object} String schema with `format` and `description` set.
  */
 export function ip6() {
 	return {
 		type: 'string',
-		pattern: P_IPv6,
+		format: 'empyria-ipv6',
 		description: 'IP address v6',
 	}
 }

package/lib/Env.js

@@ -27,8 +27,17 @@ const DEFAULT_SERVICE_SCHEMA = {
  * Builds a JSON schema for a microservice's environment variables, merging the
  * Empyria-wide defaults with any service-specific additions/overrides.
  * @param {Object} [specificSchema] - Additional or overriding property schemas, keyed by env var name.
+ * @param {Object} [options={}]
+ * @param {boolean} [options.closed] - When true, the schema rejects the whole of
+ *   `process.env` beyond its declared keys and binds `{ coerceTypes: true, removeAdditional:
+ *   true }` to itself, so `validate`/`parse` return an object holding *only* the declared
+ *   vars — no undeclared environment riding along into `settings`. Off by default:
+ *   `additionalProperties: true`, every extra var passes through unchanged.
  * @returns {Object} A JSON schema object (see `defineSchema` in `./Ata.js`).
  */
-export function createEnv(specificSchema) {
-	return defineSchema(Object.assign({}, DEFAULT_SERVICE_SCHEMA, specificSchema))
+export function createEnv(specificSchema, { closed = false } = {}) {
+	return defineSchema(
+		Object.assign({}, DEFAULT_SERVICE_SCHEMA, specificSchema),
+		closed ? { strict: true, validation: { coerceTypes: true, removeAdditional: true } } : {},
+	)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/common",
-	"version": "0.1.9",
+	"version": "0.3.0",
 	"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.13.2",
+		"ata-validator": "1.14.1",
 		"clerobee": "1.0.8",
 		"ms": "2.1.3"
 	},
@@ -29,7 +29,7 @@
 		"oxlint": "1.82.0"
 	},
 	"engines": {
-		"bun": ">=1.4.0",
+		"bun": ">=1.4.2",
 		"node": ">=26"
 	},
 	"packageManager": "bun@1.4.2"

package/test/Ata.test.js

@@ -7,8 +7,18 @@ import {
 	cloneBySchema,
 	defineSchema,
 	validate,
+	parse,
+	createParser,
+	createValidator,
 	createChecker,
 	checkSchema,
+	schemaOptions,
+	setAtaDefaults,
+	getAtaDefaults,
+	setDefaultDialect,
+	getDefaultDialect,
+	DIALECTS,
+	EMPYRIA_FORMATS,
 	bool,
 	string,
 	enumType,
@@ -17,6 +27,17 @@ import {
 	logFile,
 	nodeEnv,
 	number,
+	integer,
+	constant,
+	nullable,
+	array,
+	discriminated,
+	isoDateTime,
+	isoDate,
+	isoTime,
+	duration,
+	uri,
+	uuid,
 	email,
 	password,
 	ip4,
@@ -89,6 +110,31 @@ describe('defineSchema', () => {
 	test('disallows extra properties when strict', () => {
 		expect(defineSchema({ a: string() }, { strict: true }).additionalProperties).toBe(false)
 	})
+
+	test('an explicit additionalProperties overrides strict', () => {
+		expect(
+			defineSchema({ a: string() }, { strict: true, additionalProperties: true })
+				.additionalProperties,
+		).toBe(true)
+		expect(
+			defineSchema({ a: string() }, { additionalProperties: false }).additionalProperties,
+		).toBe(false)
+	})
+
+	test('binds validation options on a non-enumerable key, invisible to JSON/toEqual', () => {
+		const schema = defineSchema(
+			{ a: string() },
+			{ validation: { coerceTypes: true, removeAdditional: true } },
+		)
+		expect(schema).toEqual({
+			type: 'object',
+			properties: { a: { type: 'string' } },
+			required: ['a'],
+			additionalProperties: true,
+		})
+		expect(JSON.stringify(schema)).not.toContain('coerceTypes')
+		expect(schemaOptions(schema)).toEqual({ coerceTypes: true, removeAdditional: true })
+	})
 })
 
 describe('cloneBySchema', () => {
@@ -171,11 +217,11 @@ describe('schema builders', () => {
 		})
 	})
 
-	test('email/password/ip4/ip6 reference their patterns', () => {
-		expect(email().pattern).toBe(P_EMAIL)
-		expect(password().pattern).toBe(P_PASS)
-		expect(ip4().pattern).toBe(P_IPv4)
-		expect(ip6().pattern).toBe(P_IPv6)
+	test('email/password/ip4/ip6 reference their named formats', () => {
+		expect(email().format).toBe('empyria-email')
+		expect(password().format).toBe('empyria-password')
+		expect(ip4().format).toBe('empyria-ipv4')
+		expect(ip6().format).toBe('empyria-ipv6')
 	})
 })
 
@@ -189,8 +235,16 @@ describe('renderCompact / renderJSON re-exports', () => {
 describe('createChecker / checkSchema', () => {
 	const schema = defineSchema({ name: string() })
 
-	test('checkSchema returns valid:true and no errors for good input', () => {
-		expect(checkSchema(schema, { name: 'Bob' })).toEqual({ valid: true, errors: [] })
+	test('checkSchema returns valid:true, the parsed value, and no errors for good input', () => {
+		expect(checkSchema(schema, { name: 'Bob' })).toEqual({
+			valid: true,
+			data: { name: 'Bob' },
+			errors: [],
+		})
+	})
+
+	test('checkSchema reports data:undefined for bad input', () => {
+		expect(checkSchema(schema, {}).data).toBeUndefined()
 	})
 
 	test('checkSchema returns valid:false and a non-empty error list for bad input, without throwing', () => {
@@ -205,8 +259,229 @@ describe('createChecker / checkSchema', () => {
 		expect(renderCompact(errors)).toContain('name')
 	})
 
-	test('createChecker builds a reusable checker and forwards options (coerceTypes)', () => {
+	test('createChecker builds a reusable checker, forwards options, and returns the parsed value', () => {
 		const check = createChecker(defineSchema({ port: number() }), { coerceTypes: true })
-		expect(check({ port: '4040' })).toEqual({ valid: true, errors: [] })
+		expect(check({ port: '4040' })).toEqual({ valid: true, data: { port: 4040 }, errors: [] })
+	})
+})
+
+describe('named formats', () => {
+	test('EMPYRIA_FORMATS enforce their patterns', () => {
+		expect(EMPYRIA_FORMATS['empyria-email']('user@example.com')).toBe(true)
+		expect(EMPYRIA_FORMATS['empyria-email']('user@example!com')).toBe(false)
+		expect(EMPYRIA_FORMATS['empyria-password']('Abcdefg1')).toBe(true)
+		expect(EMPYRIA_FORMATS['empyria-password']('Abcdefgh')).toBe(false)
+		expect(EMPYRIA_FORMATS['empyria-ipv4']('192.168.0.1')).toBe(true)
+		expect(EMPYRIA_FORMATS['empyria-ipv4']('999.0.0.1')).toBe(false)
+	})
+
+	test('a schema from email() is enforced through this module without per-call wiring', () => {
+		const schema = defineSchema({ addr: email() })
+		expect(validate(schema, { addr: 'user@example.com' })).toEqual({ addr: 'user@example.com' })
+		expect(() => validate(schema, { addr: 'nope' })).toThrow(EmpyriaError)
+	})
+
+	test('a schema from password() is enforced (no ata-validator built-in for it)', () => {
+		const schema = defineSchema({ pw: password() })
+		expect(() => validate(schema, { pw: 'weak' })).toThrow(EmpyriaError)
+		expect(validate(schema, { pw: 'Abcdefg1' })).toEqual({ pw: 'Abcdefg1' })
+	})
+
+	test('a per-call formats entry overrides the Empyria default', () => {
+		const schema = defineSchema({ addr: email() })
+		const only = { formats: { 'empyria-email': (s) => s === 'ok@ok.io' } }
+		expect(validate(schema, { addr: 'ok@ok.io' }, only)).toEqual({ addr: 'ok@ok.io' })
+		expect(() => validate(schema, { addr: 'user@example.com' }, only)).toThrow(EmpyriaError)
+	})
+})
+
+describe('option layering: setAtaDefaults / schema-bound / per-call', () => {
+	test('getAtaDefaults starts empty', () => {
+		expect(getAtaDefaults()).toEqual({})
+	})
+
+	test('a library default is applied when no per-call option is given', () => {
+		const schema = defineSchema({ port: number() })
+		expect(() => validate(schema, { port: '8080' })).toThrow(EmpyriaError)
+		setAtaDefaults({ coerceTypes: true })
+		try {
+			expect(validate(schema, { port: '8080' })).toEqual({ port: 8080 })
+		} finally {
+			setAtaDefaults()
+		}
+		expect(getAtaDefaults()).toEqual({})
+	})
+
+	test('schema-bound validation options beat library defaults, per-call beats both', () => {
+		setAtaDefaults({ coerceTypes: false })
+		try {
+			const bound = defineSchema({ port: number() }, { validation: { coerceTypes: true } })
+			// schema-bound coerceTypes:true wins over the library default
+			expect(validate(bound, { port: '80' })).toEqual({ port: 80 })
+			// per-call coerceTypes:false wins over the schema-bound value
+			expect(() => validate(bound, { port: '80' }, { coerceTypes: false })).toThrow(
+				EmpyriaError,
+			)
+		} finally {
+			setAtaDefaults()
+		}
+	})
+})
+
+describe('parse / createParser', () => {
+	test('parse coerces and strips against a closed schema', () => {
+		const schema = defineSchema(
+			{ port: number() },
+			{ strict: true, validation: { coerceTypes: true, removeAdditional: true } },
+		)
+		expect(parse(schema, { port: '3000', stray: 'x' })).toEqual({ port: 3000 })
+	})
+
+	test('createParser is a reusable createValidator under an intent-revealing name', () => {
+		const p = createParser(defineSchema({ n: number() }), { coerceTypes: true })
+		expect(p({ n: '7' })).toEqual({ n: 7 })
+		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 })
 	})
 })

package/test/Env.test.js

@@ -1,5 +1,6 @@
 import { describe, test, expect } from 'bun:test'
 import { createEnv } from '../lib/Env.js'
+import { validate, schemaOptions } from '../lib/Ata.js'
 
 describe('createEnv', () => {
 	test('includes the shared service defaults plus service-specific additions', () => {
@@ -15,4 +16,33 @@ describe('createEnv', () => {
 		const schema = createEnv()
 		expect(schema.properties.EMPYRIA_MONGO_URI).toBeUndefined()
 	})
+
+	test('is open by default: undeclared vars pass through untouched', () => {
+		const schema = createEnv()
+		expect(schema.additionalProperties).toBe(true)
+		expect(schemaOptions(schema)).toEqual({})
+		const out = validate(
+			schema,
+			{ NODE_ENV: 'test', UNDECLARED: 'ride-along' },
+			{ coerceTypes: true },
+		)
+		expect(out.UNDECLARED).toBe('ride-along')
+	})
+
+	test('closed: rejects the wider environment and returns only the declared keys', () => {
+		const schema = createEnv({}, { closed: true })
+		expect(schema.additionalProperties).toBe(false)
+		expect(schemaOptions(schema)).toEqual({ coerceTypes: true, removeAdditional: true })
+
+		const out = validate(schema, {
+			NODE_ENV: 'test',
+			EMPYRIA_ID_LENGTH: '48',
+			PATH: '/usr/bin',
+			HOME: '/root',
+		})
+		expect(out.EMPYRIA_ID_LENGTH).toBe(48)
+		expect(out.NODE_ENV).toBe('test')
+		expect(out.PATH).toBeUndefined()
+		expect(out.HOME).toBeUndefined()
+	})
 })