ValueSet Profile
This ValueSet profile is part of the set of resource profiles supported by the API Server used with the athenaPractice 12.3 and athenaFlow 9.12 products. It further describes read and search capabilities of these products. Note: The create and update operations are NOT supported for this resource.
Overview
This resource represents a collection of vocabulary valuesused within various resources created or used by the API Server
Scope and Usage
This profile is used to define the content that will be returned by the API Server in response to requests to access ValueSet resources. All elements listed in the differential profile view are Supported, which means that the API Server is capable of supplying these fields from the product database when they have been populated via the product or its APIs.
The ValueSet resource provides information about code systems used by the API Server, and athenaPractice, athenaFlow and site specific coding systems used in the products. The content is derived from an external file created during system installation.
Supported Operations
The operations supported by this resource are listed below.
Read Operation
Read operations are executed as specified in the HL7 FHIR RESTful API implementation definition. To read a ValueSet, an application shall perform an HTTP GET, specifying the identifier of the resources being retrieved.
GET [base]/fhir/ValueSet/[id]{?_format=[json|xml]&_summary=[true|data]}
Read Operation Parameters
| Parameter | Description |
|---|---|
| [base] | Specifies the base URL of the FHIR Server, e.g., https://cpsapisandbox.virenceaz.com:9443/demoAPIServer |
| [id] | Specifies the identifier of the ValueSet resource to retrieve |
| [_format] | Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request. |
| [_summary] | Filters the output to include only summary elements (_summary=true) or to omit the generated narrative (_summary=data). Note: If the generated html narrative for the resource is not going to be used by the call, using _summary=data provides slightly improved API response times. |
Read Operation HTTP Response Codes
| Response Code | Description |
|---|---|
| 200 OK | The requested resource was found and is contained within the body of the HTTP response. |
| 401 Unauthorized | Authorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required. |
| 404 Not Found | The requested resource does not exist. The body of the HTTP response will contain an OperationOutcome resource that indicates that the resource could not be found. |
| 500 Server Error | The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error. |
Search Operation
ValueSet resources can be enumerated by retrieving the fhir/List resource with an id of ValueSet
GET [base]/fhir/List/ValueSet?{_format=[json|xml]&_summary=[true|text|data]}
Search Operation Parameters
| Parameter | Description |
|---|---|
| [base] | Specifies the base URL of the FHIR Server, e.g., https://cpsapisandbox.virenceaz.com:9443/demoAPIServer |
| [_count] | Specifies the maximum number of search results to return in a single query. Note: The count of results does not limit the number of additional resources returned via the _include parameter. No more than max-results ValueSet resources which match the search criteria will be returned. The API Server has default and maximum limits for the value that can be specified for this parameter. These limits may vary depending upon the client application vendors participation level in the AthenaHealth Partner program. Note: The API Server support the HL7 FHIR Paging capability. |
| [_format] | Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request. |
| [_summary] | Filters the output to include only narrative elements (_summary=text), summary elements (_summary=true) or to omit the generated narrative (_summary=data). Note: If the generated html narrative for the resource is not going to be used by the call, using _summary=data provides improved API response times, especially when returning larger result sets. |
Search Operation HTTP Response Codes
| Response Code | Description |
|---|---|
| 200 OK | The query was performed and any results found are contained within the body of the HTTP response. Note: The search API will return 200 OK when the query itself is successful, regardless of whether or not any matching results were found. |
| 401 Unauthorized | Authorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required. |
| 500 Server Error | The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error. |
Other Operations
This Implementation guide defines 3 operations:
| $expand | Value Set Expansion |
| $lookup | Concept Look Up |
| $validate-code | Value Set based Validation |
For more information about operations, including how they are invoked, see Operations .
Value Set Expansion
The definition of a value set is used to create a simple collection of codes suitable for use for data entry or validation. If the operation is not called at the instance level, one of the in parameters identifier, context or valueset must be provided. An expanded value set will be returned, or an OperationOutcome with an error message.
GET [base]/$expand?{operation-parameters}GET [base]/$expand?{operation-parameters}| In Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| filter | 0..1 | string | A text filter that is applied to restrict the codes that are returned (this is useful in a UI context). The interpretation of this is delegated to the server in order to allow to determine the most optimal search approach for the context | ||
| count | 0..1 | integer | Paging support - how many codes should be provided in a partial view. Paging only applies to flat expansions - servers ignore paging if the expansion is not flat. If count = 0, the client is asking how large the expansion is. Servers SHOULD honor this request for hierarchical expansions as well, and simply return the overall count | ||
| Out Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| return | 1..1 | ValueSet | The result of the expansion Note: as this the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource | ||
The value set expansion returned by this query should be treated as a transient result that will change over time (whether it does or not depends on how the value set is specified), so applications should repeat the operation each time the value set is used. Clients can work through large flat expansions in a set of pages (partial views of the full expansion) instead of just getting the full expansion in a single exchange by using offset and count parameters. Servers are not obliged to support paging, but if they do, SHALL support both the offset and count parameters. Hierarchical expansions are not subject to paging and servers simply return the entire expansion. Different servers may return different results from expanding a value set for the following reasons: * The underlying code systems are different (e.g. different versions, possibly with different defined behavior) * The server optimizes filter includes differently, such as sorting by code frequency * Servers introduce arbitrary groups to assist a user to navigate the lists based either on extensions in the definition, or additional knowledge available to the server
Concept Look Up
Given a code/system, or a Coding, get additional details about the concept
GET [base]/$lookup?{operation-parameters}| In Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| code | 0..1 | code | The code that is to be validated. If a code is provided, a system must be provided | ||
| system | 0..1 | uri | The system for the code that is to be validated | ||
| Out Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| name | 1..1 | string | A display name for the code system | ||
| display | 1..1 | string | The preferred display for this concept | ||
Note that the $lookup operation is more than just a value set search - the server finds the concept, and gathers the return information from the value set and the underlying code system definitions.
Value Set based Validation
Validate that a coded value is in the set of codes allowed by a value set. If the operation is not called at the instance level, one of the in parameters "identifier" or "valueset" must be provided. One (and only one) of the in parameters (code, coding, codeableConcept) must be provided. The operation returns a result (true / false), an error message, and the recommended display for the code
GET [base]/$validate-code?{operation-parameters}GET [base]/$validate-code?{operation-parameters}| In Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| code | 0..1 | code | The code that is to be validated. If a code is provided, a system must be provided | ||
| system | 1..1 | uri | The system for the code that is to be validated | ||
| Out Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| result | 1..1 | boolean | True if the concept details supplied are valid | ||
| display | 0..1 | string | A valid display for the concept if the system wishes to display this to a user | ||
Profile Content
The official URL for this profile is:
http://hl7.org/fhir/StructureDefinition/valueset-profile
A set of codes drawn from one or more code systems
| Name | Flags | Card. | Type | Description & Constraints | |
|---|---|---|---|---|---|
  ValueSet | I | 0..* | ValueSet | A set of codes drawn from one or more code systems vsd-7: A defined code system (if present) SHALL have a different url than the value set url vsd-2: A value set with only one import SHALL also have an include and/or an exclude unless the value set includes and inline code system vsd-5: Value set SHALL contain at least one of a codeSystem, a compose, or an expansion element | |
 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: IETF BCP-47  (required ) | ||
