FHIR Developer Skill Skill

FHIR Developer Skill

Quick Reference

HTTP Status Codes

| Code | When to Use | |------|-------------| | 200 OK | Successful read, update, or search | | 201 Created | Successful create (include Location header) | | 204 No Content | Successful delete | | 400 Bad Request | Malformed JSON, wrong resourceType | | 401 Unauthorized | Missing, expired, revoked, or malformed token (RFC 6750) | | 403 Forbidden | Valid token but insufficient scopes | | 404 Not Found | Resource doesn't exist | | 412 Precondition Failed | If-Match ETag mismatch (NOT 400!) | | 422 Unprocessable Entity | Missing required fields, invalid enum values, business rule violations |

Required Fields by Resource (FHIR R4)

| Resource | Required Fields | Everything Else | |----------|-----------------|-----------------| | Patient | (none) | All optional | | Observation | status, code | Optional | | Encounter | status, class | Optional (including subject, period) | | Condition | subject | Optional (including code, clinicalStatus) | | MedicationRequest | status, intent, medication[x], subject | Optional | | Medication | (none) | All optional | | Bundle | type | Optional |

Required vs Optional Fields (CRITICAL)

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

| Cardinality | Required? | |-------------|-----------| | 0..1, 0..* | NO | | 1..1, 1..* | YES |

Common mistake: Making subject or period required on Encounter. They are 0..1 (optional).

Value Sets (Enum Values)

Invalid enum values must return 422 Unprocessable Entity.

Patient.gender

male | female | other | unknown

Observation.status

Encounter.status

Encounter.class (Common Codes)

| Code | Display | Use | |------|---------|-----| | AMB | ambulatory | Outpatient visits | | IMP | inpatient encounter | Hospital admissions | | EMER | emergency | Emergency department | | VR | virtual | Telehealth |

Condition.clinicalStatus

Condition.verificationStatus

MedicationRequest.status

MedicationRequest.intent

Bundle.type

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, not 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)

| System | URL | |--------|-----| | LOINC | http://loinc.org | | SNOMED CT | http://snomed.info/sct | | RxNorm | http://www.nlm.nih.gov/research/umls/rxnorm | | ICD-10 | http://hl7.org/fhir/sid/icd-10 | | v3-ActCode | http://terminology.hl7.org/CodeSystem/v3-ActCode | | Observation Category | http://terminology.hl7.org/CodeSystem/observation-category | | Condition Clinical | http://terminology.hl7.org/CodeSystem/condition-clinical | | Condition Ver Status | http://terminology.hl7.org/CodeSystem/condition-ver-status |

Common LOINC Codes (Vital Signs)

| Code | Description | |------|-------------| | 8867-4 | Heart rate | | 8480-6 | Systolic blood pressure | | 8462-4 | Diastolic blood pressure | | 8310-5 | Body temperature | | 2708-6 | Oxygen saturation (SpO2) |

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

| Mistake | Correct Approach | |---------|------------------| | Making subject or period required on Encounter | Both are 0..1 (optional). Only status and class are required | | Using CodeableConcept for Encounter.class | class uses Coding directly: {"system": "...", "code": "AMB"} | | Returning 400 for ETag mismatch | Use 412 Precondition Failed for If-Match failures | | Returning 400 for invalid enum values | Use 422 Unprocessable Entity for validation errors | | Forgetting Content-Type header | Always set Content-Type: application/fhir+json | | Missing Location header on create | Return Location: /Patient/{id} with 201 Created |

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

Set Content-Type: application/fhir+json on all responses
Return meta.versionId and meta.lastUpdated on resources
Return Location header on create: /Patient/{id}
Return ETag header: W/"{versionId}"
Use OperationOutcome for all error responses
Validate required fields → 422 for missing
Validate enum values → 422 for invalid
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.

Agent Skills: FHIR Developer Skill

Install this agent skill to your local

Skill Files