FHIR Development Standards and Contribution Guidelines¶

Overview¶

This document outlines the standards and processes for contributing FHIR resources and implementations to our project. All FHIR development should be submitted via pull requests and undergo thorough review.

Standards Requirements¶

1. General Quality Standards¶

Maintain clean, well-documented code
Follow established FHIR best practices
Ensure compatibility with the Polaris system
Adhere to FHIR R4 specification
Align with CA-Core+ requirements where applicable

2. Content Requirements¶

For all FHIR elements going forward (beyond CPAR and CII implementations):

Raw and Rendered Content¶

Text Narratives: All FHIR elements must include complete text narratives
Must include text element with status "generated"
Human-readable div content summarizing the resource
Dual Value Storage: For any coded or translated values:
Include the human-readable rendered content (e.g., code.text)
Include the original raw value with appropriate coding
Store raw values in appropriate system namespaces
Example: For observations, always include code.text even if code.coding is present

This dual-storage approach ensures transparency and traceability in AI-assisted development workflows.

3. Namespace Management¶

All raw values must be properly namespaced
Use appropriate system identifiers for value sets and code systems
Follow Polaris naming conventions:
Identifier systems: https://fhir.apps.health/NamingSystem/[instance-identifier]-[resource-type]-identifier
CodeSystem URLs: https://fhir.apps.health/CodeSystem/[app-name]-app-state
Raw EMR codes: https://fhir.apps.health/[instance-identifier]/CodeSystem/[resource-type]-code

4. Polaris-Specific Requirements¶

Identifier Patterns¶

All Polaris resources must have at least one identifier matching the canonical Polaris system URI pattern: - Pattern: `^https://fhir.apps.health/NamingSystem/[A-Za-z0-9._-]+-[resource-type]-identifier# FHIR Development Standards and Contribution Guidelines

Overview¶

This document outlines the standards and processes for contributing FHIR resources and implementations to our project. All FHIR development should be submitted via pull requests and undergo thorough review.

This is enforced via FHIRPath invariants on each profile

Profile URLs¶

All profiles must use the canonical URL pattern: - https://fhir.apps.health/StructureDefinition/polaris-[resource-type]

Reference Strategy¶

All references between resources should use identifier-based references
Avoid direct resource references (Reference.reference)
Prefer Reference.identifier with appropriate system/value pairs

Must Support Elements¶

Key elements marked as Must Support (MS) across profiles include: - Resource identifiers - Status fields - Subject/patient references - Relevant clinical data fields (varies by resource type)

Review Process¶

Pull Request Workflow¶

All FHIR implementations must be submitted as pull requests
Early and frequent feedback is encouraged
Reviews will be conducted promptly upon submission

Review Availability¶

Primary reviewer available for consultation at any time
Contributors are encouraged to seek input early in the development process

Supporting Tools and Documentation¶

1. Standards Documentation¶

A comprehensive standards document detailing all requirements and best practices for FHIR development, including: - FSH (FHIR Shorthand) coding standards - JSON example standards - Mapping documentation requirements - Profile constraint patterns

2. LLM Integration¶

Development of a Large Language Model prompt for validating FHIR inputs
Prompt should validate:
Proper identifier patterns
Required narrative text elements
Dual value storage (raw + rendered)
Compliance with Polaris invariants
Include example prompts for resource generation and review

3. FIRA Blackwell Updates¶

The custom GPT assistant should be updated to include: - Complete Polaris FHIR specification (all profiles and extensions) - FSH language reference (compressed YAML version) - Coding standards for FSH and JSON - Mapping standards documentation - All Polaris-specific invariants and patterns - Example resources from the specification

4. Claude Configuration¶

Create a Claude configuration file for FHIR development
Include:
Project structure and file organization
FSH syntax highlighting and validation rules
Polaris-specific validation patterns
Links to canonical URLs and naming systems
Enable consistent development environment setup
Support developers working on FHIR implementations

Example Implementation Pattern¶

FSH Profile Example (from PolarisCorePatient)¶

Profile:        PolarisCorePatient
Parent:         Patient
Id:             polaris-core-patient
Title:          "Polaris Patient"
Description:    "Generic Polaris core profile for patient demographic..."
* ^url = "https://fhir.apps.health/StructureDefinition/polaris-core-patient"
* ^status = #draft
* obeys patient-has-polaris-id

// Narrative requirement
* text 0..1 MS
* text ^short = "Narrative"
* text ^definition = "A human-readable narrative summary..."

// Identifier with Polaris pattern
* identifier 1..* MS
// Must match pattern via invariant

JSON Example Pattern¶

{
  "resourceType": "Patient",
  "id": "avery-linwood",
  "meta": {
    "profile": ["https://fhir.apps.health/StructureDefinition/polaris-core-patient"]
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns='http://www.w3.org/1999/xhtml'>Avery Linwood, 34-year-old female...</div>"
  },
  "identifier": [{
    "system": "https://fhir.apps.health/NamingSystem/cedarbrook-clinic-patient-identifier",
    "value": "1234567890"
  }],
  // Additional fields with both raw and text values where applicable
}

Next Steps¶

Draft comprehensive FSH and JSON coding standards documents
Create LLM prompt templates for resource generation and validation
Update FIRA Blackwell knowledge base with complete Polaris specification
Develop Claude configuration template with project-specific settings
Create example pull request demonstrating the complete workflow