Teaching JSON & XML to Healthcare Professionals

The Problem

Healthcare organizations implementing FHIR face a common challenge: clinical staff and business analysts need to understand JSON and XML data formats, but:

• Generic programming tutorials use examples (shopping carts, blog posts) that don’t resonate with healthcare context
• Technical prerequisites assume knowledge of programming concepts unfamiliar to healthcare professionals
• Healthcare-specific training often skips fundamental data structure concepts, jumping straight to FHIR resources
• Learning materials rarely bridge the gap between “what is JSON?” and “reading a Patient resource”

This creates barriers to FHIR adoption and API integration projects.

Context and Requirements

I observed this gap while working on FHIR implementation projects at the HSE. Clinical informaticians, business analysts, and healthcare IT professionals were expected to:

• Review FHIR resource examples
• Validate API responses
• Understand FHIR profiles and Implementation Guides
• Participate in technical discussions about data structures

But many hadn’t worked with JSON or XML before. They needed:

• Healthcare-relevant examples using familiar clinical concepts
• Progressive learning starting from absolute basics
• Visual clarity showing structure and hierarchy
• Practical application connecting concepts to real FHIR use cases
• Self-paced materials for independent learning

What I Built

A lightweight, accessible educational resource introducing JSON and XML through a healthcare lens.

1. JSON Fundamentals

• Object structure and syntax (curly braces, key-value pairs)
• Arrays and nested objects
• Data types relevant to healthcare (strings, numbers, booleans, nulls)
• Common patterns in FHIR resources

2. XML Fundamentals

• Element structure and syntax (tags, attributes, content)
• Hierarchy and nesting
• Namespaces and validation
• CDA document structure patterns

3. Healthcare-Focused Examples

All examples use healthcare concepts:

• Patient demographics
• Medication lists
• Laboratory results
• Vital signs
• Appointment scheduling

Rather than generic programming examples.

4. Side-by-Side Comparisons

JSON vs XML representations of the same healthcare data:

• Shows when each format is appropriate
• Highlights structural differences
• Demonstrates FHIR’s support for both formats
• Explains transformation considerations

5. Progressive Complexity

Starting with single values, building to:

• Simple objects and elements
• Nested structures
• Arrays and repeating elements
• Complete FHIR resource examples
• Real-world Patient and Observation resources

Technical Approach

Minimal Dependencies

• Plain HTML and JavaScript
• No build tools or frameworks
• Works offline and on any device
• Easy to clone and customize for internal training

Interactive Learning

• Live JSON/XML editors
• Instant validation feedback
• Syntax highlighting
• Expandable/collapsible sections for exploration

Visual Structure

• Clear indentation and formatting
• Color-coded syntax
• Annotated examples
• Diagrams showing object/element relationships

Reusable Content

• Modular sections
• Easy to extract for presentations
• Adaptable for workshops
• Reference material for ongoing use

Pedagogical Decisions

Healthcare First, Programming Second

Every example connects to clinical concepts healthcare professionals already understand:

• A Patient object is a patient they know
• A MedicationStatement is a prescription they’ve seen
• An Observation is a lab result they’ve reviewed

This builds confidence before introducing technical complexity.

Avoiding Jargon

Using plain language:

• “Curly braces create an object” not “Instantiating a JSON object”
• “Tags surround content” not “Element node hierarchy”
• “Lists use square brackets” not “Array data structures”

Technical terms are introduced gradually with healthcare analogies.

Show Before Explain

Present working examples first, then explain:

• See the structure
• Understand the pattern
• Learn the rules
• Apply to new scenarios

This matches how clinical professionals learn procedures.

Hands-On Practice

Every concept includes:

• A working example
• Guided exercise
• Open-ended challenge
• Real FHIR resource to explore

Learning by doing rather than passive reading.

Standards Implementation

JSON (ECMA-404)

• Correct syntax and structure
• Proper escaping and encoding
• Valid data types
• UTF-8 encoding

XML 1.0

• Well-formed documents
• Proper nesting
• Attribute vs element usage
• Namespace awareness

HL7 FHIR R4

• Authentic Patient resource examples
• Observation resources (laboratory results, vital signs)
• MedicationStatement examples
• References to official FHIR specification

All FHIR examples use real resource structures (with synthetic data) to ensure learners see accurate representations.

What I Learned

Education vs Documentation

Documentation tells experts what they need to know. Education meets learners where they are:

• Assume nothing about prior knowledge
• Connect to existing mental models
• Build confidence incrementally
• Provide context for “why does this matter?”

Domain Context Matters

Using healthcare examples transformed comprehension:

• Faster concept uptake
• Better retention
• More engagement
• Natural transition to real FHIR resources

Generic programming tutorials would have been less effective.

Progressive Disclosure Works

Showing simple examples first, then revealing complexity:

• Prevents overwhelm
• Builds pattern recognition
• Creates “aha moments” when concepts connect
• Allows self-pacing

Accessibility Is Technical

Making content accessible required technical decisions:

• Semantic HTML for screen readers
• Clear heading hierarchy
• Sufficient color contrast
• Keyboard navigation
• Offline functionality

Accessibility isn’t extra; it’s core design.

Reusability Multiplies Impact

This resource has been used:

• As pre-work for FHIR training courses
• In API integration project onboarding
• For self-study by healthcare professionals
• As reference material during implementation
• In university health informatics courses

By keeping it simple and modular, it serves multiple use cases.

Impact and Value

Educational Applications

• Pre-training material for FHIR implementation projects
• Onboarding resource for new team members joining healthcare API projects
• Self-study reference for healthcare professionals transitioning to technical roles
• Supplementary material for university health informatics courses

Key Benefits

• Bridges the gap between clinical knowledge and technical data formats
• Uses familiar healthcare concepts (patients, medications, observations) rather than generic programming examples
• Progressive structure allows learners to move at their own pace
• No installation required - works offline on any device
• Reusable content easily adapted for workshops or presentations

Future Improvements

Potential enhancements:

• Interactive JSON/XML editor with real-time validation
• More FHIR resource examples (Condition, Procedure, DiagnosticReport)
• Video walkthroughs for visual learners
• Quizzes for knowledge checking
• CDA document structure deep-dive
• IHE profile examples (XDS metadata, XCA queries)

Why This Matters

FHIR adoption isn’t just a technical challenge—it’s an organizational change. When clinical staff and business analysts can read FHIR resources, they can:

• Participate in design discussions
• Validate implementations against requirements
• Identify data quality issues
• Understand API capabilities and limitations
• Bridge clinical and technical teams

This educational resource lowers the barrier to participation, making FHIR implementation a collaborative effort rather than a purely technical one.

---

Key Insight: Teaching technical concepts to non-technical audiences requires domain-specific examples and progressive disclosure. Healthcare professionals learn data formats faster when examples use clinical concepts they already understand.