Sharing Valuesets, Codes, and Maps (SVCM)
1.5.2-current - ci-build International flag

Sharing Valuesets, Codes, and Maps (SVCM), published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 1.5.2-current built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/ITI.SVCM/ and changes regularly. See the Directory of published versions

2:3.99 Validate Code [ITI-99]

This section corresponds to transaction [ITI-99] of the IHE IT Infrastructure Technical Framework. Transaction [ITI-99] is used by the Terminology Consumer and Terminology Repository Actors.

2:3.99.1 Scope

This transaction is used by the Terminology Consumer to validate the existence of a given code in a value set or code system. The request is received by the Terminology Repository. The Terminology Repository processes the request and returns a response as a Parameters Resource.

2:3.99.2 Actor Roles

Table 2:3.99.2-1: Actor Roles

Actor: Terminology Consumer
Role: Requests the code to validate from the Terminology Repository.
Actor: Terminology Repository
Role: Returns validation information for the code provided by the Terminology Consumer.

2:3.99.3 Referenced Standards

2:3.99.4 Messages

Terminology ConsumerTerminology RepositoryValidate ValueSet Code Request:HTTP GET <Base>/ValueSet/$validate-codeValidate ValueSet Code Response:ParametersValidate CodeSystem Code Request:HTTP GET <Base>/CodeSystem/$validate-codeValidate CodeSystem Code Response:Parameters

Figure 2:3.99.4-1: Interaction Diagram

2:3.99.4.1 Validate ValueSet Code Request Message

The Validate ValueSet Code Request message is a FHIR $validate-code operation on the ValueSet Resource.

2:3.99.4.1.1 Trigger Events

A Terminology Consumer triggers a Validate ValueSet Code Request to a Terminology Repository according to the business rules for the validation. These business rules are outside the scope of this transaction.

2:3.99.4.1.2 Message Semantics

A Terminology Consumer initiates an $validate-code request using HTTP GET as defined at http://hl7.org/fhir/valueset-operation-validate-code.html on the ValueSet Resource. The required input parameters are identified in Table 3.99.4.1.2-1.

The URL for this operation is: [base]/ValueSet/$validate-code?[parameter=value]

Where [base] is the URL of Terminology Repository.

See ITI TF-2: Appendix W for informative implementation material for this transaction.

Table 2:3.99.4.1.2-1: Validate ValueSet Code Message HTTP Input Parameters

