anthropics/healthcare

Overview

This skill is a practical guide for building and validating FHIR R4 REST endpoints in Python (FastAPI) and similar stacks. It focuses on correct HTTP status codes, required field validation, value sets, coding systems, and OperationOutcome error responses. Use it to implement create/read/update/delete, bundle transactions, search pagination, and SMART on FHIR authorization. The guidance emphasizes concrete patterns, headers, and common pitfalls to avoid.

How this skill works

The skill inspects incoming FHIR JSON payloads for required cardinality (1..1 or 1..*) and validates enumerated value sets for fields like Observation.status, Patient.gender, Encounter.class, and MedicationRequest.intent. It prescribes HTTP status codes: 201 for create, 422 for validation errors, 412 for ETag mismatches, 401/403 for auth issues, and OperationOutcome bodies for all errors. It also covers Bundle handling (transaction vs batch), search pagination, and SMART on FHIR scope enforcement.

When to use it

• Creating FHIR REST endpoints for Patient, Observation, Encounter, Condition, MedicationRequest
• Validating resource payloads and returning OperationOutcome with proper HTTP status codes
• Implementing SMART on FHIR OAuth flows and enforcing scopes
• Handling Bundles: transaction, batch, and transaction-response processing
• Implementing search, pagination (_count/_offset) and CapabilityStatement metadata

Best practices

• Validate only fields with cardinality starting at 1 as required; treat 0..1 as optional
• Return OperationOutcome JSON with Content-Type: application/fhir+json for all errors
• On create return 201 with Location header and meta.versionId/meta.lastUpdated, plus ETag W/"{versionId}"
• Use 422 Unprocessable Entity for missing/invalid domain values and 412 Precondition Failed for If-Match ETag mismatches
• Use Coding for Encounter.class and CodeableConcept for Observation.code/Condition.code; reference standard system URLs (LOINC, SNOMED, RxNorm, ICD-10)

Example use cases

• FastAPI endpoint that validates Observation.status and returns 201 or 422 with OperationOutcome
• Implementing conditional create with If-None-Exist to return 200 when a match exists or 201 when created
• Processing a transaction Bundle atomically and returning a transaction-response Bundle
• Adding SMART on FHIR token validation and scope checks to protect read/update endpoints
• Implementing paginated search that returns a searchset Bundle with navigation links