Module ref_ 

$ref resolution expands base inheritance before other composition (SPEC §5).

Resolution supports these input forms: (1) value = a single string OR an array of strings — an array resolves each path in order, then array_merge (later overrides earlier on key clash). (2) plain path options.yml → load YAML, descend by the default detectKey ['properties'] (= take the file’s properties only). (3) path-specified (file.yml).a.b → regex split, detectKeys = [‘a’,‘b’, ‘properties’] — descend a.b, then descend to properties underneath. (4) relative paths get the basepath ‘/’ prefix; absolute (/-leading) pass through (handled by the FileLoader). (5) the result is recursively processed — nested $ref is expanded.

CRUDUI normalization: $ref is the properties-layer composition entry point. The resolved result is flattened to a single properties map and laid down as the base; $patch overlays it (base first, patch overrides). Unresolved $ref (missing file / bad format / absent detectKey / cycle) is a LOAD ERROR — never valid:true.

Functions

resolve_ref

Resolve a $ref value (string or string[]) to a single flattened properties map. Each entry is resolved in declaration order and merged (later overrides earlier). Nested $ref inside a resolved doc is expanded recursively. The visiting set (canonical file keys on the current chain) detects cycles.