Polaris JSON Coding Standards¶

Version 1.1.0 — Production Standards
Last Updated: 2025-07-15

This document defines the comprehensive coding standards for JSON example files in the Polaris FHIR Implementation Guide. These standards ensure consistency, validation compliance, and proper demonstration of FHIR resource usage.

Overview¶

Purpose¶

JSON examples serve multiple critical functions: - Demonstrate proper usage of Polaris profiles - Validate profile constraints and invariants - Guide implementers with realistic scenarios - Test the Implementation Guide build process - Document real-world primary care workflows

Scope¶

These standards apply to: - All JSON files in input/examples/ - JSON snippets in documentation - JSON used in test scenarios - JSON in integration examples

Generation Standards¶

When creating new JSON examples, ALL of the following requirements must be met:

1. File Naming Convention¶

Polaris[ResourceType]-example[-descriptor].json

Examples: - PolarisCorePatient-example.json - PolarisCoreObservation-example-blood-pressure.json - PolarisCoreEncounter-example-routine-visit.json

2. Required Documentation Structure¶

Each JSON file must begin with a structured outline:

## Outline
1. Define the clinical scenario
2. Create resource skeleton with required elements
3. Add identifier with Polaris naming system
4. Include narrative text
5. Populate clinical data with raw code preservation
6. Add references to other Polaris resources
7. Validate against profile
8. Self-audit compliance

3. JSON Structure Requirements¶

Formatting¶

Indentation: 2 spaces per level (strict requirement)
No trailing commas
No comments (JSON doesn't support comments)
Consistent quote style: Double quotes only
Line endings: LF (Unix-style)

Property Order¶

resourceType
id (if present)
meta
text
identifier
status / workflow elements
Clinical/domain elements
contained (if needed)

4. Metadata Requirements¶

{
  "resourceType": "Patient",
  "meta": {
    "profile": [
      "https://fhir.apps.health/StructureDefinition/polaris-core-patient"
    ]
  }
}

Prohibited metadata fields: - meta.versionId - meta.lastUpdated (unless demonstrating history) - meta.source (unless demonstrating provenance)

Validation Standards¶

Critical Validation Errors¶

The following will cause validation failure:

Invalid JSON syntax
Malformed JSON structure
Trailing commas
Single quotes instead of double quotes
Comments in JSON
Missing required elements
No resourceType
Missing profile declaration in meta.profile
Absent required elements per profile
Invalid references
References to non-existent resources
Incorrectly formatted reference identifiers
Wrong reference type for profile constraints
Incorrect canonical URLs
Wrong pattern for Polaris resources
Invalid system URIs in identifiers
Incorrect profile URLs

Validation Warnings¶

The following generate warnings but don't fail validation:

Style inconsistencies
Non-standard indentation
Inconsistent property ordering
Excessive whitespace
Completeness issues
Missing optional but recommended elements
Absent examples of profile features
Limited demonstration of capabilities

File Structure Standards¶

Basic Structure Template¶

{
  "resourceType": "[ResourceType]",
  "id": "[resource-id]",
  "meta": {
    "profile": [
      "https://fhir.apps.health/StructureDefinition/polaris-[resourcetype]"
    ]
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">[Human readable summary]</div>"
  },
  "identifier": [
    {
      "system": "https://fhir.apps.health/NamingSystem/[instance]-[resourcetype]-identifier",
      "value": "[identifier-value]"
    }
  ],
  // Resource-specific content
}

Multi-Profile Examples¶

When demonstrating multiple profiles:

{
  "resourceType": "Patient",
  "meta": {
    "profile": [
      "https://fhir.apps.health/StructureDefinition/polaris-core-patient",
      "http://fhir.infoway-inforoute.ca/StructureDefinition/ca-core-patient"
    ]
  }
}

Content Requirements¶

Realistic Clinical Data¶

Examples must reflect realistic primary care scenarios:

✅ Good Example:

{
  "code": {
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "73211009",
      "display": "Diabetes mellitus"
    }],
    "text": "Type 2 Diabetes - controlled with diet"
  }
}

