> ## Documentation Index
> Fetch the complete documentation index at: https://zerv.wisl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema system

> How zerv assembles a version. Core, extra_core, and build components; 22 presets; and custom RON schemas.

A schema is the recipe that turns version variables into a version string. Every zerv
output, from both `version` and `flow`, is rendered through one.

## Architecture

All schemas resolve to the internal `ZervSchema` struct with three required components:

* **`core`** - primary version components (e.g., `[Major, Minor, Patch]` for SemVer)
* **`extra_core`** - additional version components (e.g., pre-release, post-release, dev)
* **`build`** - build metadata components (e.g., commit hash, branch name, build info)

`core` and `extra_core` form the sortable identity of the version; `build` carries
traceability metadata after a `+`.

**Schema resolution**: preset schemas (`standard-base`, `calver-*`, etc.) are predefined
`ZervSchema` objects that adapt based on repository state. RON schemas are parsed from text
into the same `ZervSchema` structure, providing identical functionality with custom
definitions.

## Presets

22 presets ship built-in, 11 per family:

* **`standard-*`** - SemVer-shaped cores. Suffixes add parts:
  `-context` (build context), `-prerelease`, `-post`, `-dev`, and combinations like
  `standard-base-prerelease-post-dev-context`
* **`calver-*`** - the same suffix system over a date-based core
  (`YYYY.MM.DD-<patch>`), e.g. `calver-base-prerelease-post-dev-context`

## Custom RON schemas

Write a schema inline with `--schema-ron`. Each component is a list of variables: `var(...)`
references version fields, `str("...")` injects literals:

```bash theme={null}
zerv version --schema-ron '(core:[var(Major), var(Minor), var(Patch)], extra_core:[], build:[])'
# → 1.0.0

zerv version --schema-ron '(core:[var(Major), var(Minor), var(Patch)], extra_core:[], build:[str("build.id")])'
# → 1.0.0+build.id

zerv version --schema-ron '(
    core: [var(Major), var(Minor), var(Patch)],
    extra_core: [var(PreRelease), var(Post), var(Dev)],
    build: [var(BumpedBranch), var(Distance), var(BumpedCommitHashShort)]
)'
# → 1.0.0-alpha.1.post.5.dev.123+branch.name.1.g4e9af24 (equivalent to standard-base-prerelease-post-dev-context)

zerv version --schema-ron '(
    core: [var(ts("YYYY")), var(ts("MM")), var(ts("DD")), var(Patch)],
    extra_core: [var(PreRelease), var(Post), var(Dev)],
    build: [var(BumpedBranch), var(Distance), var(BumpedCommitHashShort)]
)'
# → 2025.12.4-0.alpha.1.post.5.dev.123+branch.name.1.g{hex:7} (equivalent to calver-base-prerelease-post-dev-context)
```

The last example demonstrates date formatting with `var(ts("YYYY"))`: any chrono format
string works inside `ts(...)`.

Common uses:

* **`v`-major tags** - `(core:[var(Major)], extra_core:[], build:[])` renders bare `1`, `2`;
  add `--output-prefix v --output-format pep440` for `v1`, `v2`
* **Minimal SemVer** - drop `build` for clean, sortable versions in release artifacts
* **CalVer releases** - date-based cores for products versioned by ship date

## Schema selection

```bash theme={null}
zerv version --schema standard-base
# → 1.0.0

zerv version --schema standard-base-context
# → 1.0.0+branch.name.1.g4e9af24

zerv version --schema standard-base-prerelease
# → 1.0.0-alpha.1

zerv version --schema standard-base-prerelease-post-dev-context
# → 1.0.0-alpha.1.post.5.dev.123+branch.name.1.g4e9af24

zerv version --schema calver-base-prerelease-post-dev-context
# → 2025.12.4-0.alpha.1.post.5.dev.123+branch.name.1.g4e9af24
```

`flow` takes the same `--schema` / `--schema-ron` flags with its own preset output shapes;
see the [flow CLI](/cli/flow).

## Where to go next

* [Formats and templates](/concepts/formats-and-templates) - output formats and Tera
  templates, the layer above schemas
* [Flow concepts](/concepts/flow) - branch-driven pre-release logic