@localess/schema 4.0.0 → 4.0.1-dev.20260915135536

package/SKILL.md

@@ -1,203 +1,203 @@
----
-name: localess-schema
-description: Programmatic Localess schema definitions in TypeScript, with pure type inference of content types (no codegen). Use when defining ROOT/NODE/ENUM schemas in code, deriving content types from those definitions, or validating/exporting a schema config before pushing it to a Localess space via `@localess/cli`.
----
-
-# @localess/schema
-
-Define Localess schemas (ROOT content types, NODE nested components, ENUM
-option sets) in TypeScript and derive content types from them by pure type
-inference — no build step, no generated `.d.ts` file. Zero external
-dependencies: its only dependency is `@localess/model`, the shared,
-dependency-free domain-model package (ADR 009).
-
-`@localess/cli`'s `schema pull`/`push`/`diff`/`validate` commands sync
-definitions written with this package to and from a Localess space. See that
-package's docs for the sync workflow; this package only defines, validates,
-infers, and exports — it does no I/O.
-
-## Quick start
-
-```ts
-import { defineConfig, defineEnum, defineSchema } from '@localess/schema';
-import type { InferContentData } from '@localess/schema';
-
-const ButtonType = defineEnum({
-  id: 'ButtonType',
-  displayName: 'Button Type',
-  values: [
-    { name: 'Primary', value: 'primary' },
-    { name: 'Secondary', value: 'secondary' },
-  ],
-});
-
-const Button = defineSchema({
-  id: 'Button',
-  type: 'NODE',
-  displayName: 'Button',
-  previewField: 'label',
-  fields: [
-    { name: 'label', kind: 'TEXT', required: true, translatable: true, maxLength: 50 },
-    { name: 'type', kind: 'OPTION', source: ButtonType }, // by-value ref, normalized to 'ButtonType'
-    { name: 'icon', kind: 'ASSET', fileTypes: ['IMAGE'] },
-  ],
-});
-
-const Page = defineSchema({
-  id: 'Page',
-  type: 'ROOT',
-  fields: [
-    { name: 'title', kind: 'TEXT', required: true },
-    { name: 'blocks', kind: 'SCHEMAS', schemas: [Button] },
-  ],
-});
-
-export const config = defineConfig({ schemas: [Page, Button, ButtonType] });
-
-// Content = { _id: string; _schema: 'Page'; title: string; blocks?: ButtonContent[] }
-export type Content = InferContentData<typeof config>;
-```
-
-## API reference
-
-| Export | Purpose |
-|---|---|
-| `defineEnum(definition)` | Define an ENUM schema. Identity function; injects `type: 'ENUM'`. |
-| `defineSchema(definition)` | Define a ROOT or NODE schema. Normalizes by-value refs (`source`, `schemas`) to id strings. Throws on duplicate field names. |
-| `defineField(field)` | Define a single field, narrowed by `kind`. Optional; catches a stray property from the wrong kind at the call site, unlike a bare field literal. Identity function. |
-| `defineConfig({ schemas })` | Register the full schema list — the unit the CLI loads and inference resolves against. Throws on duplicate schema ids. |
-| `validate(config)` | Non-throwing `{ ok, issues }` — ID/name patterns, reserved names, length limits, reference resolution. |
-| `toSchemaExport(config)` | Pure mapping to the wire format (`SchemaExport[]`) the Localess API accepts/returns. |
-| `InferContentData<C>` | Union of every ROOT schema's content type in config `C`. |
-| `InferContent<S, C>` | Content type of one schema definition `S`, resolved against config `C`. |
-| `InferEnum<E>` | Literal union of an enum definition's values. |
-
-### Exported types
-
-Everything below is `export type` — importable with `import type { ... } from '@localess/schema'`.
-
-| Group | Types |
-|---|---|
-| Authoring (from `define.ts`) | `EnumDefinition` (result of `defineEnum`), `ComponentDefinition` (result of `defineSchema`), `SchemaDefinition` (`ComponentDefinition \| EnumDefinition`), `LocalessSchemaConfig` (`{ schemas: readonly SchemaDefinition[] }` — what `validate`/`toSchemaExport` accept), `SchemaFieldInput` (a field as authored: `source`/`schemas` accept by-value refs), `EnumDefinitionInput`, `ComponentDefinitionInput` |
-| Inference (from `infer.ts`) | `InferContentData`, `InferContent`, `InferEnum` |
-| Validation (from `validate.ts`) | `ValidationIssue` (`{ severity: 'error' \| 'warning'; code; path; message }`), `ValidationResult` (`{ ok; issues }`) |
-| Wire model (re-exported from `@localess/model`) | `SchemaType`, `SchemaFieldKind`, `AssetFileType`, `SchemaEnumValue`, `SchemaFieldBase`, `SchemaField`, the 18 per-kind interfaces (`SchemaFieldText`, `SchemaFieldTextarea`, `SchemaFieldRichText`, `SchemaFieldMarkdown`, `SchemaFieldNumber`, `SchemaFieldColor`, `SchemaFieldDate`, `SchemaFieldDateTime`, `SchemaFieldBoolean`, `SchemaFieldOption`, `SchemaFieldOptions`, `SchemaFieldLink`, `SchemaFieldReference`, `SchemaFieldReferences`, `SchemaFieldAsset`, `SchemaFieldAssets`, `SchemaFieldSchema`, `SchemaFieldSchemas`), `SchemaComponentExport`, `SchemaEnumExport`, `SchemaExport` |
-| Content values (re-exported from `@localess/model`) | `ContentAsset`, `ContentLink`, `ContentReference`, `ContentRichText` |
-
-## `defineField`
-
-Optional. Wraps a single field so TypeScript catches a stray property from
-the wrong `kind` at the call site — something a bare field literal inside
-`defineSchema({ fields: [...] })` cannot do:
-
-```ts
-import { defineField } from '@localess/schema';
-
-defineField({ name: 'amount', kind: 'NUMBER', maxLength: 5 });
-// ^ compile error: maxLength is not valid on a NUMBER field
-
-defineField({ name: 'amount', kind: 'NUMBER', minValue: 0 }); // OK
-```
-
-`defineSchema`'s `fields` array accepts raw literals and `defineField(...)`
-results interchangeably — by-value ref normalization (`source`, `schemas`)
-still happens exclusively in `defineSchema`, regardless of a field's origin.
-
-## By-value references
-
-`OPTION`/`OPTIONS` fields accept an enum definition (or a string id) in
-`source`; `SCHEMA`/`SCHEMAS` fields accept schema definitions (or string ids)
-in `schemas`. Both are normalized to string ids at runtime by `defineSchema`,
-matching the wire format exactly — but the *type* keeps the literal id, so
-`InferContent` resolves `OPTION` fields to the referenced enum's literal
-value union instead of plain `string`, and `SCHEMA`/`SCHEMAS` fields to the
-allowed schemas' content types (or every `NODE` schema in the config when the
-`schemas` list is omitted).
-
-Fallbacks when a reference can't be resolved against the config:
-
-- `OPTION`/`OPTIONS` whose `source` id is not in the config → `string` (or
-  `string[]`), mirroring the CLI's `type generate` behavior.
-- `InferEnum` of an enum with no `values` → `string`.
-- Unrestricted `SCHEMA`/`SCHEMAS` (no `schemas` list) in a config with no
-  `NODE` schemas → `{ _id: string; _schema: string }` (or an array of it).
-- `InferContentData` of a config with no `ROOT` schema → `never`.
-
-## Field kinds
-
-Every field carries `name`, `kind`, and the base optional properties
-(`displayName`, `required`, `description`, `defaultValue`, `translatable`).
-`required: true` fields are non-optional keys on the inferred content type;
-everything else is optional.
-
-| Kind | Extra properties | Inferred type |
-|---|---|---|
-| `TEXT`, `TEXTAREA`, `MARKDOWN` | `minLength?`, `maxLength?` | `string` |
-| `RICH_TEXT` | `minLength?`, `maxLength?` | `ContentRichText` |
-| `NUMBER` | `minValue?`, `maxValue?` | `number` |
-| `COLOR`, `DATE`, `DATETIME` | — | `string` |
-| `BOOLEAN` | — | `boolean` |
-| `OPTION` | `source` (required; enum id or `defineEnum` result) | literal union of the referenced enum's values |
-| `OPTIONS` | `source` (required), `minValues?`, `maxValues?` | that union, as an array |
-| `LINK` | — | `ContentLink` |
-| `REFERENCE` / `REFERENCES` | `path?` | `ContentReference` / `ContentReference[]` |
-| `ASSET` / `ASSETS` | `fileTypes?: AssetFileType[]`, `fileType?: AssetFileType` | `ContentAsset` / `ContentAsset[]` |
-| `SCHEMA` / `SCHEMAS` | `schemas?` (allowed ids or `defineSchema` results; unrestricted when absent) | allowed schemas' content type / array of it |
-
-`AssetFileType` is `'ANY' | 'IMAGE' | 'VIDEO' | 'TEXT' | 'AUDIO' | 'APPLICATION'`.
-
-`ContentAsset`, `ContentLink`, `ContentReference`, and `ContentRichText` are
-re-exported from `@localess/model`, the shared domain-model package (see
-ADR 009).
-
-## `validate(config)`
-
-Non-throwing. Returns `{ ok, issues }`; `ok` is `false` only when at least
-one `error`-severity issue is present (the `ValidationIssue` type allows
-`'warning'`, but every rule currently implemented reports `error`). Every
-schema in the config is checked, not just the first. Rules and their `code`:
-
-| Code | Rule |
-|---|---|
-| `schema/invalid-id` | Schema id must match `/^[a-zA-Z][a-zA-Z0-9]+$/` and be 2-50 characters. |
-| `schema/reserved-id` | Schema id must not be (case-insensitively) `Translations`, `Links`, `ContentMetadata`, `ContentReference`, `ContentRichText`, `ContentLink`, `ContentData`, `ContentAsset`, or `Content`. |
-| `schema/display-name-too-long` | Schema `displayName` ≤ 50 characters. |
-| `schema/description-too-long` | Schema `description` ≤ 250 characters. |
-| `schema/invalid-label` | Each label 2-50 characters, no spaces. |
-| `enum/invalid-value-name` | ENUM value `name` 1-50 characters. |
-| `enum/invalid-value` | ENUM `value` 1-50 characters matching `/^[a-zA-Z]$\|^[a-zA-Z][a-zA-Z0-9-_]*[a-zA-Z0-9]$/`. |
-| `schema/unknown-preview-field` | `previewField` must name a field of the same schema. |
-| `field/invalid-name` | Field name must match `/^[a-z][a-zA-Z0-9_]*[a-zA-Z0-9]$/` (camelCase), be 2-30 characters, and not contain `_i18n_`. |
-| `field/reserved-name` | Field name must not be (case-insensitively) `_id` or `_schema`. |
-| `field/display-name-too-long` | Field `displayName` ≤ 30 characters. |
-| `field/description-too-long` | Field `description` ≤ 250 characters. |
-| `field/default-value-too-long` | Field `defaultValue` ≤ 250 characters. |
-| `field/unresolved-source` | `OPTION`/`OPTIONS` `source` must be the id of a schema in the config. |
-| `field/source-not-enum` | ...and that schema must be an `ENUM`. |
-| `field/unresolved-schema-ref` | Every `SCHEMA`/`SCHEMAS` `schemas` entry must be the id of a schema in the config. |
-| `field/schema-ref-is-enum` | ...and that schema must be `ROOT` or `NODE`, not `ENUM`. |
-
-`validate` does not check for stray properties from the wrong field kind —
-use `defineField` for that (below). Duplicate field names and duplicate
-schema ids are not validation issues either: `defineSchema`/`defineConfig`
-throw on them as programming errors.
-
-## `toSchemaExport(config)`
-
-Pure mapping to `SchemaExport[]`, preserving schema order. Strips
-`undefined`-valued keys from each schema and from the items of its array
-properties (`fields`, `values`), so the result round-trips through JSON
-unchanged. Performs no I/O.
-
-## Known limitation (mitigated by `defineField`)
-
-TypeScript's excess-property check doesn't apply to object literals inside
-an array passed through a `const`-inferred generic parameter (only to
-literals checked directly against a declared type). A stray property from
-the wrong field kind — e.g. `maxLength` on a `NUMBER` field — inside a bare
-field literal in `defineSchema({ fields: [...] })` is therefore not flagged
-at the call site. Wrap the field in `defineField(...)` instead to get that
-check while keeping full literal-type preservation (see "`defineField`"
-above). Missing required properties (e.g. omitting `source` on `OPTION`) are
-still caught either way. `validate()` and the Localess backend's schema
-validation don't check for this either today.
+---
+name: localess-schema
+description: Programmatic Localess schema definitions in TypeScript, with pure type inference of content types (no codegen). Use when defining ROOT/NODE/ENUM schemas in code, deriving content types from those definitions, or validating/exporting a schema config before pushing it to a Localess space via `@localess/cli`.
+---
+
+# @localess/schema
+
+Define Localess schemas (ROOT content types, NODE nested components, ENUM
+option sets) in TypeScript and derive content types from them by pure type
+inference — no build step, no generated `.d.ts` file. Zero external
+dependencies: its only dependency is `@localess/model`, the shared,
+dependency-free domain-model package (ADR 009).
+
+`@localess/cli`'s `schema pull`/`push`/`diff`/`validate` commands sync
+definitions written with this package to and from a Localess space. See that
+package's docs for the sync workflow; this package only defines, validates,
+infers, and exports — it does no I/O.
+
+## Quick start
+
+```ts
+import { defineConfig, defineEnum, defineSchema } from '@localess/schema';
+import type { InferContentData } from '@localess/schema';
+
+const ButtonType = defineEnum({
+  id: 'ButtonType',
+  displayName: 'Button Type',
+  values: [
+    { name: 'Primary', value: 'primary' },
+    { name: 'Secondary', value: 'secondary' },
+  ],
+});
+
+const Button = defineSchema({
+  id: 'Button',
+  type: 'NODE',
+  displayName: 'Button',
+  previewField: 'label',
+  fields: [
+    { name: 'label', kind: 'TEXT', required: true, translatable: true, maxLength: 50 },
+    { name: 'type', kind: 'OPTION', source: ButtonType }, // by-value ref, normalized to 'ButtonType'
+    { name: 'icon', kind: 'ASSET', fileTypes: ['IMAGE'] },
+  ],
+});
+
+const Page = defineSchema({
+  id: 'Page',
+  type: 'ROOT',
+  fields: [
+    { name: 'title', kind: 'TEXT', required: true },
+    { name: 'blocks', kind: 'SCHEMAS', schemas: [Button] },
+  ],
+});
+
+export const config = defineConfig({ schemas: [Page, Button, ButtonType] });
+
+// Content = { _id: string; _schema: 'Page'; title: string; blocks?: ButtonContent[] }
+export type Content = InferContentData<typeof config>;
+```
+
+## API reference
+
+| Export | Purpose |
+|---|---|
+| `defineEnum(definition)` | Define an ENUM schema. Identity function; injects `type: 'ENUM'`. |
+| `defineSchema(definition)` | Define a ROOT or NODE schema. Normalizes by-value refs (`source`, `schemas`) to id strings. Throws on duplicate field names. `previewField` is restricted to the names of the schema's own `fields` (falls back to `string` when `fields` is omitted). |
+| `defineField(field)` | Define a single field, narrowed by `kind`. Optional; catches a stray property from the wrong kind at the call site, unlike a bare field literal. Identity function. |
+| `defineConfig({ schemas })` | Register the full schema list — the unit the CLI loads and inference resolves against. Throws on duplicate schema ids. |
+| `validate(config)` | Non-throwing `{ ok, issues }` — ID/name patterns, reserved names, length limits, reference resolution. |
+| `toSchemaExport(config)` | Pure mapping to the wire format (`SchemaExport[]`) the Localess API accepts/returns. |
+| `InferContentData<C>` | Union of every ROOT schema's content type in config `C`. |
+| `InferContent<S, C>` | Content type of one schema definition `S`, resolved against config `C`. |
+| `InferEnum<E>` | Literal union of an enum definition's values. |
+
+### Exported types
+
+Everything below is `export type` — importable with `import type { ... } from '@localess/schema'`.
+
+| Group | Types |
+|---|---|
+| Authoring (from `define.ts`) | `EnumDefinition` (result of `defineEnum`), `ComponentDefinition` (result of `defineSchema`), `SchemaDefinition` (`ComponentDefinition \| EnumDefinition`), `LocalessSchemaConfig` (`{ schemas: readonly SchemaDefinition[] }` — what `validate`/`toSchemaExport` accept), `SchemaFieldInput` (a field as authored: `source`/`schemas` accept by-value refs), `EnumDefinitionInput`, `ComponentDefinitionInput` |
+| Inference (from `infer.ts`) | `InferContentData`, `InferContent`, `InferEnum` |
+| Validation (from `validate.ts`) | `ValidationIssue` (`{ severity: 'error' \| 'warning'; code; path; message }`), `ValidationResult` (`{ ok; issues }`) |
+| Wire model (re-exported from `@localess/model`) | `SchemaType`, `SchemaFieldKind`, `AssetFileType`, `SchemaEnumValue`, `SchemaFieldBase`, `SchemaField`, the 18 per-kind interfaces (`SchemaFieldText`, `SchemaFieldTextarea`, `SchemaFieldRichText`, `SchemaFieldMarkdown`, `SchemaFieldNumber`, `SchemaFieldColor`, `SchemaFieldDate`, `SchemaFieldDateTime`, `SchemaFieldBoolean`, `SchemaFieldOption`, `SchemaFieldOptions`, `SchemaFieldLink`, `SchemaFieldReference`, `SchemaFieldReferences`, `SchemaFieldAsset`, `SchemaFieldAssets`, `SchemaFieldSchema`, `SchemaFieldSchemas`), `SchemaComponentExport`, `SchemaEnumExport`, `SchemaExport` |
+| Content values (re-exported from `@localess/model`) | `ContentAsset`, `ContentLink`, `ContentReference`, `ContentRichText` |
+
+## `defineField`
+
+Optional. Wraps a single field so TypeScript catches a stray property from
+the wrong `kind` at the call site — something a bare field literal inside
+`defineSchema({ fields: [...] })` cannot do:
+
+```ts
+import { defineField } from '@localess/schema';
+
+defineField({ name: 'amount', kind: 'NUMBER', maxLength: 5 });
+// ^ compile error: maxLength is not valid on a NUMBER field
+
+defineField({ name: 'amount', kind: 'NUMBER', minValue: 0 }); // OK
+```
+
+`defineSchema`'s `fields` array accepts raw literals and `defineField(...)`
+results interchangeably — by-value ref normalization (`source`, `schemas`)
+still happens exclusively in `defineSchema`, regardless of a field's origin.
+
+## By-value references
+
+`OPTION`/`OPTIONS` fields accept an enum definition (or a string id) in
+`source`; `SCHEMA`/`SCHEMAS` fields accept schema definitions (or string ids)
+in `schemas`. Both are normalized to string ids at runtime by `defineSchema`,
+matching the wire format exactly — but the *type* keeps the literal id, so
+`InferContent` resolves `OPTION` fields to the referenced enum's literal
+value union instead of plain `string`, and `SCHEMA`/`SCHEMAS` fields to the
+allowed schemas' content types (or every `NODE` schema in the config when the
+`schemas` list is omitted).
+
+Fallbacks when a reference can't be resolved against the config:
+
+- `OPTION`/`OPTIONS` whose `source` id is not in the config → `string` (or
+  `string[]`), mirroring the CLI's `type generate` behavior.
+- `InferEnum` of an enum with no `values` → `string`.
+- Unrestricted `SCHEMA`/`SCHEMAS` (no `schemas` list) in a config with no
+  `NODE` schemas → `{ _id: string; _schema: string }` (or an array of it).
+- `InferContentData` of a config with no `ROOT` schema → `never`.
+
+## Field kinds
+
+Every field carries `name`, `kind`, and the base optional properties
+(`displayName`, `required`, `description`, `defaultValue`, `translatable`).
+`required: true` fields are non-optional keys on the inferred content type;
+everything else is optional.
+
+| Kind | Extra properties | Inferred type |
+|---|---|---|
+| `TEXT`, `TEXTAREA`, `MARKDOWN` | `minLength?`, `maxLength?` | `string` |
+| `RICH_TEXT` | `minLength?`, `maxLength?` | `ContentRichText` |
+| `NUMBER` | `minValue?`, `maxValue?` | `number` |
+| `COLOR`, `DATE`, `DATETIME` | — | `string` |
+| `BOOLEAN` | — | `boolean` |
+| `OPTION` | `source` (required; enum id or `defineEnum` result) | literal union of the referenced enum's values |
+| `OPTIONS` | `source` (required), `minValues?`, `maxValues?` | that union, as an array |
+| `LINK` | — | `ContentLink` |
+| `REFERENCE` / `REFERENCES` | `path?` | `ContentReference` / `ContentReference[]` |
+| `ASSET` / `ASSETS` | `fileTypes?: AssetFileType[]`, `fileType?: AssetFileType` | `ContentAsset` / `ContentAsset[]` |
+| `SCHEMA` / `SCHEMAS` | `schemas?` (allowed ids or `defineSchema` results; unrestricted when absent) | allowed schemas' content type / array of it |
+
+`AssetFileType` is `'ANY' | 'IMAGE' | 'VIDEO' | 'TEXT' | 'AUDIO' | 'APPLICATION'`.
+
+`ContentAsset`, `ContentLink`, `ContentReference`, and `ContentRichText` are
+re-exported from `@localess/model`, the shared domain-model package (see
+ADR 009).
+
+## `validate(config)`
+
+Non-throwing. Returns `{ ok, issues }`; `ok` is `false` only when at least
+one `error`-severity issue is present (the `ValidationIssue` type allows
+`'warning'`, but every rule currently implemented reports `error`). Every
+schema in the config is checked, not just the first. Rules and their `code`:
+
+| Code | Rule |
+|---|---|
+| `schema/invalid-id` | Schema id must match `/^[a-zA-Z][a-zA-Z0-9]+$/` and be 2-50 characters. |
+| `schema/reserved-id` | Schema id must not be (case-insensitively) `Translations`, `Links`, `ContentMetadata`, `ContentReference`, `ContentRichText`, `ContentLink`, `ContentData`, `ContentAsset`, or `Content`. |
+| `schema/display-name-too-long` | Schema `displayName` ≤ 50 characters. |
+| `schema/description-too-long` | Schema `description` ≤ 250 characters. |
+| `schema/invalid-label` | Each label 2-50 characters, no spaces. |
+| `enum/invalid-value-name` | ENUM value `name` 1-50 characters. |
+| `enum/invalid-value` | ENUM `value` 1-50 characters matching `/^[a-zA-Z]$\|^[a-zA-Z][a-zA-Z0-9-_]*[a-zA-Z0-9]$/`. |
+| `schema/unknown-preview-field` | `previewField` must name a field of the same schema. |
+| `field/invalid-name` | Field name must match `/^[a-z][a-zA-Z0-9_]*[a-zA-Z0-9]$/` (camelCase), be 2-30 characters, and not contain `_i18n_`. |
+| `field/reserved-name` | Field name must not be (case-insensitively) `_id` or `_schema`. |
+| `field/display-name-too-long` | Field `displayName` ≤ 30 characters. |
+| `field/description-too-long` | Field `description` ≤ 250 characters. |
+| `field/default-value-too-long` | Field `defaultValue` ≤ 250 characters. |
+| `field/unresolved-source` | `OPTION`/`OPTIONS` `source` must be the id of a schema in the config. |
+| `field/source-not-enum` | ...and that schema must be an `ENUM`. |
+| `field/unresolved-schema-ref` | Every `SCHEMA`/`SCHEMAS` `schemas` entry must be the id of a schema in the config. |
+| `field/schema-ref-is-enum` | ...and that schema must be `ROOT` or `NODE`, not `ENUM`. |
+
+`validate` does not check for stray properties from the wrong field kind —
+use `defineField` for that (below). Duplicate field names and duplicate
+schema ids are not validation issues either: `defineSchema`/`defineConfig`
+throw on them as programming errors.
+
+## `toSchemaExport(config)`
+
+Pure mapping to `SchemaExport[]`, preserving schema order. Strips
+`undefined`-valued keys from each schema and from the items of its array
+properties (`fields`, `values`), so the result round-trips through JSON
+unchanged. Performs no I/O.
+
+## Known limitation (mitigated by `defineField`)
+
+TypeScript's excess-property check doesn't apply to object literals inside
+an array passed through a `const`-inferred generic parameter (only to
+literals checked directly against a declared type). A stray property from
+the wrong field kind — e.g. `maxLength` on a `NUMBER` field — inside a bare
+field literal in `defineSchema({ fields: [...] })` is therefore not flagged
+at the call site. Wrap the field in `defineField(...)` instead to get that
+check while keeping full literal-type preservation (see "`defineField`"
+above). Missing required properties (e.g. omitting `source` on `OPTION`) are
+still caught either way. `validate()` and the Localess backend's schema
+validation don't check for this either today.

