@localess/schema 4.0.0-dev.20260905071322

package/SKILL.md

@@ -0,0 +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.

package/dist/define.d.ts

@@ -0,0 +1,164 @@
+import { SchemaComponentExport, SchemaEnumExport, SchemaEnumValue, SchemaField, SchemaFieldKind } from './models';
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Deep-readonly view of a wire type. Definitions created with `const` type parameters carry
+ * readonly arrays/tuples, which the mutable wire types would reject — every authoring-facing
+ * type is therefore expressed through this.
+ */
+type DeepReadonly<T> = T extends readonly (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/** Result of defineEnum — readonly view of the wire SchemaEnumExport. */
+export type EnumDefinition = DeepReadonly<SchemaEnumExport>;
+/** Result of defineSchema — readonly view of the wire SchemaComponentExport. */
+export type ComponentDefinition = DeepReadonly<SchemaComponentExport>;
+/** Any schema definition. */
+export type SchemaDefinition = ComponentDefinition | EnumDefinition;
+/** A registry of schema definitions — the unit the CLI loads and inference resolves against. */
+export interface LocalessSchemaConfig {
+    schemas: readonly SchemaDefinition[];
+}
+type FieldInputOf<F> = F extends {
+    kind: 'OPTION' | 'OPTIONS';
+} ? Omit<DeepReadonly<F>, 'source'> & {
+    readonly source: string | EnumDefinition;
+} : F extends {
+    kind: 'SCHEMA' | 'SCHEMAS';
+} ? Omit<DeepReadonly<F>, 'schemas'> & {
+    readonly schemas?: readonly (string | ComponentDefinition)[];
+} : DeepReadonly<F>;
+/**
+ * A field as authored: OPTION/OPTIONS source and SCHEMA/SCHEMAS schemas accept by-value refs.
+ *
+ * Known limitation: TypeScript's excess-property check does not apply to object literals inside
+ * an array passed through a `const`-inferred generic parameter (only to literals checked directly
+ * 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. 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. */
+export interface EnumDefinitionInput {
+    id: string;
+    displayName?: string;
+    description?: string;
+    labels?: readonly string[];
+    values?: readonly SchemaEnumValue[];
+}
+/** Authoring input for defineSchema. */
+export interface ComponentDefinitionInput {
+    id: string;
+    type: 'ROOT' | 'NODE';
+    displayName?: string;
+    description?: string;
+    labels?: readonly string[];
+    previewField?: string;
+    fields?: readonly SchemaFieldInput[];
+}
+type NormalizeRef<S> = S extends {
+    readonly id: infer Id extends string;
+} ? Id : S;
+type NormalizeRefs<A> = A extends readonly unknown[] ? {
+    -readonly [K in keyof A]: NormalizeRef<A[K]>;
+} : A;
+type NormalizeField<F> = Prettify<Omit<F, 'source' | 'schemas'> & (F extends {
+    source: infer S;
+} ? {
+    source: NormalizeRef<S>;
+} : unknown) & (F extends {
+    schemas: infer A;
+} ? {
+    schemas: NormalizeRefs<A>;
+} : unknown)>;
+type DefinedEnum<TId extends string, TValues> = Prettify<{
+    id: TId;
+    type: 'ENUM';
+    displayName?: string;
+    description?: string;
+    labels?: readonly string[];
+} & (TValues extends readonly unknown[] ? {
+    values: TValues;
+} : unknown)>;
+type DefinedComponent<TId extends string, TType extends 'ROOT' | 'NODE', TFields> = Prettify<{
+    id: TId;
+    type: TType;
+    displayName?: string;
+    description?: string;
+    labels?: readonly string[];
+    previewField?: string;
+} & (TFields extends readonly unknown[] ? {
+    fields: {
+        -readonly [K in keyof TFields]: NormalizeField<TFields[K]>;
+    };
+} : unknown)>;
+/**
+ * Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
+ * exists to preserve literal types for inference.
+ *
+ * @param definition the enum definition (id, values, optional display metadata)
+ * @returns the definition with `type: 'ENUM'`, literal types preserved
+ */
+export declare function defineEnum<const TId extends string, const TValues extends readonly SchemaEnumValue[] | undefined = undefined>(definition: {
+    id: TId;
+    displayName?: string;
+    description?: string;
+    labels?: readonly string[];
+    values?: TValues;
+}): DefinedEnum<TId, TValues>;
+/**
+ * Define a single field, narrowing it to the extras valid for its `kind` and catching a stray
+ * property from the wrong kind at the call site (e.g. `maxLength` on a `NUMBER` field) — something
+ * a bare field literal inside `defineSchema({ fields: [...] })` cannot do. Optional: `defineSchema`
+ * accepts raw field literals and `defineField(...)` results interchangeably in the same `fields`
+ * array. A near-identity function like `defineEnum`/`defineSchema` — by-value ref normalization
+ * (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
+ * of a field's origin. See `docs/decisions/008-schema-package.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
+ */
+export declare function defineField<const TKind extends SchemaFieldKind, const TName extends string, const TField extends Omit<Extract<SchemaFieldInput, {
+    kind: TKind;
+}>, 'name' | 'kind'> = Omit<Extract<SchemaFieldInput, {
+    kind: TKind;
+}>, 'name' | 'kind'>>(field: {
+    kind: TKind;
+    name: TName;
+} & TField): Prettify<{
+    name: TName;
+    kind: TKind;
+} & TField>;
+/**
+ * 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.
+ *
+ * @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
+ */
+export declare function defineSchema<const TId extends string, const TType extends 'ROOT' | 'NODE', const TFields extends readonly SchemaFieldInput[] | undefined = undefined>(definition: {
+    id: TId;
+    type: TType;
+    displayName?: string;
+    description?: string;
+    labels?: readonly string[];
+    previewField?: string;
+    fields?: TFields;
+}): DefinedComponent<TId, TType, TFields>;
+/**
+ * Register schemas into a config — the unit the CLI pushes and type inference resolves against.
+ *
+ * @param config object with the full list of schema definitions
+ * @returns the config unchanged, literal types preserved
+ * @throws Error on duplicate schema ids
+ */
+export declare function defineConfig<const T extends {
+    schemas: readonly SchemaDefinition[];
+}>(config: T): T;
+export {};

package/dist/export.d.ts

@@ -0,0 +1,7 @@
+import { LocalessSchemaConfig } from './define';
+import { SchemaExport } from './models';
+/**
+ * Convert a schema config into the Localess wire format (SchemaExport[]) accepted by
+ * the push endpoint and produced by the pull endpoint. Pure data transformation.
+ */
+export declare function toSchemaExport(config: LocalessSchemaConfig): SchemaExport[];

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { ComponentDefinition, ComponentDefinitionInput, EnumDefinition, EnumDefinitionInput, LocalessSchemaConfig, SchemaDefinition, SchemaFieldInput, } from './define';
+export { defineConfig, defineEnum, defineField, defineSchema } from './define';
+export { toSchemaExport } from './export';
+export type { InferContent, InferContentData, InferEnum } from './infer';
+export type { AssetFileType, SchemaComponentExport, SchemaEnumExport, SchemaEnumValue, SchemaExport, SchemaField, SchemaFieldAsset, SchemaFieldAssets, SchemaFieldBase, SchemaFieldBoolean, SchemaFieldColor, SchemaFieldDate, SchemaFieldDateTime, SchemaFieldKind, SchemaFieldLink, SchemaFieldMarkdown, SchemaFieldNumber, SchemaFieldOption, SchemaFieldOptions, SchemaFieldReference, SchemaFieldReferences, SchemaFieldRichText, SchemaFieldSchema, SchemaFieldSchemas, SchemaFieldText, SchemaFieldTextarea, SchemaType, } from './models';
+export type { ValidationIssue, ValidationResult } from './validate';
+export { validate } from './validate';
+export type { ContentAsset, ContentLink, ContentReference, ContentRichText } from '@localess/model';

package/dist/index.js

@@ -0,0 +1,162 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/define.ts
+/**
+* Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
+* exists to preserve literal types for inference.
+*
+* @param definition the enum definition (id, values, optional display metadata)
+* @returns the definition with `type: 'ENUM'`, literal types preserved
+*/
+function defineEnum(definition) {
+	return {
+		...definition,
+		type: "ENUM"
+	};
+}
+/**
+* Define a single field, narrowing it to the extras valid for its `kind` and catching a stray
+* property from the wrong kind at the call site (e.g. `maxLength` on a `NUMBER` field) — something
+* a bare field literal inside `defineSchema({ fields: [...] })` cannot do. Optional: `defineSchema`
+* accepts raw field literals and `defineField(...)` results interchangeably in the same `fields`
+* array. A near-identity function like `defineEnum`/`defineSchema` — by-value ref normalization
+* (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
+* of a field's origin. See `docs/decisions/008-schema-package.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
+*/
+function defineField(field) {
+	return field;
+}
+/**
+* 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.
+*
+* @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
+*/
+function defineSchema(definition) {
+	const seen = /* @__PURE__ */ new Set();
+	const fields = definition.fields?.map((field) => {
+		if (seen.has(field.name)) throw new Error(`[localess/schema] Duplicate field name '${field.name}' in schema '${definition.id}'`);
+		seen.add(field.name);
+		const out = { ...field };
+		if ("source" in field && typeof field.source === "object" && field.source !== null) out.source = field.source.id;
+		if ("schemas" in field && Array.isArray(field.schemas)) out.schemas = field.schemas.map((ref) => typeof ref === "object" && ref !== null ? ref.id : ref);
+		return out;
+	});
+	return {
+		...definition,
+		...fields ? { fields } : {}
+	};
+}
+/**
+* Register schemas into a config — the unit the CLI pushes and type inference resolves against.
+*
+* @param config object with the full list of schema definitions
+* @returns the config unchanged, literal types preserved
+* @throws Error on duplicate schema ids
+*/
+function defineConfig(config) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const schema of config.schemas) {
+		if (seen.has(schema.id)) throw new Error(`[localess/schema] Duplicate schema id '${schema.id}' in config`);
+		seen.add(schema.id);
+	}
+	return config;
+}
+//#endregion
+//#region src/export.ts
+/**
+* Convert a schema config into the Localess wire format (SchemaExport[]) accepted by
+* the push endpoint and produced by the pull endpoint. Pure data transformation.
+*/
+function toSchemaExport(config) {
+	return config.schemas.map((schema) => stripUndefined({ ...schema }));
+}
+function stripUndefined(value) {
+	for (const key of Object.keys(value)) if (value[key] === void 0) delete value[key];
+	else if (Array.isArray(value[key])) value[key] = value[key].map((item) => item !== null && typeof item === "object" ? stripUndefined({ ...item }) : item);
+	return value;
+}
+//#endregion
+//#region src/validate.ts
+var SCHEMA_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9]+$/;
+var FIELD_NAME_PATTERN = /^[a-z][a-zA-Z0-9_]*[a-zA-Z0-9]$/;
+var ENUM_VALUE_PATTERN = /^[a-zA-Z]$|^[a-zA-Z][a-zA-Z0-9-_]*[a-zA-Z0-9]$/;
+var RESERVED_SCHEMA_IDS = [
+	"Translations",
+	"Links",
+	"ContentMetadata",
+	"ContentReference",
+	"ContentRichText",
+	"ContentLink",
+	"ContentData",
+	"ContentAsset",
+	"Content"
+];
+var RESERVED_FIELD_NAMES = ["_id", "_schema"];
+/**
+* Validate a schema config against the Localess authoring rules (ID/name patterns, reserved
+* names, length limits, reference resolution). Non-throwing; `ok` is false only when at least
+* one error-severity issue is present — warnings alone don't fail validation.
+*/
+function validate(config) {
+	const issues = [];
+	const error = (code, path, message) => issues.push({
+		severity: "error",
+		code,
+		path,
+		message
+	});
+	const byId = /* @__PURE__ */ new Map();
+	for (const schema of config.schemas) byId.set(schema.id, schema);
+	for (const schema of config.schemas) {
+		const path = schema.id;
+		if (schema.id.length < 2 || schema.id.length > 50 || !SCHEMA_ID_PATTERN.test(schema.id)) error("schema/invalid-id", path, `Schema id '${schema.id}' must match ${SCHEMA_ID_PATTERN} and be 2-50 characters`);
+		if (RESERVED_SCHEMA_IDS.some((it) => it.toLowerCase() === schema.id.toLowerCase())) error("schema/reserved-id", path, `Schema id '${schema.id}' is reserved`);
+		if (schema.displayName && schema.displayName.length > 50) error("schema/display-name-too-long", path, "displayName exceeds 50 characters");
+		if (schema.description && schema.description.length > 250) error("schema/description-too-long", path, "description exceeds 250 characters");
+		for (const label of schema.labels ?? []) if (label.length < 2 || label.length > 50 || label.includes(" ")) error("schema/invalid-label", path, `Label '${label}' must be 2-50 characters without spaces`);
+		if (schema.type === "ENUM") {
+			for (const value of schema.values ?? []) {
+				if (value.name.length < 1 || value.name.length > 50) error("enum/invalid-value-name", `${path}.${value.name}`, "Enum value name must be 1-50 characters");
+				if (value.value.length < 1 || value.value.length > 50 || !ENUM_VALUE_PATTERN.test(value.value)) error("enum/invalid-value", `${path}.${value.name}`, `Enum value '${value.value}' is invalid`);
+			}
+			continue;
+		}
+		const fieldNames = new Set((schema.fields ?? []).map((it) => it.name));
+		if (schema.previewField && !fieldNames.has(schema.previewField)) error("schema/unknown-preview-field", path, `previewField '${schema.previewField}' does not exist on '${schema.id}'`);
+		for (const field of schema.fields ?? []) {
+			const fieldPath = `${path}.${field.name}`;
+			if (field.name.length < 2 || field.name.length > 30 || !FIELD_NAME_PATTERN.test(field.name) || field.name.includes("_i18n_")) error("field/invalid-name", fieldPath, `Field name '${field.name}' must be camelCase, 2-30 characters, without '_i18n_'`);
+			if (RESERVED_FIELD_NAMES.some((it) => it.toLowerCase() === field.name.toLowerCase())) error("field/reserved-name", fieldPath, `Field name '${field.name}' is reserved`);
+			if (field.displayName && field.displayName.length > 30) error("field/display-name-too-long", fieldPath, "Field displayName exceeds 30 characters");
+			if (field.description && field.description.length > 250) error("field/description-too-long", fieldPath, "Field description exceeds 250 characters");
+			if (field.defaultValue && field.defaultValue.length > 250) error("field/default-value-too-long", fieldPath, "Field defaultValue exceeds 250 characters");
+			if (field.kind === "OPTION" || field.kind === "OPTIONS") {
+				const source = byId.get(field.source);
+				if (!source) error("field/unresolved-source", fieldPath, `source '${field.source}' does not resolve to a schema in the config`);
+				else if (source.type !== "ENUM") error("field/source-not-enum", fieldPath, `source '${field.source}' must be an ENUM schema`);
+			}
+			if (field.kind === "SCHEMA" || field.kind === "SCHEMAS") for (const ref of field.schemas ?? []) {
+				const target = byId.get(ref);
+				if (!target) error("field/unresolved-schema-ref", fieldPath, `schemas ref '${ref}' does not resolve to a schema in the config`);
+				else if (target.type === "ENUM") error("field/schema-ref-is-enum", fieldPath, `schemas ref '${ref}' must be a ROOT or NODE schema, not an ENUM`);
+			}
+		}
+	}
+	return {
+		ok: !issues.some((it) => it.severity === "error"),
+		issues
+	};
+}
+//#endregion
+exports.defineConfig = defineConfig;
+exports.defineEnum = defineEnum;
+exports.defineField = defineField;
+exports.defineSchema = defineSchema;
+exports.toSchemaExport = toSchemaExport;
+exports.validate = validate;

