Skip to content

Package-First IG Layout

Intent

Treat the IG as a versioned package with stable canonical + dependencies.

Structure

Package-first IG layout treats the IG as a versioned software package with stable identifiers and dependencies. Structurally it’s anchored by ig.ini + sushi-config.yaml, a stable canonical and packageId, and explicit dependency management.

  • Root config: ig.ini at repo root to support both local and auto-build pipelines
  • Package metadata: canonical URL, packageId, version, status/maturity stored in sushi-config.yaml
  • Dependency graph: explicit, pinned dependency list with documented rationale
  • Naming conventions: consistent IDs and filenames to ensure stable URLs across releases
  • Publication pipeline: predictable build → package publish → preview/update steps

Key Components

ig.ini

  • Keep ig.ini at the IG root
  • Pin template and point to correct sushi-config
  • Document any non-default parameters
  • Avoid environment-specific values
  • Verify HL7 auto-build compatibility

sushi-config.yaml

  • Define canonical, version, dependencies, and menu structure
  • Keep packageId stable from the start
  • Use consistent naming for profiles and examples
  • Ensure dependencies are resolvable
  • Validate that generated output matches expectations

package metadata

  • Maintain semantic versioning policies
  • Ensure package.json metadata matches IG packaging rules
  • Include status, maturity, and publication notes
  • Keep changelog aligned with versions
  • Publish packages predictably

dependency list

  • Declare dependencies explicitly and keep versions pinned
  • Document why each dependency exists
  • Monitor dependency updates for breaking changes
  • Keep dependency count minimal
  • Validate builds in clean environments

naming conventions

  • Establish consistent profile IDs, filenames, and canonical URLs
  • Ensure names are stable across releases
  • Avoid collisions with upstream IGs
  • Document conventions in CONTRIBUTING
  • Enforce conventions via CI linting

Behavior

Build and dependency behavior

Package-first behavior is about making builds reproducible and upgrades intentional.

Change management

  • When changing canonical/packageId/versioning, record an ADR and communicate downstream impact.
  • Confirm dependencies resolve in a clean environment (no hidden local caches).
  • Use semver rules so implementers can predict compatibility.

Dependency upgrades

  • Upgrade dependencies intentionally; capture what changed and why.
  • Re-run validation and rendering checks after upgrades.
  • If behavior changes, add regression tests and update migration notes.

Benefits

  • Reliable validation
  • Composable dependencies

Trade-offs

  • Canonical mistakes are costly

References