This guide introduces the basic concepts and structure of a Mergeway workspace. It is intended for new users who want to understand how to set up and use Mergeway effectively. For runnable sample workspaces, see the examples directory in the GitHub repository.
A Mergeway workspace is just a folder with a few predictable parts. Knowing the vocabulary makes the CLI output easier to read.
Building Blocks
- Workspace: Folder tracked in Git that contains
mergeway.yaml, schemas, and optional objects. All commands run from here. - Schema: YAML/JSON that defines fields and references. Each file describes one entity.
- Object: Optional data instances stored under
data/. - Reference: A link from one schema or field to another (
type: ref). Mergeway validates referential integrity.
Validation Flow
- Mergeway loads
mergeway.yamlto locate schemas and records. - Schemas are parsed and checked for required fields, types, and references.
- Records (if present) are validated against their schemas.
For field syntax and configuration options, see the Schema Format.