Skip to content

FSH-First, Repo-First Authoring

Intent

Use FSH + Git for diffable, distributed authoring; avoid hand-editing JSON/XML.

Structure

FSH-first authoring treats FSH as source-of-truth and generated JSON/XML as build output. Structurally it's a conventional repo layout + predictable compilation pipeline + review workflow.

  • Source layout: FSH files organized by artifact type (profiles, extensions, instances, terminology)
  • Reuse primitives: aliases and rule sets to reduce duplication and keep consistency
  • Build artifacts: generated resources treated as ephemeral outputs (not manually edited)
  • Review workflow: PR-based changes with CODEOWNERS routing for domain review
  • Developer environment: scripted/tooling support (devcontainer, make targets) so builds are repeatable

FSH-First Authoring Stack Structure Diagram

Key Components

FSH source

  • Author profiles/extensions/instances as text for clean diffs
  • Use naming conventions so artifacts remain discoverable
  • Keep FSH modular (one concern per file)
  • Prefer reuse (aliases, rule sets)
  • Avoid hand-editing generated JSON/XML

SUSHI compile

  • Treat SUSHI output as build artifacts
  • Run SUSHI locally and in CI
  • Fail builds when compilation fails or warnings exceed budget
  • Pin SUSHI version to reduce drift
  • Keep compilation logs accessible

Branch + PR

  • Require PRs for changes to ensure review and traceability
  • Use PR templates that ask for intent + tests + references
  • Keep PRs small to reduce review delay
  • Tag PRs by area (profiling/terminology/testing)
  • Use CODEOWNERS to route reviews

Codespaces/devcontainer

  • Provide a consistent toolchain for contributors
  • Pre-install IG Publisher/SUSHI/Java prerequisites
  • Include scripts for build/validate/test
  • Reduce ‘works on my machine’ issues
  • Document the one-command setup

Behavior

Author → compile → publish

Work flows from text changes to compiled artifacts to rendered IG output, with failures captured early.

Authoring

  • Write new/changed rules in FSH using conventions for naming and modularity.
  • Prefer small changes and reuse rule sets rather than copying constraints.
  • Update examples alongside constraints to keep artifacts executable.

Compilation

  • Run SUSHI locally and in CI; treat errors as blockers and warnings as budgeted debt.
  • Pin compiler versions so build output stays stable.
  • Publish build logs so contributors can debug quickly.

Review

  • Require PR review and link changes to issues/ADRs.
  • Use automated checks to reduce reviewer burden.
  • Merge only when validation and rendering are green.

Benefits

  • Reviewable diffs
  • Automation-friendly

Trade-offs

  • Requires conventions

References