Path-derived data

Normative v1. This page applies to repositories declaring mergeway.version: 1 and is normative.

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.

Synthetic field sources

A string-like, non-repeated field MAY define source with exactly one selector:

Indexes MUST be non-negative and in range for every record. Source fields cannot be integer, number, boolean, or object; cannot be repeated; and cannot define a default. An entity containing a source field MUST NOT define inline data.

The checked example covers all three selectors and $path identity:

mergeway:
  version: 1

entities:
  Page:
    identifier: slug
    include:
      - data/pages/*.yaml
    fields:
      slug: string
      title:
        type: string
        pattern: "^[A-Z]"
      file:
        type: string
        required: true
        source:
          path: true
      directory:
        type: string
        source:
          path_segment: 1
      filename:
        type: string
        source:
          path_segment_rev: 0

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

  Event:
    identifier: id
    include:
      - data/events.yaml
    fields:
      id: integer
      score: number
      published: boolean

  SelectedItem:
    identifier: id
    include:
      - path: data/catalog.json
        selector: "$.items[*]"
    fields:
      id: string
      label: string

Derived values are inserted for reads, filtering, export, and validation. They are not written back to source files. A source field MAY be required, because derivation supplies its value before schema validation.