Skip to content

Commit

Permalink
Issue #2873 - enable 'allowUnknown' profile config property
Browse files Browse the repository at this point in the history 
Signed-off-by: Mike Schroeder <mschroed@us.ibm.com>
  • Loading branch information
@michaelwschroeder
michaelwschroeder committed Oct 20, 2021
1 parent 2ab35bf commit 07d8917
Show file tree
Hide file tree
Showing 5 changed files with 492 additions and 223 deletions.
44 changes: 30 additions & 14 deletions docs/src/pages/guides/FHIRServerUsersGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ layout: post
title: IBM FHIR Server User's Guide
description: IBM FHIR Server User's Guide
Copyright: years 2017, 2021
lastupdated: "2021-10-12"
lastupdated: "2021-10-20"
permalink: /FHIRServerUsersGuide/
---

Expand Down Expand Up @@ -799,20 +799,19 @@ For example, you can configure a set of FHIRPath Constraints to run for resource
}
```

It is also possible to either require conformance to a particular profile or to disallow conformance to a particular profile through the `fhirServer/resources/<resourceType>/profiles/atLeastOne` and `fhirServer/resources/<resourceType>/profiles/notAllowed` configuration parameters.
The following configuration parameters can be used to specify rules relating to the set of profiles that are specified in a resource's `meta.profile` element:
* `fhirServer/resources/<resourceType>/profiles/atLeastOne` - this configuration parameter is used to specify a set of profiles, at least one of which a resource must claim conformance to and be successfully validated against in order to be persisted to the FHIR server.
* `fhirServer/resources/<resourceType>/profiles/notAllowed`- this configuration parameter is used to specify a set of profiles to which a resource is *not allowed* to claim conformance and be successfully validated against in order to be persisted to the FHIR server.
* `fhirServer/resources/<resourceType>/profiles/allowUnknown`- this configuration parameter is used to indicate whether a warning or an error is issued if a profile specified in a resource's `meta.profile`element is not loaded in the FHIR server. The default value is `true`, meaning unknown profiles are allowed to be specified. The profile will be ignored and just a warning will be returned. If set to `false`, this means unknown profiles are not allowed to be specified. An error will be returned and resource validation will fail.

To configure a set of profiles, at least one of which a resource must claim conformance to and be successfully validated against in order to be persisted to the FHIR server, you can use the `fhirServer/resources/<resourceType>/profiles/atLeastOne` configuration parameter. If this configuration parameter is set to a non-empty list of profiles, then the FHIR server will perform the following validation, returning FAILURE if not successful:
* Validate that at least one profile in the list is specified in the resource's `meta.profile` element
* Validate that all profiles specified in the resource's `meta.profile` element are supported by the FHIR server
* Validate that the resource's data conforms to all profiles specified in the resource's `meta.profile` element
Before calling the FHIR validator to validate a resource against the set of profiles specified in its `meta.profile` element that it is claiming conformance to, the following pre-validation will be done for that set of profiles based on the configuration parameters listed above:
1. If the `fhirServer/resources/<resourceType>/profiles/notAllowed` configuration parameter is set to a non-empty list, an error will be returned for any specified profile that is in the list, and validation will fail.
2. If the `fhirServer/resources/<resourceType>/profiles/allowUnknown` configuration parameter is set to `false`, an error will be returned for any specified profile that is not loaded in the FHIR server, and validation will fail.
3. If the `fhirServer/resources/<resourceType>/profiles/atLeastOne` configuration parameter is set to a non-empty list, an error will be returned if none of the specified profiles is in the list, and validation will fail.

If the `fhirServer/resources/<resourceType>/profiles/atLeastOne` configuration parameter is not set or is set to an empty list, then the FHIR server will perform its standard validation.
If the resource passes pre-validation successfully, it will then be passed to the FHIR validator to validate conformance to the specified set of profiles.

To configure a set of profiles to which a resource is *not allowed* to claim conformance and be successfully validated against in order to be persisted to the FHIR server, you can use the `fhirServer/resources/<resourceType>/profiles/notAllowed` configuration parameter. If this configuration parameter is set to a non-empty list of profiles, then the FHIR server will verify that the set of profiles specified in the resource's `meta.profile` element does not include any of the profiles specified in the `fhirServer/resources/<resourceType>/profiles/notAllowed` list. If a matching profile is found, validation will fail for that resource.

If the `fhirServer/resources/<resourceType>/profiles/notAllowed` configuration parameter is not set or is set to an empty list, then the FHIR server will perform its standard validation.

The following example configuration shows how to define the `fhirServer/resources/<resourceType>/profiles/atLeastOne` and `fhirServer/resources/<resourceType>/profiles/notAllowed` configuration parameters:
The following example configuration shows how to define these configuration parameters:
```
{
"fhirServer":{
Expand All @@ -824,7 +823,8 @@ The following example configuration shows how to define the `fhirServer/resource
"atLeastOne": [
"http://ibm.com/fhir/profile/partnerA",
"http://ibm.com/fhir/profile/partnerB|1.0"
]
],
"allowUnknown": false
}
},
"Patient": {
Expand All @@ -841,7 +841,16 @@ The following example configuration shows how to define the `fhirServer/resource
}
```

Given this configuration, in order for an `Observation` resource to be persisted to the FHIR server, the resource's `meta.profile` element must specify either the `http://ibm.com/fhir/profile/partnerA` profile or the `http://ibm.com/fhir/profile/partnerB|1.0` profile or both, and must successfully validate against the specified profiles. In order for a `Patient` resource to be persisted to the FHIR server, the resource's `meta.profile` element cannot specify either the `http://ibm.com/fhir/profile/partnerC` profile or the `http://ibm.com/fhir/profile/partnerD|2.0` profile, and must successfully validate against any profiles that are specified.
Given this configuration, in order for an `Observation` resource to be persisted to the FHIR server:
* the resource's `meta.profile` element must specify either the `http://ibm.com/fhir/profile/partnerA` profile or the `http://ibm.com/fhir/profile/partnerB|1.0` profile or both, based on the `fhirServer/resources/Observation/profiles/atLeastOne` list. Other profiles may be specified as well assuming they pass the following checks.
* the resource's `meta.profile` element must not specify any profile which is not loaded in the FHIR server, based on the `fhirServer/resources/Observation/profiles/allowUnknown` value of `false`
* the resource must successfully validate against all specified profiles

In order for a `Patient` resource to be persisted to the FHIR server:
* the resource's `meta.profile` element cannot specify either the `http://ibm.com/fhir/profile/partnerC` profile or the `http://ibm.com/fhir/profile/partnerD|2.0` profile, based on the `fhirServer/resources/Observation/profiles/notAllowed` list
* the resource must successfully validate against all specified profiles.

Since the `fhirServer/resources/Patient/profiles/allowUnknown` configuration parameter is not specified for `Patient` resources, the default value of `true` is used, meaning a profile that is not loaded in the FHIR server can be specified, and will simply be ignored.

If a profile in either the list specified by the `fhirServer/resources/<resourceType>/profiles/atLeastOne` configuration parameter or the list specified by the `fhirServer/resources/<resourceType>/profiles/notAllowed` configuration parameter contains a version, for example `http://ibm.com/fhir/profile/partner|1.0`, then a profile of the same name specified in the resource's `meta.profile` element will only be considered a match if it contains exactly the same version. However, if a profile in the lists specified by the configuration parameters does not contain a version, for example `http://ibm.com/fhir/profile/partner`, then a profile of the same name specified in the resource's `meta.profile` element will be considered a match whether it contains a version or not. Using the example configuration above for the `Observation` resource type, if the profile `http://ibm.com/fhir/profile/partnerA|3.2` was specified in a resource's `meta.profile` element then it would be considered a match for the `http://ibm.com/fhir/profile/partnerA` profile specified in the `fhirServer/resources/Observation/profiles/atLeastOne` list. Conversely, if the profile `http://ibm.com/fhir/profile/partnerB` was specified in the resource's `meta.profile` element then it would *not* be considered a match for the `http://ibm.com/fhir/profile/partnerB|1.0` profile specified in the `fhirServer/resources/Observation/profiles/atLeastOne` list.

Expand All @@ -851,6 +860,7 @@ See [Validation Guide - Optional profile support](https://ibm.github.io/FHIR/gui

See [Validation Guide - Making profiles available to the fhir registry](https://ibm.github.io/FHIR/guides/FHIRValidationGuide#making-profiles-available-to-the-fhir-registry-component-fhirregistry) for information about how to extend the server with additional Implementation Guide artifacts.


## 4.6 Extending search
In addition to supporting tenant-specific search parameter extensions as described in [Section 3.2.2 Tenant-specific configuration properties](#322-tenant-specific-configuration-properties), the IBM FHIR Server also supports loading
search parameters from the registry.
Expand Down Expand Up @@ -2044,6 +2054,7 @@ This section contains reference information about each of the configuration prop
|`fhirServer/resources/Resource/searchParameterCombinations`|string list|A comma-separated list of search parameter combinations supported for all resource types. Each search parameter combination is a string, where a plus sign, `+`, separates the search parameters that can be used in combination. To indicate that searching without any search parameters is allowed, an empty string must be included in the list. Including an asterisk, `*`, in the list indicates support of any search parameter combination. Individual resource types may override this value via `fhirServer/resources/<resourceType>/searchParameterCombinations`. Omitting this property is equivalent to supporting any search parameter combination.|
|`fhirServer/resources/Resource/profiles/atLeastOne`|string list|A comma-separated list of profiles, at least one of which must be specified in a resource's `meta.profile` element and successfully validated against in order for a resource to be persisted to the FHIR server. Individual resource types may override this value via `fhirServer/resources/<resourceType>/profiles/atLeastOne`. Omitting this property or specifying an empty list is equivalent to not requiring any profile assertions for a resource.|
|`fhirServer/resources/Resource/profiles/notAllowed`|string list|A comma-separated list of profiles that are not allowed to be specified in a resource's `meta.profile` element, and thus cannot be validated against in order for a resource to be persisted to the FHIR server. Individual resource types may override this value via `fhirServer/resources/<resourceType>/profiles/notAllowed`. Omitting this property or specifying an empty list is equivalent to allowing any profile assertions for a resource.|
|`fhirServer/resources/Resource/profiles/allowUnknown`|boolean|Indicates if profiles are allowed to be specified in a resource's `meta.profile` element that are not loaded in the FHIR server. If set to `false`, specifying a profile that is not loaded in the FHIR server results in an error and a resource validation failure. If set to `true`, a warning will be issued and the profile will be ignored. The default value is `true`. Individual resource types may override this value via `fhirServer/resources/<resourceType>/profiles/allowUnknown`.|
|`fhirServer/resources/<resourceType>/interactions`|string list|A list of strings that represent the RESTful interactions (create, read, vread, update, patch, delete, history, and/or search) to support for this resource type. For resources without the property, the value of `fhirServer/resources/Resource/interactions` is used.|
|`fhirServer/resources/<resourceType>/searchParameters`|object|The set of search parameters to support for this resource type. Global search parameters defined on the `Resource` resource can be overridden on a per-resourceType basis.|
|`fhirServer/resources/<resourceType>/searchParameters/<code>`|string|The URL of the search parameter definition to use for the search parameter `<code>` on resources of type `<resourceType>`.|
Expand All @@ -2052,6 +2063,7 @@ This section contains reference information about each of the configuration prop
|`fhirServer/resources/<resourceType>/searchParameterCombinations`|string list|A comma-separated list of search parameter combinations supported for this resource type. Each search parameter combination is a string, where a plus sign, `+`, separates the search parameters that can be used in combination. To indicate that searching without any search parameters is allowed, an empty string must be included in the list. Including an asterisk, `*`, in the list indicates support of any search parameter combination. For resources without the property, the value of `fhirServer/resources/Resource/searchParameterCombinations` is used.|
|`fhirServer/resources/<resourceType>/profiles/atLeastOne`|string list|A comma-separated list of profiles, at least one of which must be specified in a resource's `meta.profile` element and be successfully validated against in order for a resource of this type to be persisted to the FHIR server. If this property is not specified, or if an empty list is specified, the value of `fhirServer/resources/Resource/profiles/atLeastOne` will be used.|
|`fhirServer/resources/<resourceType>/profiles/notAllowed`|string list|A comma-separated list of profiles that are not allowed to be specified in a resource's `meta.profile` element, and thus cannot be validated against in order for a resource to be persisted to the FHIR server. If this property is not specified, or if an empty list is specified, the value of `fhirServer/resources/Resource/profiles/notAllowed` will be used.|
|`fhirServer/resources/<resourceType>/profiles/allowUnknown`|boolean|Indicates if profiles are allowed to be specified in a resource's `meta.profile` element that are not loaded in the FHIR server. If set to `false`, specifying a profile that is not loaded in the FHIR server results in an error and a resource validation failure. If set to `true`, a warning will be issued and the profile will be ignored. If this property is not specified, the value of `fhirServer/resources/Resource/profiles/allowUnknown` will be used.|
|`fhirServer/notifications/common/includeResourceTypes`|string list|A comma-separated list of resource types for which notification event messages should be published.|
|`fhirServer/notifications/common/maxNotificationSizeBytes`|integer|The maximum size in bytes of the notification that should be sent|
|`fhirServer/notifications/common/maxNotificationSizeBehavior`|string|The behavior of the notification framework when a notification is over the maxNotificationSizeBytes. Valid values are subset and omit|
Expand Down Expand Up @@ -2203,6 +2215,7 @@ This section contains reference information about each of the configuration prop
|`fhirServer/resources/Resource/searchParameterCombinations`|null (all search parameter combinations supported)|
|`fhirServer/resources/Resource/profiles/atLeastOne`|null (no resource profile assertions required)|
|`fhirServer/resources/Resource/profiles/notAllowed`|null (any resource profile assertions allowed)|
|`fhirServer/resources/Resource/profiles/allowUnknown`|true|
|`fhirServer/resources/<resourceType>/interactions`|null (inherits from `fhirServer/resources/Resource/interactions`)|
|`fhirServer/resources/<resourceType>/searchParameters`|null (all type-specific search parameters supported)|
|`fhirServer/resources/<resourceType>/searchParameters/<code>`|null|
Expand All @@ -2211,6 +2224,7 @@ This section contains reference information about each of the configuration prop
|`fhirServer/resources/<resourceType>/searchParameterCombinations`|null (inherits from `fhirServer/resources/Resource/searchParameterCombinations`)|
|`fhirServer/resources/<resourceType>/profiles/atLeastOne`|null (inherits from `fhirServer/resources/Resource/profiles/atLeastOne`)|
|`fhirServer/resources/<resourceType>/profiles/notAllowed`|null (inherits from `fhirServer/resources/Resource/profiles/notAllowed`)|
|`fhirServer/resources/<resourceType>/profiles/allowUnknown`|null (inherits from `fhirServer/resources/Resource/profiles/allowUnknown`)|
|`fhirServer/notifications/common/includeResourceTypes`|`["*"]`|
|`fhirServer/notifications/common/maxNotificationSizeBytes`|1000000|
|`fhirServer/notifications/common/maxNotificationSizeBehavior`|subset|
Expand Down Expand Up @@ -2352,6 +2366,7 @@ must restart the server for that change to take effect.
|`fhirServer/resources/Resource/searchParameterCombinations`|Y|Y|
|`fhirServer/resources/Resource/profiles/atLeastOne`|Y|Y|
|`fhirServer/resources/Resource/profiles/notAllowed`|Y|Y|
|`fhirServer/resources/Resource/profiles/allowUnknown`|Y|Y|
|`fhirServer/resources/<resourceType>/interactions`|Y|Y|
|`fhirServer/resources/<resourceType>/searchParameters`|Y|Y|
|`fhirServer/resources/<resourceType>/searchParameters/<code>`|Y|Y|
Expand All @@ -2360,6 +2375,7 @@ must restart the server for that change to take effect.
|`fhirServer/resources/<resourceType>/searchParameterCombinations`|Y|Y|
|`fhirServer/resources/<resourceType>/profiles/atLeastOne`|Y|Y|
|`fhirServer/resources/<resourceType>/profiles/notAllowed`|Y|Y|
|`fhirServer/resources/<resourceType>/profiles/allowUnknown`|Y|Y|
|`fhirServer/notifications/common/includeResourceTypes`|N|N|
|`fhirServer/notifications/common/maxNotificationSizeBytes`|Y|N|
|`fhirServer/notifications/common/maxNotificationSizeBehavior`|Y|N|
Expand Down
1 change: 1 addition & 0 deletions fhir-config/src/main/java/com/ibm/fhir/config/FHIRConfiguration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ public class FHIRConfiguration {
public static final String PROPERTY_FIELD_RESOURCES_PROFILES = "profiles";
public static final String PROPERTY_FIELD_RESOURCES_PROFILES_AT_LEAST_ONE = "atLeastOne";
public static final String PROPERTY_FIELD_RESOURCES_PROFILES_NOT_ALLOWED = "notAllowed";
public static final String PROPERTY_FIELD_RESOURCES_PROFILES_ALLOW_UNKNOWN = "allowUnknown";

// Auth and security properties
public static final String PROPERTY_SECURITY_CORS = "fhirServer/security/cors";
Expand Down
Loading

0 comments on commit 07d8917

Please sign in to comment.