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 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:

{
  "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 to create or update vocabularies:

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:

curl -X GET "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

Bulk Operations

Use bulk vocabulary operations to efficiently manage multiple vocabularies:

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 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

Concepts

Learn about the individual clinical concepts within vocabularies

Clinical Terminology Standards

Understand the major terminology standards like SNOMED CT, ICD, and LOINC

Field Validation

Explore how vocabularies enable data validation

Terminology API

Complete API reference for vocabulary management

About Clinia

Core Concepts

Search

Configuring Data Sources

Configuring Partitions

Managing Data

Master Data Management

Terminology

Identity and Access Management

AI Engine

Vocabularies

Vocabularies

What is a Vocabulary?

Vocabulary Structure

Types of Vocabularies

Standard Vocabularies

Custom Vocabularies

Managing Vocabularies

Creating a Vocabulary

Listing Vocabularies

Bulk Operations

Vocabulary Validation

Concepts

Clinical Terminology Standards

Field Validation

Terminology API

​Vocabularies

​What is a Vocabulary?

​Vocabulary Structure

​Types of Vocabularies

​Standard Vocabularies

​Custom Vocabularies

​Managing Vocabularies

​Creating a Vocabulary

​Listing Vocabularies

​Bulk Operations

​Vocabulary Validation

​Related Concepts

Concepts

Clinical Terminology Standards

Field Validation

Terminology API

Vocabularies

What is a Vocabulary?

Vocabulary Structure

Types of Vocabularies

Standard Vocabularies

Custom Vocabularies

Managing Vocabularies

Creating a Vocabulary

Listing Vocabularies

Bulk Operations

Vocabulary Validation

Related Concepts