Input Parameter Name IHE Constraint Search Type Description
url
[0..1]
[1..1] uri Value set Canonical URL. The server must know the value set (e.g., it is defined explicitly in the server's value sets, or it is defined implicitly by some code system known to the server.
code
[0..1]
[1..1] code The code that is to be validated. If a code is provided, a system or a context must be provided (if a context is provided, then the server SHALL ensure that the code is not ambiguous without a system).
system
[0..1]
[1..1] uri The system for the code that is to be validated.
_format
[0..1]
[0..1] mime-type The requested format of the response from the mime-type value set. See ITI TF-2: Appendix Z.6.
context
[0..1]
[0..0]
This parameter is not allowed when the url parameter is used.
uri
valueSet
[0..1]
[0..0]
This parameter is not allowed when the url parameter is used.
ValueSet
valueSetVersion
[0..1]
string The identifier that is used to identify a specific version of the value set to be used when validating the code. This is an arbitrary value managed by the value set author and is not expected to be globally unique. For example, it might be a timestamp (e.g., yyyymmdd) if a managed version is not available.
systemVersion
[0..1]
string The version of the system, if one was provided in the source data
display
[0..1]
string The display associated with the code, if provided. If a display is provided a code must be provided. If no display is provided, the server cannot validate the display value, but may choose to return a recommended display name using the display parameter in the outcome. Whether displays are case sensitive is code system dependent
coding
[0..1]
[0..0]
This parameter is not allowed when the code+system parameters are used.
Coding
codeableConcept
[0..1]
[0..0]
This parameter is not allowed when the code+system parameters are used.
CodeableConcept
date
[0..1]
dateTime The date for which the validation should be checked. Normally, this is the current conditions (which is the default values) but under some circumstances, systems need to validate that a correct code was used at some point in the past. A typical example of this would be where code selection is constrained to the set of codes that were available when the patient was treated, not when the record is being edited. Note that which date is appropriate is a matter for implementation policy.
abstract
[0..1]
boolean If this parameter has a value of true, the client is stating that the validation is being performed in a context where a concept designated as 'abstract' is appropriate/allowed to be used, and the server should regard abstract codes as valid. If this parameter is false, abstract codes are not considered to be valid.
Note that 'abstract' is a property defined by many HL7 code systems that indicates that the concept is a logical grouping concept that is not intended to be used as a 'concrete' concept in an actual patient/care/process record. This language is borrowed from Object Oriented theory where 'abstract' objects are never instantiated. However, in the general record and terminology eco-system, there are many contexts where it is appropriate to use these codes e.g., as decision making criterion, or when editing value sets themselves. This parameter allows a client to indicate to the server that it is working in such a context.
displayLanguage
[0..1]
code Specifies the language to be used for description when validating the display property
2:3.99.4.1.3 Expected Actions

The Terminology Repository shall process the input parameters to discover the code in the value set that matches the parameters given and return a response as per Section 2:3.99.4.2 or an OperationOutcome Resource with an error message.

2:3.99.4.2 Validate ValueSet Code Response Message

2:3.99.4.2.1 Trigger Events

The Terminology Repository found validation details of the code matching the input parameters specified by the Terminology Consumer as a result of a Validate ValueSet Code Request.

2:3.99.4.2.2 Message Semantics

See ITI TF-2: Appendix Z.6 for more details on response format handling. See ITI TF-2: Appendix Z.7 for handling guidance for Access Denied.

The response message is a FHIR Parameters Resource with properties of the code set based on the out parameters defined at http://hl7.org/fhir/valueset-operation-validate-code.html and reproduced in Table 2:3.99.4.2.2-1.

Table 2:3.99.4.2.2-1: Validate ValueSet Code Message HTTP Output Parameters

Parameter Name Type Description
result
[1..1]
boolean True if the concept details supplied are valid
message
[0..1]
string Error details, if result = false. If this is provided when result = true, the message carries hints and warnings
display
[0..1]
string A valid display for the concept if the system wishes to display this to a user
2:3.99.4.2.3 Expected Actions

The Terminology Consumer has received the response and continues with its workflow.

2:3.99.4.3 Validate CodeSystem Code Request Message

The Validate CodeSystem Code Request message is a FHIR $validate-code operation on the CodeSystem Resource.

2:3.99.4.3.1 Trigger Events

A Terminology Consumer triggers a Validate CodeSystem Code Request to a Terminology Repository according to the business rules for the validation. These business rules are outside the scope of this transaction.

2:3.99.4.3.2 Message Semantics

A Terminology Consumer initiates an $validate-code request using HTTP GET as defined at http://hl7.org/fhir/codesystem-operation-validate-code.html on the CodeSystem Resource. The required input parameters are identified in Table 2:3.99.4.3.2-1.

The URL for this operation is: [base]/CodeSystem/$validate-code

Where [base] is the URL of Terminology Repository.

See ITI TF-2: Appendix W for informative implementation material for this transaction.

Table 2:3.99.4.3.2-1: Validate CodeSystem Code Message HTTP Input Parameters

Input Parameter Name IHE Constraint Search Type Description
url
[0..1]
[1..1] uri CodeSystem URL. The server must know the code system (e.g., it is defined explicitly in the server's code systems, or it is known implicitly by the server.
code
[0..1]
[1..1] code The code that is to be validated.
_format
[0..1]
mime-type The requested format of the response from the mime-type value set. See ITI TF-2: Appendix Z.6.
codeSystem
[0..1]
[0..0]
This parameter is not allowed when the url parameter is used.
CodeSystem
version
[0..1]
string The version of the code system, if one was provided in the source data.
display
[0..1]
string The display associated with the code, if provided. If a display is provided a code must be provided. If no display is provided, the server cannot validate the display value, but may choose to return a recommended display name in an extension in the outcome. Whether displays are case sensitive is code system dependent.
coding
[0..1]
[0..0]
This parameter is not allowed when the code+url parameters are used.
Coding
codeableConcept
[0..1]
[0..0]
This parameter is not allowed when the code+url parameters are used.
CodeableConcept
date
[0..1]
dateTime The date for which the validation should be checked. Normally, this is the current conditions (which is the default values) but under some circumstances, systems need to validate that a correct code was used at some point in the past. A typical example of this would be where code selection is constrained to the set of codes that were available when the patient was treated, not when the record is being edited. Note that which date is appropriate is a matter for implementation policy.
abstract
[0..1]
boolean If this parameter has a value of true, the client is stating that the validation is being performed in a context where a concept designated as 'abstract' is appropriate/allowed to be used, and the server should regard abstract codes as valid. If this parameter is false, abstract codes are not considered to be valid.
displayLanguage
[0..1]
code Specifies the language to be used for description when validating the display property
2:3.99.4.3.3 Expected Actions

The Terminology Repository shall process the input parameters to discover the code in the code system that matches the parameters given and return a response as per Section 2:3.99.4.4 or an OperationOutcome Resource with an error message.

2:3.99.4.4 Validate CodeSystem Code Response Message

2:3.99.4.4.1 Trigger Events

The Terminology Repository found validation details of the code matching the input parameters specified by the Terminology Consumer as a result of a Validate CodeSystem Code Request.

2:3.99.4.4.2 Message Semantics

See ITI TF-2: Appendix Z.6 for more details on response format handling. See ITI TF-2: Appendix Z.7 for handling guidance for Access Denied.

The response message is a FHIR Parameters Resource with properties of the code set based on the out parameters defined at http://hl7.org/fhir/codesystem-operation-validate-code.html and reproduced in Table 2:3.99.4.4.2-1.

Table 2:3.99.4.4.2-1: Validate CodeSystem Code Message HTTP Output Parameters

Parameter Name Type Description
result
[1..1]
boolean True if the concept details supplied are valid
message
[0..1]
string Error details, if result = false. If this is provided when result = true, the message carries hints and warnings
display
[0..1]
string A valid display for the concept if the system wishes to display this to a user
2:3.99.4.4.3 Expected Actions

The Terminology Consumer has received the response and continues with its workflow.

2:3.99.5 Security Considerations

See the general Security Consideration in ITI TF-1: 51.5.

2:3.99.5.1 Security Audit Considerations

Note that the same audit message is recorded by both Terminology Consumer and Repository. The difference being the Audit Source element. Both sides record to show consistency between the message sent by the Consumer and the action taken at the Registry.

The actors involved shall record audit events according to the Audit Event for Validate Code by the Terminology Consumer and Repository.