| text | I | 0..1 | Narrative | Text summary of the resource, for human interpretation | |
| contained | 0..* | Resource | Contained, inline Resources | ||
 extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| url | ∑ | 0..1 | uri | Globally unique logical identifier for value set | |
 identifier | ∑ | 0..1 | Identifier | Additional identifier for the value set (e.g. HL7 v2 / CDA) | |
| version | ∑ | 0..1 | string | Logical identifier for this version of the value set | |
| name | ∑ | 0..1 | string | Informal name for this value set | |
| status | ?! S∑ | 1..1 | code | draft | active | retired Binding: ConformanceResourceStatus (required ) | |
| experimental | ∑ | 0..1 | boolean | If for testing purposes, not real usage | |
| publisher | ∑ | 0..1 | string | Name of the publisher (organization or individual) | |
| contact | ∑ | 0..* | BackboneElement | Contact details of the publisher | |
 extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| name | ∑ | 0..1 | string | Name of an individual to contact | |
 telecom | ∑ | 0..* | ContactPoint | Contact details for individual or publisher | |
| date | ∑ | 0..1 | dateTime | Date for given status | |
| lockedDate | ∑ | 0..1 | date | Fixed date for all referenced code systems and value sets | |
| description | ∑ | 0..1 | string | Human language description of the value set | |
| useContext | ∑ | 0..* | CodeableConcept | Content intends to support these contexts Binding: Context of Use ValueSet (extensible ) | |
| immutable | ∑ | 0..1 | boolean | Indicates whether or not any change to the content logical definition may occur | |
| requirements | 0..1 | string | Why needed | ||
| copyright | 0..1 | string | Use and/or publishing restrictions | ||
| extensible | ∑ | 0..1 | boolean | Whether this is intended to be used with an extensible binding | |
| codeSystem | ∑ I | 0..1 | BackboneElement | An inline code system, which is part of this value set vsd-8: Codes must be unique vsd-3: Within a code system definition, all the codes SHALL be unique | |
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| system | ∑ | 1..1 | uri | URI to identify the code system (e.g. in Coding.system) | |
| version | ∑ | 0..1 | string | Version (for use in Coding.version) | |
| caseSensitive | ∑ | 0..1 | boolean | If code comparison is case sensitive | |
| concept | 1..* | BackboneElement | Concepts in the code system | ||
 extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| code | 1..1 | code | Code that identifies concept | ||
