---
title: "Create a semantic connector binding"
method: POST
path: "/semantic/bindings"
tags: ["SemanticBindings"]
---

# Create a semantic connector binding

`POST /semantic/bindings`

Creates a semantic binding for a connector resource or field. This is the link that allows
validation, documentation, mapping, and future policy checks to reason over external data
using the same semantic model as credential designs, forms, parties, and relationships.

## Request body

- SemanticConnectorBindingCreateRequest — Request to bind connector resource data to a semantic model reference. Bindings may apply to a resource, a field, or a connector-specific view of a resource.
  - `connectorInstanceId` string, uuid — Stable platform identifier for a configured connector instance.
  - `resourceDescriptorId` string, uuid, required — Stable identifier for a described external or internal resource shape.
  - `fieldDescriptorId` string, uuid — Stable identifier for a field within a resource descriptor.
  - `bindingKind` string, required — Binding type, for example ATTRIBUTE, ATTRIBUTE_PROFILE, PARTY_ROLE, RELATIONSHIP_TYPE, POLICY_CLASSIFICATION, or VOCABULARY_TERM.
  - `semanticReference` SemanticReference — Reference to a semantic catalog, profile, attribute, relationship type, policy classification, or vocabulary term.
    - `referenceType` string, required — Semantic model reference type.
    - `referenceId` string, required — Stable semantic reference id.
    - `iri` string — Optional IRI for RDF/JSON-LD and vocabulary alignment.
    - `version` string — Optional semantic reference version.
  - `validationMode` 'NONE' | 'WARN' | 'ENFORCE' — Whether semantic validation is advisory, enforced, or disabled for this binding.
  - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

## Response `201`

Semantic connector binding created.

- SemanticConnectorBinding — Request to bind connector resource data to a semantic model reference. Bindings may apply to a resource, a field, or a connector-specific view of a resource.
  - `connectorInstanceId` string, uuid — Stable platform identifier for a configured connector instance.
  - `resourceDescriptorId` string, uuid, required — Stable identifier for a described external or internal resource shape.
  - `fieldDescriptorId` string, uuid — Stable identifier for a field within a resource descriptor.
  - `bindingKind` string, required — Binding type, for example ATTRIBUTE, ATTRIBUTE_PROFILE, PARTY_ROLE, RELATIONSHIP_TYPE, POLICY_CLASSIFICATION, or VOCABULARY_TERM.
  - `semanticReference` SemanticReference — Reference to a semantic catalog, profile, attribute, relationship type, policy classification, or vocabulary term.
    - `referenceType` string, required — Semantic model reference type.
    - `referenceId` string, required — Stable semantic reference id.
    - `iri` string — Optional IRI for RDF/JSON-LD and vocabulary alignment.
    - `version` string — Optional semantic reference version.
  - `validationMode` 'NONE' | 'WARN' | 'ENFORCE' — Whether semantic validation is advisory, enforced, or disabled for this binding.
  - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
  - `semanticBindingId` string, uuid, required — Stable identifier for a semantic binding between resource data and VDX semantics.
  - `createdAt` string, date-time, required — Creation timestamp.
  - `updatedAt` string, date-time, required — Last update timestamp.

## Other responses

- `400` — Validation error.
- `401` — Authentication is required.

---

[API](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api.md) · [All operations](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sphereon-opensource/connector-integration-profile-api/revisions/60cb8c70871b/schema)