SMART Scheduling Links
1.0.0 - STU 1
SMART Scheduling Links
1.0.0 - STU 1
SMART Scheduling Links, published by HL7 International / Patient Administration. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/smart-scheduling-links/ and changes regularly. See the Directory of published versions
| Official URL: http://hl7.org/fhir/uv/smart-scheduling-links/StructureDefinition/smart-scheduling-practitionerRole | Version: 1.0.0 | ||||
| Standards status: Trial-use | Maturity Level: 2 | Computable Name: SmartSchedulingPractitionerRole | |||
| Other Identifiers: OID:2.16.840.1.113883.4.642.40.91.42.8 | |||||
Each line of the PractitionerRole File is a minified JSON object that represents a set of roles/locations/specialties/services that a practitioner may perform at an organization for a period of time. The PractitionerRole resource represents the specific roles that practitioners perform at organizations where appointments are available. According to the FHIR R4 PractitionerRole definition, practitioner roles define the specific context in which practitioners provide services, including:
Example Usage Scenarios
The following are example usage scenarios for the SMART Scheduling Links PractitionerRole profile:
The following data elements must always be present or must be supported if the data is present in the sending system. They are presented below in a simple human-readable explanation. Profile specific guidance and examples are provided as well. The Formal Views below provides the formal summary, definitions, and terminology requirements.
Each PractitionerRole Must Have:
Each PractitionerRole Must Support:
Profile Specific Implementation Guidance:
Each identifier object includes a system and a value.
If a PractitionerRole is associated with organization-specific identifiers (such as role-specific employee numbers, provider numbers, or location-specific identifiers), Slot Publishers SHOULD include these.§sched-19 The system should be a URL that identifies the identifier system, preferably a page on the publisher's web site (e.g. {"system": "https://healthsystem.example.com/practitioner-role-directory", "value": "ROLE-123"})
If a PractitionerRole participates in external registry programs that assign role-specific identifiers, Slot Publishers MAY include these identifiers using the appropriate system URL for the registry.§sched-20
Any number of additional identifiers MAY be included.§sched-21 Each should populate system and value as appropriate, following FHIR identifier conventions.
Usages:
You can also check for usages in the FHIR IG Statistics
Description Differentials, Snapshots, and other representations.
| Name | Flags | Card. | Type | Description & Constraints Filter:  |
|---|---|---|---|---|
  PractitionerRole |
0..* | PractitionerRole | Roles/organizations the practitioner is associated with | |
  id |
1..1 | id | Logical id of this artifact | |
| implicitRules |
0..1 | uri | A set of rules under which this content was created | |
 modifierExtension |
0..* | Extension | Extensions that cannot be ignored | |
 identifier |
0..* | Identifier | Business Identifiers that are specific to a role/location | |
| active |
0..1 | boolean | Whether this practitioner role record is in active use | |
 period |
0..1 | Period | The period during which the practitioner is authorized to perform in these role(s) | |
 start |
C | 0..1 | dateTime | Starting time with inclusive boundary |
 end |
C | 0..1 | dateTime | End time with inclusive boundary, if not ongoing |
 practitioner |
