---
title: "Create a resource descriptor"
method: POST
path: "/resource/descriptors"
tags: ["ResourceDescriptors"]
---

# Create a resource descriptor

`POST /resource/descriptors`

Creates a reusable descriptor for data that can flow through connectors. Use this for CSV
rows, REST payloads, OIDC claim sets, SQL tables, vault objects, forms, workflow payloads,
credentials, presentations, and future resource types.

## Request body

- ResourceDescriptorCreateRequest — Request to describe a resource shape independently from any connector instance or transport. A descriptor can later be attached to one or more connectors.
  - `displayName` string, required — Human-readable resource descriptor name.
  - `description` string — Description of the logical resource and intended use.
  - `resourceKind` 'OBJECT' | 'TABULAR' | 'DOCUMENT' | 'CLAIM_SET' | 'GRAPH' | 'EVENT_STREAM' | 'FILE' | 'SECRET' | 'CONFIGURATION' | 'CREDENTIAL' | 'PRESENTATION' | 'CUSTOM', required — Logical kind of resource being accessed, independent of transport and serialization. For example, a CSV file with rows is ResourceKind TABULAR and RepresentationKind CSV.
  - `representationKind` 'JSON' | 'JSON_LD' | 'XML' | 'CSV' | 'PARQUET' | 'AVRO' | 'RDF' | 'JWT' | 'SD_JWT' | 'CBOR' | 'BINARY' | 'TEXT' | 'CUSTOM', required — Data representation or serialization format, independent of transport. This is the data shape on the wire or at rest, not the connector implementation.
  - `shapeKind` 'SCHEMA' | 'OPENAPI_SCHEMA' | 'JSON_SCHEMA' | 'RDF_SHAPE' | 'SQL_TABLE' | 'CSV_HEADER' | 'CLAIMS_SCHEMA' | 'FREEFORM' — Type of structural shape information used to describe fields and validation rules for a resource.
  - `contract` ContractRef — Reference to the schema, contract, or discovery document that defines or constrains a resource. The contract is descriptive; transport is still represented by AccessProtocol.
    - `contractKind` 'OPENAPI' | 'JSON_SCHEMA' | 'SQL_SCHEMA' | 'RDF_SCHEMA' | 'CSV_PROFILE' | 'OIDC_DISCOVERY' | 'VAULT_POLICY' | 'CUSTOM', required — Contract or schema source used to describe an external resource. Use this to point at OpenAPI documents, JSON Schema, SQL metadata, RDF shapes, CSV profiles, OIDC discovery, or custom contracts.
    - `uri` string — URI or locator for the contract document.
    - `version` string — Contract version understood by the connector.
    - `contentHash` string — Optional hash of the contract content for integrity and drift detection.
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
  - `fields` FieldDescriptorInput[] — Field-level shape, validation, semantic, and retention information.
    - `fieldPath` string, required — Path or column name within the resource representation.
    - `displayName` string — Human-readable field name.
    - `valueType` string, required — Logical value type, for example string, number, boolean, date, datetime, object, array, or binary.
    - `required` boolean — Whether the field is required for validation and mapping.
    - `multiValued` boolean — Whether the field can hold multiple values.
    - `semanticAttributeId` string, uuid — Optional semantic attribute binding used for validation, governance, and policy.
    - `sensitivity` string — Optional sensitivity or classification label used by governance and policy checks.
    - `retention` RetentionSpec — Retention metadata used by governance and future compliance checks. It can be applied to fields, resources, materialized data, or dead-letter payloads.
      - `purpose` string — Processing purpose.
      - `legalBasis` string — Legal or contractual basis for retention.
      - `retentionPeriod` string — ISO-8601 duration, for example P30D or P7Y.
      - `deleteAction` 'DELETE' | 'ANONYMIZE' | 'PSEUDONYMIZE' | 'TOMBSTONE' | 'REVIEW' — Action to apply when retention expires or deletion is required by policy.
      - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
  - `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`

Resource descriptor created.

- ResourceDescriptor — Request to describe a resource shape independently from any connector instance or transport. A descriptor can later be attached to one or more connectors.
  - `displayName` string, required — Human-readable resource descriptor name.
  - `description` string — Description of the logical resource and intended use.
  - `resourceKind` 'OBJECT' | 'TABULAR' | 'DOCUMENT' | 'CLAIM_SET' | 'GRAPH' | 'EVENT_STREAM' | 'FILE' | 'SECRET' | 'CONFIGURATION' | 'CREDENTIAL' | 'PRESENTATION' | 'CUSTOM', required — Logical kind of resource being accessed, independent of transport and serialization. For example, a CSV file with rows is ResourceKind TABULAR and RepresentationKind CSV.
  - `representationKind` 'JSON' | 'JSON_LD' | 'XML' | 'CSV' | 'PARQUET' | 'AVRO' | 'RDF' | 'JWT' | 'SD_JWT' | 'CBOR' | 'BINARY' | 'TEXT' | 'CUSTOM', required — Data representation or serialization format, independent of transport. This is the data shape on the wire or at rest, not the connector implementation.
  - `shapeKind` 'SCHEMA' | 'OPENAPI_SCHEMA' | 'JSON_SCHEMA' | 'RDF_SHAPE' | 'SQL_TABLE' | 'CSV_HEADER' | 'CLAIMS_SCHEMA' | 'FREEFORM' — Type of structural shape information used to describe fields and validation rules for a resource.
  - `contract` ContractRef — Reference to the schema, contract, or discovery document that defines or constrains a resource. The contract is descriptive; transport is still represented by AccessProtocol.
    - `contractKind` 'OPENAPI' | 'JSON_SCHEMA' | 'SQL_SCHEMA' | 'RDF_SCHEMA' | 'CSV_PROFILE' | 'OIDC_DISCOVERY' | 'VAULT_POLICY' | 'CUSTOM', required — Contract or schema source used to describe an external resource. Use this to point at OpenAPI documents, JSON Schema, SQL metadata, RDF shapes, CSV profiles, OIDC discovery, or custom contracts.
    - `uri` string — URI or locator for the contract document.
    - `version` string — Contract version understood by the connector.
    - `contentHash` string — Optional hash of the contract content for integrity and drift detection.
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
  - `fields` object[] — Stored field descriptors for this resource descriptor.
    - `fieldPath` string, required — Path or column name within the resource representation.
    - `displayName` string — Human-readable field name.
    - `valueType` string, required — Logical value type, for example string, number, boolean, date, datetime, object, array, or binary.
    - `required` boolean — Whether the field is required for validation and mapping.
    - `multiValued` boolean — Whether the field can hold multiple values.
    - `semanticAttributeId` string, uuid — Optional semantic attribute binding used for validation, governance, and policy.
    - `sensitivity` string — Optional sensitivity or classification label used by governance and policy checks.
    - `retention` RetentionSpec — Retention metadata used by governance and future compliance checks. It can be applied to fields, resources, materialized data, or dead-letter payloads.
      - `purpose` string — Processing purpose.
      - `legalBasis` string — Legal or contractual basis for retention.
      - `retentionPeriod` string — ISO-8601 duration, for example P30D or P7Y.
      - `deleteAction` 'DELETE' | 'ANONYMIZE' | 'PSEUDONYMIZE' | 'TOMBSTONE' | 'REVIEW' — Action to apply when retention expires or deletion is required by policy.
      - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `fieldDescriptorId` string, uuid, required — Stable identifier for a field within a resource descriptor.
  - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
  - `resourceDescriptorId` string, uuid, required — Stable identifier for a described external or internal resource shape.
  - `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)