@html-schema/html-schema

Framework-neutral schema form protocol package. It defines commercial form schema contracts, runtime pure helpers, extension pack metadata, capability validation, submit-model calculation, diagnostics, redaction policy, attachment metadata, and adapter contracts. Package core stays renderer-neutral: it owns schema semantics, not Vue, React Native, Element Plus, React Native Paper, DOM, native picker, upload, download, camera, or preview behavior.

Boundaries

This package does not render UI and does not depend on Vue, React, React Native, Element Plus, React Native Paper, DOM, Node-specific APIs, app routers, stores, API clients, upload/download implementations, camera, location, or offline storage.

Platform behavior belongs in app adapters. Business authorization and API calls belong in feature layers. New business inputs must start from SchemaFormSchema plus the app renderer pack: Web uses FeatureSchemaForm, and Mobile RN uses AppSchemaForm. Do not introduce a parallel form protocol for query, search, filter, login, action, drawer, dialog, or ordinary form use cases.

attachment stores SchemaAttachmentItem[] metadata and emits actions; this package never opens file pickers, constructs File/Blob/FormData, uploads bytes, downloads bytes, opens camera/document pickers, or renders file previews.

Entrypoints

| Entrypoint | Layer | Usage | | --- | --- | --- | | @html-schema/html-schema | production | Production schema contract, validation, runtime helpers, capability/value/action/attachment/diagnostics APIs. | | @html-schema/html-schema/testing | tests only | Shared parity fixtures and test-only helpers. |

Production code must not import @html-schema/html-schema/testing; keep /testing imports in package, Web, and Mobile test files only.

import { defineSchemaForm } from '@html-schema/html-schema'
import { createSchemaFormParityFixtureSchema } from '@html-schema/html-schema/testing'

Core field types

| Type | Semantics | | --- | --- | | text | Single-line text value. | | input | Alias accepted by schemas and normalized to text. | | password | Secret text value. | | textarea | Multi-line text value. | | number | Numeric value; empty value is undefined. | | choice | Choice value from static or sourced options; multiple: true uses an array value. | | select | Select value from optionsKey; multiple: true uses an array value. | | radio | Single option value from static or sourced options. | | checkbox | Boolean checked state. | | switch | Boolean on/off state. | | date | Date string value. | | datetime | Datetime string value. | | dateRange | Date range array value. | | search | Search text value. | | readonly | Read-only display value. | | attachment | Attachment metadata array value. | | subform | Repeating child-record array value. |

Commands

pnpm --filter @html-schema/html-schema test
pnpm --filter @html-schema/html-schema typecheck
pnpm --filter @html-schema/html-schema build
node scripts/schema-form-package-release-check.mjs

The release check builds and packs a temporary consumer, verifies ESM/CJS consumption for the root and /testing entrypoints, checks tarball contents, and guards against forbidden imports or runtime dependencies. It is a local dry-run guard only; it does not publish to npm.

Renderer contract

packages/schema-form defines renderer semantics only. Web and Mobile map these semantics to Vue/React Native props in app-local renderer packs.

Usage modes are: form, query, search, filter, inlineEdit, dialog, drawer, login, action, readonly.

Capability levels are: full, degraded, placeholder, unsupported. Unsupported is an error. Degraded and placeholder are warnings and must be visible to tests or diagnostics.

Renderer capabilities cover the same 17 core field types listed in the Core field types table above: text, input, password, textarea, number, choice, select, radio, checkbox, switch, date, datetime, dateRange, search, readonly, attachment, and subform.

attachment remains a metadata/action contract only. This package does not touch File, Blob, or FormData, and it does not implement upload transport.

Final adoption guidance

• Package core is renderer-neutral and publishable.
• Web FeatureSchemaForm and Mobile AppSchemaForm renderer packs implement the 17 core field types: text, input, password, textarea, number, choice, select, radio, checkbox, switch, date, datetime, dateRange, search, readonly, attachment, subform.
• Mobile 个别 renderer 能力等级可能是 degraded / placeholder，具体以 capability manifest 为准；这不等于真实附件 transport 或复杂子表单商业能力已经 full。
• attachment is metadata + action contract only. Real file selection, camera capture, upload, download, preview, retry, authorization, and transport belong to app/feature handlers.
• Query, search, filter, login, and action are schema usage modes; they are not reasons to create separate page-level form protocols.
• P2/P3 direct-input exceptions are structured in docs/superpowers/inventories/2026-05-26-schema-form-business-input-inventory.md with allowedDirectInputReason, allowedUntilPhase, and replacementTarget.

Value, actions, and parity fixtures

Standard renderer value kinds are closed to: string, number, boolean, scalar, scalarArray, date, datetime, dateRange, readonly, attachmentList, recordArray, and unknown. Renderer manifests must not invent free-form value kinds. Use getSchemaFormValueContract(), getSchemaFormEmptyValue(), normalizeSchemaFormFieldModelValue(), and normalizeSchemaFormFieldSubmitValue() to keep Web and Mobile adapters aligned.

Action scopes are field, form, attachment, and business. Form-level schema actions emit form-action; field renderers emit field-action; attachment renderers emit metadata-only attachment payloads.

Shared parity fixtures live in createSchemaFormParityFixtureSchema(), createSchemaFormParityFixtureValues(), and createSchemaFormParityFixtureOptions(). Package, Web, and Mobile tests should consume these fixtures when asserting value semantics, capability warnings, actions, and runtime effects.

Attachment payloads remain metadata-only. Real File, Blob, FormData, native file handles, camera results, uploads, downloads, and previews must stay in app/feature side channels keyed by action transaction/candidate ids.

Release note

R5 adds public contract exports for value semantics, action payloads, adapter runtime, renderer capabilities, and parity fixtures. This public API change is recorded in .changeset/schema-form-parity-hardening.md as a minor release for @html-schema/html-schema.