fhir-developer-skill | SkillBundle

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

TypeScript/Express:

Pydantic v2 Models (use Literal, not const=True):

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:

CodeableConcept - Used by Observation.code, Condition.code:

Reference

Identifier

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:

RESTful Endpoints

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:

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