From b6126afcb854a634ece6cef55f32d531a2e0fbfa Mon Sep 17 00:00:00 2001 From: Josh Mandel Date: Tue, 6 Feb 2024 11:29:39 -0600 Subject: [PATCH] Info and experimental formatting thanks to bvdh --- .gitignore | 3 +++ input/images/information-svgrepo-com.svg | 7 ++++++ input/includes/exp-div.html | 1 + input/includes/exp-span.html | 1 + input/includes/exp.html | 1 + input/includes/info-note.html | 5 +++++ input/pages/app-launch.md | 13 ++++++----- input/pages/app-state.md | 3 ++- input/pages/brands.md | 7 ++++-- input/pages/index.md | 2 ++ input/pages/scopes-and-launch-context.md | 25 ++++++++++++--------- smart-template/content/assets/css/smart.css | 8 ++++++- 12 files changed, 55 insertions(+), 21 deletions(-) create mode 100644 input/images/information-svgrepo-com.svg create mode 100644 input/includes/exp-div.html create mode 100644 input/includes/exp-span.html create mode 100644 input/includes/exp.html create mode 100644 input/includes/info-note.html diff --git a/.gitignore b/.gitignore index 34be3fef..0b5c00ff 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +.index.db +.index.json +FHIR-smart.xml .DS_Store Thumbs.db /fsh-generated diff --git a/input/images/information-svgrepo-com.svg b/input/images/information-svgrepo-com.svg new file mode 100644 index 00000000..b4038eb5 --- /dev/null +++ b/input/images/information-svgrepo-com.svg @@ -0,0 +1,7 @@ + + + + + + + \ No newline at end of file diff --git a/input/includes/exp-div.html b/input/includes/exp-div.html new file mode 100644 index 00000000..a9741275 --- /dev/null +++ b/input/includes/exp-div.html @@ -0,0 +1 @@ +
\ No newline at end of file diff --git a/input/includes/exp-span.html b/input/includes/exp-span.html new file mode 100644 index 00000000..648c08dc --- /dev/null +++ b/input/includes/exp-span.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/input/includes/exp.html b/input/includes/exp.html new file mode 100644 index 00000000..246d4088 --- /dev/null +++ b/input/includes/exp.html @@ -0,0 +1 @@ +EXP \ No newline at end of file diff --git a/input/includes/info-note.html b/input/includes/info-note.html new file mode 100644 index 00000000..8aa5ce26 --- /dev/null +++ b/input/includes/info-note.html @@ -0,0 +1,5 @@ +
+ + {{include.text}} +
+ diff --git a/input/pages/app-launch.md b/input/pages/app-launch.md index a1ce4ac2..68ea56a5 100644 --- a/input/pages/app-launch.md +++ b/input/pages/app-launch.md @@ -646,9 +646,9 @@ includes the following parameters: Token that can be used to obtain a new access token, using the same or a subset of the original authorization grants - authorization_details + authorization_details {%include exp.html%} optional - Additional details describing where this token can be used, and any per-location context (experimental; see details) + {%include exp-span.html%}Additional details describing where this token can be used, and any per-location context (experimental; see details) @@ -701,8 +701,9 @@ interaction are not defined by this specification.* At this point, **the authorization flow is complete**. -##### Experimental: Authorization Details for Multiple Servers +##### {%include exp.html%} Experimental: Authorization Details for Multiple Servers +{%include exp-div.html%} If an authorization server wishes to provide a token that can be used with more than one FHIR server (i.e., the token can be used with app's requested `aud` as well as additional endpoints), the following structures from [rfc9396](https://datatracker.ietf.org/doc/html/rfc9396) can be included in the access token response: * `authorization_details` array of objects, where each object may include @@ -734,7 +735,7 @@ For example, an access request to an R4 FHIR server could potentially result in }] } ``` - +
#### Examples @@ -876,9 +877,9 @@ The response is a JSON object containing a new access token, with the following The refresh token issued by the authorization server. If present, the app should discard any previous refresh_token associated with this launch and replace it with this new value. - authorization_details + authorization_details{%include exp.html%} optional - Additional details describing where this token can be used, and any per-location context (experimental; see details) + {%include exp-span.html%}Additional details describing where this token can be used, and any per-location context (experimental; see details) diff --git a/input/pages/app-state.md b/input/pages/app-state.md index 6d561b78..42e7c809 100644 --- a/input/pages/app-state.md +++ b/input/pages/app-state.md @@ -1,4 +1,5 @@ -### `smart-app-state` capability +{%include exp-div.html%} +### `smart-app-state` capability {%include exp.html%} This experimental capability allows apps to persist a small amount of configuration data to an EHR's FHIR server. Conformance requirements described diff --git a/input/pages/brands.md b/input/pages/brands.md index e54af86e..1de7338e 100644 --- a/input/pages/brands.md +++ b/input/pages/brands.md @@ -28,7 +28,7 @@ Using this model, an **app** can: ### Brand Information -*Note*: The overview tables and annotated examples on this page are intended for convenience and clarity. In case of any discrepancies, the formal profiles should be considered the definitive source of truth. +{% include info-note.html text=conformance_note %} #### Information Included In Each Brand @@ -79,7 +79,10 @@ Commonly, a single Brand is typically associated with a single Portal that offer ### Conformance Overview -*Note*: This conformance overview is intended for convenience and clarity. In case of any discrepancies, the formal profiles should be considered the definitive source of truth. +{% capture conformance_note %} +The overview tables and annotated examples on this page are intended for convenience and clarity. In case of any discrepancies, the formal profiles should be considered the definitive source of truth. +{% endcapture %} +{% include info-note.html text=conformance_note %} * **Health Data Provider**. Any organization that offers SMART on FHIR access to its users and wishes to appear as a branded entity in user-facing apps. A Health Data Provider works with a Brand Bundle Publisher and SMART on FHIR Server to manage Organization and Endpoint details. * RECOMMENDED to define an Organization identifier where `system` is `urn:ietf:rfc:3986` and `value` is the HTTPS URL for the brand's primary web presence, omitting any "www." prefix from the domain and omitting any path component diff --git a/input/pages/index.md b/input/pages/index.md index 793e807c..f7f1c2ca 100644 --- a/input/pages/index.md +++ b/input/pages/index.md @@ -2,6 +2,8 @@ This implementation guide describes a set of foundational patterns based on [OAuth 2.0](https://tools.ietf.org/html/rfc6749) for client applications to authorize, authenticate, and integrate with FHIR-based data systems. The patterns defined in this specification are introduced in the sections below. For background on SMART Health IT, see [smarthealthit.org](https://smarthealthit.org). +Portions of the specification designated as Experimental are indicated by {%include exp.html%} and background shading. + ### [Discovery of Server Capabilities and Configuration](conformance.html) SMART defines a discovery document, available at `.well-known/smart-configuration` relative to a FHIR Server Base URL, allowing clients to learn the authorization endpoint URLs and features a server supports. This information helps client direct authorization requests to the right endpoint, and helps clients construct an authorization request that the server can support. diff --git a/input/pages/scopes-and-launch-context.md b/input/pages/scopes-and-launch-context.md index ea98b26b..540fd5d0 100644 --- a/input/pages/scopes-and-launch-context.md +++ b/input/pages/scopes-and-launch-context.md @@ -1,5 +1,3 @@ - - SMART on FHIR's authorization scheme uses OAuth scopes to communicate (and negotiate) access requirements. Providing apps with access to broad data sets is consistent with current common practices (e.g., interface engines also provide access to broad data sets); access is also limited based on the privileges of the user in context. In general, we use scopes for three kinds of data: @@ -107,14 +105,14 @@ for broad support; we reserve the right to make some search parameters mandatory in the future. -#### Experimental features - +#### Experimental features {%include exp.html%} +{%include exp-div.html%} Because the search parameter based syntax here is quite general, it opens up the possibility of using many features that servers may have trouble supporting in a consistent and performant fashion. Given the current level of implementation experience, the following features should be considered experimental, even if they are supported by a server: * Use of search modifiers such as `Observation.rs?code:in=http://valueset.example.org/ValueSet/diabetes-codes` * Use of search parameter chaining such as `Observation.rs?patient.birthdate=1990` * Use of [FHIR's `_filter` capabilities](https://www.hl7.org/fhir/search_filter.html) - + #### Scope size over the wire @@ -490,7 +488,7 @@ Requested Scope | Meaning ----------------|--------- `launch/patient` | Need patient context at launch time (FHIR Patient resource). `launch/encounter` | Need encounter context at launch time (FHIR Encounter resource). -Others (Experimental) | Any SMART EHR MAY extend this list to support additional context. When specifying resource types, convert the type names to *all lowercase* (e.g., `launch/diagnosticreport`). In situations where the same resource type might be used for more than one purpose (e.g., in a medication reconciliation app, one List of at-home medications and another List of in-hospital medications), the app can solicit context with a specific role by appending `?role={role}` (see [example below](#fhircontext-example-medication-reconciliation)). +Others {%include exp.html%} | Any SMART EHR MAY extend this list to support additional context. When specifying resource types, convert the type names to *all lowercase* (e.g., `launch/diagnosticreport`). In situations where the same resource type might be used for more than one purpose (e.g., in a medication reconciliation app, one List of at-home medications and another List of in-hospital medications), the app can solicit context with a specific role by appending `?role={role}` (see [example below](#fhircontext-example-medication-reconciliation)). {:.grid} When using `?role=` in launch context requests: @@ -557,20 +555,21 @@ Launch context parameter | Example value | Meaning {:.grid} -#### `fhirContext` (Experimental) +#### `fhirContext` {%include exp.html%} -To allow application flexibility, maintain backwards compatibility, and keep a +{%include exp-div.html%} To allow application flexibility, maintain backwards compatibility, and keep a predictable JSON structure, any contextual resource types that were requested by a launch scope will appear in the `fhirContext` array. The two exceptions are Patient and Encounter resource types, which will *not be deprecated from top-level parameters*, and they will *not be permitted* within the `fhirContext` array unless they -include a `role` other than `"launch"`. +include a `role` other than `"launch"`. Each object in the `fhirContext` array SHALL include at least one of `"reference"`, `"canonical"`, or `"identifier"`, and MAY contain additional properties: -* `"reference"` (string): relative reference to a FHIR resource. Note that there MAY be more than one `fhirContext` item referencing the same type of resource. + +* `"reference"` (string): relative reference to a FHIR resource. Note that there MAY be more than one `fhirContext` item referencing the same type of resource. * `"canonical"` (string): canonical URL for the `fhirContext` item (MAY include a version suffix) @@ -591,6 +590,7 @@ the same role. promote awareness and reuse. * Note: We have not yet defined a protocol for apps to discover which roles an EHR supports; as such, it is important for EHRs to include this information in their developer documentation. + Note that for `"identifier"` and `"canonical"`, this specification does not define rules for access control. The app may reach out to different servers to resolve these, authenticating as needed. @@ -657,6 +657,7 @@ the EHR might supply `fhirContext` like: }] } ``` +
App Launch Intent (optional)
`intent`: Some SMART apps might offer more than one context or user interface @@ -684,8 +685,9 @@ Note that *SMART makes no effort to standardize `intent` values*. Intents simpl provide a mechanism for tighter custom integration between an app and a SMART EHR. The meaning of intent values must be negotiated between the app and the EHR. -##### SMART App Styling (experimental[^1]) +##### SMART App Styling (experimental[^1]) {%include exp.html%} {: #styling} +{%include exp-div.html%} `smart_style_url`: In order to mimic the style of the SMART EHR more closely, SMART apps can check for the existence of this launch context parameter and, if provided, download the JSON file referenced by the URL value. @@ -735,6 +737,7 @@ Optionally, if the client app detects a new version of the SMART Style object store the new property values and request approval to use the new values from a client app stakeholder. This allows for safeguarding against poor usability that might occur from the immediate use of these values in the client app UI. + ### Scopes for requesting identity data diff --git a/smart-template/content/assets/css/smart.css b/smart-template/content/assets/css/smart.css index 5a4c4daf..97f644f8 100644 --- a/smart-template/content/assets/css/smart.css +++ b/smart-template/content/assets/css/smart.css @@ -1,4 +1,10 @@ .smart-code code { word-break: break-all; white-space: pre-wrap; -} \ No newline at end of file +} + +.optional { color: #CC3F00; } +.caption { color: darkgreen; font-weight: bold; } +.expSpan { background-color: #fff5e6; } +.expBlock { padding-top: 5px; padding-left: 5px; padding-right: 10px; padding-bottom: 5px; background-color: #fff5e6; } +.expIcon { padding-left: 3px; padding-right: 3px; border: 1px grey solid; font-weight: bold; color: black; background-color: #fff5e6 vertical-align: middle;}