@effected/schemastore 0.9.1 → 0.11.0

package/CanonicalJson.js

@@ -1,4 +1,4 @@
-import { Effect, Result, Schema } from "effect";
+import { Effect, JsonPointer, Result, Schema } from "effect";
 
 //#region src/CanonicalJson.ts
 /**
@@ -48,7 +48,24 @@ var SerializeFailure = class {
 		this.error = error;
 	}
 };
-const escapePointerSegment = (segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1");
+const EQUALITY_STACK_GUARD = 256 * 8;
+const isPlainRecord = (node) => {
+	if (typeof node !== "object" || node === null || Array.isArray(node)) return false;
+	const prototype = Object.getPrototypeOf(node);
+	return prototype === Object.prototype || prototype === null;
+};
+const contentEqual = (a, b, depth) => {
+	if (a === b) return true;
+	if (depth >= EQUALITY_STACK_GUARD) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((element, index) => contentEqual(element, b[index], depth + 1));
+	}
+	if (!isPlainRecord(a) || !isPlainRecord(b)) return false;
+	const aKeys = Object.keys(a);
+	if (aKeys.length !== Object.keys(b).length) return false;
+	return aKeys.every((key) => Object.hasOwn(b, key) && contentEqual(a[key], b[key], depth + 1));
+};
 /**
 * Deterministic, canonical JSON text: the package's owned serializer, so a
 * consumer never shells out to an external formatter to produce a stable
@@ -89,6 +106,24 @@ var CanonicalJson = class CanonicalJson {
 	* primitive — synchronous callers can use that variant directly.
 	*/
 	static serialize = Effect.fn("CanonicalJson.serialize")((value, options) => Effect.fromResult(CanonicalJson.serializeResult(value, options)));
+	/**
+	* Content equality under the serializer's own semantics: two values are
+	* equal when they would parse to the same JSON document — object key
+	* order is a serialization detail and is ignored, array order is data
+	* and is not. `NaN` is never equal to itself (it is not JSON). The same
+	* reference compares `true` before any structural walk — so a cyclic
+	* value equals itself — and the comparison is total: two distinct
+	* cyclic or hostile-depth values report `false` at the stack guard
+	* rather than overflowing.
+	*
+	* This is the comparison `SchemaFile`'s write-if-changed and
+	* `DocumentDiff`'s leaf comparison already make, exported so a consumer
+	* writing its own JSON artifact (a catalog entry) can decide "unchanged"
+	* by the same rule instead of re-implementing it.
+	*/
+	static equals(left, right) {
+		return contentEqual(left, right, 0);
+	}
 };
 const indentUnit = (indent) => {
 	if (!Number.isInteger(indent) || indent < 0) throw new Error(`indent must be "tab" or a non-negative integer space count, got ${indent}`);
@@ -128,7 +163,7 @@ const emit = (value, path, depth, unit) => {
 	}));
 	const entries = Object.entries(value);
 	if (entries.length === 0) return "{}";
-	return `{\n${entries.map(([key, member]) => `${indent}${JSON.stringify(key)}: ${emit(member, `${path}/${escapePointerSegment(key)}`, depth + 1, unit)}`).join(",\n")}\n${closing}}`;
+	return `{\n${entries.map(([key, member]) => `${indent}${JSON.stringify(key)}: ${emit(member, `${path}/${JsonPointer.escapeToken(key)}`, depth + 1, unit)}`).join(",\n")}\n${closing}}`;
 };
 
 //#endregion

package/CatalogEntry.js

