fhir-developer-skill

FHIR API development guide for building healthcare endpoints. Use when: (1) Creating FHIR REST endpoints (Patient, Observation, Encounter, Condition, MedicationRequest), (2) Validating FHIR resources and returning proper HTTP status codes and error responses, (3) Implementing SMART on FHIR authorization and OAuth scopes, (4) Working with Bundles, transactions, batch operations, or search pagination. Covers FHIR R4 resource structures, required fields, value sets (status codes, gender, intent), coding systems (LOINC, SNOMED, RxNorm, ICD-10), and OperationOutcome error handling.

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "fhir-developer-skill" with this command: npx skills add anthropics/healthcare/anthropics-healthcare-fhir-developer-skill

FHIR Developer Skill

Quick Reference

HTTP Status Codes

CodeWhen to Use
200 OKSuccessful read, update, or search
201 CreatedSuccessful create (include Location header)
204 No ContentSuccessful delete
400 Bad RequestMalformed JSON, wrong resourceType
401 UnauthorizedMissing, expired, revoked, or malformed token (RFC 6750)
403 ForbiddenValid token but insufficient scopes
404 Not FoundResource doesn't exist
412 Precondition FailedIf-Match ETag mismatch (NOT 400!)
422 Unprocessable EntityMissing required fields, invalid enum values, business rule violations

Required Fields by Resource (FHIR R4)

ResourceRequired FieldsEverything Else
Patient(none)All optional
Observationstatus, codeOptional
Encounterstatus, classOptional (including subject, period)
ConditionsubjectOptional (including code, clinicalStatus)
MedicationRequeststatus, intent, medication[x], subjectOptional
Medication(none)All optional
BundletypeOptional

Required vs Optional Fields (CRITICAL)

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

CardinalityRequired?
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

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)

CodeDisplayUse
AMBambulatoryOutpatient visits
IMPinpatient encounterHospital admissions
EMERemergencyEmergency department
VRvirtualTelehealth

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

SystemURL
LOINChttp://loinc.org
SNOMED CThttp://snomed.info/sct
RxNormhttp://www.nlm.nih.gov/research/umls/rxnorm
ICD-10http://hl7.org/fhir/sid/icd-10
v3-ActCodehttp://terminology.hl7.org/CodeSystem/v3-ActCode
Observation Categoryhttp://terminology.hl7.org/CodeSystem/observation-category
Condition Clinicalhttp://terminology.hl7.org/CodeSystem/condition-clinical
Condition Ver Statushttp://terminology.hl7.org/CodeSystem/condition-ver-status

Common LOINC Codes (Vital Signs)

CodeDescription
8867-4Heart rate
8480-6Systolic blood pressure
8462-4Diastolic blood pressure
8310-5Body temperature
2708-6Oxygen 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

MistakeCorrect Approach
Making subject or period required on EncounterBoth are 0..1 (optional). Only status and class are required
Using CodeableConcept for Encounter.classclass uses Coding directly: {"system": "...", "code": "AMB"}
Returning 400 for ETag mismatchUse 412 Precondition Failed for If-Match failures
Returning 400 for invalid enum valuesUse 422 Unprocessable Entity for validation errors
Forgetting Content-Type headerAlways set Content-Type: application/fhir+json
Missing Location header on createReturn 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

  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.

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Related Skills

Related by shared tags or category signals.

Coding

clinical-trial-protocol-skill

No summary provided by upstream source.

Repository SourceNeeds Review
General

prior-auth-review-skill

No summary provided by upstream source.

Repository SourceNeeds Review
Coding

frontend-design

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

Repository SourceNeeds Review
160.5K94.2Kanthropics
Coding

xlsx

Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.

Repository SourceNeeds Review
28.4K94.2Kanthropics