FHIR MapBuilder

September 20, 2026 · View on GitHub

FHIR MapBuilder is a Visual Studio Code extension designed to facilitate the edition of FHIR StructureMap resources using FHIR Mapping Language (FML).

User documentation: what the extension does and how to use it, in the extension's README (the page shown on the marketplaces).
Install: VS Code Marketplace or Open VSX.
Developer documentation: this README, CONTRIBUTING.md and the architecture decisions under docs/adr/.

Reporting a vulnerability: SECURITY.md.

📂 Project Structure

This repository contains two interconnected projects:

vscode-extension – A Visual Studio Code (VS Code) extension written in TypeScript.
fhir-mapbuilder-validation – A Java Spring Boot REST API that provides backend validation.

The VS Code extension relies on the JAR file generated by the Spring Boot application.

fhir-mapbuilder/
│── vscode-extension/           # VS Code extension (TypeScript)
│   ├── src/
│   ├── package.json
│   ├── tsconfig.json
│   ├── ...
│   ├── target/                 # This is where the JAR file should be placed
│── fhir-mapbuilder-validation/ # Spring Boot REST API (Java)
│   ├── src/
│   ├── pom.xml
│   ├── ...
│── README.md

🛠 Setup & Installation

Clone the Repository

git clone https://github.com/aphp/fhir-mapbuilder.git
cd fhir-mapbuilder

Java 21 Requirement

This application requires Java Development Kit (JDK) version 21 to run. Please ensure that Java 21 is installed and correctly added to your system's PATH.

Build & Package the Java Application

cd fhir-mapbuilder-validation
mvn clean package

After running this command, the JAR file fhir-mapbuilder-validation.jar will be generated in the target/ folder.

Move the JAR File to the Extension Project

cd ..
mkdir -p vscode-extension/target
mv fhir-mapbuilder-validation/target/fhir-mapbuilder-validation.jar vscode-extension/target

Install Dependencies & Package the VS Code Extension

cd vscode-extension
npm ci
npx vsce package --baseImagesUrl=https://raw.githubusercontent.com/aphp/fhir-mapbuilder/refs/heads/main/vscode-extension

This command will generate a .vsix file, which can be installed in VS Code.

🚀 Running the Applications

Start the Java Spring Boot Application

cd fhir-mapbuilder-validation
mvn spring-boot:run

Run the VS Code Extension

Open vscode-extension in VS Code.
Press F5 to start a new Extension Development Host.

⚙️ GitHub Workflows

Five GitHub Actions workflows automate the project. Every workflow declares permissions: {} at the top and each job elevates to the minimum it needs; the design is recorded in docs/adr/.

Workflow	Trigger	What it does	ADR
`ci.yml`	PR, push to `main`, manual	Lint, format and type checks; the TypeScript and Java test suites with Codecov coverage (the `ts` and `java` components each gate at 90 %); an advisory OSV scan on PRs; a `build` job that packages the `.vsix`, smoke-tests the validation jar over `GET /health` and asserts the jar is bundled into the `.vsix`; an advisory `os-smoke` job that runs the same jar smoke test and the extension unit tests on Windows and macOS.	0002
`commit-policy.yml`	PR opened / edited / synchronized, manual	`dco` and `commitlint` check every non-merge commit (a DCO `Signed-off-by` trailer, a valid Conventional Commit); `pr-title` validates the PR title, which becomes the merge-commit subject. Also runs on `pull_request_target`, so PRs from forks are covered.	0001
`dependency-review.yml`	PR, manual	`actions/dependency-review-action` blocks a PR that introduces a high or critical vulnerability, or a dependency under a strong copyleft licence. The check is named `dependency-review`.	0002
`audit.yml`	Weekly cron, manual	OSV-Scanner run over `pom.xml` + `package-lock.json`; uploads the SARIF, so each vulnerability is a Code scanning alert that closes by itself once fixed. No issue is opened. A finding does not fail the job; only a scan that cannot run does.	0002
`dependabot-auto-merge.yml`	Dependabot PRs	Enables auto-merge for patch updates and for minor updates of direct dev-dependencies.	0002
`release.yml`	push to `main`, manual (`publish_tag`, `dry_run`)	release-please maintains a release PR from the commit history; merging it cuts the tag + GitHub Release, then `build` → `publish-marketplace` / `publish-openvsx` package and publish the `.vsix` to both registries, and a post-publish `smoke` job checks the new version surfaced on Open VSX. `workflow_dispatch` never publishes without a tag: with no `publish_tag` it is a package-only rehearsal on `HEAD`; with an existing `publish_tag` (`vX.Y.Z`) it rebuilds at that tag, checks the sources match it, and republishes only with `dry_run: false`. Every job has a timeout.	0003

📜 License

This project is licensed under the MIT License.