Explanation on Mergeway

Why metadata as code?

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

Why metadata as code?

Metadata often begins as a small configuration file and grows into shared operational data: catalogs, ownership mappings, content, product definitions, or service inventories. A conventional database makes that data queryable, but its changes can become detached from the code, review, and deployment process that depends on it.

Mergeway takes the opposite starting point. YAML and JSON records live in a Git repository beside explicit entity schemas. A proposed data change is therefore an ordinary change set: it has an author, a diff, reviewers, automated checks, and recoverable history.

The Mergeway repository model

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

The Mergeway repository model

Mergeway separates the logical data model from the files used to store it. Four terms keep that distinction clear.

Repository

A repository is the Git or project boundary containing Mergeway configuration, entity schemas, and record files. Documentation uses this term for the versioned body of data people review and share.

The configuration entry point is normally mergeway.yaml. A repository can keep definitions inline or include other files. Record sources can use YAML or JSON and can be divided into directories that make sense to maintainers.

The validation model

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

The validation model

Validation answers one repository-level question: can Mergeway load this file-based database as a consistent set of entities, records, and relationships? It proceeds in layers so a useful local error is reported before a dependent check produces noise.

Format

The format phase reads configured YAML and JSON sources. Syntax errors, unsupported document shapes, or data that cannot be decoded stop the affected source from becoming records. Formatting and parsing are related but distinct: canonical formatting makes reviews predictable, while format validation determines whether data can be read.

Semantic diff versus file diff

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

Semantic diff versus file diff

A Git file diff answers “which lines changed?” A Mergeway semantic diff answers “which records changed, and how?” Both views are useful, but they describe different layers of a repository.

Logical records outlive files

Mergeway loads YAML, JSON, selected arrays, and other configured sources into one logical database. An entity name and identifier—such as Post[post-001]—form a record’s identity. Its source file is provenance, not identity.

MCP access and security

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

MCP access and security

mergeway-mcp separates mutation authority from inspection. Its catalog contains six query tools and no create, update, delete, shell, or arbitrary file-read tool. Calls reload saved repository state but never persist changes.

What read-only guarantees

Through this server’s tools, a client can discover schemas, record fields, logical identifiers, configured backing paths, and structured exports. It cannot ask this server to modify them. This is narrower than saying the entire AI client is read-only: the client may have shell, editor, network, or other MCP tools with separate permissions.

Editor architecture

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

Editor architecture

Mergeway separates repository intelligence from editor presentation. mergeway-lsp is the editor-neutral process: an LSP client launches it over stdio, supplies workspace folders and full document text, and renders the returned diagnostics and language features. An editor extension may add commands or a visual editor, but those are separate consumers of the same repository model.

editor UI and client
 │ stdio LSP
 ▼
mergeway-lsp
 │ roots + unsaved overlays
 ▼
configuration, data loader, validator, record index
 │
 ▼
repository files on disk

Roots establish isolation

At initialization the server takes workspaceFolders, or falls back to rootUri and then legacy rootPath. Each candidate is checked directly for mergeway.yaml and then mergeway.yml. A valid candidate gets its own configuration, records, and identifier index. This isolation means equal identifiers in two roots neither collide nor navigate across roots.

Schema design choices

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

Schema design choices

Mergeway does not prescribe one repository layout. The durable choice is the one that makes identity, ownership, review, and automation clear for the team maintaining the records.

Native fields or JSON Schema

Native fields integrate directly with entity references, inheritance, defaults, enums, and path-derived fields. They are usually the clearest choice when Mergeway owns the schema.

Use json_schema when an external system owns an object contract or when its supported draft 2020-12 constraints are valuable. Mergeway converts only its documented subset, and JSON-Schema-backed entities cannot use inheritance. The JSON Schema guide demonstrates the boundary.

Component architecture

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

Component architecture

Mergeway’s components are separate interfaces over one file-backed repository model. The specification defines the contract; shared Go packages load and validate it; each runnable component adds a workflow-specific boundary.

repository files
 │
 ▼
configuration + data + validation core
 │
 ├── mergeway-cli operations, validation, formatting, export
 │ └── JSON subprocess interface ── mergeway-python
 ├── mergeway-diff snapshots and semantic comparison
 ├── mergeway-mcp read-only MCP tools
 └── mergeway-lsp diagnostics and language features
 ▲
 │ stdio LSP
 editor integrations

Shared repository core

internal/config loads and normalizes configuration. internal/data discovers sources and represents records. internal/validation applies configuration, format, schema, and reference checks. This layering keeps identity, inheritance, path derivation, and reference semantics consistent across interfaces.