Release 5 Preview #3

2.49 Resource SubscriptionTopic - Content

FHIR Infrastructure Work GroupMaturity Level: 0 Trial UseSecurity Category: Business Compartments: Not linked to any defined compartments

Describes a stream of resource state changes identified by trigger criteria and annotated with labels useful to filter projections from this topic.

This document contains information about the SubscriptionTopic resource and details specific to options in it. See Subscriptions for general information about using Subscriptions in FHIR.

The SubscriptionTopic resource is used to define conceptual or computable events for Subscription resources. A SubscriptionTopic defines the data and change of interest, as well as allowed filters so that servers can implement specific functionality around subscriptions and clearly communicate boundaries to clients. In other words, a SubscriptionTopic is a way of describing a state change to know what is of interest. Because it describes a state change, a SubscriptionTopic is typically defined by either a resource-operation pair or value criteria tested against the previous and current states.

Subscription Topics are intended to be discoverable, reusable, and extensible. Definitions should be computably defined whenever possible, but the conceptual definition is the arbiter between any discrepancies. For example, a query-based and a FHIRPath-based definition may differ slightly because of what is expressable in each language. In such cases, the goal is correct implmentation of the concept - not literal translations between computable definitions.

A SubscriptionTopic represents a well-defined concept to both a client and a server. These concepts fall under several categories:

  • Concept Definition - e.g., Start of a Clinical Encounter, New Observation
  • Resource Operation Pairs - e.g., create on Observation resources
  • Resource Value Tests - e.g., Encounter:%previous.status!='in-progress' and %current.status='in-progress'

The SubscriptionTopic resource is used in the Subscriptions Framework. Information about the Boundaries and Relationships both within the Subscriptions Framework and to other areas of the FHIR specification can be found here.

This resource is referenced by Subscription, SubscriptionStatus and itself.

This resource implements the Definition pattern.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SubscriptionTopic TUDomainResourceDefinition Pattern
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... url Σ1..1uriLogical canonical URL to reference this SubscriptionTopic (globally unique)
... identifier Σ0..*IdentifierBusiness Identifier for SubscriptionTopic
... version Σ0..1stringBusiness version of the SubscriptionTopic
... derivedFrom Σ0..*canonical(SubscriptionTopic)Based on FHIR protocol or definition
... status ?!Σ1..1codedraft | active | retired | unknown
PublicationStatus (Required)
... experimental ?!Σ0..1booleanIf for testing purposes, not real usage
... date Σ0..1dateTimeDate status first applied
... publisher Σ0..1Reference(Practitioner | PractitionerRole | Organization)The name of the individual or organization that published the SubscriptionTopic
... contact Σ0..*ContactDetailContact details for the publisher
... description 0..1markdownNatural language description of the ToSubscriptionTopicpic
... useContext Σ0..*UsageContextContent intends to support these contexts
... jurisdiction Σ0..*CodeableConceptIntended jurisdiction for Topic (if applicable)
Jurisdiction (Extensible)
... purpose 0..1markdownWhy this SubscriptionTopic is defined
... copyright 0..1markdownUse and/or publishing restrictions
... approvalDate 0..1dateWhen SubscriptionTopic is/was approved by publisher
... lastReviewDate 0..1dateDate the Subscription Topic was last reviewed by the publisher
... effectivePeriod Σ0..1PeriodThe effective date range for the SubscriptionTopic
... resourceTrigger Σ0..*BackboneElementCriteria for including a resource update in the subscription topic
.... description Σ0..1stringText representation of the trigger
.... resourceType Σ0..1uriAllowed Data type or Resource (reference to definition) for this definition
FHIRDefinedType (Extensible)
.... methodCriteria Σ0..*codecreate | update | delete
Interaction Trigger (Required)
.... queryCriteria Σ0..1BackboneElementQuery based trigger rule
..... previous Σ0..1stringRule applied to previous resource state
..... resultForCreate Σ0..1codetest-passes | test-fails
CriteriaNotExistsBehavior (Required)
..... current Σ0..1stringRule applied to current resource state
..... resultForDelete Σ0..1codetest-passes | test-fails
CriteriaNotExistsBehavior (Required)
..... requireBoth Σ0..1booleanBoth must be true flag
.... fhirPathCriteria Σ0..*stringFHIRPath based trigger rule
.... canFilterBy Σ0..*BackboneElementProperties by which a Subscription can further filter a SubscriptionTopic
..... searchParamName Σ0..1stringSearch parameter that serves as filter key
..... searchModifier Σ0..*code= | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
Subscription Search Modifier (Required)
..... documentation Σ0..1markdownDescription of this filter parameter

doco Documentation for this format

UML Diagram (Legend)