@@ -98,7 +98,9 @@ var CatalogEntry = class CatalogEntry extends Schema.Class("CatalogEntry")({
 	* Assembles an entry from a catalog identity plus
 	* {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
 	* versioned mode (the `versions` map and latest-pointing `url` are
-	* derived), omit it for the unversioned mode. Throws an `Error` naming
+	* derived), omit it for the unversioned mode. `layout` (default
+	* `"flat"`) and `current` (default: the newest label) are forwarded to
+	* {@link SchemaVersioning.catalogUrls} verbatim. Throws an `Error` naming
 	* both spellings when two labels compare equal under
 	* {@link SchemaVersioning.Order} (`1.2` and `1.2.0`): each would be its
 	* own key and URL for one document.
@@ -108,7 +110,9 @@ var CatalogEntry = class CatalogEntry extends Schema.Class("CatalogEntry")({
 		const urls = SchemaVersioning.catalogUrls({
 			baseUrl: options.baseUrl,
 			name: options.fileBaseName ?? options.name,
-			...options.versions !== void 0 ? { versions: options.versions } : {}
+			...options.versions !== void 0 ? { versions: options.versions } : {},
+			...options.layout !== void 0 ? { layout: options.layout } : {},
+			...options.current !== void 0 ? { current: options.current } : {}
 		});
 		return CatalogEntry.make({
 			name: options.name,

package/DocumentDiff.js

@@ -1,3 +1,4 @@
+import { CanonicalJson } from "./CanonicalJson.js";
 import { KeywordFamilies } from "./KeywordFamilies.js";
 
 //#region src/DocumentDiff.ts
@@ -28,19 +29,6 @@ const SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
 	"not"
 ]);
 const isSchemaObject = (node) => typeof node === "object" && node !== null && !Array.isArray(node);
-const VALUE_COMPARISON_STACK_GUARD = 256 * 8;
-const deepEqual = (a, b, depth) => {
-	if (a === b) return true;
-	if (depth >= VALUE_COMPARISON_STACK_GUARD) return false;
-	if (Array.isArray(a) || Array.isArray(b)) {
-		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
-		return a.every((element, index) => deepEqual(element, b[index], depth + 1));
-	}
-	if (!isSchemaObject(a) || !isSchemaObject(b)) return false;
-	const aKeys = Object.keys(a);
-	if (aKeys.length !== Object.keys(b).length) return false;
-	return aKeys.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key], depth + 1));
-};
 const worst = (left, right) => {
 	if (left === "contract" || right === "contract") return "contract";
 	if (left === "annotations" || right === "annotations") return "annotations";
@@ -49,8 +37,8 @@ const worst = (left, right) => {
 const isAnnotationKey = (key) => DOCUMENTATION_KEYWORDS.has(key) || KeywordFamilies.isDeclared(key);
 const compareSchema = (a, b, depth) => {
 	if (a === b) return "none";
-	if (depth >= 256) return deepEqual(a, b, 0) ? "none" : "contract";
-	if (!isSchemaObject(a) || !isSchemaObject(b)) return deepEqual(a, b, depth) ? "none" : "contract";
+	if (depth >= 256) return CanonicalJson.equals(a, b) ? "none" : "contract";
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return CanonicalJson.equals(a, b) ? "none" : "contract";
 	let change = "none";
 	const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
 	for (const key of keys) {
@@ -62,7 +50,7 @@ const compareSchema = (a, b, depth) => {
 		const left = a[key];
 		const right = b[key];
 		if (isAnnotationKey(key)) {
-			change = worst(change, deepEqual(left, right, depth) ? "none" : "annotations");
+			change = worst(change, CanonicalJson.equals(left, right) ? "none" : "annotations");
 			continue;
 		}
 		if (SCHEMA_MAP_KEYWORDS.has(key)) change = worst(change, compareSchemaMap(left, right, depth + 1));
@@ -70,13 +58,13 @@ const compareSchema = (a, b, depth) => {
 		else if (SCHEMA_KEYWORDS.has(key)) change = worst(change, compareSchema(left, right, depth + 1));
 		else if (key === "items") change = worst(change, Array.isArray(left) || Array.isArray(right) ? compareSchemaArray(left, right, depth + 1) : compareSchema(left, right, depth + 1));
 		else if (key === "dependencies") change = worst(change, compareDependencies(left, right, depth + 1));
-		else change = worst(change, deepEqual(left, right, depth) ? "none" : "contract");
+		else change = worst(change, CanonicalJson.equals(left, right) ? "none" : "contract");
 		if (change === "contract") return "contract";
 	}
 	return change;
 };
 const compareSchemaMap = (a, b, depth) => {
-	if (!isSchemaObject(a) || !isSchemaObject(b)) return deepEqual(a, b, depth) ? "none" : "contract";
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return CanonicalJson.equals(a, b) ? "none" : "contract";
 	let change = "none";
 	const names = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
 	for (const name of names) {
@@ -96,14 +84,14 @@ const compareSchemaArray = (a, b, depth) => {
 	return change;
 };
 const compareDependencies = (a, b, depth) => {
-	if (!isSchemaObject(a) || !isSchemaObject(b)) return deepEqual(a, b, depth) ? "none" : "contract";
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return CanonicalJson.equals(a, b) ? "none" : "contract";
 	let change = "none";
 	const names = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
 	for (const name of names) {
 		if (!Object.hasOwn(a, name) || !Object.hasOwn(b, name)) return "contract";
 		const left = a[name];
 		const right = b[name];
-		change = worst(change, Array.isArray(left) || Array.isArray(right) ? deepEqual(left, right, depth) ? "none" : "contract" : compareSchema(left, right, depth + 1));
+		change = worst(change, Array.isArray(left) || Array.isArray(right) ? CanonicalJson.equals(left, right) ? "none" : "contract" : compareSchema(left, right, depth + 1));
 		if (change === "contract") return "contract";
 	}
 	return change;

package/DocumentLint.js

@@ -1,5 +1,5 @@
 import { KeywordFamilies } from "./KeywordFamilies.js";
-import { Schema } from "effect";
+import { JsonPointer, Schema } from "effect";
 
 //#region src/DocumentLint.ts
 /**
@@ -74,14 +74,20 @@ const DRAFT_07_KEYWORDS = /* @__PURE__ */ new Set([
 	"writeOnly"
 ]);
 const URL_LINE = /^https?:\/\/\S+$/;
-const escapePointerSegment = (segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1");
-const unescapePointerSegment = (segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~");
 const isSchemaObject = (node) => typeof node === "object" && node !== null && !Array.isArray(node);
+const localPointer = (ref) => {
+	if (!ref.startsWith("#/")) return;
+	try {
+		return ref.slice(2).split("/").map((token) => JsonPointer.unescapeToken(decodeURIComponent(token)));
+	} catch {
+		return;
+	}
+};
 const checkRef = (value, path, context) => {
 	if (typeof value !== "string") return;
 	if (value === "#") return;
-	const match = /^#\/\$defs\/([^/]+)/.exec(value);
-	if (match !== null && Object.hasOwn(context.defs, unescapePointerSegment(match[1]))) return;
+	const pointer = localPointer(value);
+	if (pointer !== void 0 && pointer.length >= 2 && pointer[0] === "$defs" && Object.hasOwn(context.defs, pointer[1])) return;
 	context.findings.push(DocumentLintFinding.make({
 		check: "UnresolvedRef",
 		severity: "warning",
@@ -89,6 +95,24 @@ const checkRef = (value, path, context) => {
 		message: `$ref "${value}" does not resolve against the document's $defs pool`
 	}));
 };
+const describedNode = (document) => {
+	const keys = Object.keys(document.root);
+	if (keys.length !== 1 || keys[0] !== "$ref" || typeof document.root.$ref !== "string") return {
+		node: document.root,
+		path: ""
+	};
+	const pointer = localPointer(document.root.$ref);
+	if (pointer === void 0 || pointer.length !== 2 || pointer[0] !== "$defs") return {
+		node: document.root,
+		path: ""
+	};
+	const name = pointer[1];
+	const entry = Object.hasOwn(document.defs, name) ? document.defs[name] : void 0;
+	return isSchemaObject(entry) ? {
+		node: entry,
+		path: `/$defs/${JsonPointer.escapeToken(name)}`
+	} : void 0;
+};
 const lintSchema = (node, path, depth, context) => {
 	if (!isSchemaObject(node)) return;
 	if (depth >= 256) {
@@ -101,7 +125,7 @@ const lintSchema = (node, path, depth, context) => {
 		return;
 	}
 	for (const [key, value] of Object.entries(node)) {
-		const keyPath = `${path}/${escapePointerSegment(key)}`;
+		const keyPath = `${path}/${JsonPointer.escapeToken(key)}`;
 		if (!DRAFT_07_KEYWORDS.has(key) && !KeywordFamilies.isDeclared(key)) {
 			context.findings.push(DocumentLintFinding.make({
 				check: "UnknownKeyword",
@@ -119,11 +143,11 @@ const lintSchema = (node, path, depth, context) => {
 			case "patternProperties":
 			case "$defs":
 			case "definitions":
-				if (isSchemaObject(value)) for (const [name, subschema] of Object.entries(value)) lintSchema(subschema, `${keyPath}/${escapePointerSegment(name)}`, depth + 1, context);
+				if (isSchemaObject(value)) for (const [name, subschema] of Object.entries(value)) lintSchema(subschema, `${keyPath}/${JsonPointer.escapeToken(name)}`, depth + 1, context);
 				break;
 			case "dependencies":
 				if (isSchemaObject(value)) {
-					for (const [name, dependency] of Object.entries(value)) if (!Array.isArray(dependency)) lintSchema(dependency, `${keyPath}/${escapePointerSegment(name)}`, depth + 1, context);
+					for (const [name, dependency] of Object.entries(value)) if (!Array.isArray(dependency)) lintSchema(dependency, `${keyPath}/${JsonPointer.escapeToken(name)}`, depth + 1, context);
 				}
 				break;
 			case "items":
@@ -162,10 +186,18 @@ const lintSchema = (node, path, depth, context) => {
 *   non-standard families ({@link KeywordFamilies}: `x-taplo*`, `x-tombi-*`,
 *   `x-intellij-*`, `x-ai-*` and the vscode set), which ajv strict mode would reject.
 * - `DescriptionWithoutUrl` — advisory: SchemaStore's description
-*   convention ends the root description with a docs URL line.
+*   convention ends the root description with a docs URL line. Read from
+*   the root, or from the `$defs` entry a bare local `$ref` root names —
+*   where assembly places a root annotation.
 *
-* Tractable because the input is bounded `toJsonSchemaDocument` output;
-* this is not a general JSON Schema validator.
+* Tractable because the input is the bounded {@link StoreDocument} shape,
+* not because assembly built it: the warning checks earn their keep on a
+* document the pipeline did not build — hand-assembled through
+* `StoreDocument.draft07`, or read back off disk. A local `$defs` pointer
+* is decoded the way ajv decodes it, so no `$ref` into the pool that the
+* engine gate resolves is reported `UnresolvedRef`; a `#/definitions/...`
+* pointer stays a warning on purpose, since the pool lives under `$defs`.
+* This is not a general JSON Schema validator.
 *
 * @public
 */
@@ -181,15 +213,16 @@ var DocumentLint = class {
 			findings: []
 		};
 		lintSchema(document.root, "", 0, context);
-		for (const [name, definition] of Object.entries(document.defs)) lintSchema(definition, `/$defs/${escapePointerSegment(name)}`, 1, context);
-		const description = document.root.description;
+		for (const [name, definition] of Object.entries(document.defs)) lintSchema(definition, `/$defs/${JsonPointer.escapeToken(name)}`, 1, context);
+		const described = describedNode(document);
+		const description = described?.node.description;
 		if (typeof description === "string") {
 			const lines = description.split("\n");
 			const last = lines[lines.length - 1] ?? "";
 			if (!URL_LINE.test(last.trim())) context.findings.push(DocumentLintFinding.make({
 				check: "DescriptionWithoutUrl",
 				severity: "advisory",
-				path: "/description",
+				path: `${described?.path ?? ""}/description`,
 				message: "SchemaStore's description convention ends with a documentation URL on its own line (<description>\\n<docs-url>)"
 			}));
 		}

package/README.md

@@ -320,6 +320,14 @@ The classification is key-order insensitive and keyword-position aware, like the
 
 `CanonicalJson` is the deterministic serializer behind `serializeResult` and `SchemaFile.write`: insertion-order keys (assembly owns ordering — nothing is sorted), tab indentation by default, LF line endings and a single trailing newline, so equal documents serialize to equal bytes. Where `JSON.stringify` silently drops or rewrites `undefined`, `NaN` and non-plain objects, it fails typed instead — `NonJsonValueError` carries a JSON pointer to the offending value, and `JsonDepthExceededError` catches hostile nesting and cycles.
 
+`CanonicalJson.equals` is content equality under the same semantics: two values are equal when they would parse to the same JSON document — object key order is ignored, arrays compare positionally, and a non-plain object (a class instance, a `Date`) compares by reference. It is the comparison `SchemaFile`'s write-if-changed and `DocumentDiff`'s leaf checks already make, exported so a consumer writing its own JSON artifact can decide "unchanged" by the same rule.
+
+## Root annotations
+
+Some annotations cannot be expressed on the source schema — a `Schema.Class` root's `title`, or a description on a field the generator filtered. `rootAnnotations` (on `StoreDocumentOptions`, and forwarded from `SchemaTarget.rootAnnotations` by the pipeline) merges them onto the emitted root after assembly. The gate is up front: only the standard annotation keywords (`title`, `description`, `$comment`, `default`, `examples`, `readOnly`, `writeOnly`, `contentMediaType`, `contentEncoding`) and the declared keyword families are admitted; anything else fails with `UndeclaredAnnotationKeyError` before generation, so the override cannot become a back door for assertion keywords.
+
+Placement follows the assembled root: an inline root takes the annotations directly; a bare local `$ref` root whose `$defs` entry nothing else references takes them on that entry (Draft-07 validators ignore `$ref` siblings); a bare `$ref` root whose entry is shared — a recursive class — becomes `{ ...annotations, allOf: [{ $ref }] }`, so the document is annotated without every occurrence of the type inheriting its title.
+
 ## Features
 
 - `StoreDocument` — the assembly pipeline: `fromSchema` / `fromSchemaResult`, the `draft07` constructor for hand-built documents, the flat `toJson()` publication shape, `serializeResult()`, the `DRAFT_07_META_SCHEMA` constant and `SchemaConversionError`.
@@ -331,8 +339,8 @@ The classification is key-order insensitive and keyword-position aware, like the
 - `DocumentDiff` — `classify` puts two documents in `"none"` / `"annotations"` / `"contract"`, the signal for whether a change needs a new schema version, plus `isClean` for the clean case.
 - `SchemaPipeline` — the emit loop over a target manifest, two-phase and all-or-nothing across targets: `run` and `check`, the single-target `runOne` and `checkOne`, `PipelineFinding`, `SchemaGateError` and an overridable gating predicate, plus the contract gate (`ContractChangePolicy`, `ContractChangeTarget`, `SchemaContractChangeError`, `PipelineCheckResult.contractBlocked`) that refuses to rewrite a published document's validation contract in place.
 - `SchemaFile` — write-if-changed IO over core `FileSystem` / `Path`, comparing by content and answering what changed as a value; `check` is the non-writing drift half, answering `wouldWrite` alongside `change`.
-- `SchemaTarget` — the target manifest vocabulary: schema, `$id`, destination path, an optional name, an optional version that requires one, and optional per-target `jsonSchema` generation options.
-- `CanonicalJson` — the deterministic serializer with typed failures (`NonJsonValueError`, `JsonDepthExceededError`).
+- `SchemaTarget` — the target manifest vocabulary: schema, `$id`, destination path, an optional name, an optional version that requires one, optional per-target `jsonSchema` generation options and `rootAnnotations` merged onto the emitted root.
+- `CanonicalJson` — the deterministic serializer with typed failures (`NonJsonValueError`, `JsonDepthExceededError`) and `equals`, content equality under the same semantics.
 
 ## License
 

package/SchemaPipeline.js

@@ -197,7 +197,8 @@ var SchemaPipeline = class SchemaPipeline {
 			for (const target of targets) {
 				const document = yield* StoreDocument.fromSchema(target.schema, {
 					$id: target.$id,
-					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {}
+					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {},
+					...target.rootAnnotations !== void 0 ? { rootAnnotations: target.rootAnnotations } : {}
 				});
 				const findings = yield* gather(document, options);
 				yield* gate(target, findings, options);
@@ -253,7 +254,8 @@ var SchemaPipeline = class SchemaPipeline {
 			for (const target of targets) {
 				const document = yield* StoreDocument.fromSchema(target.schema, {
 					$id: target.$id,
-					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {}
+					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {},
+					...target.rootAnnotations !== void 0 ? { rootAnnotations: target.rootAnnotations } : {}
 				});
 				const findings = yield* gather(document, options);
 				const { wouldWrite, change } = yield* files.check(target.path, document, options?.write);

package/SchemaTarget.js

@@ -29,7 +29,8 @@ var SchemaTarget = class {
 			published: options.published ?? false,
 			...options.name !== void 0 ? { name: options.name } : {},
 			...version !== void 0 ? { version } : {},
-			...options.jsonSchema !== void 0 ? { jsonSchema: options.jsonSchema } : {}
+			...options.jsonSchema !== void 0 ? { jsonSchema: options.jsonSchema } : {},
+			...options.rootAnnotations !== void 0 ? { rootAnnotations: options.rootAnnotations } : {}
 		};
 	}
 };

package/SchemaVersioning.js

@@ -73,7 +73,7 @@ const bumpNext = (current, parsed, components) => {
 	}
 };
 const assertSimpleName = (name) => {
-	if (name.length === 0 || /[/\\\s]/.test(name)) throw new Error(`Schema name must be a non-empty simple file base name, got "${name}"`);
+	if (!SchemaVersioning.isSimpleName(name)) throw new Error(`Schema name must be a non-empty simple file base name, got "${name}"`);
 };
 const joinUrl = (baseUrl, file) => {
 	let end = baseUrl.length;
@@ -182,22 +182,35 @@ var SchemaVersioning = class SchemaVersioning {
 		return reparsed.success;
 	}
 	/**
+	* Whether a name is a simple file base name — non-empty, no path
+	* separators, no whitespace — the rule every schema name is held to
+	* ({@link SchemaVersioning.fileName} throws on anything else; `defineConfig`
+	* rejects a schema key the same way). One predicate so the two cannot drift.
+	*/
+	static isSimpleName(name) {
+		return name.length > 0 && !/[/\\\s]/.test(name);
+	}
+	/**
 	* Derives the schema file name for a catalog name: `name.json`
-	* unversioned, `name-<version>.json` versioned.
+	* unversioned, `name-<version>.json` versioned under the `"flat"`
+	* layout (the default and the only shape SchemaStore serves), or
+	* `<version>/name-<version>.json` under `"versioned"`.
 	*
 	* The name must be a simple file base name (no separators, no
 	* whitespace); anything else is a wiring mistake and throws.
 	*/
-	static fileName(name, version) {
+	static fileName(name, version, layout = "flat") {
 		assertSimpleName(name);
-		return version === void 0 ? `${name}.json` : `${name}-${version}.json`;
+		if (version === void 0) return `${name}.json`;
+		const file = `${name}-${version}.json`;
+		return layout === "versioned" ? `${version}/${file}` : file;
 	}
 	/**
 	* The canonical URL a schema file is hosted at: `baseUrl` joined with
 	* {@link SchemaVersioning.fileName}.
 	*/
-	static schemaUrl(baseUrl, name, version) {
-		return joinUrl(baseUrl, SchemaVersioning.fileName(name, version));
+	static schemaUrl(baseUrl, name, version, layout = "flat") {
+		return joinUrl(baseUrl, SchemaVersioning.fileName(name, version, layout));
 	}
 	/**
 	* Assembles the `url`/`versions` half of a catalog entry.
@@ -205,29 +218,38 @@ var SchemaVersioning = class SchemaVersioning {
 	* Omitting `versions` selects the unversioned mode (`url` only,
 	* pointing at the plain `name.json`). Providing them selects the
 	* versioned mode: the `versions` map carries every label, and `url`
-	* points at the latest version's file. An **empty** `versions` array is
+	* points at `current` (default: the newest label under
+	* {@link SchemaVersioning.Order}). An **empty** `versions` array is
 	* a contradiction (versioned mode with no versions) and throws — pass
-	* `undefined` for the unversioned mode.
+	* `undefined` for the unversioned mode. `current`, when given, must
+	* compare equal under {@link SchemaVersioning.Order} to a member of
+	* `versions` or this throws; `url` is built from that member's own
+	* spelling (the `versions` map's key), not from the `current` argument
+	* verbatim — so a differently-spelled equivalent (`"1.2"` matching a
+	* `"1.2.0"` member) still points `url` at the same file the map does.
+	*
+	* `layout` (default `"flat"`) is forwarded to every URL derivation, so
+	* `"versioned"` nests every map value and `url` under its own version
+	* directory.
 	*
-	* Labels are inserted in ascending {@link SchemaVersioning.Order}, but a
-	* bare-major label (`"2"`) is array-index-like, so JavaScript enumerates
-	* it FIRST regardless of insertion order — the serialized order of the
-	* `versions` map is not meaningful when such a label is present. A two-
-	* or three-component label is never integer-like and keeps insertion
-	* order through serialization. Deriving ordering from the labels
-	* themselves (as {@link SchemaVersioning.latest} does) is still the
-	* robust read.
+	* Labels are inserted in ascending {@link SchemaVersioning.Order}; see
+	* {@link CatalogUrls.versions} for why a bare-major key's serialized
+	* position is not meaningful.
 	*/
 	static catalogUrls(options) {
 		const { baseUrl, name, versions } = options;
-		if (versions === void 0) return { url: SchemaVersioning.schemaUrl(baseUrl, name) };
+		const layout = options.layout ?? "flat";
+		if (versions === void 0) return { url: SchemaVersioning.schemaUrl(baseUrl, name, void 0, layout) };
 		if (versions.length === 0) throw new Error(`catalogUrls received an empty versions array for "${name}": pass undefined for the unversioned mode`);
 		const ascending = [...versions].sort(SchemaVersioning.Order);
 		const map = {};
-		for (const version of ascending) map[version] = SchemaVersioning.schemaUrl(baseUrl, name, version);
+		for (const version of ascending) map[version] = SchemaVersioning.schemaUrl(baseUrl, name, version, layout);
 		const newest = ascending[ascending.length - 1];
+		const requested = options.current ?? newest;
+		const current = ascending.find((v) => SchemaVersioning.Order(v, requested) === 0);
+		if (current === void 0) throw new Error(`catalogUrls: current "${requested}" is not one of the versions of "${name}"`);
 		return {
-			url: SchemaVersioning.schemaUrl(baseUrl, name, newest),
+			url: SchemaVersioning.schemaUrl(baseUrl, name, current, layout),
 			versions: map
 		};
 	}