---
title: "Validate an import mapping"
method: POST
path: "/v1/collections/import/validate-mapping"
tags: ["Collections"]
---

# Validate an import mapping

`POST /v1/collections/import/validate-mapping`

Validate a finalized source->target mapping before any import. Flags a missing root-identity mapping, source/target type mismatches, vector-dim mismatches against a known index, and unknown source fields.

## Request body

- MappingValidationRequest — Request body for POST /v1/collections/import/validate-mapping.
  - `source_fields` SourceField[] — The declared source fields.
    - `path` string, required
    - `type` 'string' | 'integer' | 'float' | 'boolean' | 'datetime' | 'vector' | 'object' | 'null', required
  - `mapping` ImportMapping, required — The finalized mapping. This IS the import config.
    - `fields` FieldMapping[]
      - `source_field` string, required
      - `target` MappingTarget, required — Where a source field lands in the Mixpeek document.
        - `kind` 'metadata' | 'vector' | 'identity' | 'parent' | 'ignore', required — metadata | vector | identity | parent | ignore
        - `path` string, nullable — Target path for kind=metadata (e.g. 'metadata.brand').
        - `index` string, nullable — Vector index name for kind=vector.
        - `dim` integer, nullable — Vector dimension for kind=vector.
        - `dtype` string, nullable — Source vector dtype for kind=vector (e.g. 'float16-base64').
        - `role` 'root_object_id' | 'root_bucket_id' | 'source_object_id' | 'source_document_id' | 'source_collection_id' | 'document_id' | 'content_hash', nullable — Lineage role for kind=identity.
        - `chain_position` integer, nullable — Position in chain[] for kind=parent.
        - `expected_type` 'string' | 'integer' | 'float' | 'boolean' | 'datetime' | 'vector' | 'object' | 'null', nullable — The source type this target requires. When set and the inferred source type differs, validate_mapping flags it (unhappy case f).
    - `source_type` 'bucket' | 'collection', nullable
    - `chain_template` object, nullable
  - `known_index_dims` object, nullable — Known target vector index dims, for dim-mismatch checks.

## Response `200`

Successful Response

- MappingValidationResult
  - `ok` boolean, required
  - `errors` MappingValidationError[]
    - `field` string, nullable — Source field the error is about; None for whole-mapping errors.
    - `error` string, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/f507f74ec843/schema)