Skip to content

v2.5.0

Choose a tag to compare

View all tags
@JoshuaHarris391 JoshuaHarris391 released this 03 Jul 02:01
v2.5.0
738c5f9

Warning

The allOf $ref wrapping introduced in v2.5.0 was based on a misdiagnosis and has been reverted in v2.6.1. Do not use the fix-refs command from this release. The real cause of missing descriptions in the data-dictionary viewer is description: null placeholders in _definitions.yaml — the null-description warning (kept in v2.6.1) diagnoses it.

Features

  • Preserve $ref sibling annotations via allOf wrapping and add fix-refs command (1f805ad)

Gen3 resolves data dictionaries with JSON Schema draft-04 semantics, where any keyword sitting as a direct sibling of $ref is ignored during resolution. Properties written as {description: ..., $ref: ...} therefore lost their description/termDef/term in dictionaryutils, and the data-dictionary viewer showed "No Description". This release keeps those annotations by moving the $ref into an allOf list, with the annotations as siblings of allOf.

Details

  • New refs module — single source of truth for the transform. Idempotent; never touches bare refs, refs already inside allOf/anyOf/oneOf, the properties: {$ref: ...} merge construct, or _definitions.yaml/_terms.yaml/_settings.yaml.
  • Generator fix — format_datetime no longer drops the property description when emitting the _definitions.yaml#/datetime ref; annotations are preserved beside allOf.
  • New CLI command — gen3schemadev fix-refs -y <dir> [--dry-run] rewrites an existing dictionary in place (recursive) with a per-file, per-property report of what was wrapped and what was skipped and why.
  • Rule validator — props_must_have_type now recognises refs wrapped in allOf/anyOf/oneOf, so fixed properties are not flagged as missing type/enum. Legacy top-level sibling refs still validate as before.
  • Shipped templates — sibling-$ref properties in project.yaml (id, programs) and program.yaml (id) rewritten to the allOf form.

Notes for downstream consumers

  • Resolved-schema shape changes for wrapped properties: the referenced definition content now nests under allOf[0] after resolution (gen3-validator), instead of being merged flat.
  • After updating a deployed dictionary, the compiled dictionary must be rebuilt and the portal cache refreshed before descriptions appear in the UI.

Full Changelog: v2.4.0...v2.5.0

Assets 2
Loading