package/dist/define.d.ts

@@ -37,9 +37,9 @@ type FieldInputOf<F> = F extends {
  * against a declared type), so a stray property from a different kind (e.g. `maxLength` on a
  * `NUMBER` field) inside `defineSchema({ fields: [...] })` will not be flagged at the call site.
  * Missing required properties (e.g. omitting `source` on `OPTION`) are still caught, since that is
- * ordinary structural assignability, not a freshness check. Sanity documents the same limitation
- * for their unwrapped array fields; the alternative is a per-field wrapper function, which this
- * package deliberately avoids (see ADR 008).
+ * ordinary structural assignability, not a freshness check. Wrap a field in `defineField(...)` to
+ * get the excess-property check at the call site; raw literals and `defineField` results are
+ * accepted interchangeably (see ADR 008).
  */
 export type SchemaFieldInput = FieldInputOf<SchemaField>;
 /** Authoring input for defineEnum: type is injected by the helper. */
@@ -100,8 +100,21 @@ type DefinedComponent<TId extends string, TType extends 'ROOT' | 'NODE', TFields
  * Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
  * exists to preserve literal types for inference.
  *
+ * - `id` — unique schema id; also what `OPTION`/`OPTIONS` fields reference via `source`
+ * - `values` — the fixed option set; each `{ name, value }` becomes one selectable option, and
+ *   every `value` across the config becomes part of `InferEnum`'s literal union
+ *
  * @param definition the enum definition (id, values, optional display metadata)
  * @returns the definition with `type: 'ENUM'`, literal types preserved
