Specification on Mergeway

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Mergeway version 1 defines a file-based database. A repository combines configuration documents, entity definitions, and record sources. Configuration gives independently stored YAML, JSON, Markdown, and OKF files one logical data model.

Scope

Version 1 specifies:

recursive configuration loading and entity composition;
native and JSON-Schema-derived field definitions;
inline, single-record, multi-record, selector, and OKF data sources;
field and path identifiers, references, and inheritance;
format, schema, and reference validation.

It does not require a directory convention, Git, a particular editor, or a public service. Write-command behavior and tool-specific interfaces belong to their component references.

Terminology

Mon, 01 Jan 0001 00:00:00 +0000

Terminology

Core terms

Repository: The root used to resolve entity data-source paths and to express normalized record paths. A repository is also called a workspace in older CLI output.
Entry configuration: The configuration document passed to the implementation, normally mergeway.yaml beneath the repository root.
Configuration document: A YAML file with a required mergeway.version block and optional configuration includes or entity definitions.
Entity: A named logical type with an identifier definition, a field schema, and zero or more records. Entity names begin with an uppercase ASCII letter.
Record: One map of field names to values associated with exactly one entity. Older internal help may call a record an “object”; JSON object retains its format-specific meaning.
Data source: Inline data, a file matched by an entity include, an items array, or values selected from a document.
Field: A named value in a record governed by a field definition. A property is a nested field inside an object field.
Identifier: The non-empty string representation that uniquely addresses a record within its entity and assignable inheritance hierarchy.
Reference: A scalar identifier value, or repeated array of identifier values, whose field type names one or more target entities.
Assignable hierarchy: An entity together with all descendants that extend it. Parent-typed queries and references include descendants.

Path terms

Configuration-relative path: A path resolved from the directory containing the configuration document. Top-level configuration include entries and json_schema use this base.
Repository-relative path: A slash-normalized path relative to the repository root. Entity data include entries use the repository root as their base, including when the entity was declared in an included configuration document.

Normative pages use these terms consistently. Advice and conceptual background remain in the repository-model explanation.

Conformance and requirement language

Mon, 01 Jan 0001 00:00:00 +0000

Conformance and requirement language

Requirement keywords

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY express requirement strength as described by RFC 2119 and RFC 8174 when, and only when, shown in capitals.

MUST and MUST NOT identify unconditional requirements.
SHOULD and SHOULD NOT permit a departure only when its consequences are understood.
MAY identifies optional behavior.

Descriptive present-tense statements on normative pages are requirements of the version 1 data model even when a keyword would add no clarity. Examples are normative for structure and behavior but their names and values are non-normative.

Repository and configuration

Mon, 01 Jan 0001 00:00:00 +0000

Repository and configuration

Entry and version

An implementation loads one YAML entry configuration. The conventional path is mergeway.yaml, but callers MAY select another path. The repository root is supplied separately and is the base for entity data paths.

Every configuration document MUST contain:

mergeway:
 version: 1

Version 1 is the only version defined here. A missing mergeway block, missing version, or other version is a configuration error.

Entity definitions

Mon, 01 Jan 0001 00:00:00 +0000

Entity definitions

Names and members

An entity name MUST begin with an uppercase ASCII letter. Remaining characters MAY be ASCII letters, digits, hyphens, or underscores.

Member	Requirement and meaning
`description`	Optional human-readable string.
`identifier`	Required on a root entity; inherited by descendants.
`extends`	Optional name of one parent entity.
`include`	Optional array of record sources.
`fields`	Native field map; mutually exclusive with `json_schema`.
`json_schema`	Configuration-relative JSON Schema path; mutually exclusive with `fields` and inheritance.
`data`	Optional array of inline record maps.

An entity MUST define native fields or json_schema. A descendant using native fields MAY inherit all its fields and add none. A concrete entity with no descendants MUST provide at least one include or inline record. A schema-only entity MAY omit both only when another entity extends it.

Field definitions and types

Mon, 01 Jan 0001 00:00:00 +0000

Field definitions and types

Names and forms

A field or property name MUST be non-empty and contain only ASCII letters, digits, hyphens, or underscores. A scalar string is shorthand for an optional, non-repeated field with that type:

fields:
 title: string

The expanded mapping accepts:

Member	Meaning
`type`	Required primitive, `object`, entity reference, or reference union.
`required`	When true, a value or non-null default MUST exist. Defaults to false.
`repeated`	When true, the record value MUST be an array and each item is validated. Defaults to false.
`format`	String annotation; `email`, `uri`, and `url` are enforced case-insensitively.
`enum`	Array of allowed strings for `type: enum`.
`default`	Value used during validation when the record field is absent.
`properties`	Nested field map required by `type: object`.
`unique`	When true, present values MUST be unique within the entity.
`pattern`	Go regular expression enforced on `string` and `enum` values.
`description`	Optional human-readable string.
`source`	One path-derived selector.

default satisfies validation but does not mutate the record or promise that every read/export surface materializes the value. Unrecognized format strings are retained as annotations and are not validated in version 1. Extra record fields are not rejected by schema validation.

