Generate RAML API specifications from HL7 FHIR JSON schemas programmatically — extend the Exchange FHIR RAML Auto-generator to produce R5 resource definitions and downloadable API instances.
FHIR R5 RAML Auto-generator
Objective: Accelerate FHIR API specification work by generating RAML definitions programmatically from HL7 FHIR JSON schemas — extending the MuleSoft FHIR RAML Auto-generator System API (today R4) to produce FHIR R5 resource specifications and downloadable API instances.
What's Getting Built
- FHIR R5 RAML Auto-generator (System API) — generates downloadable FHIR R5 RAML specification packages from HL7 JSON schemas on demand ·
GET /ping, GET /list?fhirVersion=R5, GET /build, POST /build
- HL7 FHIR R5 JSON schema store (target) — R5 StructureDefinitions and datatypes the generator reads to build RAML ·
LOAD R5 StructureDefinition package, SOURCE R5 datatypes
- RAML package download (target) — zipped RAML output published to Exchange as a draft asset and imported into Design Center for editing ·
GET .zip download, PUBLISH Exchange draft, IMPORT Design Center
- Schema-update regeneration job (Batch flow) — async CI job that regenerates specs when the HL7 schema package updates and diffs against the prior version ·
POST /build (batched resource lists), TRIGGER on schema package update
Prerequisites
- Anypoint Platform org with Design Center access for RAML import and validation.
- FHIR RAML Auto-generator System API imported from Exchange as the base implementation.
- HL7 FHIR R5 JSON StructureDefinition package for the generator schema store.
- REST API validation tooling (Anypoint Studio or CI pipeline) to verify generated specs.
Architecture
1. Business requirements
- Eliminate manual RAML authoring for each FHIR resource an organization exposes.
- Generate specifications that stay aligned when HL7 publishes schema updates.
- Support selective resource builds (single resource, resource list, or full R5 package).
- Output Design Center–ready RAML and optional implementation scaffold as a .zip.
- Reduce specification errors that slip in during manual copy-from-IG workflows.
2. Source asset
The FHIR RAML Auto-generator System API on Anypoint Exchange generates RAML from HL7 FHIR R4 JSON schemas. This accelerator extends that pattern to R5.
3. API operations (extended)
| Operation |
Purpose |
| Get Ping |
Health check for the generator service. |
| Get List |
Return all available FHIR JSON schema names and URLs for the configured version (R5). |
| Get Build |
Build an API instance from query parameters; return a .zip of RAML files. |
| Post Build |
Build an API instance from a JSON body listing resources and options; return a .zip. |
4. R5 extension work
- Source FHIR R5 JSON StructureDefinitions and datatypes from the HL7 publication package.
- Update the schema-to-RAML mapping rules for R5-specific changes (new resources, renamed elements, cardinality changes).
- Version the generator so R4 and R5 builds can coexist during migration windows.
- Validate generated RAML against MuleSoft REST API validation rules before zipping.
5. Build options
- Resource selection: Single resource (e.g., Patient), comma-separated list, or full R5 set.
- Profile filtering: Generate only US Core or other IG-constrained profiles when specified.
- Output format: RAML 1.0 with data types, examples, and trait libraries for pagination and search.
- Include examples: Optionally embed HL7 example instances as RAML examples.
6. Integration into API lifecycle
- Publish generated RAML to Anypoint Exchange as a draft asset for review.
- Import into Design Center for team editing before implementation.
- Wire the generator into CI so schema updates trigger spec regeneration and diff review.
- Pair with the accelerator's FHIR error-message API policy for consistent OperationOutcome errors.
7. Error handling and operations
- Return structured errors when a requested resource or profile is not found in the R5 package.
- Log every build request with resource list, version, and output size.
- Monitor build duration; alert when schema package load failures block generation.
8. Security and compliance
- Encrypt PHI in transit and at rest.
- Audit-log every access to and modification of patient data.
- Enforce minimum-necessary access for integration operators and support users.
For additional HIPAA controls, API policies, and reference security patterns, see the MuleSoft Accelerator for Healthcare on Anypoint Exchange.
Testing and validation
- Call Get Ping and Get List with
fhirVersion=R5; confirm core resources (Patient, Observation, Condition, Encounter) appear in the schema catalog.
- Run Get Build for a single Patient resource; import the returned .zip into Design Center without validation errors.
- Run Post Build with a comma-separated resource list and verify the archive size and file count match the request.
- Request a non-existent resource name and confirm a structured error — not an empty or corrupt .zip.
Phased rollout
Phase 1 — Connect
- Import FHIR RAML Auto-generator System API and HL7 FHIR R5 JSON schema package into non-production runtime.
- Expose Get Ping, Get List, and Get Build on API Manager with OAuth credentials for Design Center users.
Phase 2 — Map and test
- Generate RAML for core resources (Patient, Observation, Condition, Encounter); complete Testing and validation and Design Center import.
- Wire CI job to regenerate specs on schema package updates and diff against prior version.
Phase 3 — Production
- Publish approved RAML packages to Exchange as draft assets for API implementation teams.
- Enable Post Build for bulk resource lists used by platform COE self-service.
Success metrics
- Generated RAML passes Design Center import and REST validation for 100% of requested core resources.
- Median Get/Post Build response time ≤ 30 seconds for a single-resource build at P95.
- Schema package upgrade to new HL7 publication completed with regression diff reviewed within one sprint.
- API COE self-service adoption — track builds per month and reduction in manual RAML authoring hours.
Configuration checklist
Before first sandbox deploy, complete the shared Healthcare integration configuration checklist — secure property keys, TLS, OAuth, and credential naming conventions are documented once for all Exchange use cases.
9. Implementation starting point
Download the FHIR RAML Auto-generator System API from Anypoint Exchange as the base implementation.
Import the HL7 FHIR R5 JSON schema package into the generator's schema store (replace or version alongside R4).
Update DataWeave (or Java) mapping modules for R5 element renames and new datatypes.
Add a fhirVersion query parameter (default R5) to Get List and Get/Post Build operations.
Test generated RAML for core resources (Patient, Observation, Condition, Encounter) against Design Center import and REST validation.
Troubleshooting
- Get Build returns empty or corrupt .zip — Likely cause: requested resource not in R5 schema store or mapping module failure. Fix: Verify resource name via Get List, check server logs for schema load errors, and retry after schema package refresh.
- Design Center import fails validation — Likely cause: R5 element rename not handled in DataWeave mapping module. Fix: Update mapping for the failing datatype and regenerate; compare diff against R4 output for the same resource.
- Get List missing expected R5 resources — Likely cause:
fhirVersion parameter omitted or wrong schema package loaded. Fix: Confirm R5 StructureDefinition package path and pass fhirVersion=R5 on list and build operations.
- Build times out on full R5 package — Likely cause: generating entire spec exceeds HTTP timeout. Fix: Use Post Build with batched resource lists or run bulk builds via async CI job with extended timeout.
Deliverable: A Mule System API that generates downloadable FHIR R5 RAML specification packages from HL7 JSON schemas on demand.