+ *
+ * @example
+ * const Status = defineEnum({
+ *   id: 'Status',
+ *   values: [
+ *     { name: 'Draft', value: 'draft' },
+ *     { name: 'Published', value: 'published' },
+ *   ],
+ * });
  */
 export declare function defineEnum<const TId extends string, const TValues extends readonly SchemaEnumValue[] | undefined = undefined>(definition: {
     id: TId;
@@ -119,8 +132,29 @@ export declare function defineEnum<const TId extends string, const TValues exten
  * (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
  * of a field's origin. See `docs/decisions/008-schema-package.md`.
  *
+ * Every `kind` accepts `name` (required), plus `displayName?`, `required?`, `description?`,
+ * `defaultValue?`, `translatable?`. Kind-specific extras:
+ * - `TEXT` / `TEXTAREA` / `RICH_TEXT` / `MARKDOWN` — `minLength?`, `maxLength?`
+ * - `NUMBER` — `minValue?`, `maxValue?`
+ * - `COLOR` / `DATE` / `DATETIME` / `BOOLEAN` / `LINK` — no extras
+ * - `OPTION` — `source` (required: an ENUM definition from `defineEnum`, or its id)
+ * - `OPTIONS` — `source` (required, same as `OPTION`), `minValues?`, `maxValues?`
+ * - `REFERENCE` / `REFERENCES` — `path?`
+ * - `ASSET` / `ASSETS` — `fileTypes?`, `fileType?`
+ * - `SCHEMA` / `SCHEMAS` — `schemas?` (allowed definitions from `defineSchema`, or their ids;
+ *   every `NODE` schema in the config is allowed when omitted)
+ *
+ * Full field-kind reference, including the type each kind infers to: `docs/schema.md`.
+ *
  * @param field the field definition; `kind` selects which extra properties are allowed
  * @returns the field unchanged, with `name`/`kind`/extras narrowed to their literal types
+ *
+ * @example
+ * defineField({ name: 'title', kind: 'TEXT', required: true, maxLength: 100 });
+ * @example
+ * defineField({ name: 'status', kind: 'OPTION', source: Status }); // Status = defineEnum(...)
+ * @example
+ * defineField({ name: 'blocks', kind: 'SCHEMAS', schemas: [Button] }); // Button = defineSchema(...)
  */
 export declare function defineField<const TKind extends SchemaFieldKind, const TName extends string, const TField extends Omit<Extract<SchemaFieldInput, {
     kind: TKind;
@@ -133,14 +167,36 @@ export declare function defineField<const TKind extends SchemaFieldKind, const T
     name: TName;
     kind: TKind;
 } & TField>;
+/** Union of a schema's own field names; falls back to plain `string` when `fields` is omitted. */
+type FieldNameOf<TFields> = TFields extends readonly {
+    name: infer N extends string;
+}[] ? N : string;
 /**
  * Define a ROOT (content type) or NODE (nested component) schema.
  * Normalizes by-value references (enum in `source`, components in `schemas`) to their id strings;
  * the returned type keeps those ids as literals for inference.
  *
+ * - `id` — unique schema id; also the `_schema` value on its inferred content type, and what
+ *   `SCHEMA`/`SCHEMAS` fields reference via `schemas`
+ * - `type` — `'ROOT'` for a fetchable content type, `'NODE'` for a nested component only reachable
+ *   through another schema's `SCHEMA`/`SCHEMAS` field
+ * - `previewField` — name of one of this schema's own fields, shown as its preview label in the
+ *   Localess editor; restricted to the field names in `fields` (falls back to plain `string`
+ *   when `fields` is omitted)
+ * - `fields` — ordered list of `defineField(...)` results and/or raw field literals; see
+ *   `defineField` for the per-kind property reference
+ *
  * @param definition the schema definition; `type` selects ROOT or NODE
  * @returns the definition with references normalized to id strings, literal types preserved
  * @throws Error on duplicate field names — a programming error, not a validation concern
+ *
+ * @example
+ * const Button = defineSchema({
+ *   id: 'Button',
+ *   type: 'NODE',
+ *   previewField: 'label',
+ *   fields: [defineField({ name: 'label', kind: 'TEXT', required: true })],
+ * });
  */
 export declare function defineSchema<const TId extends string, const TType extends 'ROOT' | 'NODE', const TFields extends readonly SchemaFieldInput[] | undefined = undefined>(definition: {
     id: TId;
@@ -148,7 +204,7 @@ export declare function defineSchema<const TId extends string, const TType exten
     displayName?: string;
     description?: string;
     labels?: readonly string[];
-    previewField?: string;
+    previewField?: FieldNameOf<TFields>;
     fields?: TFields;
 }): DefinedComponent<TId, TType, TFields>;
 /**

package/dist/index.js

@@ -4,8 +4,21 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
 * exists to preserve literal types for inference.
 *
+* - `id` — unique schema id; also what `OPTION`/`OPTIONS` fields reference via `source`
+* - `values` — the fixed option set; each `{ name, value }` becomes one selectable option, and
+*   every `value` across the config becomes part of `InferEnum`'s literal union
+*
 * @param definition the enum definition (id, values, optional display metadata)
 * @returns the definition with `type: 'ENUM'`, literal types preserved
+*
+* @example
+* const Status = defineEnum({
+*   id: 'Status',
+*   values: [
+*     { name: 'Draft', value: 'draft' },
+*     { name: 'Published', value: 'published' },
+*   ],
+* });
 */
 function defineEnum(definition) {
 	return {
@@ -22,8 +35,29 @@ function defineEnum(definition) {
 * (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
 * of a field's origin. See `docs/decisions/008-schema-package.md`.
 *
+* Every `kind` accepts `name` (required), plus `displayName?`, `required?`, `description?`,
+* `defaultValue?`, `translatable?`. Kind-specific extras:
+* - `TEXT` / `TEXTAREA` / `RICH_TEXT` / `MARKDOWN` — `minLength?`, `maxLength?`
+* - `NUMBER` — `minValue?`, `maxValue?`
+* - `COLOR` / `DATE` / `DATETIME` / `BOOLEAN` / `LINK` — no extras
+* - `OPTION` — `source` (required: an ENUM definition from `defineEnum`, or its id)
+* - `OPTIONS` — `source` (required, same as `OPTION`), `minValues?`, `maxValues?`
+* - `REFERENCE` / `REFERENCES` — `path?`
+* - `ASSET` / `ASSETS` — `fileTypes?`, `fileType?`
+* - `SCHEMA` / `SCHEMAS` — `schemas?` (allowed definitions from `defineSchema`, or their ids;
+*   every `NODE` schema in the config is allowed when omitted)
+*
+* Full field-kind reference, including the type each kind infers to: `docs/schema.md`.
+*
 * @param field the field definition; `kind` selects which extra properties are allowed
 * @returns the field unchanged, with `name`/`kind`/extras narrowed to their literal types
+*
+* @example
+* defineField({ name: 'title', kind: 'TEXT', required: true, maxLength: 100 });
+* @example
+* defineField({ name: 'status', kind: 'OPTION', source: Status }); // Status = defineEnum(...)
+* @example
+* defineField({ name: 'blocks', kind: 'SCHEMAS', schemas: [Button] }); // Button = defineSchema(...)
 */
 function defineField(field) {
 	return field;
@@ -33,9 +67,27 @@ function defineField(field) {
 * Normalizes by-value references (enum in `source`, components in `schemas`) to their id strings;
 * the returned type keeps those ids as literals for inference.
 *
+* - `id` — unique schema id; also the `_schema` value on its inferred content type, and what
+*   `SCHEMA`/`SCHEMAS` fields reference via `schemas`
+* - `type` — `'ROOT'` for a fetchable content type, `'NODE'` for a nested component only reachable
+*   through another schema's `SCHEMA`/`SCHEMAS` field
+* - `previewField` — name of one of this schema's own fields, shown as its preview label in the
+*   Localess editor; restricted to the field names in `fields` (falls back to plain `string`
+*   when `fields` is omitted)
+* - `fields` — ordered list of `defineField(...)` results and/or raw field literals; see
+*   `defineField` for the per-kind property reference
+*
 * @param definition the schema definition; `type` selects ROOT or NODE
 * @returns the definition with references normalized to id strings, literal types preserved
 * @throws Error on duplicate field names — a programming error, not a validation concern
+*
+* @example
+* const Button = defineSchema({
+*   id: 'Button',
+*   type: 'NODE',
+*   previewField: 'label',
+*   fields: [defineField({ name: 'label', kind: 'TEXT', required: true })],
+* });
 */
 function defineSchema(definition) {
 	const seen = /* @__PURE__ */ new Set();

package/dist/index.mjs

@@ -3,8 +3,21 @@
 * Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
 * exists to preserve literal types for inference.
 *
+* - `id` — unique schema id; also what `OPTION`/`OPTIONS` fields reference via `source`
+* - `values` — the fixed option set; each `{ name, value }` becomes one selectable option, and
+*   every `value` across the config becomes part of `InferEnum`'s literal union
+*
 * @param definition the enum definition (id, values, optional display metadata)
 * @returns the definition with `type: 'ENUM'`, literal types preserved
+*
+* @example
+* const Status = defineEnum({
+*   id: 'Status',
+*   values: [
+*     { name: 'Draft', value: 'draft' },
+*     { name: 'Published', value: 'published' },
+*   ],
+* });
 */
 function defineEnum(definition) {
 	return {
@@ -21,8 +34,29 @@ function defineEnum(definition) {
 * (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
 * of a field's origin. See `docs/decisions/008-schema-package.md`.
 *
+* Every `kind` accepts `name` (required), plus `displayName?`, `required?`, `description?`,
+* `defaultValue?`, `translatable?`. Kind-specific extras:
+* - `TEXT` / `TEXTAREA` / `RICH_TEXT` / `MARKDOWN` — `minLength?`, `maxLength?`
+* - `NUMBER` — `minValue?`, `maxValue?`
+* - `COLOR` / `DATE` / `DATETIME` / `BOOLEAN` / `LINK` — no extras
+* - `OPTION` — `source` (required: an ENUM definition from `defineEnum`, or its id)
+* - `OPTIONS` — `source` (required, same as `OPTION`), `minValues?`, `maxValues?`
+* - `REFERENCE` / `REFERENCES` — `path?`
+* - `ASSET` / `ASSETS` — `fileTypes?`, `fileType?`
+* - `SCHEMA` / `SCHEMAS` — `schemas?` (allowed definitions from `defineSchema`, or their ids;
+*   every `NODE` schema in the config is allowed when omitted)
+*
+* Full field-kind reference, including the type each kind infers to: `docs/schema.md`.
+*
 * @param field the field definition; `kind` selects which extra properties are allowed
 * @returns the field unchanged, with `name`/`kind`/extras narrowed to their literal types
+*
+* @example
+* defineField({ name: 'title', kind: 'TEXT', required: true, maxLength: 100 });
+* @example
+* defineField({ name: 'status', kind: 'OPTION', source: Status }); // Status = defineEnum(...)
+* @example
+* defineField({ name: 'blocks', kind: 'SCHEMAS', schemas: [Button] }); // Button = defineSchema(...)
 */
 function defineField(field) {
 	return field;
@@ -32,9 +66,27 @@ function defineField(field) {
 * Normalizes by-value references (enum in `source`, components in `schemas`) to their id strings;
 * the returned type keeps those ids as literals for inference.
 *
+* - `id` — unique schema id; also the `_schema` value on its inferred content type, and what
+*   `SCHEMA`/`SCHEMAS` fields reference via `schemas`
+* - `type` — `'ROOT'` for a fetchable content type, `'NODE'` for a nested component only reachable
+*   through another schema's `SCHEMA`/`SCHEMAS` field
+* - `previewField` — name of one of this schema's own fields, shown as its preview label in the
+*   Localess editor; restricted to the field names in `fields` (falls back to plain `string`
+*   when `fields` is omitted)
+* - `fields` — ordered list of `defineField(...)` results and/or raw field literals; see
+*   `defineField` for the per-kind property reference
+*
 * @param definition the schema definition; `type` selects ROOT or NODE
 * @returns the definition with references normalized to id strings, literal types preserved
 * @throws Error on duplicate field names — a programming error, not a validation concern
+*
+* @example
+* const Button = defineSchema({
+*   id: 'Button',
+*   type: 'NODE',
+*   previewField: 'label',
+*   fields: [defineField({ name: 'label', kind: 'TEXT', required: true })],
+* });
 */
 function defineSchema(definition) {
 	const seen = /* @__PURE__ */ new Set();

package/dist/infer.d.ts

@@ -9,11 +9,9 @@ type SchemasOf<C> = C extends {
 type FindById<C, Id> = Extract<SchemasOf<C>, {
     id: Id;
 }>;
-type NodeIds<C> = [
-    Extract<SchemasOf<C>, {
-        type: 'NODE';
-    }>
-] extends [never] ? never : Extract<SchemasOf<C>, {
+type NodeIds<C> = [Extract<SchemasOf<C>, {
+    type: 'NODE';
+}>] extends [never] ? never : Extract<SchemasOf<C>, {
     type: 'NODE';
 }> extends {
     id: infer Id extends string;
@@ -93,11 +91,9 @@ export type InferContent<S, C> = S extends {
     _id: string;
     _schema: Id;
 } & FieldsObject<S, C>> : never;
-type RootIds<C> = [
-    Extract<SchemasOf<C>, {
-        type: 'ROOT';
-    }>
-] extends [never] ? never : Extract<SchemasOf<C>, {
+type RootIds<C> = [Extract<SchemasOf<C>, {
+    type: 'ROOT';
+}>] extends [never] ? never : Extract<SchemasOf<C>, {
     type: 'ROOT';
 }> extends {
     id: infer Id extends string;

package/package.json

@@ -1,57 +1,57 @@
-{
-  "name": "@localess/schema",
-  "version": "4.0.0",
-  "description": "Programmatic schema definitions for Localess with TypeScript content type inference.",
-  "keywords": [
-    "localess",
-    "sdk",
-    "schema",
-    "cms",
-    "javascript",
-    "typescript"
-  ],
-  "author": "Lessify",
-  "homepage": "https://github.com/Lessify/localess-js",
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "SKILL.md"
-  ],
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Lessify/localess-js.git",
-    "directory": "packages/schema"
-  },
-  "bugs": {
-    "url": "https://github.com/Lessify/localess-js/issues"
-  },
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
-  },
-  "license": "MIT",
-  "dependencies": {
-    "@localess/model": "*"
-  },
-  "devDependencies": {
-    "@types/node": "^24",
-    "typescript": "^5.9.3",
-    "vite": "^8.0.16",
-    "vite-plugin-dts": "^5.0.0"
-  },
-  "engines": {
-    "node": ">= 24.0.0"
-  }
-}
+{
+  "name": "@localess/schema",
+  "version": "4.0.1-dev.20260915135536",
+  "description": "Programmatic schema definitions for Localess with TypeScript content type inference.",
+  "keywords": [
+    "localess",
+    "sdk",
+    "schema",
+    "cms",
+    "javascript",
+    "typescript"
+  ],
+  "author": "Lessify",
+  "homepage": "https://github.com/Lessify/localess-js",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "SKILL.md"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lessify/localess-js.git",
+    "directory": "packages/schema"
+  },
+  "bugs": {
+    "url": "https://github.com/Lessify/localess-js/issues"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@localess/model": "4.0.1-dev.20260915135536"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.0"
+  },
+  "engines": {
+    "node": ">= 24.0.0"
+  }
+}