Records and data sources

Mon, 01 Jan 0001 00:00:00 +0000

Records and data sources

Entity includes

An entity include is an array. Each entry is either a non-empty glob string or a mapping with non-empty path and optional selector:

include:
 - data/users/*.yaml
 - path: data/catalog.json
 selector: "$.items[*]"

Paths are resolved from the repository root, not the configuration document. Matches are sorted. Duplicate entries with the same path and selector are collapsed. A data glob MAY match no files.

Identifiers and references

Mon, 01 Jan 0001 00:00:00 +0000

Identifiers and references

Identifier definitions

A root entity MUST define identifier as one of:

a field name string, such as identifier: id;
the reserved string identifier: $path; or
a mapping with required field plus optional generated Boolean and pattern string.

Identifier field names use the field-name character set. The field’s record value MUST be a non-empty string or numeric scalar. Its canonical identifier is the scalar’s string representation. The identifier field does not become required merely because it names a field; a usable value is nevertheless required for every record.

Validation and error model

Mon, 01 Jan 0001 00:00:00 +0000

Validation and error model

Configuration loading

Configuration parsing, include resolution, normalization, inheritance construction, and JSON Schema conversion happen before repository validation. A failure in this stage is a configuration error and prevents validation. Examples include an unsupported version, duplicate entity definition, invalid field definition, unknown reference type, or inheritance cycle.

Validation phases

Repository validation proceeds in dependency order:

JSON Schema interoperability

Mon, 01 Jan 0001 00:00:00 +0000

JSON Schema interoperability

Import

An entity MAY replace native fields with json_schema, whose path is resolved relative to the declaring configuration document. The file MUST contain a JSON object schema with properties. fields and json_schema are mutually exclusive, and a JSON-Schema-backed entity cannot participate in inheritance.

Version 1 supports this conversion subset:

JSON Schema construct	Mergeway field result
`type: string`, `integer`, `number`, `boolean`	Corresponding primitive field.
`type: object` plus `properties`	Nested `object` and properties.
`type: array` plus one `items` schema	`repeated: true` element field.
`required`	Required fields at that object level.
string `enum`, string `const`, or `oneOf` string constants	`enum` field.
`description`, `format`, `pattern`, `default`	Corresponding field metadata.
`x-reference-type`	One entity reference.
in-document `$ref`	Resolved JSON Pointer.

A type array MAY contain null plus one supported non-null type. Multiple non-null types are unsupported. External $ref values, reference unions in x-reference-type, non-string enum values, and unsupported JSON Schema types are configuration errors. A $schema declaration MAY identify draft 2020-12, but version 1 implements the subset above; it does not perform arbitrary draft 2020-12 keyword validation.

Path-derived data

Mon, 01 Jan 0001 00:00:00 +0000

Path-derived data

Normalized path

Path-derived behavior starts with the record source path relative to the repository root. Implementations clean the platform path and expose it with / separators. A source outside the root therefore retains leading .. segments.

`$path` identifiers

identifier: $path uses that normalized path as the record identifier. Each matched file MUST yield exactly one record. Inline data, top-level items arrays, and selectors that return multiple records are invalid with $path. The record does not need a literal $path field.

Open Knowledge Format mapping

Mon, 01 Jan 0001 00:00:00 +0000

Open Knowledge Format mapping

Recognized sources

An entity include that matches a .md or .okf file reads it as an Open Knowledge Format concept document. The document MUST begin with a line containing exactly --- and MUST contain a later closing delimiter line. Content between the delimiters is decoded as a YAML map.

Frontmatter MUST contain a non-empty type whose value exactly equals the including entity. type associates the source and is removed from record fields. Other frontmatter entries become fields. All content after the closing delimiter becomes the string field body, preserving its Markdown text.

Changelog and migration notes

Mon, 01 Jan 0001 00:00:00 +0000

Changelog and migration notes

2026-10-19 — Version 1 baseline

Published the first consolidated normative specification, aligned with Mergeway release v0.10.0 and mergeway.version: 1. It covers the native configuration model, inheritance, reference unions, JSONPath selectors, JSON Schema interoperability, path-derived data, $path identifiers, OKF records, and phased validation.

Existing conforming version 1 repositories require no migration for this documentation publication.

Specification on Mergeway

Overview

Overview

Scope

Terminology

Terminology

Core terms

Path terms

Conformance and requirement language

Conformance and requirement language

Requirement keywords

Repository and configuration

Repository and configuration

Entry and version

Entity definitions

Entity definitions

Names and members

Field definitions and types

Field definitions and types

Names and forms

Records and data sources

Records and data sources

Entity includes

Identifiers and references

Identifiers and references

Identifier definitions

Validation and error model

Validation and error model

Configuration loading

Validation phases

JSON Schema interoperability

JSON Schema interoperability

Import

Path-derived data

Path-derived data

Normalized path

$path identifiers

Open Knowledge Format mapping

Open Knowledge Format mapping

Recognized sources

Changelog and migration notes

Changelog and migration notes

2026-10-19 — Version 1 baseline

`$path` identifiers