Release 5 Ballot

This page is part of the FHIR Specification (v5.0.0-ballot: FHIR R5 Ballot Preview). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3

8.9 Resource Endpoint - Content

Patient Administration Work GroupMaturity Level: 2 Trial UseSecurity Category: Business Compartments: Not linked to any defined compartments

The technical details of an endpoint that can be used for electronic services, such as for web services providing XDS.b, a REST endpoint for another FHIR server, or a s/Mime email address. This may include any security context information.

8.9.1 Scope and Usage

An endpoint describes the technical details of a location that can be connected to for the delivery/retrieval of information. Sufficient information is required to ensure that a connection can be made securely, and appropriate data transmitted as defined by the endpoint owner. This is not a description of details of the current system, as found in CapabilityStatement, but of another (potentially external) system.
These may be locally hosted services, regional services, or national service.

These resources are typically used to identify where to locate endpoint details for:

  • Questionnaires: Where to send information (currently an SDC extension with just the address)
  • ValueSet: Where related Terminology Services can be found (where not local)
  • Subscription: The destination to send the subscribed data (or to pull)
  • Messaging: (currently defined in the Message Header, but only as the address)
  • Referrals: Where to send referral requests
    (linked to the services directory resources - Organization/Location/Practitioner/HealthcareService)
  • Referrals - Templates: Where to locate referral templates (Questionnaires)
    (linked to the services directory resources - Organization/Location/Practitioner/HealthcareService)
  • CarePlans: Where a shared CarePlan can be found
  • Scheduling: Where to lookup to discover schedules/availability information
    (linked to the services directory resources - Organization/Location/Practitioner/HealthcareService)
  • Scheduling: Where to lookup to send appointment requests
    (linked to the services directory resources - Organization/Location/Practitioner/HealthcareService)
  • Patient/Person: Location of Master Patient/Person Indexes
  • Service Provider Directories: Location of related directories (parent/child/federated)
  • DICOM/imaging: Location of where to query, retrieve or store imaging content and metadata (QIDO-RS, WADO-RS, WADO-URI, STOW-RS)

8.9.2 Boundaries and Relationships

8.9.2.1 CapabilityStatement

