cms-schema

module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0

README

cms-schema

The schema of a Norcube CMS site as a Go module: the typed model of .norcube/cms/, the loader that assembles the directory and resolves $ref, the resolvers that map a content file to its collection, URL and assets, and the validators that check a site the way the editor does, offline.

The Norcube CLI wraps it as nrc cms validate; the CMS service uses the same code to load schemas and build its content index. A site's CI can run it to block a pull request that breaks the content model.

Install

go install github.com/norcubeplatform/cms-schema/cmd/cms-schema-validate@latest

Requires Go 1.26 or later. The module depends on gopkg.in/yaml.v3 and nothing else.

Use

cms-schema-validate                       # the site in the current directory
cms-schema-validate path/to/site --strict # warnings fail the run
cms-schema-validate --only schema         # schema files alone, no content
cms-schema-validate --json > report.json  # for CI

Exit codes: 0 clean, 1 findings at error severity, 2 usage or I/O error, 3 not a CMS site.

Each finding names the file, the field path inside it, a severity, a rule id and a message:

error    src/content/pages/about.md#seats        content.required          Seats is required.
warning  src/content/pages/index.md#blocks[0].link  links.unresolved_link  links to /about/, which no content file produces
error    .norcube/cms/collections/pages.yml#fields.tier  schema.default_not_option  default "enterprise" of "Tier" is not one of its options

What it checks

schema — the directory loads and makes sense: YAML parses, every $ref names a block or an input, every field has key, type and label, types and knobs are ones the editor reads, select defaults are options, bounds are ordered, regexes compile, visibleIf and computed paths name fields, storages and defaultStorage agree, the preview, redirects and variables blocks are consistent, no two collections claim one directory without literal match names to tell them apart.

content — every content file against its collection, with the editor's rules: required, value shape (including select options), item discriminators of multi-shape arrays, array bounds, regex, length, number bounds, uniqueness, custom validators, out-of-schema keys per extraKeysPolicy, a body where the collection has none. Fields hidden by hidden or by a false visibleIf are skipped, as in the editor.

links — the site as a whole: two files resolving to one URL, site links that no file produces and no knownPaths entry covers, images and files that do not exist, reference fields whose target is gone, orphaned identity sidecars.

The rule ids are listed in report/rules.go and are frozen: a released id is never renamed or reused.

As a library

res, err := validate.Site(os.DirFS("."), validate.Options{Strict: true})
for _, f := range res.Findings {
    fmt.Println(f)
}
Package What it holds
report Finding, severities, the frozen rule ids.
schema The typed model (Config, Collection, Field, Storage…), Parse, array item shapes, conditions.
load Load(fs.FS): directory or legacy single file, merge, $ref, schema version.
content Markdown-with-frontmatter and YAML data files to plain values; identity sidecars.
resolve Collection for a path, locale, URL and slug fallback, storage values, links in text.
validate Schema, Page, Links and the Site runner.

Fixtures

testdata/sites/* are small sites with an expected.json of the findings a run must produce. They pin the rules for every implementation of them: the dashboard's validators run the same fixtures. Regenerate with go test ./validate -run TestFixtures -update and read the diff.

Regular expressions

The editor evaluates regex knobs in JavaScript; this module uses Go's RE2 engine. A pattern RE2 cannot compile (lookaround, backreferences) is reported as schema.invalid_regex and skipped in content checks rather than silently passed. Keep patterns to the common subset when a site is checked in CI.

License

Apache License 2.0, see LICENSE.

Directories

Path Synopsis
cmd
cms-schema-validate command
Command cms-schema-validate checks a site checkout's `.norcube/cms/` configuration and content.
Command cms-schema-validate checks a site checkout's `.norcube/cms/` configuration and content.
Package content reads content files the way the CMS does: Markdown with a YAML frontmatter fence, or a whole-file YAML data document, into plain Go values (maps, slices, strings, numbers, booleans) that match what the editor sees after its YAML to JSON round trip.
Package content reads content files the way the CMS does: Markdown with a YAML frontmatter fence, or a whole-file YAML data document, into plain Go values (maps, slices, strings, numbers, booleans) that match what the editor sees after its YAML to JSON round trip.
Package load assembles a site's `.norcube/cms/` directory (or the legacy single `norcube-cms.config.yml`) into one merged document, the same way the CMS service does: `config.yml` supplies the root keys, each file under `collections/`, `blocks/` and `inputs/` becomes one entry keyed by its basename, `inputsFromGlob` adds more inputs, every `$ref` is replaced by the block or input it names, and the schema version is checked.
Package load assembles a site's `.norcube/cms/` directory (or the legacy single `norcube-cms.config.yml`) into one merged document, the same way the CMS service does: `config.yml` supplies the root keys, each file under `collections/`, `blocks/` and `inputs/` becomes one entry keyed by its basename, `inputsFromGlob` adds more inputs, every `$ref` is replaced by the block or input it names, and the schema version is checked.
Package report holds the finding type every check in this module produces and the frozen list of rule identifiers.
Package report holds the finding type every check in this module produces and the frozen list of rule identifiers.
Package resolve answers the questions a site's layout decides: which collection a file belongs to, what URL it renders at, what repository path an image value points to, and which values in a text are links into the site.
Package resolve answers the questions a site's layout decides: which collection a file belongs to, what URL it renders at, what repository path an image value points to, and which values in a text are links into the site.
Package schema is the typed model of a Norcube CMS site configuration: the root config, its collections, blocks, inputs and storages, and the field definitions they are made of.
Package schema is the typed model of a Norcube CMS site configuration: the root config, its collections, blocks, inputs and storages, and the field definitions they are made of.
Package validate runs the checks: the schema on its own, every content file against its collection, and the links between files.
Package validate runs the checks: the schema on its own, every content file against its collection, and the links between files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL