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

# Validate Mappings

> Validate the accuracy and quality of OMOP concept mappings between vocabularies - verify translations before committing them to source_to_concept_map.

## Overview

This endpoint validates concept mappings between vocabularies, checking for concept validity, domain compatibility, and relationship correctness. It returns a validation score and identifies potential issues with each mapping.

## Request Body

<ParamField body="mappings" type="array" required>
  Array of concept mappings to validate (1-100 items)

  <Expandable title="mappings">
    <ParamField body="source_concept_id" type="integer" required>
      The source OMOP concept ID
    </ParamField>

    <ParamField body="target_concept_id" type="integer" required>
      The target OMOP concept ID to validate mapping to
    </ParamField>

    <ParamField body="mapping_type" type="string" required>
      The relationship type of the mapping (e.g., "Maps to", "Maps to value", "direct")
    </ParamField>
  </Expandable>
</ParamField>

## Query Parameters

<ParamField query="vocab_release" type="string">
  Specific vocabulary release version (e.g., "2025.1")
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="array" required>
  Array of validation results matching the input order

  <Expandable title="data">
    <ResponseField name="source_concept_id" type="integer">
      The source concept ID that was validated
    </ResponseField>

    <ResponseField name="target_concept_id" type="integer">
      The target concept ID that was validated
    </ResponseField>

    <ResponseField name="mapping_type" type="string">
      The mapping relationship type that was validated
    </ResponseField>

    <ResponseField name="is_valid" type="boolean">
      Whether the mapping is considered valid (validation\_score >= 0.50)
    </ResponseField>

    <ResponseField name="validation_score" type="number">
      Overall validation score (0.0-1.0). Score starts at 1.0 and is reduced based on issues found.
    </ResponseField>

    <ResponseField name="issues" type="array">
      Array of validation issue descriptions (strings)
    </ResponseField>

    <ResponseField name="recommendations" type="array">
      Array of recommendations to improve the mapping (strings)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  Response metadata and API information

  <Expandable title="meta">
    <ResponseField name="request_id" type="string">
      Unique request identifier for debugging
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the response
    </ResponseField>

    <ResponseField name="vocab_release" type="string">
      Vocabulary release version used
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.omophub.com/v1/mappings/validate" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mappings": [
        {
          "source_concept_id": 201826,
          "target_concept_id": 443735,
          "mapping_type": "Maps to"
        },
        {
          "source_concept_id": 4182210,
          "target_concept_id": 320128,
          "mapping_type": "Maps to"
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.omophub.com/v1/mappings/validate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      mappings: [
        {
          source_concept_id: 201826,
          target_concept_id: 443735,
          mapping_type: "Maps to"
        }
      ]
    })
  });

  const result = await response.json();
  for (const validation of result.data) {
    console.log(`${validation.source_concept_id} → ${validation.target_concept_id}`);
    console.log(`  Valid: ${validation.is_valid}, Score: ${validation.validation_score}`);
    if (validation.issues.length > 0) {
      console.log(`  Issues: ${validation.issues.join(', ')}`);
    }
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.omophub.com/v1/mappings/validate",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "mappings": [
              {
                  "source_concept_id": 201826,
                  "target_concept_id": 443735,
                  "mapping_type": "Maps to"
              }
          ]
      }
  )

  result = response.json()
  for validation in result["data"]:
      print(f"{validation['source_concept_id']} → {validation['target_concept_id']}")
      print(f"  Valid: {validation['is_valid']}, Score: {validation['validation_score']}")
      if validation["issues"]:
          print(f"  Issues: {', '.join(validation['issues'])}")
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "source_concept_id": 201826,
        "target_concept_id": 443735,
        "mapping_type": "Maps to",
        "is_valid": true,
        "validation_score": 0.85,
        "issues": [],
        "recommendations": []
      },
      {
        "source_concept_id": 4182210,
        "target_concept_id": 320128,
        "mapping_type": "Maps to",
        "is_valid": false,
        "validation_score": 0.40,
        "issues": [
          "No direct mapping relationship exists",
          "Domain mismatch between concepts"
        ],
        "recommendations": [
          "Verify mapping relationship type is correct",
          "Consider using a target concept in the same domain"
        ]
      }
    ],
    "meta": {
      "request_id": "req_validate_abc123",
      "timestamp": "2024-12-22T10:00:00Z",
      "vocab_release": "2025.2"
    }
  }
  ```
</ResponseExample>

## Validation Scoring

The validation score starts at 1.0 (100%) and is reduced based on issues found:

| Issue                                   | Score Reduction |
| --------------------------------------- | --------------- |
| Invalid source concept                  | -0.40           |
| Invalid target concept                  | -0.40           |
| Domain mismatch                         | -0.20           |
| Standard to non-standard mapping        | -0.15           |
| No relationship exists between concepts | -0.25           |

A mapping is considered **valid** when `validation_score >= 0.50`.

## Related Endpoints

* [Get Concept Mappings](/api-reference/mappings/get-concept-mappings) - Get mappings for a concept
* [Batch Map Concepts](/api-reference/mappings/batch-map-concepts) - Map multiple concepts at once