Repository modeling on Mergeway

Reuse a JSON Schema

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

Reuse a JSON Schema

Use json_schema when another tool already owns the record contract or when draft 2020-12 constraints are more suitable than native Mergeway fields. This procedure targets Mergeway v0.10.0 and the release-equivalent examples/json-schema fixture.

Point an entity at the schema

Copy examples/json-schema to a working directory. Its entry configuration resolves the schema relative to mergeway.yaml:

entities:
 Customer:
 description: Customers defined via a JSON Schema file.
 identifier: id
 include:
 - data/customers/*.yaml
 json_schema: schemas/customer.json

Keep fields absent: json_schema and native fields are mutually exclusive. The JSON Schema must describe an object and expose the configured identifier in properties.

Load records with JSONPath

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

Load records with JSONPath

Use a selector when a JSON file wraps the records you want beneath another property. This procedure targets Mergeway v0.10.0 and examples/jsonpath.

Add a structured include

Copy the example, then inspect its User entity:

entities:
 User:
 identifier: id
 fields:
 id: string
 name: string
 include:
 - path: data/users.json
 selector: "$.users[*]"

The selector runs against the decoded JSON document. Each selected object becomes one User record and must provide a usable id.

Check the result

Run these commands from the copied repository:

Model inheritance and reference unions

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

Model inheritance and reference unions

Entity inheritance models an assignable family; a reference union models a value that may target one of several independent entities. These procedures target Mergeway v0.10.0 and the release-equivalent examples/inheritance and examples/reference-union fixtures.

Reuse a parent schema

In examples/inheritance, Animal supplies identity and common fields while Dog adds breed:

Animal:
 identifier: id
 fields:
 id: { type: string, required: true }
 name: { type: string, required: true }

Dog:
 extends: Animal
 include:
 - data/dogs/*.yaml
 fields:
 breed: { type: string, required: true }

Animal may remain schema-only because it has a descendant. A field typed as Animal accepts an Animal or descendant record. Validate and observe the assignable query:

Derive identifiers and fields from paths

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

Derive identifiers and fields from paths

Use path-derived data when the repository layout already carries stable identity or classification. This procedure targets Mergeway v0.10.0 and examples/path-identifier plus examples/path-segments.

Use the complete path as identity

examples/path-identifier configures:

Note:
 identifier: $path
 include:
 - data/notes/*.yaml
 fields:
 title: { type: string, required: true }
 body: string

The records do not store an ID. Confirm the normalized repository-relative identifiers:

mergeway-cli --root examples/path-identifier validate
mergeway-cli --root examples/path-identifier list --type Note
mergeway-cli --root examples/path-identifier get --type Note data/notes/alpha.yaml

Expose selected path values

examples/path-segments keeps a field identifier but derives three read-only fields:

Load Open Knowledge Format documents

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

Load Open Knowledge Format documents

Mergeway v0.10.0 supports the checked examples/okf fixture, so this workflow is part of the launch documentation rather than deferred content.

Configure the mapping

Copy examples/okf. Its Knowledge entity includes both supported extensions and derives id from the filename:

Knowledge:
 identifier: id
 include:
 - data/concepts/*.md
 - data/concepts/*.okf
 fields:
 id:
 type: string
 required: true
 source: { path_segment_rev: 0 }
 title: { type: string, required: true }
 description: string
 tags: { type: string, repeated: true }
 body: { type: string, required: true }

Each document begins with YAML frontmatter whose type is exactly Knowledge. Mergeway removes type, maps the other frontmatter keys to fields, and exposes the content after the closing delimiter as body.