Skip to main content

​
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:
PropertyTypeDescription
keystringUnique identifier for the vocabulary, provided as a URL parameter
titlestringHuman-readable name of the vocabulary
descriptionstringDetailed 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