Design: UMF schemas and their published browser
Example from HELIX’s own docs. This generated page comes from
docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.
Source identity (from
02-design/design-umf-schemas.md):
ddx:
id: helix.design.umf-schemas
authoring:
home: repo
schemas:
- id: helix.schema-reference
version: "1.0.0"
title: Design schema reference
path: docs/helix/02-design/schemas/schema-reference.umf.yaml
schemaFormat: umf
definition: [publishing, SchemaReference]- Explore schema: Design schema reference (version 1.0.0)
Scope and Authority
PRD R-14 and the operator’s implementation request govern this change. The
in-tree catalog binds. Design mode applies UMF reuse by default; Contracts and
Data/Solution/Technical Designs retain their existing authority boundaries.
workflows/references/umf-schemas.md owns the reference and reuse contract;
workflows/references/publishing.md owns the publishing integration.
Schema Basis
The worked model reuses UMF core 0.10.0 and umf.ddd 0.1.0 value-object fields
and equality, as defined by UMF’s spec/extensions/ddd/package.json. No domain
pack supplies HELIX publication references; SchemaReference is a local concept.
It models the five required reference fields. The optional definition selector,
nonempty-string rules, path containment, format enum, source availability,
identity agreement and browser limits remain explicit publication checks in
documentor.schemas, not claims inferred from DDD field types. Runtime input
validation does not depend on the browser or UMF SDK. The model is explanatory;
the shared reference contract remains normative for publication behavior.
Implementation Plan
Publication owns only its marked index and inventoried generated files. It refuses unowned output collisions, preserves unrelated site files, and retires only unchanged generated files. Discovery includes rendered guide references; standalone and integrated commands share target-aware output resolution. Invalid schema metadata must produce an actionable command error rather than a traceback. Automatic table discovery applies browser limits only to identified TableSpecs.
- Add the core reuse procedure, reference contract, artifact prompts/templates, and conditional blocking review criteria. Preserve historical prose and omit irrelevant modeling sections.
- Add
documentor.schemas: validate explicit references, retain source bytes, deduplicate identities, generate catalog/provenance and copy verified browser assets. Integrate Hugo/static/Hextra site assembly and published artifact links. - Pin browser 2.0.0 in the site’s lockfile. Prepare schema output before local and CI Hugo builds. Include original licenses and source downloads.
- Exercise this model end to end under
/helix/, including definition selection, errors, reproducibility, stale output and source retirement.
Verification and Completion
Focused Python tests cover discovery, byte preservation, conflicting identities,
invalid selections, paths outside the repository, missing inputs, stale output,
retired sources and browser package integrity. The browser test follows the
published design link and checks its selected definition and embedded index.
Run just test, just test-documentor, catalog synchronization, a production
Hugo build and the schema browser test. A renderer pass makes no instance or
native-semantic validation claim. No automatic upstream contribution, schema
migration, application runtime dependency or tracker work is in scope.
The embedded browser follows the microsite’s resolved theme on load and live changes, preserving the selected schema and definition. The standalone explorer honors the saved site preference and otherwise follows the system theme. Trait delegation uses the same resolution during planning and rendering; adopted pages selected by mapping or glob contribute schema references. Invalid UMF collection shapes produce source-specific command errors.
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
artifacts/design-umf-schemas.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:8191b7b5…eb475903
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/artifacts/design-umf-schemas/",
"digest": {
"alg": "sha256",
"value": "8191b7b5702c3d901f681ebee31a67adbfe0929c4cd056a97b7ba122eb475903"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "gMx5TYZqFgDoETEZxMiNWWftuAcZc2ZqSYpKT-6XurzouLaq6Mmj7TR9ehSDeFiyvV7kkPzcrfpkYkWJGbBHBA",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}