❌ Bad Example:

{
  "code": {
    "coding": [{
      "system": "http://snomed.info/sct", 
      "code": "12345",
      "display": "Test condition"
    }]
  }
}

Data Completeness¶

Include all Must Support elements: - Populate with realistic values - Demonstrate proper usage - Show edge cases where appropriate

Memorable Test Data¶

Use consistent, memorable test data: - Patient: "Emma Rodriguez" - Practitioner: "Dr. Sarah Chen" - Organization: "Riverside Family Health Centre" - Locations: Named after Alberta cities/regions

Identifier and Reference Standards¶

Identifier Patterns¶

{
  "identifier": [
    {
      "system": "https://fhir.apps.health/NamingSystem/emr-primary-patient-identifier",
      "value": "PAT-2024-789012",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "MR",
          "display": "Medical record number"
        }]
      }
    },
    {
      "system": "https://fhir.apps.health/alberta/NamingSystem/phn",
      "value": "123456789",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "JHN",
          "display": "Jurisdictional health number"
        }]
      }
    }
  ]
}

Reference Patterns¶

Identifier-based references (preferred):¶

{
  "subject": {
    "identifier": {
      "system": "https://fhir.apps.health/NamingSystem/emr-primary-patient-identifier",
      "value": "PAT-2024-789012"
    },
    "display": "Emma Rodriguez"
  }
}

Direct references (when needed):¶

{
  "subject": {
    "reference": "Patient/emma-rodriguez",
    "display": "Emma Rodriguez"
  }
}

Coded Element Standards¶

Dual Code Storage Pattern¶

All coded elements must preserve both mapped and raw codes:

{
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "38341003",
        "display": "Hypertensive disorder"
      },
      {
        "system": "https://fhir.apps.health/NamingSystem/emr-primary-condition-codes",
        "code": "HT-001",
        "display": "High Blood Pressure",
        "userSelected": true
      }
    ],
    "text": "Hypertension - Stage 2, controlled"
  }
}

Code System Usage¶

Type	System Pattern	Example
SNOMED CT	`http://snomed.info/sct`	International terminology
LOINC	`http://loinc.org`	Lab and observation codes
ICD-10-CM	`http://hl7.org/fhir/sid/icd-10-cm`	Diagnosis codes
RxNorm	`http://www.nlm.nih.gov/research/umls/rxnorm`	Medication codes
Local EMR	`https://fhir.apps.health/NamingSystem/[instance]-[type]`	Original EMR codes

Required Coding Elements¶

{
  "coding": [{
    "system": "required",
    "code": "required", 
    "display": "strongly recommended",
    "userSelected": "when applicable"
  }]
}

Narrative and Text Standards¶

Generated Narrative Requirements¶

{
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Emma Rodriguez</b> (Female, DOB: 1978-03-15)</p><p>PHN: 123456789</p><p>Primary Care Provider: Dr. Sarah Chen at Riverside Family Health Centre</p></div>"
  }
}

Narrative Best Practices¶

Concise Summary: Include key identifying information
Clinical Context: Add relevant clinical details
Human Readable: Write for healthcare providers
XHTML Valid: Ensure proper XML structure
No Styling: Avoid CSS or styling attributes

Text Elements in Clinical Data¶

Always include .text for coded concepts:

{
  "valueCodeableConcept": {
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "260385009",
      "display": "Negative"
    }],
    "text": "Negative - no evidence found"
  }
}

Data Type Standards¶

DateTime Formats¶

Always use full ISO 8601 with timezone:

{
  "effectiveDateTime": "2024-03-15T10:30:00-06:00",
  "issued": "2024-03-15T14:45:00-06:00",
  "period": {
    "start": "2024-03-15T10:00:00-06:00",
    "end": "2024-03-15T11:00:00-06:00"
  }
}

