SPsphereon-opensource
SemanticBindings

Create a semantic connector binding

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.

post/semantic/bindings

Request

Request body

connectorInstanceIdstring uuid

Stable platform identifier for a configured connector instance.

resourceDescriptorIdstring uuid required

Stable identifier for a described external or internal resource shape.

fieldDescriptorIdstring uuid

Stable identifier for a field within a resource descriptor.

bindingKindstring required

Binding type, for example ATTRIBUTE, ATTRIBUTE_PROFILE, PARTY_ROLE, RELATIONSHIP_TYPE, POLICY_CLASSIFICATION, or VOCABULARY_TERM.

validationMode'NONE' | 'WARN' | 'ENFORCE'

Whether semantic validation is advisory, enforced, or disabled for this binding.

metadataStringMap

Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

Example request

{
  "connectorInstanceId": "3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5",
  "resourceDescriptorId": "41436f49-040c-4f5f-9c7f-657f43762e2b",
  "fieldDescriptorId": "f00b9edc-5498-483f-9b91-a42ef080b909",
  "bindingKind": "ATTRIBUTE",
  "semanticReference": {
    "referenceType": "semantic-attribute",
    "referenceId": "employee.email",
    "iri": "https://vocab.example.com/employee#email",
    "version": "1.0"
  },
  "validationMode": "ENFORCE"
}

Response

Semantic connector binding created.

connectorInstanceIdstring uuid

Stable platform identifier for a configured connector instance.

resourceDescriptorIdstring uuid required

Stable identifier for a described external or internal resource shape.

fieldDescriptorIdstring uuid

Stable identifier for a field within a resource descriptor.

bindingKindstring required

Binding type, for example ATTRIBUTE, ATTRIBUTE_PROFILE, PARTY_ROLE, RELATIONSHIP_TYPE, POLICY_CLASSIFICATION, or VOCABULARY_TERM.

validationMode'NONE' | 'WARN' | 'ENFORCE'

Whether semantic validation is advisory, enforced, or disabled for this binding.

metadataStringMap

Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

semanticBindingIdstring uuid required

Stable identifier for a semantic binding between resource data and VDX semantics.

createdAtstring date-time required

Creation timestamp.

updatedAtstring date-time required

Last update timestamp.

Example response

{
  "semanticBindingId": "20392e94-3b35-4a77-afc2-5e552a0a4023",
  "connectorInstanceId": "3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5",
  "resourceDescriptorId": "41436f49-040c-4f5f-9c7f-657f43762e2b",
  "fieldDescriptorId": "f00b9edc-5498-483f-9b91-a42ef080b909",
  "bindingKind": "ATTRIBUTE",
  "semanticReference": {
    "referenceType": "semantic-attribute",
    "referenceId": "employee.email",
    "iri": "https://vocab.example.com/employee#email",
    "version": "1.0"
  },
  "validationMode": "ENFORCE",
  "createdAt": "2026-06-18T09:30:00Z",
  "updatedAt": "2026-06-18T09:30:00Z"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.