> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vocabularies

> Understanding vocabularies as containers for clinical terminology concepts in Clinia

# Vocabularies

A **vocabulary** is a collection of related clinical concepts organized under a specific terminology system. In Clinia, vocabularies serve as containers that group [concepts](/explanation/concepts) from the same standard or organization.

## What is a Vocabulary?

Vocabularies provide the organizational structure for terminology systems, ensuring that related clinical concepts are grouped together logically. They act as the top-level containers in Clinia's terminology hierarchy.

**Key characteristics:**

* **Unique identifier**: Each vocabulary has a unique key (e.g., `snomed-ct`, `icd-10`)
* **Metadata**: Includes title, description, and version information
* **Scope**: Contains concepts from a single terminology system
* **Management**: Can be standard (SNOMED CT, ICD, LOINC) or custom organizational vocabularies

## Vocabulary Structure

A vocabulary in Clinia contains the following properties:

| Property      | Type     | Description                                                       |
| ------------- | -------- | ----------------------------------------------------------------- |
| `key`         | `string` | Unique identifier for the vocabulary, provided as a URL parameter |
| `title`       | `string` | Human-readable name of the vocabulary                             |
| `description` | `string` | Detailed description of the vocabulary's purpose and scope        |

**Example payload:**

```json theme={null}
{
  "title": "SNOMED CT International Edition",
  "description": "Systematized Nomenclature of Medicine Clinical Terms - comprehensive clinical terminology covering diseases, procedures, anatomy, and clinical findings"
}
```

## Types of Vocabularies

### Standard Vocabularies

These are established, internationally recognized terminology systems:

* **SNOMED CT**: Comprehensive clinical terminology
* **ICD-10/ICD-11**: International Classification of Diseases
* **LOINC**: Laboratory and clinical observations
* **RxNorm**: Medication terminologies
* **CPT**: Current Procedural Terminology

### Custom Vocabularies

Organizations can create custom vocabularies for:

* **Internal coding systems**: Organization-specific clinical codes
* **Local terminologies**: Regional or specialty-specific concepts
* **Value sets**: Curated subsets of standard terminologies
* **Custom mappings**: Translations between different systems

## Managing Vocabularies

### Creating a Vocabulary

Use the [upsert vocabulary endpoint](/api-reference/vocabularies/upsert-a-vocabulary-in-the-terminology) to create or update vocabularies:

```bash theme={null}
curl -X PUT "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/{vocabularyKey}" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Custom Clinical Terminology",
    "description": "Organization-specific clinical codes and concepts"
  }'
```

### Listing Vocabularies

Retrieve all available vocabularies in your workspace:

```bash theme={null}
curl -X GET "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"
```

### Bulk Operations

Use [bulk vocabulary operations](/api-reference/vocabularies/bulk-upsert-or-delete-vocabularies) to efficiently manage multiple vocabularies:

```bash theme={null}
curl -X POST "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/bulk" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "action": "UPSERT",
        "upsert": {
          "key": "custom-vocab-1",
          "title": "Custom Vocabulary 1",
          "description": "First custom vocabulary"
        }
      }
    ]
  }'
```

## Vocabulary Validation

Vocabularies play a crucial role in [data validation](/explanation/field-validation/vocabulary) by:

* **Providing scope**: Defining which concepts are valid within a specific domain
* **Ensuring consistency**: Maintaining standardized representations across systems
* **Enabling validation rules**: Supporting field validation based on vocabulary membership

## Related Concepts

<CardGroup cols={2}>
  <Card title="Concepts" icon="lightbulb" href="/explanation/concepts">
    Learn about the individual clinical concepts within vocabularies
  </Card>

  <Card title="Clinical Terminology Standards" icon="book-medical">
    Understand the major terminology standards like SNOMED CT, ICD, and LOINC
  </Card>

  <Card title="Field Validation" icon="shield-check" href="/explanation/field-validation/vocabulary">
    Explore how vocabularies enable data validation
  </Card>

  <Card title="Terminology API" icon="code" href="/api-reference/vocabularies/list-all-the-vocabularies-in-the-terminology">
    Complete API reference for vocabulary management
  </Card>
</CardGroup>