The endpoint is distinct from a capability statement in that the CapabilityStatement statement describes the entire capability of a system (and in the metadata case, just this system)
Where the endpoint resource describes the technical details for how to connect, and for what purposes (which could be a small sub-set of the system's capabilities, and might not be a FHIR endpoint).

8.9.2.2 ContactPoint

Endpoints are used to facilitate system to system communication, providing the details of the addressing of the system, purpose of use, protocols required/provided, and any other details required to communicate between the systems. (such as configuration parameters, require headers ...) The address value in the endpoint can only be used in the context of the provided details.

E.g. If the endpoint has a URL for an XDS service, using that in a browser by a user is meaningless.

E.g.2 If the endpoint has a US Direct address, using this to send a normal email message will not work, as they are not true email addresses (even though they appear to be)

A ContactPoint contains contact information, such as a phone number, web address that a user can directly interact with, no additional information would be required to use the value. The value is generally used to communicate with an entity directly, not a system.

8.9.3 Background and Context

8.9.3.1 Expected Implementations

  • Any solution where there are distributed FHIR servers deployed and need discovery/configuration
  • Systems advertising connectivity information in a DICOM environment
  • (Refer to the scope and usage section for common uses)

8.9.4 References to this Resource

8.9.5 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Endpoint TUDomainResourceThe technical details of an endpoint that can be used for electronic services

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... identifier Σ0..*IdentifierIdentifies this endpoint across multiple systems

... status ?!Σ1..1codeactive | suspended | error | off | entered-in-error | test
EndpointStatus (Required)
... connectionType Σ1..*CodeableConceptProtocol/Profile/Standard to be used with this endpoint connection
Endpoint Connection Type (Example)

... description Σ0..1stringAdditional details about the endpoint that could be displayed as further information to identify the description beyond its name
... environmentType Σ0..*CodeableConceptThe type of environment(s) exposed at this endpoint
EndpointEnvironment (Extensible)

... managingOrganization Σ0..1Reference(Organization)Organization that manages this endpoint (might not be the organization that exposes the endpoint)
... contact 0..*ContactPointContact details for source (e.g. troubleshooting)

... period Σ0..1PeriodInterval the endpoint is expected to be operational
... payloadType Σ0..*CodeableConceptThe type of content that may be used at this endpoint (e.g. XDS Discharge summaries)
Endpoint Payload Type (Example)

... payloadMimeType Σ0..*codeMimetype to send. If not specified, the content could be anything (including no payload, if the connectionType defined this)
MimeType (Required)

... address Σ1..1urlThe technical base address for connecting to this endpoint
... header 0..*stringUsage depends on the channel type


doco Documentation for this format

See the Extensions for this resource

UML Diagram (Legend)

Endpoint (DomainResource)Identifier for the organization that is used to identify the endpoint across multiple disparate systemsidentifier : Identifier [0..*]The endpoint status represents the general expected availability of an endpoint (this element modifies the meaning of other elements)status : code [1..1] « null (Strength=Required)EndpointStatus! »A coded value that represents the technical details of the usage of this endpoint, such as what WSDLs should be used in what way. (e.g. XDS.b/DICOM/cds-hook)connectionType : CodeableConcept [1..*] « null (Strength=Example)EndpointConnectionType?? »A friendly name that this endpoint can be referred to withname : string [0..1]The description of the endpoint and what it is for (typically used as supplemental information in an endpoint directory describing it's usage/purpose)description : string [0..1]The type of environment(s) exposed at this endpoint (dev, prod, test, etc)environmentType : CodeableConcept [0..*] « null (Strength=Extensible)EndpointEnvironment+ »The organization that manages this endpoint (even if technically another organization is hosting this in the cloud, it is the organization associated with the data)managingOrganization : Reference [0..1] « Organization »Contact details for a human to contact about the endpoint. The primary use of this for system administrator troubleshootingcontact : ContactPoint [0..*]The interval during which the endpoint is expected to be operationalperiod : Period [0..1]The payload type describes the acceptable content that can be communicated on the endpointpayloadType : CodeableConcept [0..*] « null (Strength=Example)EndpointPayloadType?? »The mime type to send the payload in - e.g. application/fhir+xml, application/fhir+json. If the mime type is not specified, then the sender could send any content (including no content depending on the connectionType)payloadMimeType : code [0..*] « null (Strength=Required)Mime Types! »The uri that describes the actual end-point to connect toaddress : url [1..1]Additional headers / information to send as part of the notificationheader : string [0..*]

XML Template

<Endpoint xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Identifies this endpoint across multiple systems --></identifier>
 <status value="[code]"/><!-- 1..1 active | suspended | error | off | entered-in-error | test -->
 <connectionType><!-- 1..* CodeableConcept Protocol/Profile/Standard to be used with this endpoint connection --></connectionType>
 <name value="[string]"/><!-- 0..1 A name that this endpoint can be identified by -->
 <description value="[string]"/><!-- 0..1 Additional details about the endpoint that could be displayed as further information to identify the description beyond its name -->
 <environmentType><!-- 0..* CodeableConcept The type of environment(s) exposed at this endpoint --></environmentType>
 <managingOrganization><!-- 0..1 Reference(Organization) Organization that manages this endpoint (might not be the organization that exposes the endpoint) --></managingOrganization>
 <contact><!-- 0..* ContactPoint Contact details for source (e.g. troubleshooting) --></contact>
 <period><!-- 0..1 Period Interval the endpoint is expected to be operational --></period>
 <payloadType><!-- 0..* CodeableConcept The type of content that may be used at this endpoint (e.g. XDS Discharge summaries) --></payloadType>
 <payloadMimeType value="[code]"/><!-- 0..* Mimetype to send. If not specified, the content could be anything (including no payload, if the connectionType defined this) -->
 <address value="[url]"/><!-- 1..1 The technical base address for connecting to this endpoint -->
 <header value="[string]"/><!-- 0..* Usage depends on the channel type -->
</Endpoint>

JSON Template

{doco
  "resourceType" : "Endpoint",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "identifier" : [{ Identifier }], // Identifies this endpoint across multiple systems
  "status" : "<code>", // R!  active | suspended | error | off | entered-in-error | test
  "connectionType" : [{ CodeableConcept }], // R!  Protocol/Profile/Standard to be used with this endpoint connection
  "name" : "<string>", // A name that this endpoint can be identified by
  "description" : "<string>", // Additional details about the endpoint that could be displayed as further information to identify the description beyond its name
  "environmentType" : [{ CodeableConcept }], // The type of environment(s) exposed at this endpoint
  "managingOrganization" : { Reference(Organization) }, // Organization that manages this endpoint (might not be the organization that exposes the endpoint)
  "contact" : [{ ContactPoint }], // Contact details for source (e.g. troubleshooting)
  "period" : { Period }, // Interval the endpoint is expected to be operational
  "payloadType" : [{ CodeableConcept }], // The type of content that may be used at this endpoint (e.g. XDS Discharge summaries)
  "payloadMimeType" : ["<code>"], // Mimetype to send. If not specified, the content could be anything (including no payload, if the connectionType defined this)
  "address" : "<url>", // R!  The technical base address for connecting to this endpoint
  "header" : ["<string>"] // Usage depends on the channel type
}

Turtle Template

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


[ a fhir:Endpoint;
  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:Endpoint.identifier [ Identifier ], ... ; # 0..* Identifies this endpoint across multiple systems
  fhir:Endpoint.status [ code ]; # 1..1 active | suspended | error | off | entered-in-error | test
  fhir:Endpoint.connectionType [ CodeableConcept ], ... ; # 1..* Protocol/Profile/Standard to be used with this endpoint connection
  fhir:Endpoint.name [ string ]; # 0..1 A name that this endpoint can be identified by
  fhir:Endpoint.description [ string ]; # 0..1 Additional details about the endpoint that could be displayed as further information to identify the description beyond its name
  fhir:Endpoint.environmentType [ CodeableConcept ], ... ; # 0..* The type of environment(s) exposed at this endpoint
  fhir:Endpoint.managingOrganization [ Reference(Organization) ]; # 0..1 Organization that manages this endpoint (might not be the organization that exposes the endpoint)
  fhir:Endpoint.contact [ ContactPoint ], ... ; # 0..* Contact details for source (e.g. troubleshooting)
  fhir:Endpoint.period [ Period ]; # 0..1 Interval the endpoint is expected to be operational
  fhir:Endpoint.payloadType [ CodeableConcept ], ... ; # 0..* The type of content that may be used at this endpoint (e.g. XDS Discharge summaries)
  fhir:Endpoint.payloadMimeType [ code ], ... ; # 0..* Mimetype to send. If not specified, the content could be anything (including no payload, if the connectionType defined this)
  fhir:Endpoint.address [ url ]; # 1..1 The technical base address for connecting to this endpoint
  fhir:Endpoint.header [ string ], ... ; # 0..* Usage depends on the channel type
]

Changes since R4

Endpoint
Endpoint.connectionType
  • Max Cardinality changed from 1 to *
  • Type changed from Coding to CodeableConcept
  • Remove Binding http://hl7.org/fhir/ValueSet/endpoint-connection-type (extensible)
  • Remove Binding http://hl7.org/fhir/ValueSet/endpoint-connection-type (extensible)
Endpoint.description
  • Added Element
Endpoint.environmentType
  • Added Element
Endpoint.payloadType
  • Min Cardinality changed from 1 to 0
  • Min Cardinality changed from 1 to 0

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 3 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.)

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Endpoint TUDomainResourceThe technical details of an endpoint that can be used for electronic services

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... identifier Σ0..*IdentifierIdentifies this endpoint across multiple systems

... status ?!Σ1..1codeactive | suspended | error | off | entered-in-error | test
EndpointStatus (Required)
... connectionType Σ1..*CodeableConceptProtocol/Profile/Standard to be used with this endpoint connection
Endpoint Connection Type (Example)

... description Σ0..1stringAdditional details about the endpoint that could be displayed as further information to identify the description beyond its name
... environmentType Σ0..*CodeableConceptThe type of environment(s) exposed at this endpoint
EndpointEnvironment (Extensible)

... managingOrganization Σ0..1Reference(Organization)Organization that manages this endpoint (might not be the organization that exposes the endpoint)
... contact 0..*ContactPointContact details for source (e.g. troubleshooting)

... period Σ0..1PeriodInterval the endpoint is expected to be operational
... payloadType Σ0..*CodeableConceptThe type of content that may be used at this endpoint (e.g. XDS Discharge summaries)
Endpoint Payload Type (Example)

... payloadMimeType Σ0..*codeMimetype to send. If not specified, the content could be anything (including no payload, if the connectionType defined this)
MimeType (Required)

... address Σ1..1urlThe technical base address for connecting to this endpoint
... header 0..*stringUsage depends on the channel type


doco Documentation for this format

See the Extensions for this resource

UML Diagram (Legend)

Endpoint (DomainResource)Identifier for the organization that is used to identify the endpoint across multiple disparate systemsidentifier : Identifier [0..*]The endpoint status represents the general expected availability of an endpoint (this element modifies the meaning of other elements)status : code [1..1] « null (Strength=Required)EndpointStatus! »A coded value that represents the technical details of the usage of this endpoint, such as what WSDLs should be used in what way. (e.g. XDS.b/DICOM/cds-hook)connectionType : CodeableConcept [1..*] « null (Strength=Example)EndpointConnectionType?? »A friendly name that this endpoint can be referred to withname : string [0..1]The description of the endpoint and what it is for (typically used as supplemental information in an endpoint directory describing it's usage/purpose)description : string [0..1]The type of environment(s) exposed at this endpoint (dev, prod, test, etc)environmentType : CodeableConcept [0..*] « null (Strength=Extensible)EndpointEnvironment+ »The organization that manages this endpoint (even if technically another organization is hosting this in the cloud, it is the organization associated with the data)managingOrganization : Reference [0..1] « Organization »Contact details for a human to contact about the endpoint. The primary use of this for system administrator troubleshootingcontact : ContactPoint [0..*]The interval during which the endpoint is expected to be operationalperiod : Period [0..1]The payload type describes the acceptable content that can be communicated on the endpointpayloadType : CodeableConcept [0..*] « null (Strength=Example)EndpointPayloadType?? »The mime type to send the payload in - e.g. application/fhir+xml, application/fhir+json. If the mime type is not specified, then the sender could send any content (including no content depending on the connectionType)payloadMimeType : code [0..*] « null (Strength=Required)Mime Types! »The uri that describes the actual end-point to connect toaddress : url [1..1]Additional headers / information to send as part of the notificationheader : string [0..*]

XML Template

<Endpoint xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Identifies this endpoint across multiple systems --></identifier>
 <status value="[code]"/><!-- 1..1 active | suspended | error | off | entered-in-error | test -->
 <connectionType><!-- 1..* CodeableConcept Protocol/Profile/Standard to be used with this endpoint connection --></connectionType>
 <name value="[string]"/><!-- 0..1 A name that this endpoint can be identified by -->
 <description value="[string]"/><!-- 0..1 Additional details about the endpoint that could be displayed as further information to identify the description beyond its name -->
 <environmentType><!-- 0..* CodeableConcept The type of environment(s) exposed at this endpoint --></environmentType>
 <managingOrganization><!-- 0..1 Reference(Organization) Organization that manages this endpoint (might not be the organization that exposes the endpoint) --></managingOrganization>
 <contact><!-- 0..* ContactPoint Contact details for source (e.g. troubleshooting) --></contact>
 <period><!-- 0..1 Period Interval the endpoint is expected to be operational --></period>
 <payloadType><!-- 0..* CodeableConcept The type of content that may be used at this endpoint (e.g. XDS Discharge summaries) --></payloadType>
 <payloadMimeType value="[code]"/><!-- 0..* Mimetype to send. If not specified, the content could be anything (including no payload, if the connectionType defined this) -->
 <address value="[url]"/><!-- 1..1 The technical base address for connecting to this endpoint -->
 <header value="[string]"/><!-- 0..* Usage depends on the channel type -->
</Endpoint>

JSON Template

{doco
  "resourceType" : "Endpoint",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "identifier" : [{ Identifier }], // Identifies this endpoint across multiple systems
  "status" : "<code>", // R!  active | suspended | error | off | entered-in-error | test
  "connectionType" : [{ CodeableConcept }], // R!  Protocol/Profile/Standard to be used with this endpoint connection
  "name" : "<string>", // A name that this endpoint can be identified by
  "description" : "<string>", // Additional details about the endpoint that could be displayed as further information to identify the description beyond its name
  "environmentType" : [{ CodeableConcept }], // The type of environment(s) exposed at this endpoint
  "managingOrganization" : { Reference(Organization) }, // Organization that manages this endpoint (might not be the organization that exposes the endpoint)
  "contact" : [{ ContactPoint }], // Contact details for source (e.g. troubleshooting)
  "period" : { Period }, // Interval the endpoint is expected to be operational
  "payloadType" : [{ CodeableConcept }], // The type of content that may be used at this endpoint (e.g. XDS Discharge summaries)
  "payloadMimeType" : ["<code>"], // Mimetype to send. If not specified, the content could be anything (including no payload, if the connectionType defined this)
  "address" : "<url>", // R!  The technical base address for connecting to this endpoint
  "header" : ["<string>"] // Usage depends on the channel type
}

Turtle Template

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


[ a fhir:Endpoint;
  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:Endpoint.identifier [ Identifier ], ... ; # 0..* Identifies this endpoint across multiple systems
  fhir:Endpoint.status [ code ]; # 1..1 active | suspended | error | off | entered-in-error | test
  fhir:Endpoint.connectionType [ CodeableConcept ], ... ; # 1..* Protocol/Profile/Standard to be used with this endpoint connection
  fhir:Endpoint.name [ string ]; # 0..1 A name that this endpoint can be identified by
  fhir:Endpoint.description [ string ]; # 0..1 Additional details about the endpoint that could be displayed as further information to identify the description beyond its name
  fhir:Endpoint.environmentType [ CodeableConcept ], ... ; # 0..* The type of environment(s) exposed at this endpoint
  fhir:Endpoint.managingOrganization [ Reference(Organization) ]; # 0..1 Organization that manages this endpoint (might not be the organization that exposes the endpoint)
  fhir:Endpoint.contact [ ContactPoint ], ... ; # 0..* Contact details for source (e.g. troubleshooting)
  fhir:Endpoint.period [ Period ]; # 0..1 Interval the endpoint is expected to be operational
  fhir:Endpoint.payloadType [ CodeableConcept ], ... ; # 0..* The type of content that may be used at this endpoint (e.g. XDS Discharge summaries)
  fhir:Endpoint.payloadMimeType [ code ], ... ; # 0..* Mimetype to send. If not specified, the content could be anything (including no payload, if the connectionType defined this)
  fhir:Endpoint.address [ url ]; # 1..1 The technical base address for connecting to this endpoint
  fhir:Endpoint.header [ string ], ... ; # 0..* Usage depends on the channel type
]

Changes since Release 4

Endpoint
Endpoint.connectionType
  • Max Cardinality changed from 1 to *
  • Type changed from Coding to CodeableConcept
  • Remove Binding http://hl7.org/fhir/ValueSet/endpoint-connection-type (extensible)
  • Remove Binding http://hl7.org/fhir/ValueSet/endpoint-connection-type (extensible)
Endpoint.description
  • Added Element
Endpoint.environmentType
  • Added Element
Endpoint.payloadType
  • Min Cardinality changed from 1 to 0
  • Min Cardinality changed from 1 to 0

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 3 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.)

 

Additional definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions, the spreadsheet version & the dependency analysis

8.9.5.1 Terminology Bindings

PathDefinitionTypeReference
Endpoint.status

The status of the endpoint.

RequiredEndpointStatus
Endpoint.connectionType

This is an example value set defined by the FHIR project, that could be used to represent possible connection type profile values.

ExampleEndpointConnectionType
Endpoint.environmentType

The environment type of the endpoint.

ExtensibleEndpointEnvironment
Endpoint.payloadType

This is an example value set defined by the FHIR project, that could be used to represent possible payload document types.

ExampleEndpointPayloadType
Endpoint.payloadMimeType

This value set includes all possible codes from BCP-13 (http://tools.ietf.org/html/bcp13)

RequiredMime Types

8.9.6 Notes

  • The IHE connection types that were defined in R4 have been moved to IHE defined profiles and vocabulary at https://profiles.ihe.net/ITI/mCSD

8.9.7 Search Parameters

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

NameTypeDescriptionExpressionIn Common
connection-typetokenProtocol/Profile/Standard to be used with this endpoint connectionEndpoint.connectionType
identifiertokenIdentifies this endpoint across multiple systemsEndpoint.identifier
name NstringA name that this endpoint can be identified byEndpoint.name
organizationreferenceThe organization that is managing the endpointEndpoint.managingOrganization
(Organization)
payload-typetokenThe type of content that may be used at this endpoint (e.g. XDS Discharge summaries)Endpoint.payloadType
status NtokenThe current status of the Endpoint (usually expected to be active)Endpoint.status