JSON schema generator from FHIR Logical Models

Requirements: FHIR Logical Model to JSON Schema Conversion Tool

Overview

This document describes the requirements for a tool that converts FHIR Logical Models defined in FSH (FHIR Shorthand) format into JSON Schemas. The tool must handle essential FHIR-specific features, especially robust support for ValueSet-based enumerations, leveraging the ValueSet schema generation logic introduced in PR #55.

---

Functional Requirements

1. Input Parsing

• **Accept one or more fhir logical models that were produced during the FHIR IG build process
• Recognize Logical Models within FSH files by detecting lines starting with Logical:. Each Logical Model must be parsed with its:
  • Name
  • Parent (if specified)
  • Element definitions (fields, datatypes, cardinalities, constraints)
• Ignore non-logical-model content (e.g., profiles, value sets, code systems).

2. Field Mapping

• Map FHIR datatypes to JSON Schema types:
  • string, boolean, integer, decimal, date, dateTime, etc.
• Support cardinality mapping:
  • 1..1 → required property
  • 0..1 → optional property
  • 0..* or 1..* → array property, required if lower bound is ≥1
• Handle nested and complex structures (objects, arrays, etc.).

3. ValueSet Integration

• Detect fields with ValueSet bindings (e.g., * status 1..1 code from MyStatusVS).
• For any field referencing a ValueSet:
  • Reference the corresponding ValueSet JSON Schema as generated by the logic in PR #55.
  • Use the appropriate $ref property to link to the ValueSet schema.
  • Ensure the JSON Schema output is compatible with the naming and structure conventions established in PR #55.
• Fail gracefully if a referenced ValueSet schema does not exist, providing a meaningful error or warning.

4. Output

• Produce one JSON Schema file per Logical Model.
  • Schema file names and $id fields should follow a clear, deterministic pattern using the canonical of the Logical model. for example http://smart.who.int/base/StructureDefinition/FunctionalRequirement.json.schema for the FunctionalRequirement LM
• Schema output must include:
  • title: Logical Model name
  • type: object
  • properties: mapped from FSH elements
  • required: array of required properties based on cardinality
  • $ref references to ValueSet schemas where needed

5. Tool Operation

this should be implemented as a python script that executes after the IG publisher and after the valueset json schema generation runs in the github pages deploy workflow with files saved to the output/ directory.

Non-Functional Requirements

• Language: Python (to match repo conventions and maximize accessibility).
• Code Quality: Well-structured, modular, and tested. Minimal dependencies.
• Documentation: Clear README and inline code documentation.
• Extensibility: Designed so future support for additional FHIR artifacts (e.g., profiles) can be added.

---

Examples

Example 1: FSH to JSON Schema with ValueSet

FSH

Logical: Animal
Parent: Base
* name 1..1 string
* species 1..1 code from AnimalSpeciesVS
* age 0..1 integer

JSON Schema

{
  "title": "Animal",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "species": { "$ref": "AnimalSpeciesVS.schema.json" },
    "age": { "type": "integer" }
  },
  "required": ["name", "species"]
}

Here, AnimalSpeciesVS.schema.json is produced by the ValueSet expansion logic from PR #55.

---

References

• PR #55: Add ValueSet JSON schema generation from IG publisher expansions.json
• FHIR Shorthand (FSH) Documentation
• FHIR Logical Models
• JSON Schema Specification

---

Open Questions

• Should the tool validate FSH files before processing?
• Should the tool support multi-level/nested Logical Models?
• Should unsupported FHIR datatypes be flagged as errors or mapped as generic objects?

---

Acceptance Criteria

• Tool correctly identifies and processes Logical Models from FSH files.
• Tool maps ValueSet bindings using $ref to generated ValueSet schemas per PR #55.
• Output JSON Schemas conform to both FHIR and JSON Schema standards.
• Documentation and usage instructions are clear and complete.