package/dist/index.mjs

@@ -0,0 +1,156 @@
+//#region src/define.ts
+/**
+* Define an ENUM schema. Identity function apart from injecting `type: 'ENUM'`;
+* exists to preserve literal types for inference.
+*
+* @param definition the enum definition (id, values, optional display metadata)
+* @returns the definition with `type: 'ENUM'`, literal types preserved
+*/
+function defineEnum(definition) {
+	return {
+		...definition,
+		type: "ENUM"
+	};
+}
+/**
+* Define a single field, narrowing it to the extras valid for its `kind` and catching a stray
+* property from the wrong kind at the call site (e.g. `maxLength` on a `NUMBER` field) — something
+* a bare field literal inside `defineSchema({ fields: [...] })` cannot do. Optional: `defineSchema`
+* accepts raw field literals and `defineField(...)` results interchangeably in the same `fields`
+* array. A near-identity function like `defineEnum`/`defineSchema` — by-value ref normalization
+* (`source`, `schemas`) still happens exclusively in `defineSchema`, applied uniformly regardless
+* of a field's origin. See `docs/decisions/008-schema-package.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
+*/
+function defineField(field) {
+	return field;
+}
+/**
+* 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.
+*
+* @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
+*/
+function defineSchema(definition) {
+	const seen = /* @__PURE__ */ new Set();
+	const fields = definition.fields?.map((field) => {
+		if (seen.has(field.name)) throw new Error(`[localess/schema] Duplicate field name '${field.name}' in schema '${definition.id}'`);
+		seen.add(field.name);
+		const out = { ...field };
+		if ("source" in field && typeof field.source === "object" && field.source !== null) out.source = field.source.id;
+		if ("schemas" in field && Array.isArray(field.schemas)) out.schemas = field.schemas.map((ref) => typeof ref === "object" && ref !== null ? ref.id : ref);
+		return out;
+	});
+	return {
+		...definition,
+		...fields ? { fields } : {}
+	};
+}
+/**
+* Register schemas into a config — the unit the CLI pushes and type inference resolves against.
+*
+* @param config object with the full list of schema definitions
+* @returns the config unchanged, literal types preserved
+* @throws Error on duplicate schema ids
+*/
+function defineConfig(config) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const schema of config.schemas) {
+		if (seen.has(schema.id)) throw new Error(`[localess/schema] Duplicate schema id '${schema.id}' in config`);
+		seen.add(schema.id);
+	}
+	return config;
+}
+//#endregion
+//#region src/export.ts
+/**
+* Convert a schema config into the Localess wire format (SchemaExport[]) accepted by
+* the push endpoint and produced by the pull endpoint. Pure data transformation.
+*/
+function toSchemaExport(config) {
+	return config.schemas.map((schema) => stripUndefined({ ...schema }));
+}
+function stripUndefined(value) {
+	for (const key of Object.keys(value)) if (value[key] === void 0) delete value[key];
+	else if (Array.isArray(value[key])) value[key] = value[key].map((item) => item !== null && typeof item === "object" ? stripUndefined({ ...item }) : item);
+	return value;
+}
+//#endregion
+//#region src/validate.ts
+var SCHEMA_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9]+$/;
+var FIELD_NAME_PATTERN = /^[a-z][a-zA-Z0-9_]*[a-zA-Z0-9]$/;
+var ENUM_VALUE_PATTERN = /^[a-zA-Z]$|^[a-zA-Z][a-zA-Z0-9-_]*[a-zA-Z0-9]$/;
+var RESERVED_SCHEMA_IDS = [
+	"Translations",
+	"Links",
+	"ContentMetadata",
+	"ContentReference",
+	"ContentRichText",
+	"ContentLink",
+	"ContentData",
+	"ContentAsset",
+	"Content"
+];
+var RESERVED_FIELD_NAMES = ["_id", "_schema"];
+/**
+* Validate a schema config against the Localess authoring rules (ID/name patterns, reserved
+* names, length limits, reference resolution). Non-throwing; `ok` is false only when at least
+* one error-severity issue is present — warnings alone don't fail validation.
+*/
+function validate(config) {
+	const issues = [];
+	const error = (code, path, message) => issues.push({
+		severity: "error",
+		code,
+		path,
+		message
+	});
+	const byId = /* @__PURE__ */ new Map();
+	for (const schema of config.schemas) byId.set(schema.id, schema);
+	for (const schema of config.schemas) {
+		const path = schema.id;
+		if (schema.id.length < 2 || schema.id.length > 50 || !SCHEMA_ID_PATTERN.test(schema.id)) error("schema/invalid-id", path, `Schema id '${schema.id}' must match ${SCHEMA_ID_PATTERN} and be 2-50 characters`);
+		if (RESERVED_SCHEMA_IDS.some((it) => it.toLowerCase() === schema.id.toLowerCase())) error("schema/reserved-id", path, `Schema id '${schema.id}' is reserved`);
+		if (schema.displayName && schema.displayName.length > 50) error("schema/display-name-too-long", path, "displayName exceeds 50 characters");
+		if (schema.description && schema.description.length > 250) error("schema/description-too-long", path, "description exceeds 250 characters");
+		for (const label of schema.labels ?? []) if (label.length < 2 || label.length > 50 || label.includes(" ")) error("schema/invalid-label", path, `Label '${label}' must be 2-50 characters without spaces`);
+		if (schema.type === "ENUM") {
+			for (const value of schema.values ?? []) {
+				if (value.name.length < 1 || value.name.length > 50) error("enum/invalid-value-name", `${path}.${value.name}`, "Enum value name must be 1-50 characters");
+				if (value.value.length < 1 || value.value.length > 50 || !ENUM_VALUE_PATTERN.test(value.value)) error("enum/invalid-value", `${path}.${value.name}`, `Enum value '${value.value}' is invalid`);
+			}
+			continue;
+		}
+		const fieldNames = new Set((schema.fields ?? []).map((it) => it.name));
+		if (schema.previewField && !fieldNames.has(schema.previewField)) error("schema/unknown-preview-field", path, `previewField '${schema.previewField}' does not exist on '${schema.id}'`);
+		for (const field of schema.fields ?? []) {
+			const fieldPath = `${path}.${field.name}`;
+			if (field.name.length < 2 || field.name.length > 30 || !FIELD_NAME_PATTERN.test(field.name) || field.name.includes("_i18n_")) error("field/invalid-name", fieldPath, `Field name '${field.name}' must be camelCase, 2-30 characters, without '_i18n_'`);
+			if (RESERVED_FIELD_NAMES.some((it) => it.toLowerCase() === field.name.toLowerCase())) error("field/reserved-name", fieldPath, `Field name '${field.name}' is reserved`);
+			if (field.displayName && field.displayName.length > 30) error("field/display-name-too-long", fieldPath, "Field displayName exceeds 30 characters");
+			if (field.description && field.description.length > 250) error("field/description-too-long", fieldPath, "Field description exceeds 250 characters");
+			if (field.defaultValue && field.defaultValue.length > 250) error("field/default-value-too-long", fieldPath, "Field defaultValue exceeds 250 characters");
+			if (field.kind === "OPTION" || field.kind === "OPTIONS") {
+				const source = byId.get(field.source);
+				if (!source) error("field/unresolved-source", fieldPath, `source '${field.source}' does not resolve to a schema in the config`);
+				else if (source.type !== "ENUM") error("field/source-not-enum", fieldPath, `source '${field.source}' must be an ENUM schema`);
+			}
+			if (field.kind === "SCHEMA" || field.kind === "SCHEMAS") for (const ref of field.schemas ?? []) {
+				const target = byId.get(ref);
+				if (!target) error("field/unresolved-schema-ref", fieldPath, `schemas ref '${ref}' does not resolve to a schema in the config`);
+				else if (target.type === "ENUM") error("field/schema-ref-is-enum", fieldPath, `schemas ref '${ref}' must be a ROOT or NODE schema, not an ENUM`);
+			}
+		}
+	}
+	return {
+		ok: !issues.some((it) => it.severity === "error"),
+		issues
+	};
+}
+//#endregion
+export { defineConfig, defineEnum, defineField, defineSchema, toSchemaExport, validate };