| abstract | 0..1 | boolean | If this code is not for use as a real concept | ||
| display | 0..1 | string | Text to display to the user | ||
| definition | 0..1 | string | Formal definition | ||
| designation | 0..* | BackboneElement | Additional representations for the concept | ||
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| language | 0..1 | code | Human language of the designation Binding: IETF BCP-47 (required ) | ||
| use | 0..1 | Coding | Details how this designation would be used Binding: Designation Use (extensible ) | ||
| value | 1..1 | string | The text value for this designation | ||
 concept | 0..* | Child Concepts (is-a/contains/categorizes) | |||
| compose | I | 0..1 | BackboneElement | When value set includes codes from elsewhere vsd-1: A value set composition SHALL have an include or an import | |
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| import | ∑ I | 0..* | uri | Import the contents of another value set | |
| include | ∑ I | 0..* | BackboneElement | Include one or more codes from a code system vsd-11: Cannot have both concept and filter | |
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| system | ∑ | 1..1 | uri | The system the codes come from | |
| version | ∑ | 0..1 | string | Specific version of the code system referred to | |
| concept | I | 0..* | BackboneElement | A concept defined in the system | |
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| code | 1..1 | code | Code or expression from system | ||
| display | 0..1 | string | Test to display for this code for this value set | ||
| designation | 0..* | Additional representations for this valueset | |||
| filter | I | 0..* | BackboneElement | Select codes/concepts by their properties (including relationships) | |
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| property | 1..1 | code | A property defined by the code system | ||
| op | 1..1 | code | = | is-a | is-not-a | regex | in | not-in Binding: FilterOperator (required ) | ||
| value | 1..1 | code | Code from the system, or regex criteria | ||
| exclude | I | 0..* | Explicitly exclude codes | ||
| expansion | I | 0..1 | BackboneElement | Used when the value set is "expanded" | |
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| identifier | 1..1 | uri | Uniquely identifies this expansion | ||
| timestamp | 1..1 | dateTime | Time ValueSet expansion happened | ||
| total | 0..1 | integer | Total number of codes in the expansion | ||
| offset | 0..1 | integer | Offset at which this resource starts | ||
| parameter | 0..* | BackboneElement | Parameter that controlled the expansion process | ||
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| name | 1..1 | string | Name as assigned by the server | ||
 value[x] | 0..1 | string , boolean , integer , decimal , uri , code | Value of the named parameter | ||
| contains | I | 0..* | BackboneElement | Codes in the value set vsd-6: SHALL have a code or a display vsd-9: Must have a code if not abstract vsd-10: Must have a system if a code is present | |
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| system | 0..1 | uri | System value for the code | ||
| abstract | 0..1 | boolean | If user cannot select this entry | ||
| version | 0..1 | string | Version in which this code/display is defined | ||
| code | I | 0..1 | code | Code - if blank, this is not a selectable code | |
| display | I | 0..1 | string | User display for the concept | |
| contains | 0..* | Codes contained under this entry | |||