0..1 | Reference(Practitioner) | Practitioner that is able to provide the defined services for the organization | |
| organization |
0..1 | Reference(Organization) | Organization where the roles are available | |
| code |
0..* | CodeableConcept | Roles which this practitioner may perform Binding: PractitionerRole (example): The role a person plays representing an organization. | |
| specialty |
0..* | CodeableConcept | Specific specialty of the practitioner Binding: PracticeSettingCodeValueSet (preferred): Specific specialty associated with the agency. | |
| location |
0..* | Reference(Location) | The location(s) at which this practitioner provides care | |
| healthcareService |
0..* | Reference(Healthcare Service) | The list of healthcare services that this worker provides for this role's Organization/Location(s) | |
| telecom |
0..* | ContactPoint | Contact details that are specific to the role/location/service | |
| Documentation for this format | ||||
| Path | Status | Usage | ValueSet | Version | Source |
| PractitionerRole.code | Base | example | Practitioner role | 📍4.0.1 | FHIR Std. |
| PractitionerRole.specialty | Base | preferred | Practice Setting Code Value Set | 📍4.0.1 | FHIR Std. |
| Id | Grade | Path(s) | Description | Expression |
| dom-2 | error | PractitionerRole | If the resource is contained in another resource, it SHALL NOT contain nested Resources |
contained.contained.empty()
|
| dom-3 | error | PractitionerRole | If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource |
contained.where((('#'+id in (%resource.descendants().reference | %resource.descendants().as(canonical) | %resource.descendants().as(uri) | %resource.descendants().as(url))) or descendants().where(reference = '#').exists() or descendants().where(as(canonical) = '#').exists() or descendants().where(as(canonical) = '#').exists()).not()).trace('unmatched', id).empty()
|
| dom-4 | error | PractitionerRole | If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated |
contained.meta.versionId.empty() and contained.meta.lastUpdated.empty()
|
| dom-5 | error | PractitionerRole | If a resource is contained in another resource, it SHALL NOT have a security label |
contained.meta.security.empty()
|
| dom-6 | best practice | PractitionerRole | A resource should have narrative for robust management |
text.`div`.exists()
|
| ele-1 | error | **ALL** elements | All FHIR elements must have a @value or children |
hasValue() or (children().count() > id.count())
|
| ext-1 | error | **ALL** extensions | Must have either extensions or value[x], not both |
extension.exists() != value.exists()
|
This structure is derived from PractitionerRole
| Name | Flags | Card. | Type | Description & Constraints Filter: |
|---|---|---|---|---|
| PractitionerRole |
0..* | PractitionerRole | Roles/organizations the practitioner is associated with | |
 id |
1..1 | id | Logical id of this artifact | |
| identifier |
0..* | Identifier | Business Identifiers that are specific to a role/location | |
| active |
0..1 | boolean | Whether this practitioner role record is in active use | |
| period |
0..1 | Period | The period during which the practitioner is authorized to perform in these role(s) | |
| start |
0..1 | dateTime | Starting time with inclusive boundary | |
| end |
0..1 | dateTime | End time with inclusive boundary, if not ongoing | |
| practitioner |
0..1 | Reference(Practitioner) | Practitioner that is able to provide the defined services for the organization | |
| organization |
0..1 | Reference(Organization) | Organization where the roles are available | |
| code |
0..* | CodeableConcept | Roles which this practitioner may perform | |
| specialty |
0..* | CodeableConcept | Specific specialty of the practitioner | |
| location |
0..* | Reference(Location) | The location(s) at which this practitioner provides care | |
| healthcareService |
0..* | Reference(Healthcare Service) | The list of healthcare services that this worker provides for this role's Organization/Location(s) | |
| telecom |
0..* | ContactPoint | Contact details that are specific to the role/location/service | |
| Documentation for this format | ||||
| Name | Flags | Card. | Type | Description & Constraints Filter: | ||||
|---|---|---|---|---|---|---|---|---|
| PractitionerRole |
0..* | PractitionerRole | Roles/organizations the practitioner is associated with | |||||
| id |
1..1 | id | Logical id of this artifact | |||||
| meta |
0..1 | Meta | Metadata about the resource | |||||
| implicitRules |
0..1 | uri | A set of rules under which this content was created | |||||
| language |
0..1 | code | Language of the resource content Binding: CommonLanguages (preferred): A human language.
| |||||
| text |
0..1 | Narrative | Text summary of the resource, for human interpretation This profile does not constrain the narrative in regard to content, language, or traceability to data elements | |||||
| contained |
0..* | Resource | Contained, inline Resources | |||||
 extension |
