@golemui/gui-schemas

中文文档
2.2.1发布于 2026/11/16MITTypeScriptESM + CJS构建来源已验证近 30 天下载 2971

JSON Schemas for GolemUI form definitions, so dynamic forms written in JSON get editor completion and validation. Open source (MIT).

原始使用文档
文档目录6 节
  1. Install
  2. Layout
  3. Validating with Ajv
  4. Converting a JSON Schema into a gui form
  5. Documentation
  6. License

@golemui/gui-schemas

GolemUI: dynamic forms from JSON for React, Angular, Vue, Lit and vanilla JS.

Install

npm install @golemui/gui-schemas

Layout

schemas/
  form.schema.json           form envelope (generated)
  widgets.schema.json        widget union + knownWidgetTypes enum (generated)
  layout-widget.schema.json  layout widget union (generated)
  validators.schema.json     the gui validator set (handwritten)
  ranges.schema.json         shared date and time range defs (handwritten)
  components/*.schema.json   per-widget schemas (handwritten)
  core/*.schema.json         vendored copy of the @golemui/schemas core file (generated)

Every file under schemas/ is reachable as a raw asset, for example @golemui/gui-schemas/schemas/components/textinput.schema.json. The package also has a JavaScript entry point that exports the same files as objects.

The generated files derive from the widget manifest (src/lib/widget-manifest.ts). Do not edit them, run npm run generate:schemas after changing the manifest or the @golemui/schemas core sources. CI fails when generated files are stale.

The shared common.schema.json moved to the @golemui/schemas package and is vendored here under schemas/core/. Raw-asset imports of @golemui/gui-schemas/schemas/common.schema.json must switch to schemas/core/common.schema.json. The vendored copy is identical to the core source apart from its $id, which is rebased onto this tree (https://golemui.com/schemas/gui/core/common.schema.json) so it matches the retrieval URI that sibling refs resolve to. validators.schema.json stays at the schemas/ root and is owned by this package: validation vocabulary is implementation-specific, so it is not part of the core layer, and its $id is now https://golemui.com/schemas/gui/validators.schema.json. The package entry-point export names (commonSchema, validatorsSchema, and every component schema export) are unchanged, but the $id values and $ref layout are not.

These $id values are identifiers, not download URLs. The matching tree under https://golemui.com/schemas/ is not published yet, so nothing dereferences them today.

Validating with Ajv

Every shipped file declares the $id that its siblings reference, so registering the files is all that is needed. A component ref like ../core/common.schema.json resolves to the vendored core copy's own $id.

import Ajv2020 from 'ajv/dist/2020';
import {
  commonSchema,
  rangesSchema,
  textinputSchema,
  validatorsSchema,
} from '@golemui/gui-schemas';

const ajv = new Ajv2020();
ajv.addSchema(commonSchema);
ajv.addSchema(validatorsSchema);
ajv.addSchema(rangesSchema);
const validate = ajv.compile(textinputSchema);

The raw schemas/ files behave the same way: registering each one by its own $id resolves the whole tree, with no JavaScript from this package involved. The core common.schema.json of @golemui/schemas keeps its own $id, so both packages can be loaded into one Ajv instance.

Converting a JSON Schema into a gui form

@golemui/gui-schemas/json-schema exports guiPreset, the gui widget set for the fromJsonSchema converter of @golemui/schemas/json-schema. The converter and its customization layers are described in the @golemui/schemas README. The same function is also exported as preset, the name that npx @golemui/schemas convert --preset @golemui/gui-schemas/json-schema loads.

import { fromJsonSchema } from '@golemui/schemas/json-schema';
import { guiPreset } from '@golemui/gui-schemas/json-schema';

const { formDefinition, diagnostics } = fromJsonSchema(schema, {
  preset: guiPreset({ submitLabel: 'Save', enumThresholds: { radio: 3 } }),
});

The preset picks these widgets:

  • enum, or oneOf/anyOf of const: radiogroup up to enumThresholds.radio options (0 by default), select up to enumThresholds.select (6 by default), dropdown above.
  • strings: dateInput, dateTimePicker and timeInput by format, password for format: password, writeOnly or a secret-looking name, markdown for contentMediaType: text/markdown, textarea from maxLength 200, and textinput otherwise. A const is a read-only input.
  • number and integer: number. boolean: checkbox.
  • arrays: repeater for objects, multiList or multiDropdown for choices, tags for other values, and a row of inputs for a tuple.
  • objects: a flex column. objectTitle: 'markdownText' or 'alert' shows the object title above its properties.

title is the label, description the hint, examples[0] the placeholder, readOnly makes an input read-only, and default is the default value. Constraints become the gui validator. The date-time widgets write the local time without a UTC offset, which the local-datetime diagnostic points out.

The package builds ES and CommonJS modules. require('@golemui/gui-schemas') loads index.cjs, which replaces the earlier index.umd.cjs.

Documentation

License

MIT

版本与发布记录

@golemui/gui-schemas 共发布 60 个版本,首次发布于 2026/05/27;过去 12 个月发布了 60 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.2.1latest2026/11/16今天
2.2.1-rc.0next2026/11/16今天
2.2.02026/11/133 天前
2.2.0-rc.22026/11/133 天前
2.2.0-rc.12026/11/134 天前
2.2.0-rc.02026/11/124 天前

关于 @golemui/gui-schemas 的常见问题

@golemui/gui-schemas 是什么?

JSON Schemas for GolemUI form definitions, so dynamic forms written in JSON get editor completion and validation. Open source (MIT).

如何安装 @golemui/gui-schemas?

在项目目录运行 npm install @golemui/gui-schemas,或使用 pnpm add / yarn add / bun add。

@golemui/gui-schemas 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@golemui/gui-schemas 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@golemui/gui-schemas 可以商用吗?

@golemui/gui-schemas 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@golemui/gui-schemas 的下载量有多少?

根据 npm 官方下载统计,@golemui/gui-schemas 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,971 次,日均约 99 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@golemui/gui-schemas 还在维护吗?

最新版本 2.2.1 发布于 2026/11/16(今天);至今共发布 60 个版本,其中过去 12 个月发布了 60 个;首次发布于 2026/05/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。