App State Profile¶
| Canonical | ../StructureDefinition/nexus-emr-core-appstate |
|---|---|
| Status | active · 1.26.0 |
| Base | Basic (constraint) |
| Source | FSH · JSON |
A profile for representing external application state in Nexus EMR.
FSH
The authored source of truth: resources/StructureDefinition-nexus-emr-core-appstate.fsh (edit on GitHub). One FSH file may define several related artifacts.
// NexusEmrCoreAppState.fsh
// A resource that allows arbitrary name-value data to be associated with most FHIR resources (patient, document, organization, etc).
// Initially identified through CPAR and CII use cases, this profile addresses the general need for external applications / integrations / apps to store settings-type data in the FHIR repository.
// This profile adopts the existing HL7 standard for application state rather than inventing one:
// Persisting App State (Experimental) - SMART App Launch v2.2.0
// https://build.fhir.org/ig/HL7/smart-app-launch/app-state.html
Alias: $NexusEmrCoreAppState = ../StructureDefinition/nexus-emr-core-appstate
// Pattern for App State Code System URL
Invariant: app-state-system-inv
Description: "AppState coding.system must match Nexus EMR CodeSystem URL rules."
Severity: #error
Expression: "system.matches('../CodeSystem/[a-zA-Z0-9.-]+-app-state')"
// Profile Definition
// @intro
// Defines a profile on the Basic resource for representing external
// application state as namespaced name-value pairs in Nexus EMR.
//
// Based on smart-app-state approach.
Profile: NexusEmrCoreAppState
Parent: Basic
Id: nexus-emr-core-appstate
Title: "App State Profile"
Description: """
A profile for representing external application state in Nexus EMR.
**Some stored records do not satisfy this profile.** `code.coding.system` is constrained at error
severity to a `../CodeSystem/[app-name]-app-state` URL (invariant
`app-state-system-inv`), and records are filed today under systems that cannot match it, so a
consumer validating `Basic` resources against this profile will meet records that fail; that is
tracked as FHIR-386. This guide declares no code system for them, because an app-state namespace
is declared by the app whose state it is rather than here.
"""
// THE effective date for this profile (see the EffectiveDate / NoEffectiveDate
// RuleSets): one date concept per resource, declared here rather than guessed.
* insert EffectiveDate([[created]])
// SMART on FHIR exposure -- this resource is reachable by an app, and these are the
// permissions each operation costs (see SmartExposed + the SmartExposed RuleSet).
* insert SmartExposed(basic)
* ^url = $NexusEmrCoreAppState // Canonical URL from alias
* ^status = #active
* ^publisher = "WELLSTAR Technologies Corp."
// --- Element Constraints ---
// The value-carrier extensions defined in this file ARE the profile's payload surface:
// wired in explicitly (2026-08-06) so consumers can rely on the slice names — they were
// previously declared but never referenced by the profile.
* extension contains
AppStateStringValue named stringValue 0..* and
AppStateBooleanValue named booleanValue 0..*
* extension[stringValue] ^short = "Namespaced string state value"
* extension[booleanValue] ^short = "Namespaced boolean state value"
* . ^short = "Nexus EMR App State Core"
* . ^definition = """
Represents application state information for Nexus EMR applications, capturing key details
like state type, content, and associated resources using standard Nexus EMR references.
Uses instance-specific identifiers for tracking application state across systems.
"""
* meta.source 0..1 MS
* meta.source ^short = "Identifies EMR instance & pipeline version the resource came from"
* meta.source ^definition = "A URI that identifies the EMR pipeline and version from which this resource originated. This tells you which EMR instance (recommend using the instance identifier), and the version of the pipeline code/transformations."
* text 0..1 MS // Narrative element with human-readable summary
* text ^short = "Narrative"
* text ^definition = "A human-readable narrative summary of the NexusEmrCoreAppState resource for human interpretation."
// App State does not require an 'identifier'
// NOT Must Support, and the reason is that nothing mints one. `identifier` here is
// RECOMMENDED but not required, under no mandated system -- and since the instance-scoped
// scheme was retired (FHIR-71) no producer writes a business identifier onto this type at
// all. Must Support asserts that an implementer can be expected to populate an element;
// claiming it for one the specification neither mandates nor produces states a guarantee
// that is not being made. The element stays available and documented -- a writer with a
// source-system identifier should still carry it.
* identifier 0..1
* identifier ^short = "Business identifier for app state"
* identifier ^definition = "Optional identifier for this application state entry."
* identifier ^comment = "Most app state entries are identified by their code and subject rather than explicit identifiers."
// Code: Identifies the semantic type & namespace of the state.
* code 1..1 MS
* code ^short = "Type and namespace of application state"
* code ^definition = "Identifies what kind of application state this represents and which application namespace it belongs to."
* code ^comment = "The code acts as both a type discriminator and namespace identifier for the state data."
* code.coding 1..1 MS
* code.coding ^short = "Coded type of state"
* code.coding ^definition = "The coded representation of the application state type."
* code.coding obeys app-state-system-inv
* code.coding.system 1..1 MS
* code.coding.system ^short = "Application-specific CodeSystem URL"
* code.coding.system ^definition = "Must follow pattern: ../CodeSystem/[app-name]-app-state"
* code.coding.code 1..1 MS
* code.coding.code ^short = "Specific state type code"
* code.coding.code ^definition = "The specific type of state within the application's namespace."
* code.coding.display MS
* code.coding.display ^short = "Human-readable state type name"
* code.text MS
* code.text ^short = "Plain text description of state type"
// Subject: Links state to Patient, PractitionerRole, DocumentReference, Org, etc. SU.
* subject 1..1 SU
* subject ^short = "Resource this state is associated with"
* subject ^definition = "The FHIR resource (Patient, PractitionerRole, Organization, etc.) that this application state is associated with."
* subject ^comment = "Application state is always linked to a specific resource for context."
* subject only Reference(NexusEmrCorePatient or NexusEmrCorePractitionerRole or NexusEmrCorePractitioner or NexusEmrCoreOrganization)
* subject.reference MS
* subject.reference ^short = "Reference to the associated resource"
* subject.type MS
* subject.type ^short = "Type of resource referenced"
* subject.display MS
* subject.display ^short = "Display name of referenced resource"
// Extension: Holds the state value. Uses different extensions for each type.
* extension 1..* MS
* extension ^short = "The actual state value(s) - can have an arbitrary number of state values"
* extension ^definition = "Contains the application state values using type-specific extensions (string, boolean, etc.)."
* extension ^comment = "Different extension types support different value data types."
* extension.url 1..1 MS
* extension.url ^short = "Extension type URL"
* extension.url ^definition = "Identifies which type of value extension is being used (string, boolean, etc.)."
// @intro
// A String-valued parameter to store in a Nexus EMR application state entry.
Extension: AppStateStringValue
Parent: Extension
Id: app-state-string-value
Title: "App State String Value Extension"
Description:
"""
A simple extension to hold the value of a Nexus EMR application-state entry as a string.
"""
* ^url = "../StructureDefinition/app-state-string-value"
* ^context.type = #element
* ^context.expression = "Basic"
* valueString 1..1 MS
* valueString ^short = "String state value"
* valueString ^definition = "The application state value as a string."
* valueString ^comment = "Can contain any string data including JSON, XML, or plain text."
Extension: AppStateBooleanValue
Parent: Extension
Id: app-state-boolean-value
Title: "App State Boolean Value Extension"
Description:
"""
A simple extension to hold the value of a Nexus EMR application-state entry as a boolean.
"""
* ^url = "../StructureDefinition/app-state-boolean-value"
* ^context.type = #element
* ^context.expression = "Basic"
* valueBoolean 1..1 MS
* valueBoolean ^short = "Boolean state value"
* valueBoolean ^definition = "The application state value as a boolean (true/false)."
* valueBoolean ^comment = "Used for flags, toggles, and binary state values."