0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension |
0..* | Extension | Extensions that cannot be ignored | |||||
| identifier |
0..* | Identifier | Business Identifiers that are specific to a role/location | |||||
| active |
0..1 | boolean | Whether this practitioner role record is in active use | |||||
| period |
0..1 | Period | The period during which the practitioner is authorized to perform in these role(s) | |||||
| id |
0..1 | string | Unique id for inter-element referencing | |||||
| extension |
0..* | Extension | Additional content defined by implementations Slice: Unordered, Open by value:url | |||||
| start |
C | 0..1 | dateTime | Starting time with inclusive boundary | ||||
| end |
C | 0..1 | dateTime | End time with inclusive boundary, if not ongoing | ||||
| practitioner |
0..1 | Reference(Practitioner) | Practitioner that is able to provide the defined services for the organization | |||||
| organization |
0..1 | Reference(Organization) | Organization where the roles are available | |||||
| code |
0..* | CodeableConcept | Roles which this practitioner may perform Binding: PractitionerRole (example): The role a person plays representing an organization. | |||||
| specialty |
0..* | CodeableConcept | Specific specialty of the practitioner Binding: PracticeSettingCodeValueSet (preferred): Specific specialty associated with the agency. | |||||
| location |
0..* | Reference(Location) | The location(s) at which this practitioner provides care | |||||
| healthcareService |
0..* | Reference(Healthcare Service) | The list of healthcare services that this worker provides for this role's Organization/Location(s) | |||||
| telecom |
0..* | ContactPoint | Contact details that are specific to the role/location/service | |||||
| availableTime |
0..* | BackboneElement | Times the Service Site is available | |||||
| id |
0..1 | string | Unique id for inter-element referencing | |||||
| extension |
0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension |
0..* | Extension | Extensions that cannot be ignored even if unrecognized | |||||
| daysOfWeek |
0..* | code | mon | tue | wed | thu | fri | sat | sun Binding: DaysOfWeek (required): The days of the week. | |||||
| allDay |
0..1 | boolean | Always available? e.g. 24 hour service | |||||
| availableStartTime |
0..1 | time | Opening time of day (ignored if allDay = true) | |||||
| availableEndTime |
0..1 | time | Closing time of day (ignored if allDay = true) | |||||
| notAvailable |
0..* | BackboneElement | Not available during this time due to provided reason | |||||
| id |
0..1 | string | Unique id for inter-element referencing | |||||
| extension |
0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension |
0..* | Extension | Extensions that cannot be ignored even if unrecognized | |||||
| description |
1..1 | string | Reason presented to the user explaining why time not available | |||||
| during |
0..1 | Period | Service not available from this date | |||||
| availabilityExceptions |
0..1 | string | Description of availability exceptions | |||||
| endpoint |
0..* | Reference(Endpoint) | Technical endpoints providing access to services operated for the practitioner with this role | |||||
| Documentation for this format | ||||||||
| Path | Status | Usage | ValueSet | Version | Source |
| PractitionerRole.language | Base | preferred | Common Languages | 📍4.0.1 | FHIR Std. |
| PractitionerRole.code | Base | example | Practitioner role | 📍4.0.1 | FHIR Std. |
| PractitionerRole.specialty | Base | preferred | Practice Setting Code Value Set | 📍4.0.1 | FHIR Std. |
| PractitionerRole.availableTime.daysOfWeek | Base | required | DaysOfWeek | 📍4.0.1 | FHIR Std. |
| Id | Grade | Path(s) | Description | Expression |
| dom-2 | error | PractitionerRole | If the resource is contained in another resource, it SHALL NOT contain nested Resources |
contained.contained.empty()
|
| dom-3 | error | PractitionerRole | If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource |
contained.where((('#'+id in (%resource.descendants().reference | %resource.descendants().as(canonical) | %resource.descendants().as(uri) | %resource.descendants().as(url))) or descendants().where(reference = '#').exists() or descendants().where(as(canonical) = '#').exists() or descendants().where(as(canonical) = '#').exists()).not()).trace('unmatched', id).empty()
|
| dom-4 | error | PractitionerRole | If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated |
contained.meta.versionId.empty() and contained.meta.lastUpdated.empty()
|
| dom-5 | error | PractitionerRole | If a resource is contained in another resource, it SHALL NOT have a security label |
contained.meta.security.empty()
|
| dom-6 | best practice | PractitionerRole | A resource should have narrative for robust management |
text.`div`.exists()
|
| ele-1 | error | **ALL** elements | All FHIR elements must have a @value or children |
hasValue() or (children().count() > id.count())
|
| ext-1 | error | **ALL** extensions | Must have either extensions or value[x], not both |
extension.exists() != value.exists()
|
This structure is derived from PractitionerRole
Summary
Mandatory: 1 element
Must-Support: 13 elements
Structures
This structure refers to these other structures:
Maturity: 2
Key Elements View
| Name | Flags | Card. | Type | Description & Constraints Filter: |
|---|---|---|---|---|
| PractitionerRole |
0..* | PractitionerRole | Roles/organizations the practitioner is associated with | |
| id |
1..1 | id | Logical id of this artifact | |
| implicitRules |
0..1 | uri | A set of rules under which this content was created | |
| modifierExtension |
0..* | Extension | Extensions that cannot be ignored | |
| identifier |
0..* | Identifier | Business Identifiers that are specific to a role/location | |
| active |
0..1 | boolean | Whether this practitioner role record is in active use | |
| period |
0..1 | Period | The period during which the practitioner is authorized to perform in these role(s) | |
| start |
C | 0..1 | dateTime | Starting time with inclusive boundary |
| end |
C | 0..1 | dateTime | End time with inclusive boundary, if not ongoing |
| practitioner |
0..1 | Reference(Practitioner) | Practitioner that is able to provide the defined services for the organization | |
| organization |
0..1 | Reference(Organization) | Organization where the roles are available | |
| code |
0..* | CodeableConcept | Roles which this practitioner may perform Binding: PractitionerRole (example): The role a person plays representing an organization. | |
| specialty |
0..* | CodeableConcept | Specific specialty of the practitioner Binding: PracticeSettingCodeValueSet (preferred): Specific specialty associated with the agency. | |
| location |
0..* | Reference(Location) | The location(s) at which this practitioner provides care | |
| healthcareService |
0..* | Reference(Healthcare Service) | The list of healthcare services that this worker provides for this role's Organization/Location(s) | |
| telecom |
0..* | ContactPoint | Contact details that are specific to the role/location/service | |
| Documentation for this format | ||||
| Path | Status | Usage | ValueSet | Version | Source |
| PractitionerRole.code | Base | example | Practitioner role | 📍4.0.1 | FHIR Std. |
| PractitionerRole.specialty | Base | preferred | Practice Setting Code Value Set | 📍4.0.1 | FHIR Std. |
| Id | Grade | Path(s) | Description | Expression |
| dom-2 | error | PractitionerRole | If the resource is contained in another resource, it SHALL NOT contain nested Resources |
contained.contained.empty()
|
| dom-3 | error | PractitionerRole | If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource |
contained.where((('#'+id in (%resource.descendants().reference | %resource.descendants().as(canonical) | %resource.descendants().as(uri) | %resource.descendants().as(url))) or descendants().where(reference = '#').exists() or descendants().where(as(canonical) = '#').exists() or descendants().where(as(canonical) = '#').exists()).not()).trace('unmatched', id).empty()
|
| dom-4 | error | PractitionerRole | If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated |
contained.meta.versionId.empty() and contained.meta.lastUpdated.empty()
|
| dom-5 | error | PractitionerRole | If a resource is contained in another resource, it SHALL NOT have a security label |
contained.meta.security.empty()
|
| dom-6 | best practice | PractitionerRole | A resource should have narrative for robust management |
text.`div`.exists()
|
| ele-1 | error | **ALL** elements | All FHIR elements must have a @value or children |
hasValue() or (children().count() > id.count())
|
| ext-1 | error | **ALL** extensions | Must have either extensions or value[x], not both |
extension.exists() != value.exists()
|
Differential View
This structure is derived from PractitionerRole
| Name | Flags | Card. | Type | Description & Constraints Filter: |
|---|---|---|---|---|
| PractitionerRole |
0..* | PractitionerRole | Roles/organizations the practitioner is associated with | |
| id |
1..1 | id | Logical id of this artifact | |
| identifier |
0..* | Identifier | Business Identifiers that are specific to a role/location | |
| active |
0..1 | boolean | Whether this practitioner role record is in active use | |
| period |
0..1 | Period | The period during which the practitioner is authorized to perform in these role(s) | |
| start |
0..1 | dateTime | Starting time with inclusive boundary | |
| end |
0..1 | dateTime | End time with inclusive boundary, if not ongoing | |
| practitioner |
0..1 | Reference(Practitioner) | Practitioner that is able to provide the defined services for the organization | |
| organization |
0..1 | Reference(Organization) | Organization where the roles are available | |
| code |
0..* | CodeableConcept | Roles which this practitioner may perform | |
| specialty |
0..* | CodeableConcept | Specific specialty of the practitioner | |
| location |
0..* | Reference(Location) | The location(s) at which this practitioner provides care | |
| healthcareService |
0..* | Reference(Healthcare Service) | The list of healthcare services that this worker provides for this role's Organization/Location(s) | |
| telecom |
0..* | ContactPoint | Contact details that are specific to the role/location/service | |
| Documentation for this format | ||||
Snapshot ViewView
| Name | Flags | Card. | Type | Description & Constraints Filter: | ||||
|---|---|---|---|---|---|---|---|---|
| PractitionerRole |
0..* | PractitionerRole | Roles/organizations the practitioner is associated with | |||||
| id |
1..1 | id | Logical id of this artifact | |||||
| meta |
0..1 | Meta | Metadata about the resource | |||||
| implicitRules |
0..1 | uri | A set of rules under which this content was created | |||||
| language |
0..1 | code | Language of the resource content Binding: CommonLanguages (preferred): A human language.
| |||||
| text |
0..1 | Narrative | Text summary of the resource, for human interpretation This profile does not constrain the narrative in regard to content, language, or traceability to data elements | |||||
| contained |
0..* | Resource | Contained, inline Resources | |||||
| extension |
0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension |
0..* | Extension | Extensions that cannot be ignored | |||||
| identifier |
0..* | Identifier | Business Identifiers that are specific to a role/location | |||||
| active |
0..1 | boolean | Whether this practitioner role record is in active use | |||||
| period |
0..1 | Period | The period during which the practitioner is authorized to perform in these role(s) | |||||
| id |
0..1 | string | Unique id for inter-element referencing | |||||
| extension |
0..* | Extension | Additional content defined by implementations Slice: Unordered, Open by value:url | |||||
| start |
C | 0..1 | dateTime | Starting time with inclusive boundary | ||||
| end |
C | 0..1 | dateTime | End time with inclusive boundary, if not ongoing | ||||
| practitioner |
0..1 | Reference(Practitioner) | Practitioner that is able to provide the defined services for the organization | |||||
| organization |
0..1 | Reference(Organization) | Organization where the roles are available | |||||
| code |
0..* | CodeableConcept | Roles which this practitioner may perform Binding: PractitionerRole (example): The role a person plays representing an organization. | |||||
| specialty |
0..* | CodeableConcept | Specific specialty of the practitioner Binding: PracticeSettingCodeValueSet (preferred): Specific specialty associated with the agency. | |||||
| location |
0..* | Reference(Location) | The location(s) at which this practitioner provides care | |||||
| healthcareService |
0..* | Reference(Healthcare Service) | The list of healthcare services that this worker provides for this role's Organization/Location(s) | |||||
| telecom |
0..* | ContactPoint | Contact details that are specific to the role/location/service | |||||
| availableTime |
0..* | BackboneElement | Times the Service Site is available | |||||
| id |
0..1 | string | Unique id for inter-element referencing | |||||
| extension |
0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension |
0..* | Extension | Extensions that cannot be ignored even if unrecognized | |||||
| daysOfWeek |
0..* | code | mon | tue | wed | thu | fri | sat | sun Binding: DaysOfWeek (required): The days of the week. | |||||
| allDay |
0..1 | boolean | Always available? e.g. 24 hour service | |||||
| availableStartTime |
0..1 | time | Opening time of day (ignored if allDay = true) | |||||
| availableEndTime |
0..1 | time | Closing time of day (ignored if allDay = true) | |||||
| notAvailable |
0..* | BackboneElement | Not available during this time due to provided reason | |||||
| id |
0..1 | string | Unique id for inter-element referencing | |||||
| extension |
0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension |
0..* | Extension | Extensions that cannot be ignored even if unrecognized | |||||
| description |
1..1 | string | Reason presented to the user explaining why time not available | |||||
| during |
0..1 | Period | Service not available from this date | |||||
| availabilityExceptions |
0..1 | string | Description of availability exceptions | |||||
| endpoint |
0..* | Reference(Endpoint) | Technical endpoints providing access to services operated for the practitioner with this role | |||||
| Documentation for this format | ||||||||
| Path | Status | Usage | ValueSet | Version | Source |
| PractitionerRole.language | Base | preferred | Common Languages | 📍4.0.1 | FHIR Std. |
| PractitionerRole.code | Base | example | Practitioner role | 📍4.0.1 | FHIR Std. |
| PractitionerRole.specialty | Base | preferred | Practice Setting Code Value Set | 📍4.0.1 | FHIR Std. |
| PractitionerRole.availableTime.daysOfWeek | Base | required | DaysOfWeek | 📍4.0.1 | FHIR Std. |
| Id | Grade | Path(s) | Description | Expression |
| dom-2 | error | PractitionerRole | If the resource is contained in another resource, it SHALL NOT contain nested Resources |
contained.contained.empty()
|
| dom-3 | error | PractitionerRole | If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource |
contained.where((('#'+id in (%resource.descendants().reference | %resource.descendants().as(canonical) | %resource.descendants().as(uri) | %resource.descendants().as(url))) or descendants().where(reference = '#').exists() or descendants().where(as(canonical) = '#').exists() or descendants().where(as(canonical) = '#').exists()).not()).trace('unmatched', id).empty()
|
| dom-4 | error | PractitionerRole | If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated |
contained.meta.versionId.empty() and contained.meta.lastUpdated.empty()
|
| dom-5 | error | PractitionerRole | If a resource is contained in another resource, it SHALL NOT have a security label |
contained.meta.security.empty()
|
| dom-6 | best practice | PractitionerRole | A resource should have narrative for robust management |
text.`div`.exists()
|
| ele-1 | error | **ALL** elements | All FHIR elements must have a @value or children |
hasValue() or (children().count() > id.count())
|
| ext-1 | error | **ALL** extensions | Must have either extensions or value[x], not both |
extension.exists() != value.exists()
|
This structure is derived from PractitionerRole
Summary
Mandatory: 1 element
Must-Support: 13 elements
Structures
This structure refers to these other structures:
Maturity: 2
Other representations of profile: CSV, Excel, Schematron
IG © 2026+ HL7 International / Patient Administration and Boston Children's Hospital. Package hl7.fhir.uv.smart-scheduling-links#1.0.0 based on FHIR 4.0.1. Generated 2026-10-21
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change