Quantities¶

Include all components:

{
  "valueQuantity": {
    "value": 120,
    "unit": "mm[Hg]",
    "system": "http://unitsofmeasure.org",
    "code": "mm[Hg]"
  }
}

Money Values¶

For Canadian healthcare:

{
  "amount": {
    "value": 45.00,
    "currency": "CAD"
  }
}

Contact Information¶

{
  "telecom": [
    {
      "system": "phone",
      "value": "403-555-1234",
      "use": "work"
    },
    {
      "system": "email", 
      "value": "info@riversidehealth.ca",
      "use": "work"
    }
  ]
}

Testing and Validation¶

Validation Checklist¶

Before submitting JSON examples:

[ ] JSON Syntax: Validates as proper JSON
[ ] Profile Compliance: Validates against declared profiles
[ ] Invariant Satisfaction: Meets all profile invariants
[ ] Reference Integrity: All references resolve correctly
[ ] Identifier Patterns: Matches Polaris naming systems
[ ] Must Support: All MS elements populated
[ ] Code Systems: Valid codes and systems
[ ] Narrative: Generated text present and valid XHTML
[ ] Timestamps: ISO 8601 format with timezones
[ ] No Prohibited Fields: No id, versionId, lastUpdated

Validation Tools¶

FHIR Validator: Official HL7 validator
IG Publisher: Validates during build
JSON Schema: Structure validation
Profile Validator: Specific profile compliance

Common Validation Errors¶

Error	Cause	Solution
"Unknown resource type"	Wrong resourceType	Check spelling and case
"Profile not found"	Invalid profile URL	Verify canonical URL
"Invariant failure"	Missing required pattern	Check invariant expression
"Invalid reference"	Bad reference format	Use identifier-based reference
"Code not in value set"	Invalid coded value	Check allowed codes

Examples and Patterns¶

Complete Patient Example¶

{
  "resourceType": "Patient",
  "id": "emma-rodriguez",
  "meta": {
    "profile": [
      "https://fhir.apps.health/StructureDefinition/polaris-core-patient"
    ]
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Emma Rodriguez</b> (Female, DOB: 1978-03-15)</p><p>PHN: 123456789</p><p>Address: 123 Maple Street, Calgary, AB T2P 1A1</p></div>"
  },
  "identifier": [
    {
      "system": "https://fhir.apps.health/NamingSystem/riverside-health-patient-identifier", 
      "value": "PAT-2024-789012",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "MR"
        }]
      }
    },
    {
      "system": "https://fhir.apps.health/alberta/NamingSystem/phn",
      "value": "123456789",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "JHN"
        }]
      }
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Rodriguez",
      "given": ["Emma", "Marie"]
    }
  ],
  "gender": "female",
  "birthDate": "1978-03-15",
  "address": [
    {
      "use": "home",
      "line": ["123 Maple Street"],
      "city": "Calgary",
      "state": "AB",
      "postalCode": "T2P 1A1",
      "country": "CA"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "403-555-0123",
      "use": "home"
    },
    {
      "system": "email",
      "value": "emma.rodriguez@email.ca",
      "use": "home"
    }
  ],
  "generalPractitioner": [
    {
      "identifier": {
        "system": "https://fhir.apps.health/NamingSystem/riverside-health-practitioner-identifier",
        "value": "PRAC-001"
      },
      "display": "Dr. Sarah Chen"
    }
  ]
}

Observation with Raw Code Example¶