SubscriptionTopic (DomainResource)An absolute URL that is used to identify this SubscriptionTopic when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this Topic is (or will be) published. The URL SHOULD include the major version of the Topic. For more information see [Technical and Business Versions](resource.html#versions)url : uri [1..1]Business identifiers assigned to this SubscriptionTopic by the performer and/or other systems. These identifiers remain constant as the resource is updated and propagates from server to serveridentifier : Identifier [0..*]The identifier that is used to identify this version of the SubscriptionTopic when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the Topic author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions are orderableversion : string [0..1]A short, descriptive, user-friendly title for the SubscriptionTopic, for example, "admission"title : string [0..1]The canonical URL pointing to another FHIR-defined SubscriptionTopic that is adhered to in whole or in part by this SubscriptionTopicderivedFrom : canonical [0..*] « SubscriptionTopic »The current state of the SubscriptionTopic (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of an artifact. (Strength=Required)PublicationStatus! »A flag to indicate that this TopSubscriptionTopicic is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage (this element modifies the meaning of other elements)experimental : boolean [0..1]For draft definitions, indicates the date of initial creation. For active definitions, represents the date of activation. For withdrawn definitions, indicates the date of withdrawaldate : dateTime [0..1]Helps establish the "authority/credibility" of the SubscriptionTopic. May also allow for contactpublisher : Reference [0..1] « Practitioner|PractitionerRole| Organization »Contact details to assist a user in finding and communicating with the publishercontact : ContactDetail [0..*]A free text natural language description of the Topic from the consumer's perspectivedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of code system definitionsuseContext : UsageContext [0..*]A jurisdiction in which the Topic is intended to be usedjurisdiction : CodeableConcept [0..*] « Countries and regions within which this artifact is targeted for use. (Strength=Extensible)Jurisdiction ValueSet+ »Explains why this Topic is needed and why it has been designed as it haspurpose : markdown [0..1]A copyright statement relating to the SubscriptionTopic and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the SubscriptionTopiccopyright : markdown [0..1]The date on which the asset content was approved by the publisher. Approval happens once when the content is officially approved for usageapprovalDate : date [0..1]The date on which the asset content was last reviewed. Review happens periodically after that, but doesn't change the original approval datelastReviewDate : date [0..1]The period during which the SubscriptionTopic content was or is planned to be effectiveeffectivePeriod : Period [0..1]ResourceTriggerThe human readable description of what triggers inclusion into this subscription topic - for example, "Beginning of a clinical encounter"description : string [0..1]URL of the Resource that is the type used in this trigger. Relative URLs are relative to the StructureDefinition root of the implemented FHIR version (e.g., http://hl7.org/fhir/StructureDefinition). For example, "Patient" maps to http://hl7.org/fhir/StructureDefinition/Patient. For more information, see <a href="elementdefinition-definitions.html#ElementDefinition.type.code">ElementDefinition.type.code</a>resourceType : uri [0..1] « Either a resource or a data type, including logical model types. (Strength=Extensible)FHIRDefinedType+ »The REST interaction based rules that the server should use to determine when to trigger a notification for this topicmethodCriteria : code [0..*] « FHIR RESTful interaction used for subscription topic trigger. (Strength=Required)InteractionTrigger! »The FHIRPath based rules that the server should use to determine when to trigger a notification for this topic. If there are multiple, FHIRPath filters are joined with ANDfhirPathCriteria : string [0..*]QueryCriteriaThe FHIR query based rules are applied to the previous resource stateprevious : string [0..1]What behavior a server will exhibit if the previous state of a resource does NOT exist (e.g., during a CREATE)resultForCreate : code [0..1] « Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete). (Strength=Required)CriteriaNotExistsBehavior! »The FHIR query based rules are applied to the current resource statecurrent : string [0..1]What behavior a server will exhibit if the current state of a resource does NOT exist (e.g., during a DELETE)resultForDelete : code [0..1] « Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete). (Strength=Required)CriteriaNotExistsBehavior! »If set to true, both current and previous criteria must evaluate true to trigger a notification for this topic. Otherwise a notification for this topic will be triggered if either one evaluates to truerequireBoth : boolean [0..1]CanFilterByA search parameter (like "patient") which is a label for the filtersearchParamName : string [0..1]Allowable operators to apply when determining matches (Search Modifiers)searchModifier : code [0..*] « Operator to apply to filter label. (Strength=Required)SubscriptionSearchModifier! »Description of how this filter parameter is intended to be useddocumentation : markdown [0..1]The FHIR query based rules that the server should use to determine when to trigger a notification for this subscription topicqueryCriteria[0..1]List of properties by which Subscriptions on the subscription topic can be filteredcanFilterBy[0..*]The criteria for including updates to a nominated resource in the subscription topic. Thie criteria may be just a human readable description and/or a full FHIR search string or FHIRPath expressionresourceTrigger[0..*]

XML Template

<SubscriptionTopic xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 1..1 Logical canonical URL to reference this SubscriptionTopic (globally unique) -->
 <identifier><!-- 0..* Identifier Business Identifier for SubscriptionTopic --></identifier>
 <version value="[string]"/><!-- 0..1 Business version of the SubscriptionTopic -->
 <title value="[string]"/><!-- 0..1 Name for this SubscriptionTopic (Human friendly) -->
 <derivedFrom><!-- 0..* canonical(SubscriptionTopic) Based on FHIR protocol or definition --></derivedFrom>
 <status value="[code]"/><!-- 1..1 draft | active | retired | unknown -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date status first applied -->
 <publisher><!-- 0..1 Reference(Organization|Practitioner|PractitionerRole) The name of the individual or organization that published the SubscriptionTopic --></publisher>
 <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the ToSubscriptionTopicpic -->
 <useContext><!-- 0..* UsageContext Content intends to support these contexts --></useContext>
 <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for Topic (if applicable) --></jurisdiction>
 <purpose value="[markdown]"/><!-- 0..1 Why this SubscriptionTopic is defined -->
 <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions -->
 <approvalDate value="[date]"/><!-- 0..1 When SubscriptionTopic is/was approved by publisher -->
 <lastReviewDate value="[date]"/><!-- 0..1 Date the Subscription Topic was last reviewed by the publisher -->
 <effectivePeriod><!-- 0..1 Period The effective date range for the SubscriptionTopic --></effectivePeriod>
 <resourceTrigger>  <!-- 0..* Criteria for including a resource update in the subscription topic -->
  <description value="[string]"/><!-- 0..1 Text representation of the trigger -->
  <resourceType value="[uri]"/><!-- 0..1 Allowed Data type or Resource (reference to definition) for this definition -->
  <methodCriteria value="[code]"/><!-- 0..* create | update | delete -->
  <queryCriteria>  <!-- 0..1 Query based trigger rule -->
   <previous value="[string]"/><!-- 0..1 Rule applied to previous resource state -->
   <resultForCreate value="[code]"/><!-- 0..1 test-passes | test-fails -->
   <current value="[string]"/><!-- 0..1 Rule applied to current resource state -->
   <resultForDelete value="[code]"/><!-- 0..1 test-passes | test-fails -->
   <requireBoth value="[boolean]"/><!-- 0..1 Both must be true flag -->
  </queryCriteria>
  <fhirPathCriteria value="[string]"/><!-- 0..* FHIRPath based trigger rule -->
  <canFilterBy>  <!-- 0..* Properties by which a Subscription can further filter a SubscriptionTopic -->
   <searchParamName value="[string]"/><!-- 0..1 Search parameter that serves as filter key -->
   <searchModifier value="[code]"/><!-- 0..* = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type -->
   <documentation value="[markdown]"/><!-- 0..1 Description of this filter parameter -->
  </canFilterBy>
 </resourceTrigger>
</SubscriptionTopic>

JSON Template

{doco
  "resourceType" : "SubscriptionTopic",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // R!  Logical canonical URL to reference this SubscriptionTopic (globally unique)
  "identifier" : [{ Identifier }], // Business Identifier for SubscriptionTopic
  "version" : "<string>", // Business version of the SubscriptionTopic
  "title" : "<string>", // Name for this SubscriptionTopic (Human friendly)
  "derivedFrom" : [{ canonical(SubscriptionTopic) }], // Based on FHIR protocol or definition
  "status" : "<code>", // R!  draft | active | retired | unknown
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Date status first applied
  "publisher" : { Reference(Organization|Practitioner|PractitionerRole) }, // The name of the individual or organization that published the SubscriptionTopic
  "contact" : [{ ContactDetail }], // Contact details for the publisher
  "description" : "<markdown>", // Natural language description of the ToSubscriptionTopicpic
  "useContext" : [{ UsageContext }], // Content intends to support these contexts
  "jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for Topic (if applicable)
  "purpose" : "<markdown>", // Why this SubscriptionTopic is defined
  "copyright" : "<markdown>", // Use and/or publishing restrictions
  "approvalDate" : "<date>", // When SubscriptionTopic is/was approved by publisher
  "lastReviewDate" : "<date>", // Date the Subscription Topic was last reviewed by the publisher
  "effectivePeriod" : { Period }, // The effective date range for the SubscriptionTopic
  "resourceTrigger" : [{ // Criteria for including a resource update in the subscription topic
    "description" : "<string>", // Text representation of the trigger
    "resourceType" : "<uri>", // Allowed Data type or Resource (reference to definition) for this definition
    "methodCriteria" : ["<code>"], // create | update | delete
    "queryCriteria" : { // Query based trigger rule
      "previous" : "<string>", // Rule applied to previous resource state
      "resultForCreate" : "<code>", // test-passes | test-fails
      "current" : "<string>", // Rule applied to current resource state
      "resultForDelete" : "<code>", // test-passes | test-fails
      "requireBoth" : <boolean> // Both must be true flag
    },
    "fhirPathCriteria" : ["<string>"], // FHIRPath based trigger rule
    "canFilterBy" : [{ // Properties by which a Subscription can further filter a SubscriptionTopic
      "searchParamName" : "<string>", // Search parameter that serves as filter key
      "searchModifier" : ["<code>"], // = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
      "documentation" : "<markdown>" // Description of this filter parameter
    }]
  }]
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:SubscriptionTopic;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:SubscriptionTopic.url [ uri ]; # 1..1 Logical canonical URL to reference this SubscriptionTopic (globally unique)
  fhir:SubscriptionTopic.identifier [ Identifier ], ... ; # 0..* Business Identifier for SubscriptionTopic
  fhir:SubscriptionTopic.version [ string ]; # 0..1 Business version of the SubscriptionTopic
  fhir:SubscriptionTopic.title [ string ]; # 0..1 Name for this SubscriptionTopic (Human friendly)
  fhir:SubscriptionTopic.derivedFrom [ canonical(SubscriptionTopic) ], ... ; # 0..* Based on FHIR protocol or definition
  fhir:SubscriptionTopic.status [ code ]; # 1..1 draft | active | retired | unknown
  fhir:SubscriptionTopic.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage
  fhir:SubscriptionTopic.date [ dateTime ]; # 0..1 Date status first applied
  fhir:SubscriptionTopic.publisher [ Reference(Organization|Practitioner|PractitionerRole) ]; # 0..1 The name of the individual or organization that published the SubscriptionTopic
  fhir:SubscriptionTopic.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher
  fhir:SubscriptionTopic.description [ markdown ]; # 0..1 Natural language description of the ToSubscriptionTopicpic
  fhir:SubscriptionTopic.useContext [ UsageContext ], ... ; # 0..* Content intends to support these contexts
  fhir:SubscriptionTopic.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for Topic (if applicable)
  fhir:SubscriptionTopic.purpose [ markdown ]; # 0..1 Why this SubscriptionTopic is defined
  fhir:SubscriptionTopic.copyright [ markdown ]; # 0..1 Use and/or publishing restrictions
  fhir:SubscriptionTopic.approvalDate [ date ]; # 0..1 When SubscriptionTopic is/was approved by publisher
  fhir:SubscriptionTopic.lastReviewDate [ date ]; # 0..1 Date the Subscription Topic was last reviewed by the publisher
  fhir:SubscriptionTopic.effectivePeriod [ Period ]; # 0..1 The effective date range for the SubscriptionTopic
  fhir:SubscriptionTopic.resourceTrigger [ # 0..* Criteria for including a resource update in the subscription topic
    fhir:SubscriptionTopic.resourceTrigger.description [ string ]; # 0..1 Text representation of the trigger
    fhir:SubscriptionTopic.resourceTrigger.resourceType [ uri ]; # 0..1 Allowed Data type or Resource (reference to definition) for this definition
    fhir:SubscriptionTopic.resourceTrigger.methodCriteria [ code ], ... ; # 0..* create | update | delete
    fhir:SubscriptionTopic.resourceTrigger.queryCriteria [ # 0..1 Query based trigger rule
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.previous [ string ]; # 0..1 Rule applied to previous resource state
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.resultForCreate [ code ]; # 0..1 test-passes | test-fails
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.current [ string ]; # 0..1 Rule applied to current resource state
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.resultForDelete [ code ]; # 0..1 test-passes | test-fails
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.requireBoth [ boolean ]; # 0..1 Both must be true flag
    ];
    fhir:SubscriptionTopic.resourceTrigger.fhirPathCriteria [ string ], ... ; # 0..* FHIRPath based trigger rule
    fhir:SubscriptionTopic.resourceTrigger.canFilterBy [ # 0..* Properties by which a Subscription can further filter a SubscriptionTopic
      fhir:SubscriptionTopic.resourceTrigger.canFilterBy.searchParamName [ string ]; # 0..1 Search parameter that serves as filter key
      fhir:SubscriptionTopic.resourceTrigger.canFilterBy.searchModifier [ code ], ... ; # 0..* = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
      fhir:SubscriptionTopic.resourceTrigger.canFilterBy.documentation [ markdown ]; # 0..1 Description of this filter parameter
    ], ...;
  ], ...;
]

Changes since R3

This resource did not exist in Release 2

This analysis is available as XML or JSON.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SubscriptionTopic TUDomainResourceDefinition Pattern
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... url Σ1..1uriLogical canonical URL to reference this SubscriptionTopic (globally unique)
... identifier Σ0..*IdentifierBusiness Identifier for SubscriptionTopic
... version Σ0..1stringBusiness version of the SubscriptionTopic
... derivedFrom Σ0..*canonical(SubscriptionTopic)Based on FHIR protocol or definition
... status ?!Σ1..1codedraft | active | retired | unknown
PublicationStatus (Required)
... experimental ?!Σ0..1booleanIf for testing purposes, not real usage
... date Σ0..1dateTimeDate status first applied
... publisher Σ0..1Reference(Practitioner | PractitionerRole | Organization)The name of the individual or organization that published the SubscriptionTopic
... contact Σ0..*ContactDetailContact details for the publisher
... description 0..1markdownNatural language description of the ToSubscriptionTopicpic
... useContext Σ0..*UsageContextContent intends to support these contexts
... jurisdiction Σ0..*CodeableConceptIntended jurisdiction for Topic (if applicable)
Jurisdiction (Extensible)
... purpose 0..1markdownWhy this SubscriptionTopic is defined
... copyright 0..1markdownUse and/or publishing restrictions
... approvalDate 0..1dateWhen SubscriptionTopic is/was approved by publisher
... lastReviewDate 0..1dateDate the Subscription Topic was last reviewed by the publisher
... effectivePeriod Σ0..1PeriodThe effective date range for the SubscriptionTopic
... resourceTrigger Σ0..*BackboneElementCriteria for including a resource update in the subscription topic
.... description Σ0..1stringText representation of the trigger
.... resourceType Σ0..1uriAllowed Data type or Resource (reference to definition) for this definition
FHIRDefinedType (Extensible)
.... methodCriteria Σ0..*codecreate | update | delete
Interaction Trigger (Required)
.... queryCriteria Σ0..1BackboneElementQuery based trigger rule
..... previous Σ0..1stringRule applied to previous resource state
..... resultForCreate Σ0..1codetest-passes | test-fails
CriteriaNotExistsBehavior (Required)
..... current Σ0..1stringRule applied to current resource state
..... resultForDelete Σ0..1codetest-passes | test-fails
CriteriaNotExistsBehavior (Required)
..... requireBoth Σ0..1booleanBoth must be true flag
.... fhirPathCriteria Σ0..*stringFHIRPath based trigger rule
.... canFilterBy Σ0..*BackboneElementProperties by which a Subscription can further filter a SubscriptionTopic
..... searchParamName Σ0..1stringSearch parameter that serves as filter key
..... searchModifier Σ0..*code= | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
Subscription Search Modifier (Required)
..... documentation Σ0..1markdownDescription of this filter parameter

doco Documentation for this format

UML Diagram (Legend)

SubscriptionTopic (DomainResource)An absolute URL that is used to identify this SubscriptionTopic when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this Topic is (or will be) published. The URL SHOULD include the major version of the Topic. For more information see [Technical and Business Versions](resource.html#versions)url : uri [1..1]Business identifiers assigned to this SubscriptionTopic by the performer and/or other systems. These identifiers remain constant as the resource is updated and propagates from server to serveridentifier : Identifier [0..*]The identifier that is used to identify this version of the SubscriptionTopic when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the Topic author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions are orderableversion : string [0..1]A short, descriptive, user-friendly title for the SubscriptionTopic, for example, "admission"title : string [0..1]The canonical URL pointing to another FHIR-defined SubscriptionTopic that is adhered to in whole or in part by this SubscriptionTopicderivedFrom : canonical [0..*] « SubscriptionTopic »The current state of the SubscriptionTopic (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of an artifact. (Strength=Required)PublicationStatus! »A flag to indicate that this TopSubscriptionTopicic is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage (this element modifies the meaning of other elements)experimental : boolean [0..1]For draft definitions, indicates the date of initial creation. For active definitions, represents the date of activation. For withdrawn definitions, indicates the date of withdrawaldate : dateTime [0..1]Helps establish the "authority/credibility" of the SubscriptionTopic. May also allow for contactpublisher : Reference [0..1] « Practitioner|PractitionerRole| Organization »Contact details to assist a user in finding and communicating with the publishercontact : ContactDetail [0..*]A free text natural language description of the Topic from the consumer's perspectivedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of code system definitionsuseContext : UsageContext [0..*]A jurisdiction in which the Topic is intended to be usedjurisdiction : CodeableConcept [0..*] « Countries and regions within which this artifact is targeted for use. (Strength=Extensible)Jurisdiction ValueSet+ »Explains why this Topic is needed and why it has been designed as it haspurpose : markdown [0..1]A copyright statement relating to the SubscriptionTopic and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the SubscriptionTopiccopyright : markdown [0..1]The date on which the asset content was approved by the publisher. Approval happens once when the content is officially approved for usageapprovalDate : date [0..1]The date on which the asset content was last reviewed. Review happens periodically after that, but doesn't change the original approval datelastReviewDate : date [0..1]The period during which the SubscriptionTopic content was or is planned to be effectiveeffectivePeriod : Period [0..1]ResourceTriggerThe human readable description of what triggers inclusion into this subscription topic - for example, "Beginning of a clinical encounter"description : string [0..1]URL of the Resource that is the type used in this trigger. Relative URLs are relative to the StructureDefinition root of the implemented FHIR version (e.g., http://hl7.org/fhir/StructureDefinition). For example, "Patient" maps to http://hl7.org/fhir/StructureDefinition/Patient. For more information, see <a href="elementdefinition-definitions.html#ElementDefinition.type.code">ElementDefinition.type.code</a>resourceType : uri [0..1] « Either a resource or a data type, including logical model types. (Strength=Extensible)FHIRDefinedType+ »The REST interaction based rules that the server should use to determine when to trigger a notification for this topicmethodCriteria : code [0..*] « FHIR RESTful interaction used for subscription topic trigger. (Strength=Required)InteractionTrigger! »The FHIRPath based rules that the server should use to determine when to trigger a notification for this topic. If there are multiple, FHIRPath filters are joined with ANDfhirPathCriteria : string [0..*]QueryCriteriaThe FHIR query based rules are applied to the previous resource stateprevious : string [0..1]What behavior a server will exhibit if the previous state of a resource does NOT exist (e.g., during a CREATE)resultForCreate : code [0..1] « Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete). (Strength=Required)CriteriaNotExistsBehavior! »The FHIR query based rules are applied to the current resource statecurrent : string [0..1]What behavior a server will exhibit if the current state of a resource does NOT exist (e.g., during a DELETE)resultForDelete : code [0..1] « Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete). (Strength=Required)CriteriaNotExistsBehavior! »If set to true, both current and previous criteria must evaluate true to trigger a notification for this topic. Otherwise a notification for this topic will be triggered if either one evaluates to truerequireBoth : boolean [0..1]CanFilterByA search parameter (like "patient") which is a label for the filtersearchParamName : string [0..1]Allowable operators to apply when determining matches (Search Modifiers)searchModifier : code [0..*] « Operator to apply to filter label. (Strength=Required)SubscriptionSearchModifier! »Description of how this filter parameter is intended to be useddocumentation : markdown [0..1]The FHIR query based rules that the server should use to determine when to trigger a notification for this subscription topicqueryCriteria[0..1]List of properties by which Subscriptions on the subscription topic can be filteredcanFilterBy[0..*]The criteria for including updates to a nominated resource in the subscription topic. Thie criteria may be just a human readable description and/or a full FHIR search string or FHIRPath expressionresourceTrigger[0..*]

XML Template

<SubscriptionTopic xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 1..1 Logical canonical URL to reference this SubscriptionTopic (globally unique) -->
 <identifier><!-- 0..* Identifier Business Identifier for SubscriptionTopic --></identifier>
 <version value="[string]"/><!-- 0..1 Business version of the SubscriptionTopic -->
 <title value="[string]"/><!-- 0..1 Name for this SubscriptionTopic (Human friendly) -->
 <derivedFrom><!-- 0..* canonical(SubscriptionTopic) Based on FHIR protocol or definition --></derivedFrom>
 <status value="[code]"/><!-- 1..1 draft | active | retired | unknown -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date status first applied -->
 <publisher><!-- 0..1 Reference(Organization|Practitioner|PractitionerRole) The name of the individual or organization that published the SubscriptionTopic --></publisher>
 <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the ToSubscriptionTopicpic -->
 <useContext><!-- 0..* UsageContext Content intends to support these contexts --></useContext>
 <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for Topic (if applicable) --></jurisdiction>
 <purpose value="[markdown]"/><!-- 0..1 Why this SubscriptionTopic is defined -->
 <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions -->
 <approvalDate value="[date]"/><!-- 0..1 When SubscriptionTopic is/was approved by publisher -->
 <lastReviewDate value="[date]"/><!-- 0..1 Date the Subscription Topic was last reviewed by the publisher -->
 <effectivePeriod><!-- 0..1 Period The effective date range for the SubscriptionTopic --></effectivePeriod>
 <resourceTrigger>  <!-- 0..* Criteria for including a resource update in the subscription topic -->
  <description value="[string]"/><!-- 0..1 Text representation of the trigger -->
  <resourceType value="[uri]"/><!-- 0..1 Allowed Data type or Resource (reference to definition) for this definition -->
  <methodCriteria value="[code]"/><!-- 0..* create | update | delete -->
  <queryCriteria>  <!-- 0..1 Query based trigger rule -->
   <previous value="[string]"/><!-- 0..1 Rule applied to previous resource state -->
   <resultForCreate value="[code]"/><!-- 0..1 test-passes | test-fails -->
   <current value="[string]"/><!-- 0..1 Rule applied to current resource state -->
   <resultForDelete value="[code]"/><!-- 0..1 test-passes | test-fails -->
   <requireBoth value="[boolean]"/><!-- 0..1 Both must be true flag -->
  </queryCriteria>
  <fhirPathCriteria value="[string]"/><!-- 0..* FHIRPath based trigger rule -->
  <canFilterBy>  <!-- 0..* Properties by which a Subscription can further filter a SubscriptionTopic -->
   <searchParamName value="[string]"/><!-- 0..1 Search parameter that serves as filter key -->
   <searchModifier value="[code]"/><!-- 0..* = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type -->
   <documentation value="[markdown]"/><!-- 0..1 Description of this filter parameter -->
  </canFilterBy>
 </resourceTrigger>
</SubscriptionTopic>

JSON Template

{doco
  "resourceType" : "SubscriptionTopic",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // R!  Logical canonical URL to reference this SubscriptionTopic (globally unique)
  "identifier" : [{ Identifier }], // Business Identifier for SubscriptionTopic
  "version" : "<string>", // Business version of the SubscriptionTopic
  "title" : "<string>", // Name for this SubscriptionTopic (Human friendly)
  "derivedFrom" : [{ canonical(SubscriptionTopic) }], // Based on FHIR protocol or definition
  "status" : "<code>", // R!  draft | active | retired | unknown
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Date status first applied
  "publisher" : { Reference(Organization|Practitioner|PractitionerRole) }, // The name of the individual or organization that published the SubscriptionTopic
  "contact" : [{ ContactDetail }], // Contact details for the publisher
  "description" : "<markdown>", // Natural language description of the ToSubscriptionTopicpic
  "useContext" : [{ UsageContext }], // Content intends to support these contexts
  "jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for Topic (if applicable)
  "purpose" : "<markdown>", // Why this SubscriptionTopic is defined
  "copyright" : "<markdown>", // Use and/or publishing restrictions
  "approvalDate" : "<date>", // When SubscriptionTopic is/was approved by publisher
  "lastReviewDate" : "<date>", // Date the Subscription Topic was last reviewed by the publisher
  "effectivePeriod" : { Period }, // The effective date range for the SubscriptionTopic
  "resourceTrigger" : [{ // Criteria for including a resource update in the subscription topic
    "description" : "<string>", // Text representation of the trigger
    "resourceType" : "<uri>", // Allowed Data type or Resource (reference to definition) for this definition
    "methodCriteria" : ["<code>"], // create | update | delete
    "queryCriteria" : { // Query based trigger rule
      "previous" : "<string>", // Rule applied to previous resource state
      "resultForCreate" : "<code>", // test-passes | test-fails
      "current" : "<string>", // Rule applied to current resource state
      "resultForDelete" : "<code>", // test-passes | test-fails
      "requireBoth" : <boolean> // Both must be true flag
    },
    "fhirPathCriteria" : ["<string>"], // FHIRPath based trigger rule
    "canFilterBy" : [{ // Properties by which a Subscription can further filter a SubscriptionTopic
      "searchParamName" : "<string>", // Search parameter that serves as filter key
      "searchModifier" : ["<code>"], // = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
      "documentation" : "<markdown>" // Description of this filter parameter
    }]
  }]
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:SubscriptionTopic;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:SubscriptionTopic.url [ uri ]; # 1..1 Logical canonical URL to reference this SubscriptionTopic (globally unique)
  fhir:SubscriptionTopic.identifier [ Identifier ], ... ; # 0..* Business Identifier for SubscriptionTopic
  fhir:SubscriptionTopic.version [ string ]; # 0..1 Business version of the SubscriptionTopic
  fhir:SubscriptionTopic.title [ string ]; # 0..1 Name for this SubscriptionTopic (Human friendly)
  fhir:SubscriptionTopic.derivedFrom [ canonical(SubscriptionTopic) ], ... ; # 0..* Based on FHIR protocol or definition
  fhir:SubscriptionTopic.status [ code ]; # 1..1 draft | active | retired | unknown
  fhir:SubscriptionTopic.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage
  fhir:SubscriptionTopic.date [ dateTime ]; # 0..1 Date status first applied
  fhir:SubscriptionTopic.publisher [ Reference(Organization|Practitioner|PractitionerRole) ]; # 0..1 The name of the individual or organization that published the SubscriptionTopic
  fhir:SubscriptionTopic.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher
  fhir:SubscriptionTopic.description [ markdown ]; # 0..1 Natural language description of the ToSubscriptionTopicpic
  fhir:SubscriptionTopic.useContext [ UsageContext ], ... ; # 0..* Content intends to support these contexts
  fhir:SubscriptionTopic.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for Topic (if applicable)
  fhir:SubscriptionTopic.purpose [ markdown ]; # 0..1 Why this SubscriptionTopic is defined
  fhir:SubscriptionTopic.copyright [ markdown ]; # 0..1 Use and/or publishing restrictions
  fhir:SubscriptionTopic.approvalDate [ date ]; # 0..1 When SubscriptionTopic is/was approved by publisher
  fhir:SubscriptionTopic.lastReviewDate [ date ]; # 0..1 Date the Subscription Topic was last reviewed by the publisher
  fhir:SubscriptionTopic.effectivePeriod [ Period ]; # 0..1 The effective date range for the SubscriptionTopic
  fhir:SubscriptionTopic.resourceTrigger [ # 0..* Criteria for including a resource update in the subscription topic
    fhir:SubscriptionTopic.resourceTrigger.description [ string ]; # 0..1 Text representation of the trigger
    fhir:SubscriptionTopic.resourceTrigger.resourceType [ uri ]; # 0..1 Allowed Data type or Resource (reference to definition) for this definition
    fhir:SubscriptionTopic.resourceTrigger.methodCriteria [ code ], ... ; # 0..* create | update | delete
    fhir:SubscriptionTopic.resourceTrigger.queryCriteria [ # 0..1 Query based trigger rule
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.previous [ string ]; # 0..1 Rule applied to previous resource state
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.resultForCreate [ code ]; # 0..1 test-passes | test-fails
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.current [ string ]; # 0..1 Rule applied to current resource state
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.resultForDelete [ code ]; # 0..1 test-passes | test-fails
      fhir:SubscriptionTopic.resourceTrigger.queryCriteria.requireBoth [ boolean ]; # 0..1 Both must be true flag
    ];
    fhir:SubscriptionTopic.resourceTrigger.fhirPathCriteria [ string ], ... ; # 0..* FHIRPath based trigger rule
    fhir:SubscriptionTopic.resourceTrigger.canFilterBy [ # 0..* Properties by which a Subscription can further filter a SubscriptionTopic
      fhir:SubscriptionTopic.resourceTrigger.canFilterBy.searchParamName [ string ]; # 0..1 Search parameter that serves as filter key
      fhir:SubscriptionTopic.resourceTrigger.canFilterBy.searchModifier [ code ], ... ; # 0..* = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
      fhir:SubscriptionTopic.resourceTrigger.canFilterBy.documentation [ markdown ]; # 0..1 Description of this filter parameter
    ], ...;
  ], ...;
]

Changes since Release 3

This resource did not exist in Release 2

This analysis is available as XML or JSON.

 

See the Profiles & Extensions and the alternate definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions, the spreadsheet version & the dependency analysis a

PathDefinitionTypeReference
SubscriptionTopic.status The lifecycle status of an artifact.RequiredPublicationStatus
SubscriptionTopic.jurisdiction Countries and regions within which this artifact is targeted for use.ExtensibleJurisdiction ValueSet
SubscriptionTopic.resourceTrigger.resourceType Either a resource or a data type, including logical model types.ExtensibleFHIRDefinedType
SubscriptionTopic.resourceTrigger.methodCriteria FHIR RESTful interaction used for subscription topic trigger.RequiredInteractionTrigger
SubscriptionTopic.resourceTrigger.queryCriteria.resultForCreate
SubscriptionTopic.resourceTrigger.queryCriteria.resultForDelete
Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete).RequiredCriteriaNotExistsBehavior
SubscriptionTopic.resourceTrigger.canFilterBy.searchModifier Operator to apply to filter label.RequiredSubscriptionSearchModifier

Each server is responsible for accurately implementing each SubscriptionTopic it advertises support for. Due to the breadth of possible topics, detailed implementation guidance cannot be provided here. Following are a few topics to consider when implementing a Subscription Topic within a server:

Defining a new SubscriptionTopic requires clear communication to implementers of both clients and servers around requirements and expectations. Anyone defining a SubscriptionTopic is encouraged to publish their definition at registry.fhir.org . Below are some areas which should be considered when creating a SubscriptionTopic.

Definitions for Subscription Topics fall into three categories, which are described in more detail below. Good definitions will have useful definitions for two parts (conceptual and one of the other two), but the server implementation should always prioritize accurately representing the concept definition.

Subscription Topics MUST always document the concept it represents. While a short definition is included in the SubscriptionTopic itself, this documentation will typically not be sufficient for implementers. Definitions must be clear and specific. For example, if the goal is to define an 'admission' topic, the single word is common enough to feel sufficient - implementers generally know what an 'admission' is and could implement something that would qualify. However, is the intention to represent a patient being physically admitted to a care facility, or the start of a clinical encounter? Either definition is common, and without more information implementations will not be consistent. Without complete and specific definitions, server implementions will vary and clients will have unexpected behavior.

Subscription Topics based on Resource Operation Pairs are the simplest to describe - definitions include the resource type (e.g., Patient, Encounter) and the operation of interest (e.g., create, delete).

Subscription Topics for resource-operation pairs are defined using the SubscriptionTopic.resourceTrigger.resourceType and SubscriptionTopic.resourceTrigger.methodCriteria fields.

Subscription Topics defined around resource create operations are triggered each time a resource of the specified type is created.

Filters for create operations are restricted to the type of resource being created and must be evaluated on the created resource instance. If more complicated filtering is required (e.g., new Observations when a Patient has a given diagnosis), implementers should use the computable definitions provided by Resource Value Tests.

  • Example using 'create' operation

Subscription Topics defined around resource delete operations are triggered each time a resource of the specified type is deleted.

Filters for delete operations are restricted to the type of resource being deleted and must be evaluated on the resource instance being deleted. If more complicated filtering is required (e.g., deleting a Patient which has a particular Observation), implementers should use the computable definitions provided by Resource Value Tests.

  • Example using 'delete' operation

Subscription Topics defined around resource update operations are triggered each time the server updates a resource of the specified type. Triggering an update operation does not imply that the resource has changes visible to the subscriber, nor does it require servers to monitor resources for actual changes. Servers MAY generate notifications on their internal triggers, regardless of actual changes (e.g., a client issuing an HTTP PUT with an identical resource).

Filters for update operations are restricted to the type of resource being updated and must be evaluated on the resource instance after the update is performed (e.g., post-state change). If more complicated filtering is required (e.g., detecting when an Encounter leaves the 'in-progress' state), implementers should use the computable definitions provided by Resource Value Tests.

  • Example using 'update' operation

If a topic requires more granularity than operations provide, a topic can provide either FHIRPath or query (Search) definitions to test against state changes.

Computable Definitions serve two purposes when defining topics. First, some server implementers may be able to use computable definitions directly (or with minimal changes). In this scenario, the benifit of a computable definition is quite large (e.g., user-defined SubscriptionTopics, high portability, etc.). Second, implementers that do not use computable definitions internally will be able to read definitions during their implementation in order to precisley understand what is being defined.

Query definitions are based on Search evaluations performed before and/or after a state change in the server. Allowed query parameters are based on the SubscriptionTopic.resourceTrigger.resourceType (e.g., if the resource is an Encounter, the list of available search parameters can be found here).

FHIRPath expressions can be used to define topical state changes in a server. Each FHIRPath expression is assumed to be provided the inputs listed below. If multiple FHIRPath expressions are present in SubscriptionTopic.resourceTrigger.fhirPathCriteria, they are joined together by AND clauses.

FHIRPath expression input variables:

  • Variable [previous] = resource instance prior to state change being applied
  • Variable [current] - resource instance post state change being applied

In order to reduce the complexity of evaluating Subscription requests at runtime, topics define what filters clients are allowed to request. These filters are applied in servers to filter possible events into events that a particular client is interested in (e.g., from a topic defining all all admissions to a subscription for admissions on patients within a care team).

The element SubscriptionTopic.canFilterBy.searchParamName contains the name of the search parameter used to filter events for the focus resource (defined by SubscriptionTopic.resourceTrigger.resourceType). The search parameter must be either from the list of Parameters for all resources (e.g., _id, _tag) or the parameters defined by the specific resource (e.g., Encounter Search Parameters, Patient search parameters, etc.).

If a search parameter name is not provided, it is defaulted to _id.

The element SubscriptionTopic.canFilterBy.searchModifier contains the search modifier used when evaluating a change. Allowed search parameters are pulled from Search, with the addition of = to show simple equality (e.g., no modifier). Note that modifiers are only valid for specific types of data (e.g., a modifer of sa (starts after) has no meaning when applied to a string).

If a search modifier is not provided, it is defaulted to = (no modifer).

When to evaluate filters depends on the type of change covered by the topic.

Filters for create operations must be applied after the resource has been created. For example, a topic interested in new patients may allow filters on elements within the patient resource (e.g., new patients in a specified age range).

Filters for delete operations must be applied before the resource has been deleted. For example, a topic interested in practitioners being removed may allow filters on the practitioner resource (e.g., removed practitioners with a specific qualification).

Filters for update operations can be applied to either the pre-update or post-update state. Servers SHOULD document their method of operation.

Implementers are encouraged to add additional filters, but cannot remove existing ones nor change the 'concept' of a SubscriptionTopic during derivation. For example:

  • Deriving a new SubscriptionTopic with the same concept but a different computable definition is OK.
  • Deriving a new SubscriptionTopic to expose additional canFilterBy parameters is OK.
  • Deriving a new SubscriptionTopic to remove an existing canFilterBy parameter is NOT ok.
  • Deriving a new SubscriptionTopic based on a different resource than its parent is NOT ok (e.g., start/end of medication derived from encounter).

Trial-Use Note: Warning: This section is still in early drafting.

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

NameTypeDescriptionExpressionIn Common
date NdateDate status first appliedSubscriptionTopic.date
derived-or-self NuriA server defined search that matches either the url or derivedFromSubscriptionTopic.url | SubscriptionTopic.derivedFrom
identifiertokenBusiness Identifier for SubscriptionTopicSubscriptionTopic.identifier
publisherreferenceThe name of the individual or organization that published the SubscriptionTopicSubscriptionTopic.publisher
(Practitioner, Organization, PractitionerRole)
resource-type NuriAllowed Data type or Resource (reference to definition) for this definitionSubscriptionTopic.resourceTrigger.resourceType
status Ntokendraft | active | retired | unknownSubscriptionTopic.status
title NstringName for this SubscriptionTopic (Human friendly)SubscriptionTopic.title
trigger-description NstringText representation of the triggerSubscriptionTopic.resourceTrigger.description
url NuriLogical canonical URL to reference this SubscriptionTopic (globally unique)SubscriptionTopic.url
version NtokenBusiness version of the SubscriptionTopicSubscriptionTopic.version