FHIR Developer Skill

Quick Reference

HTTP Status Codes

200 OK

201 Created

Location

204 No Content

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

412 Precondition Failed

422 Unprocessable Entity

Required Fields by Resource (FHIR R4)

status

code

status

class

subject

period

subject

code

clinicalStatus

status

intent

medication[x]

subject

type

Required vs Optional Fields (CRITICAL)

Only validate fields with cardinality starting with "1" as required.

0..1

0..*

1..1

1..*

Common mistake: Making

subject

period

Value Sets (Enum Values)

Invalid enum values must return

422 Unprocessable Entity

Patient.gender

male | female | other | unknown

Observation.status

registered | preliminary | final | amended | corrected | cancelled | entered-in-error | unknown

Encounter.status

planned | arrived | triaged | in-progress | onleave | finished | cancelled | entered-in-error | unknown

Encounter.class (Common Codes)

AMB

IMP

EMER

VR

Condition.clinicalStatus

active | recurrence | relapse | inactive | remission | resolved

Condition.verificationStatus

unconfirmed | provisional | differential | confirmed | refuted | entered-in-error

MedicationRequest.status

active | on-hold | cancelled | completed | entered-in-error | stopped | draft | unknown

MedicationRequest.intent

proposal | plan | order | original-order | reflex-order | filler-order | instance-order | option

Bundle.type

document | message | transaction | transaction-response | batch | batch-response | history | searchset | collection

Validation Pattern

Python/FastAPI:

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

def operation_outcome(severity: str, code: str, diagnostics: str):
    return {
        "resourceType": "OperationOutcome",
        "issue": [{"severity": severity, "code": code, "diagnostics": diagnostics}]
    }

VALID_OBS_STATUS = {"registered", "preliminary", "final", "amended",
                    "corrected", "cancelled", "entered-in-error", "unknown"}

@app.post("/Observation", status_code=201)
async def create_observation(data: dict):
    if not data.get("status"):
        return JSONResponse(status_code=422, content=operation_outcome(
            "error", "required", "Observation.status is required"
        ), media_type="application/fhir+json")

    if data["status"] not in VALID_OBS_STATUS:
        return JSONResponse(status_code=422, content=operation_outcome(
            "error", "value", f"Invalid status '{data['status']}'"
        ), media_type="application/fhir+json")
    # ... create resource

TypeScript/Express:

const VALID_OBS_STATUS = new Set(['registered', 'preliminary', 'final', 'amended',
  'corrected', 'cancelled', 'entered-in-error', 'unknown']);

app.post('/Observation', (req, res) => {
  if (!req.body.status) {
    return res.status(422).contentType('application/fhir+json')
      .json(operationOutcome('error', 'required', 'Observation.status is required'));
  }
  if (!VALID_OBS_STATUS.has(req.body.status)) {
    return res.status(422).contentType('application/fhir+json')
      .json(operationOutcome('error', 'value', `Invalid status '${req.body.status}'`));
  }
  // ... create resource
});

Pydantic v2 Models (use

Literal

const=True

from typing import Literal
from pydantic import BaseModel

class Patient(BaseModel):
    resourceType: Literal["Patient"] = "Patient"
    id: str | None = None
    gender: Literal["male", "female", "other", "unknown"] | None = None

Coding Systems (URLs)

http://loinc.org

http://snomed.info/sct

http://www.nlm.nih.gov/research/umls/rxnorm

http://hl7.org/fhir/sid/icd-10

http://terminology.hl7.org/CodeSystem/v3-ActCode

http://terminology.hl7.org/CodeSystem/observation-category

http://terminology.hl7.org/CodeSystem/condition-clinical

http://terminology.hl7.org/CodeSystem/condition-ver-status

Common LOINC Codes (Vital Signs)

8867-4

8480-6

8462-4

8310-5

2708-6

Data Type Patterns

Coding (direct) vs CodeableConcept (wrapped)

Coding - Used by

Encounter.class

{"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB"}

CodeableConcept - Used by

Observation.code

Condition.code

{"coding": [{"system": "http://loinc.org", "code": "8480-6"}], "text": "Systolic BP"}

Reference

{"reference": "Patient/123", "display": "John Smith"}

Identifier

{"system": "http://hospital.example.org/mrn", "value": "12345"}

Common Mistakes

subject

period

status

class

Encounter.class

class

{"system": "...", "code": "AMB"}

412 Precondition Failed

422 Unprocessable Entity

Content-Type: application/fhir+json

Location: /Patient/{id}

Resource Structures

For complete JSON examples of all resources, see references/resource-examples.md.

Quick reference for error responses:

{
  "resourceType": "OperationOutcome",
  "issue": [{"severity": "error", "code": "not-found", "diagnostics": "Patient/123 not found"}]
}

RESTful Endpoints

POST   /[ResourceType]              # Create (returns 201 + Location header)
GET    /[ResourceType]/[id]         # Read
PUT    /[ResourceType]/[id]         # Update
DELETE /[ResourceType]/[id]         # Delete (returns 204)
GET    /[ResourceType]?param=value  # Search (returns Bundle)
GET    /metadata                    # CapabilityStatement
POST   /                            # Bundle transaction/batch

Conditional Operations

If-Match (optimistic locking):

• Client sends:

  If-Match: W/"1"

• Mismatch returns

  412 Precondition Failed

If-None-Exist (conditional create):

• Client sends:

  If-None-Exist: identifier=http://mrn|12345

• Match exists: return existing (200)
• No match: create new (201)

Reference Files

For detailed guidance, see:

• Resource Examples: Complete JSON structures for Patient, Observation, Encounter, Condition, MedicationRequest, OperationOutcome, CapabilityStatement
• SMART on FHIR Authorization: OAuth flows, scope syntax (v1/v2), backend services, scope enforcement
• Pagination: Search result pagination,

  _count

  /

  _offset

  parameters, link relations
• Bundle Operations: Transaction vs batch semantics, atomicity, processing order

Implementation Checklist

1. Set

   Content-Type: application/fhir+json

   on all responses
2. Return

   meta.versionId

   and

   meta.lastUpdated

   on resources
3. Return

   Location

   header on create:

   /Patient/{id}

4. Return

   ETag

   header:

   W/"{versionId}"

5. Use OperationOutcome for all error responses
6. Validate required fields → 422 for missing
7. Validate enum values → 422 for invalid
8. Search returns Bundle with

   type: "searchset"

Quick Start Script

To scaffold a new FHIR API project with correct Pydantic v2 patterns:

python scripts/setup_fhir_project.py my_fhir_api

Creates a FastAPI project with correct models, OperationOutcome helpers, and Patient CRUD endpoints.