---
title: "Add a field descriptor"
method: POST
path: "/resource/descriptors/{resourceDescriptorId}/fields"
tags: ["ResourceDescriptors"]
---

# Add a field descriptor

`POST /resource/descriptors/{resourceDescriptorId}/fields`

Adds a field to a descriptor. Use this to document a CSV column, JSON path, SQL column,
OIDC claim, form field, credential claim, or presentation attribute that can be validated,
mapped, governed, or transformed.

## Path parameters

- `resourceDescriptorId` string, uuid, required — Stable identifier for a described external or internal resource shape.

## Request body

- FieldDescriptorInput — Field definition for a resource descriptor. A field can carry semantic meaning, validation hints, sensitivity, and retention metadata.
  - `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.

## Response `201`

Field descriptor created.

- FieldDescriptor — Field definition for a resource descriptor. A field can carry semantic meaning, validation hints, sensitivity, and retention metadata.
  - `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.

## Other responses

- `400` — Validation error.
- `401` — Authentication is required.
- `404` — The requested resource was not found.

---

[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)