## On this page

The `$validate-code` operation checks whether a code is a valid member of a specific ValueSet. Unlike CodeSystem validation (which checks if a code exists anywhere in a code system), ValueSet validation confirms that a code is within the specific subset of codes allowed for a particular use-such as the list of valid allergy severity codes or permitted procedure types.

This is critical for enforcing business rules and data quality, ensuring that clinical data conforms to the specific terminology constraints defined for your application's forms and interfaces.

## Use Cases

- **Input Validation**: Ensure user-selected codes or codes from external systems are valid for specific fields or expected ValueSets before processing.
- **Constraint Enforcement**: Validate that incoming data meets ValueSet-based constraints defined in FHIR profiles or implementation guides like US Core.
- **Custom Picklist Validation**: Verify selections against organization-specific ValueSets that subset larger code systems.

## Invoke the `$validate-code` operation

```
[baseUrl]/ValueSet/$validate-code

[baseUrl]/ValueSet/[id]/$validate-code
```

## Parameters

| Name     | Type      | Description                                                              | Required |
|----------|-----------|--------------------------------------------------------------------------|----------|
| `url`    | `uri`     | The canonical URL of the ValueSet to validate against                   | No\*   |
| `code`   | `string`  | The code to look up.                                                    | No       |
| `system` | `string`  | The canonical URL of the code system the code belongs to.              | No       |
| `coding` | `Coding`  | Look up via full Coding.                                               | No       |
| `codeableConcept` | `CodeableConcept` | Look up multiple related codes.                          | No       |
| `display` | `string` | Additionally validate the given display text                            | No       |
| `abstract` | `boolean` | Whether codes labeled as abstract should be included. Abstract codes represent broad categories or groupings rather than specific concepts, e.g. "Vital Signs" | No |

\* If no `url` is provided, the operation must be invoked on a specific `ValueSet` instance.

### Required Parameters

Although no parameters are strictly required by the operation, at least one of the following must be provided:

- Both `code` and `system` parameters (and optionally `display`)
- The `coding` parameter
- The `codeableConcept` parameter with at least one contained `coding`

## Output

The operation returns a `Parameters` resource containing the validation result.

| Name    | Type      | Description                                                  | Required |
|---------|-----------|--------------------------------------------------------------|----------|
| `result`  | `boolean` | Whether or not any given coding is included in the `ValueSet` | Yes      |
| `display` | `string`  | The display text of the included code                        | No       |

### Error Responses

**Example**: Specified `ValueSet` could not be found by URL (400 Bad Request)

```js
{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "details": {
                "text": "ValueSet http://example.com/ValueSet/missing not found"
            }
        }
    ]
}
```

## Examples

**Request**:

- TypeScript
- cURL

```ts
const result = await medplum.post(medplum.fhirUrl('ValueSet', '$validate-code').toString(), {
  resourceType: 'Parameters',
  parameter: [
    { name: 'url', valueUri: 'http://hl7.org/fhir/ValueSet/condition-severity' },
    { name: 'coding', valueCoding: { system: 'http://snomed.info/sct', code: '255604002' } },
  ],
});
```

```bash
curl 'https://api.medplum.com/fhir/R4/ValueSet/$validate-code' \
  -X POST \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer $MY_ACCESS_TOKEN" \
  -d '{"resourceType":"Parameters","parameter":[{"name":"url","valueUri":"http://hl7.org/fhir/ValueSet/condition-severity"},{"name":"coding","valueCoding":{"system":"http://snomed.info/sct","code":"255604002"}}]}'
```

**Response**: (200 OK)

```js
{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "result", "valueBoolean": true },
    { "name": "display", "valueString": "Mild (qualifier value)" }
  ]
}
```