{
  "resourceType": "Observation",
  "id": "blood-pressure-example",
  "meta": {
    "profile": [
      "https://fhir.apps.health/StructureDefinition/polaris-core-observation"
    ]
  },
  "text": {
    "status": "generated", 
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Blood Pressure: 132/84 mmHg (2024-03-15)</p></div>"
  },
  "identifier": [
    {
      "system": "https://fhir.apps.health/NamingSystem/riverside-health-observation-identifier",
      "value": "OBS-2024-456789"
    }
  ],
  "status": "final",
  "category": [
    {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
        "code": "vital-signs",
        "display": "Vital Signs"
      }]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "85354-9",
        "display": "Blood pressure panel"
      },
      {
        "system": "https://fhir.apps.health/NamingSystem/riverside-health-observation-codes",
        "code": "BP-READING",
        "display": "Blood Pressure Reading",
        "userSelected": true
      }
    ],
    "text": "Blood Pressure"
  },
  "subject": {
    "identifier": {
      "system": "https://fhir.apps.health/NamingSystem/riverside-health-patient-identifier",
      "value": "PAT-2024-789012"
    },
    "display": "Emma Rodriguez"
  },
  "effectiveDateTime": "2024-03-15T10:30:00-06:00",
  "performer": [
    {
      "identifier": {
        "system": "https://fhir.apps.health/NamingSystem/riverside-health-practitioner-identifier",
        "value": "PRAC-001"
      },
      "display": "Dr. Sarah Chen"
    }
  ],
  "component": [
    {
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "8480-6",
          "display": "Systolic blood pressure"
        }]
      },
      "valueQuantity": {
        "value": 132,
        "unit": "mmHg",
        "system": "http://unitsofmeasure.org",
        "code": "mm[Hg]"
      }
    },
    {
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "8462-4",
          "display": "Diastolic blood pressure"
        }]
      },
      "valueQuantity": {
        "value": 84,
        "unit": "mmHg", 
        "system": "http://unitsofmeasure.org",
        "code": "mm[Hg]"
      }
    }
  ]
}

Self-Audit Template¶

## Self-Audit

| Standard | Compliant | Notes |
|----------|-----------|-------|
| File naming convention | ✓ | PolarisResourceType-example.json |
| Outline section | ✓ | Included above JSON |
| 2-space indentation | ✓ | Consistent throughout |
| Property order | ✓ | Standard order followed |
| No comments | ✓ | Pure JSON |
| No server metadata | ✓ | No id, versionId, lastUpdated |
| Canonical URLs | ✓ | Polaris patterns used |
| Raw code preservation | ✓ | userSelected codes included |
| ISO 8601 timestamps | ✓ | With timezone |
| Identifier present | ✓ | Polaris naming system |
| Realistic data | ✓ | Primary care scenario |
| Narrative text | ✓ | Generated status with div |
| Profile declared | ✓ | In meta.profile |
| Must Support populated | ✓ | All MS elements included |
| References valid | ✓ | Identifier-based |

**All Polaris JSON coding standards have been met.**

Compliance Statement¶

All JSON examples in the Polaris FHIR Implementation Guide must comply with these standards. Non-compliant files will be rejected during code review. These standards ensure:

Consistency across all examples
Validity against profiles and FHIR specification
Clarity for implementers
Testability in automated pipelines
Maintainability over time

Document Version: 1.1.0
Effective Date: 2025-01-15
Review Cycle: Quarterly

Quick Reference Card¶

Essential Patterns¶

// Identifier
"identifier": [{
  "system": "https://fhir.apps.health/NamingSystem/[instance]-[type]-identifier",
  "value": "[identifier]"
}]

// Reference
"subject": {
  "identifier": {
    "system": "https://fhir.apps.health/NamingSystem/[instance]-patient-identifier",
    "value": "[identifier]"
  },
  "display": "[name]"
}

// Coded with raw
"code": {
  "coding": [
    {
      "system": "[standard terminology]",
      "code": "[standard code]",
      "display": "[standard display]"
    },
    {
      "system": "https://fhir.apps.health/NamingSystem/[instance]-[type]",
      "code": "[raw code]", 
      "display": "[raw display]",
      "userSelected": true
    }
  ],
  "text": "[human readable]"
}

// DateTime
"effectiveDateTime": "2024-03-15T10:30:00-06:00"

// Narrative
"text": {
  "status": "generated",
  "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">[summary]</div>"
}