package/dist/infer.d.ts

@@ -0,0 +1,103 @@
+import { ContentAsset, ContentLink, ContentReference, ContentRichText } from '@localess/model';
+import { SchemaEnumValue } from './models';
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type SchemasOf<C> = C extends {
+    schemas: readonly (infer D)[];
+} ? D : never;
+type FindById<C, Id> = Extract<SchemasOf<C>, {
+    id: Id;
+}>;
+type NodeIds<C> = [Extract<SchemasOf<C>, {
+    type: 'NODE';
+}>] extends [never] ? never : Extract<SchemasOf<C>, {
+    type: 'NODE';
+}> extends {
+    id: infer Id extends string;
+} ? Id : never;
+type EnumValuesUnion<E> = E extends {
+    values: readonly SchemaEnumValue[];
+} ? E extends {
+    values: readonly {
+        value: infer V extends string;
+    }[];
+} ? V : string : string;
+/** Literal union of an ENUM definition's values (falls back to `string` when values are absent). */
+export type InferEnum<E> = EnumValuesUnion<E>;
+type ResolveEnum<Id extends string, C> = [FindById<C, Id>] extends [never] ? string : EnumValuesUnion<FindById<C, Id>>;
+type AllowedIds<F, C> = F extends {
+    schemas: readonly (infer Id extends string)[];
+} ? Id : NodeIds<C>;
+type ResolveSchemaContent<F, C> = [AllowedIds<F, C>] extends [never] ? {
+    _id: string;
+    _schema: string;
+} : ContentByIds<AllowedIds<F, C>, C>;
+type ContentByIds<Id extends string, C> = Id extends unknown ? InferContent<FindById<C, Id>, C> : never;
+type FieldValue<F, C> = F extends {
+    kind: 'TEXT' | 'TEXTAREA' | 'MARKDOWN' | 'COLOR' | 'DATE' | 'DATETIME';
+} ? string : F extends {
+    kind: 'NUMBER';
+} ? number : F extends {
+    kind: 'BOOLEAN';
+} ? boolean : F extends {
+    kind: 'RICH_TEXT';
+} ? ContentRichText : F extends {
+    kind: 'LINK';
+} ? ContentLink : F extends {
+    kind: 'ASSET';
+} ? ContentAsset : F extends {
+    kind: 'ASSETS';
+} ? ContentAsset[] : F extends {
+    kind: 'REFERENCE';
+} ? ContentReference : F extends {
+    kind: 'REFERENCES';
+} ? ContentReference[] : F extends {
+    kind: 'OPTION';
+    source: infer S extends string;
+} ? ResolveEnum<S, C> : F extends {
+    kind: 'OPTIONS';
+    source: infer S extends string;
+} ? ResolveEnum<S, C>[] : F extends {
+    kind: 'SCHEMA';
+} ? ResolveSchemaContent<F, C> : F extends {
+    kind: 'SCHEMAS';
+} ? ResolveSchemaContent<F, C>[] : unknown;
+type FieldsOf<S> = S extends {
+    fields: readonly (infer F)[];
+} ? F : never;
+type RequiredFieldNames<S> = FieldsOf<S> extends infer F ? (F extends {
+    required: true;
+    name: infer N extends string;
+} ? N : never) : never;
+type OptionalFieldNames<S> = FieldsOf<S> extends infer F ? (F extends {
+    required: true;
+} ? never : F extends {
+    name: infer N extends string;
+} ? N : never) : never;
+type FieldByName<S, N> = Extract<FieldsOf<S>, {
+    name: N;
+}>;
+type FieldsObject<S, C> = Prettify<{
+    [N in RequiredFieldNames<S>]: FieldValue<FieldByName<S, N>, C>;
+} & {
+    [N in OptionalFieldNames<S>]?: FieldValue<FieldByName<S, N>, C>;
+}>;
+/** Content type of a single ROOT/NODE definition, resolved against config C. */
+export type InferContent<S, C> = S extends {
+    type: 'ROOT' | 'NODE';
+    id: infer Id extends string;
+} ? Prettify<{
+    _id: string;
+    _schema: Id;
+} & FieldsObject<S, C>> : never;
+type RootIds<C> = [Extract<SchemasOf<C>, {
+    type: 'ROOT';
+}>] extends [never] ? never : Extract<SchemasOf<C>, {
+    type: 'ROOT';
+}> extends {
+    id: infer Id extends string;
+} ? Id : never;
+/** Union of the content types of every ROOT schema in config C. */
+export type InferContentData<C> = ContentByIds<RootIds<C>, C>;
+export {};

package/dist/models.d.ts

@@ -0,0 +1 @@
+export * from '@localess/model';

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+import { LocalessSchemaConfig } from './define';
+export interface ValidationIssue {
+    severity: 'error' | 'warning';
+    code: string;
+    path: string;
+    message: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    issues: ValidationIssue[];
+}
+/**
+ * Validate a schema config against the Localess authoring rules (ID/name patterns, reserved
+ * names, length limits, reference resolution). Non-throwing; `ok` is false only when at least
+ * one error-severity issue is present — warnings alone don't fail validation.
+ */
+export declare function validate(config: LocalessSchemaConfig): ValidationResult;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@localess/schema",
+  "version": "4.0.0-dev.20260905071322",
+  "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.0-dev.20260905071322"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.0"
+  },
+  "engines": {
+    "node": ">= 24.0.0"
+  }
+}