connector-components.yml

openapi: 3.0.4
info:
  title: Connector Components
  version: 0.1.0
  description: Shared schemas, parameters, and request bodies for the Connector Registry API.

components:
  parameters:
    ConnectorInstanceId:
      name: connectorInstanceId
      in: path
      description: Stable identifier of the configured connector instance. This is not the Party id; the connector instance has its own id and points at its backing Party.
      required: true
      schema:
        $ref: '#/components/schemas/ConnectorInstanceId'
      example: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
    IdentityId:
      name: identityId
      in: path
      description: Stable Identity id assigned to the connector Party. Identifiers remain nested under the Identity.
      required: true
      schema:
        $ref: '#/components/schemas/IdentityId'
      example: 3a5cf979-2d89-4057-a721-c7ab884f0c68
    ResourceDescriptorId:
      name: resourceDescriptorId
      in: path
      description: Stable identifier of the resource descriptor that describes the shape, representation, and semantic meaning of a connector resource.
      required: true
      schema:
        $ref: '#/components/schemas/ResourceDescriptorId'
      example: 41436f49-040c-4f5f-9c7f-657f43762e2b
    BindingId:
      name: bindingId
      in: path
      description: Stable identifier of an operation binding, such as a configured source read or destination write operation.
      required: true
      schema:
        $ref: '#/components/schemas/OperationBindingId'
      example: 2777417e-82ce-4d3e-b96c-94e00a4d9a93
    TransformationId:
      name: transformationId
      in: path
      description: Stable identifier of a reusable transformation between resource descriptors.
      required: true
      schema:
        $ref: '#/components/schemas/TransformationId'
      example: 0e60abcc-41b5-4cc5-bec2-f0047f129341
    RouteId:
      name: routeId
      in: path
      description: Stable identifier of a connector route that composes a source operation, destination operation, optional transformation, and trigger policy.
      required: true
      schema:
        $ref: '#/components/schemas/ConnectorRouteId'
      example: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
    RunId:
      name: runId
      in: path
      description: Stable identifier of a connector route or operation execution.
      required: true
      schema:
        $ref: '#/components/schemas/ConnectorRunId'
      example: 9a785884-63ea-4b07-9976-264a1fc595f1
    InvocationBindingId:
      name: invocationBindingId
      in: path
      description: Stable identifier of a connector invocation binding.
      required: true
      schema:
        $ref: '#/components/schemas/ConnectorInvocationBindingId'
      example: issuer-config-1:post-issuance:proof-vault
    LogicalConnectionBindingId:
      name: logicalConnectionBindingId
      in: path
      description: Stable identifier of a logical connection binding.
      required: true
      schema:
        $ref: '#/components/schemas/LogicalConnectionBindingId'
      example: brand-a-proof-vault
    ExposureDescriptorId:
      name: exposureDescriptorId
      in: path
      description: Stable identifier of a route exposure descriptor.
      required: true
      schema:
        $ref: '#/components/schemas/RouteExposureDescriptorId'
    RouteExposureGrantId:
      name: grantId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/RouteExposureGrantId'
      example: proof-vault-read-exposure
    DataProductId:
      name: dataProductId
      in: path
      description: Stable identifier of a connector data product descriptor.
      required: true
      schema:
        $ref: '#/components/schemas/ConnectorDataProductId'
      example: dp-proof-status
    Role:
      name: role
      in: query
      description: Filters connectors or attached resources by data-flow role.
      required: false
      schema:
        $ref: '#/components/schemas/DataFlowRole'
      example: SOURCE
    OperationKind:
      name: operationKind
      in: query
      description: Filters by the logical operation taxonomy, independent of the transport-specific operation name.
      required: false
      schema:
        $ref: '#/components/schemas/OperationKind'
      example: READ
    ResourceKind:
      name: resourceKind
      in: query
      description: Filters by logical resource kind. This does not imply a transport or serialization format.
      required: false
      schema:
        $ref: '#/components/schemas/ResourceKind'
      example: TABULAR
    ConnectorType:
      name: connectorType
      in: query
      description: Filters by extensible connector runtime family, for example http.openapi, sql.postgresql, identity.oidc, storage.vault, storage.blob, interaction.form, or internal.party-semantic-store. CSV remains a representation kind, not a connector type.
      required: false
      schema:
        $ref: '#/components/schemas/ConnectorType'
      example: http.openapi
    ConnectorRunStatus:
      name: status
      in: query
      description: Filters connector executions by lifecycle status.
      required: false
      schema:
        $ref: '#/components/schemas/ConnectorRunStatus'
      example: FAILED
    RouteIdQuery:
      name: routeId
      in: query
      description: Filters connector executions by route id.
      required: false
      schema:
        $ref: '#/components/schemas/ConnectorRouteId'
      example: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
    ConnectorInstanceIdQuery:
      name: connectorInstanceId
      in: query
      description: Filters connector executions by the registry connector instance id.
      required: false
      schema:
        $ref: '#/components/schemas/ConnectorInstanceId'
      example: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
    InvocationBindingIdQuery:
      name: invocationBindingId
      in: query
      description: Filters connector executions by Phase 5 invocation binding lineage.
      required: false
      schema:
        $ref: '#/components/schemas/ConnectorInvocationBindingId'
      example: issuer-config-1:post-issuance:proof-vault
    LogicalConnectionBindingIdQuery:
      name: logicalConnectionBindingId
      in: query
      description: Filters connector executions by logical connection binding lineage.
      required: false
      schema:
        $ref: '#/components/schemas/LogicalConnectionBindingId'
      example: brand-a-proof-vault
    PhysicalConnectorInstanceIdQuery:
      name: physicalConnectorInstanceId
      in: query
      description: Filters connector executions by physical connector instance lineage.
      required: false
      schema:
        $ref: '#/components/schemas/ConnectorInstanceId'
      example: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
    ConnectorExchangeModeQuery:
      name: exchangeMode
      in: query
      description: Filters connector executions by the Phase 5 data-direction and initiation-side quadrant.
      required: false
      schema:
        $ref: '#/components/schemas/ConnectorExchangeMode'
      example: PLATFORM_INITIATED_PUSH
    ProtocolSurfaceQuery:
      name: protocolSurface
      in: query
      description: Filters connector executions by the product, protocol, form, portal, workflow, or application surface that initiated the run.
      required: false
      schema:
        $ref: '#/components/schemas/ConnectorOwnerSurface'
      example: OID4VCI
    CorrelationIdQuery:
      name: correlationId
      in: query
      description: Filters connector executions by durable route-run correlation id.
      required: false
      schema:
        type: string
      example: route-correlation-1

  schemas:
    ConnectorInstanceId:
      type: string
      format: uuid
      description: Stable platform identifier for a configured connector instance.
      example: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
    ConnectorPartyId:
      type: string
      format: uuid
      description: Party identifier assigned to the connector instance.
      example: f9c97b4e-e756-4b70-b230-6f1d9f81b426
    PartyId:
      type: string
      format: uuid
      description: Existing Party model identifier.
      example: 7f23f56e-c24d-4cbe-839d-5fc09048a851
    IdentityId:
      type: string
      format: uuid
      description: Existing Identity model identifier.
      example: 3a5cf979-2d89-4057-a721-c7ab884f0c68
    IdentifierId:
      type: string
      format: uuid
      description: Existing Identifier model identifier.
      example: 6b1c4c89-dfe0-4ce2-b8a4-2e1d57343a6c
    ResourceDescriptorId:
      type: string
      format: uuid
      description: Stable identifier for a described external or internal resource shape.
      example: 41436f49-040c-4f5f-9c7f-657f43762e2b
    ConnectorId:
      type: string
      format: uuid
      description: Stable identifier for a connector instance.
      example: 5f1b2f49-1397-44a7-bf5e-11340b4777c7
    FieldDescriptorId:
      type: string
      format: uuid
      description: Stable identifier for a field within a resource descriptor.
      example: f00b9edc-5498-483f-9b91-a42ef080b909
    ConnectorResourceId:
      type: string
      format: uuid
      description: Stable identifier for a resource attached to a connector instance.
      example: b4cf21b1-0292-4803-8d32-9ebf9f5359a2
    OperationBindingId:
      type: string
      format: uuid
      description: Stable identifier for a connector operation binding.
      example: 2777417e-82ce-4d3e-b96c-94e00a4d9a93
    SemanticBindingId:
      type: string
      format: uuid
      description: Stable identifier for a semantic binding between resource data and VDX semantics.
      example: 20392e94-3b35-4a77-afc2-5e552a0a4023
    TransformationId:
      type: string
      format: uuid
      description: Stable identifier for a transformation definition.
      example: 0e60abcc-41b5-4cc5-bec2-f0047f129341
    ConnectorRouteId:
      type: string
      format: uuid
      description: Stable identifier for a connector route.
      example: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
    ConnectorRunId:
      type: string
      format: uuid
      description: Stable identifier for a connector route or operation run.
      example: 9a785884-63ea-4b07-9976-264a1fc595f1
    ConnectorInvocationBindingId:
      type: string
      description: Stable identifier of the domain invocation binding that caused a connector call.
      example: issuer-config-1:post-issuance:proof-vault
    LogicalConnectionBindingId:
      type: string
      description: Stable identifier of a tenant, OU, brand, legal-entity, or channel usage binding for a physical connector instance.
      example: brand-a-proof-vault
    RouteExposureDescriptorId:
      type: string
      description: Stable identifier of an externally callable route exposure descriptor.
      example: proof-vault-read-exposure
    RouteExposureGrantId:
      type: string
      description: Stable identifier of a route exposure grant.
      example: grant-proof-vault-reader
    ConnectorDataProductId:
      type: string
      description: Stable identifier of a connector data product descriptor.
      example: dp-proof-status
    ConnectorType:
      type: string
      description: Extensible connector family identifier. This names the connector implementation or adapter family, not the transport, resource kind, or representation.
      example: http.openapi
    TenantId:
      type: string
      description: Tenant identifier used by tenant-scoped connector registration, routing, and execution.
      example: acme

    DataFlowRole:
      type: string
      description: How a connector participates in data movement. Use SOURCE for reads and DESTINATION for writes. Connectors that support both roles declare both values in supportedRoles.
      enum:
        - SOURCE
        - DESTINATION
      example: SOURCE
    ConnectorLifecycleStatus:
      type: string
      description: Lifecycle state of a connector instance in the connector registry.
      enum:
        - DRAFT
        - ACTIVE
        - SUSPENDED
        - RETIRED
      example: ACTIVE
    ConnectorManagementMode:
      type: string
      description: Indicates whether the platform manages connector runtime/configuration or references an externally managed system. Runtime placement is described separately by runtimeMode.
      enum:
        - MANAGED
        - EXTERNAL
      example: EXTERNAL
    ConnectorRuntimeMode:
      type: string
      description: Indicates where execution happens when a connector operation is invoked.
      enum:
        - HOSTED
        - REMOTE_AGENT
        - EXTERNAL_CALLBACK
      example: REMOTE_AGENT
    ConnectorExchangeMode:
      type: string
      description: Explicit exchange quadrant. Data direction and initiation side remain separate axes in run responses.
      enum:
        - PLATFORM_INITIATED_PULL
        - PLATFORM_INITIATED_PUSH
        - EXTERNALLY_INITIATED_READ
        - EXTERNALLY_INITIATED_WRITE
        - SUBSCRIPTION_CALLBACK
        - BIDIRECTIONAL_SYNC
      example: PLATFORM_INITIATED_PUSH
    ConnectorDataDirection:
      type: string
      description: Direction of data movement relative to the platform operating the connector.
      enum:
        - INBOUND
        - OUTBOUND
        - BIDIRECTIONAL
      example: OUTBOUND
    ConnectorInitiationSide:
      type: string
      description: Side that initiated the exchange.
      enum:
        - PLATFORM
        - EXTERNAL
        - SUBSCRIPTION_CALLBACK
        - BIDIRECTIONAL_SYNC
      example: PLATFORM
    ConnectorOwnerSurface:
      type: string
      description: Product, protocol, form, portal, workflow, or application surface that owns a connector invocation binding.
      enum:
        - OID4VCI
        - OID4VP
        - FORM
        - PORTAL
        - WORKFLOW
        - APPLICATION
      example: OID4VCI
    ConnectorInvocationStage:
      type: string
      description: Product or protocol lifecycle stage at which a connector invocation can run.
      enum:
        - OID4VCI_START
        - OID4VCI_AUTHORIZATION
        - OID4VCI_PRE_AUTHORIZED
        - OID4VCI_TOKEN
        - OID4VCI_CREDENTIAL_REQUEST
        - OID4VCI_DEFERRED
        - OID4VCI_PRE_ISSUE
        - OID4VCI_POST_ISSUANCE
        - OID4VCI_NOTIFICATION_RECEIPT
        - OID4VP_AFTER_VALIDATION
        - OID4VP_PRE_REQUEST_ENRICHMENT
        - FORM_LIFECYCLE
        - FORM_ACTION_START
        - FORM_ACTION_COMPLETE
        - FORM_FIELD_LOOKUP
        - FORM_SUBMIT
        - PORTAL_FLOW
        - WORKFLOW_STEP_EXECUTION
      example: OID4VCI_CREDENTIAL_REQUEST
    ConnectorInvocationRole:
      type: string
      description: Role the connector performs for a lifecycle invocation.
      enum:
        - ENRICHMENT_SOURCE
        - EXPORT_DESTINATION
        - VAULT_RETENTION
        - NOTIFICATION
        - BIDIRECTIONAL_SYNC
        - ROUTE_ORCHESTRATION
      example: VAULT_RETENTION
    ConnectorExecutionTiming:
      type: string
      description: Timing contract for connector invocation execution.
      enum:
        - INLINE_REQUIRED
        - INLINE_OPTIONAL
        - DEFERRED_ASYNC
        - DURABLE_OUTBOX
      example: INLINE_REQUIRED
    ConnectorFailureEffect:
      type: string
      description: How connector invocation failure affects the owning protocol, form, portal, or workflow.
      enum:
        - FAIL_PROTOCOL
        - CONTINUE_WITHOUT_EFFECT
        - DEAD_LETTER
        - QUARANTINE
        - RETRY_ONLY
      example: FAIL_PROTOCOL
    ConnectorDiscriminatorSource:
      type: string
      description: Source of a logical connection discriminator value.
      enum:
        - LOGICAL_CONTEXT
        - AUTHENTICATED_CONTEXT
        - PAYLOAD_FIELD
        - STATIC_VALUE
      example: LOGICAL_CONTEXT
    ConnectorDiscriminatorPlacement:
      type: string
      description: Where a logical connection discriminator is applied to an outbound connector request.
      enum:
        - HEADER
        - QUERY
        - BODY_FIELD
        - CONFIG
        - METADATA
      example: HEADER
    ConnectorAuthOverlayMode:
      type: string
      description: Authentication overlay mode for a logical connection binding.
      enum:
        - USE_PHYSICAL_BASE
        - TENANT_SECRET_REF
        - DELEGATED_OAUTH_CLIENT
        - MTLS_IDENTITY
        - CONNECTOR_CREDENTIAL_SELECTOR
      example: TENANT_SECRET_REF
    ConnectorDeploymentMode:
      type: string
      description: Deployment mode projected into the system catalog for a logical connection binding.
      enum:
        - MANAGED
        - EXTERNAL
        - HYBRID
      example: HYBRID
    ConnectorAuditCategory:
      type: string
      description: Audit category used by governed connector invocations, runs, and externally callable route exposures.
      enum:
        - PROTOCOL_ISSUANCE
        - PROTOCOL_VERIFICATION
        - FORM
        - PORTAL
        - WORKFLOW
        - DATASPACE
        - INDUSTRIAL
        - EXTERNAL_EXCHANGE
        - VAULT
        - SYSTEM_CATALOG
      example: EXTERNAL_EXCHANGE
    OperationKind:
      type: string
      description: Reusable operation taxonomy shared by connectors, inventory, policy, and workflows. The operation kind is logical; connector-local details live in operationName.
      enum:
        - READ
        - WRITE
        - UPDATE
        - DELETE
        - UPSERT
        - QUERY
        - SEARCH
        - IMPORT
        - EXPORT
        - INVOKE
        - DISCOVER
        - VALIDATE
      example: READ
    OperationTransferMode:
      type: string
      description: Transfer semantics for an operation binding. Streaming and batching are execution modes of a logical operation, not operation kinds.
      enum:
        - SINGLE
        - BATCH
        - STREAM
      default: SINGLE
      example: STREAM
    AccessProtocol:
      type: string
      description: "Transport or access protocol. This is intentionally separate from ResourceKind and RepresentationKind: for example, CSV data can be read over HTTPS, S3, SFTP, FILE, or VAULT."
      enum:
        - HTTP
        - HTTPS
        - JDBC
        - ODBC
        - SFTP
        - FILE
        - S3
        - AZURE_BLOB
        - GCS
        - KAFKA
        - AMQP
        - MQTT
        - OIDC
        - DIDCOMM
        - VAULT
        - INTERNAL
        - CUSTOM
      example: HTTPS
    ResourceKind:
      type: string
      description: Logical kind of resource being accessed, independent of transport and serialization. For example, a CSV file with rows is ResourceKind TABULAR and RepresentationKind CSV.
      enum:
        - OBJECT
        - TABULAR
        - DOCUMENT
        - CLAIM_SET
        - GRAPH
        - EVENT_STREAM
        - FILE
        - SECRET
        - CONFIGURATION
        - CREDENTIAL
        - PRESENTATION
        - CUSTOM
      example: TABULAR
    RepresentationKind:
      type: string
      description: Data representation or serialization format, independent of transport. This is the data shape on the wire or at rest, not the connector implementation.
      enum:
        - JSON
        - JSON_LD
        - XML
        - CSV
        - PARQUET
        - AVRO
        - RDF
        - JWT
        - SD_JWT
        - CBOR
        - BINARY
        - TEXT
        - CUSTOM
      example: CSV
    ShapeKind:
      type: string
      description: Type of structural shape information used to describe fields and validation rules for a resource.
      enum:
        - SCHEMA
        - OPENAPI_SCHEMA
        - JSON_SCHEMA
        - RDF_SHAPE
        - SQL_TABLE
        - CSV_HEADER
        - CLAIMS_SCHEMA
        - FREEFORM
      example: CSV_HEADER
    ContractKind:
      type: string
      description: 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.
      enum:
        - OPENAPI
        - JSON_SCHEMA
        - SQL_SCHEMA
        - RDF_SCHEMA
        - CSV_PROFILE
        - OIDC_DISCOVERY
        - VAULT_POLICY
        - CUSTOM
      example: OPENAPI
    BindingDirection:
      type: string
      description: Direction of data movement represented by an operation binding.
      enum:
        - INBOUND
        - OUTBOUND
        - BIDIRECTIONAL
      example: INBOUND
    TransformationLanguage:
      type: string
      description: Transformation representation used by a transformation definition.
      enum:
        - ATTRIBUTE_MAPPER
        - JSONATA
        - JQ
        - CEL
        - SQL
        - TEMPLATE
        - CUSTOM
      example: ATTRIBUTE_MAPPER
    MaterializationMode:
      type: string
      description: How, if at all, connector data may be retained or projected into platform storage.
      enum:
        - NONE
        - CACHE
        - PERSIST
        - MIRROR
        - INDEX
      example: PERSIST
    SecretBindingMode:
      type: string
      description: How credentials are referenced. Secret values are never sent inline through this API.
      enum:
        - SECRET_REF
        - VAULT_KEY
        - EXTERNAL_SECRET_REF
      example: SECRET_REF
    ConnectorRunStatus:
      type: string
      description: Execution status of a route run or connector operation run.
      enum:
        - QUEUED
        - RUNNING
        - SUCCEEDED
        - FAILED
        - PARTIALLY_FAILED
        - CANCELLED
      example: SUCCEEDED
    RouteAtomicity:
      type: string
      description: Failure and rollback semantics expected for a route run.
      enum:
        - BEST_EFFORT
        - PER_RECORD
        - ALL_OR_NOTHING
      example: PER_RECORD
    DestinationDeliveryMode:
      type: string
      description: Delivery timing and batching behavior expected by a destination operation binding.
      enum:
        - SYNC
        - ASYNC
        - BATCH
        - STREAMING
      example: BATCH
    DestinationAckMode:
      type: string
      description: Acknowledgement level a destination must provide before the platform treats delivery as complete.
      enum:
        - NONE
        - ACCEPTED
        - COMMITTED
        - VERIFIED
      example: COMMITTED
    RetentionDeleteAction:
      type: string
      description: Action to apply when retention expires or deletion is required by policy.
      enum:
        - DELETE
        - ANONYMIZE
        - PSEUDONYMIZE
        - TOMBSTONE
        - REVIEW
      example: ANONYMIZE

    ConnectorInstanceCreateRequest:
      type: object
      description: Request to register a connector instance and create or link the backing Party. Identity data is required so the connector aggregate is Party-backed at creation time.
      required:
        - displayName
        - connectorType
        - supportedRoles
        - identities
      properties:
        displayName:
          type: string
          minLength: 1
          description: Human-readable name shown in administrative UIs and audit trails.
          example: Workday employee profile API
        description:
          type: string
          description: Operational purpose of the connector instance.
          example: Reads employee profile attributes used for employee credential issuance.
        connectorType:
          $ref: '#/components/schemas/ConnectorType'
        managementMode:
          $ref: '#/components/schemas/ConnectorManagementMode'
        runtimeMode:
          $ref: '#/components/schemas/ConnectorRuntimeMode'
        partyId:
          $ref: '#/components/schemas/PartyId'
        supportedRoles:
          type: array
          description: Data-flow roles supported by this connector instance.
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/DataFlowRole'
          example: [SOURCE]
        supportedOperations:
          type: array
          description: Logical operations this connector instance can perform.
          uniqueItems: true
          items:
            $ref: '#/components/schemas/OperationKind'
          example: [READ, QUERY, DISCOVER]
        identities:
          type: array
          description: Identities assigned to the connector Party. Exactly one identity must be marked as default. Each identity must reference an existing identity or include at least one identifier.
          minItems: 1
          items:
            $ref: '#/components/schemas/ConnectorIdentityInput'
        endpoints:
          type: array
          description: Runtime endpoints exposed or consumed by this connector instance.
          items:
            $ref: '#/components/schemas/ConnectorEndpointInput'
        credentials:
          type: array
          description: Credential references used by the connector. Secret values are never sent inline.
          items:
            $ref: '#/components/schemas/ConnectorCredentialRef'
        configBindings:
          type: array
          description: Platform settings bindings that hold non-secret connector configuration and secret reference prefixes.
          items:
            $ref: '#/components/schemas/ConnectorConfigBindingRef'
        defaultAccessProtocol:
          $ref: '#/components/schemas/AccessProtocol'
        defaultEgressPolicy:
          $ref: '#/components/schemas/EgressPolicy'
        defaultMaterializationPolicy:
          $ref: '#/components/schemas/MaterializationPolicy'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        displayName: Workday employee profile API
        description: Reads employee profile attributes used for employee credential issuance.
        connectorType: http.openapi
        managementMode: EXTERNAL
        runtimeMode: REMOTE_AGENT
        supportedRoles: [SOURCE]
        supportedOperations: [READ, QUERY, DISCOVER]
        identities:
          - identityRole: external-system
            displayName: Workday tenant acme-prod
            isDefault: true
            identifiers:
              - identifierType: DNS_NAME
                value: hr.example.com
                isPrimary: true
                isVerified: true
              - identifierType: SYSTEM_ID
                value: workday:acme-prod
                isPrimary: false
                isVerified: true
        endpoints:
          - endpointRole: data
            accessProtocol: HTTPS
            uri: https://hr.example.com/api/v1
            isPrimary: true
        credentials:
          - bindingMode: SECRET_REF
            secretRef: secret://tenant/acme/connectors/workday/oauth-client
            credentialType: oauth2-client
            label: Workday OAuth client
        configBindings:
          - settingsScope: service-instance
            settingsKeyPrefix: connector.workday.acme-prod
        defaultAccessProtocol: HTTPS
        metadata:
          owner_team: people-ops

    ConnectorInstanceUpdateRequest:
      type: object
      description: Partial update for connector instance metadata, lifecycle status, supported operations, and default policies. Omitted fields remain unchanged.
      properties:
        displayName:
          type: string
          description: Updated display name.
          example: Workday employee profile API
        description:
          type: string
          description: Updated operational description.
          example: Reads employee profile attributes through the regional HR integration.
        lifecycleStatus:
          $ref: '#/components/schemas/ConnectorLifecycleStatus'
        managementMode:
          $ref: '#/components/schemas/ConnectorManagementMode'
        runtimeMode:
          $ref: '#/components/schemas/ConnectorRuntimeMode'
        supportedRoles:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/DataFlowRole'
        supportedOperations:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/OperationKind'
        defaultAccessProtocol:
          $ref: '#/components/schemas/AccessProtocol'
        defaultEgressPolicy:
          $ref: '#/components/schemas/EgressPolicy'
        defaultMaterializationPolicy:
          $ref: '#/components/schemas/MaterializationPolicy'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        lifecycleStatus: ACTIVE
        supportedOperations: [READ, QUERY, DISCOVER]
        metadata:
          owner_team: people-ops
          support_queue: hr-integrations

    ConnectorInstance:
      type: object
      description: Registered connector instance with its own stable id and a backing Party id. Runtime credentials are represented only as references.
      required:
        - connectorInstanceId
        - partyId
        - displayName
        - connectorType
        - lifecycleStatus
        - supportedRoles
        - createdAt
        - updatedAt
      properties:
        connectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        partyId:
          $ref: '#/components/schemas/ConnectorPartyId'
        displayName:
          type: string
          description: Human-readable name of the connector instance.
          example: Workday employee profile API
        description:
          type: string
          description: Operational purpose of the connector instance.
          example: Reads employee profile attributes used for employee credential issuance.
        connectorType:
          $ref: '#/components/schemas/ConnectorType'
        lifecycleStatus:
          $ref: '#/components/schemas/ConnectorLifecycleStatus'
        managementMode:
          $ref: '#/components/schemas/ConnectorManagementMode'
        runtimeMode:
          $ref: '#/components/schemas/ConnectorRuntimeMode'
        defaultAccessProtocol:
          $ref: '#/components/schemas/AccessProtocol'
        supportedRoles:
          type: array
          items:
            $ref: '#/components/schemas/DataFlowRole'
        supportedOperations:
          type: array
          items:
            $ref: '#/components/schemas/OperationKind'
        identities:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorIdentity'
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorEndpoint'
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorCredentialRef'
        configBindings:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorConfigBindingRef'
        defaultEgressPolicy:
          $ref: '#/components/schemas/EgressPolicy'
        defaultMaterializationPolicy:
          $ref: '#/components/schemas/MaterializationPolicy'
        metadata:
          $ref: '#/components/schemas/StringMap'
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp.
          example: '2026-06-18T08:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp.
          example: '2026-06-18T08:45:00Z'
      example:
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        partyId: f9c97b4e-e756-4b70-b230-6f1d9f81b426
        displayName: Workday employee profile API
        description: Reads employee profile attributes used for employee credential issuance.
        connectorType: http.openapi
        lifecycleStatus: ACTIVE
        managementMode: EXTERNAL
        runtimeMode: REMOTE_AGENT
        defaultAccessProtocol: HTTPS
        supportedRoles: [SOURCE]
        supportedOperations: [READ, QUERY, DISCOVER]
        identities:
          - identityId: 3a5cf979-2d89-4057-a721-c7ab884f0c68
            identityRole: external-system
            displayName: Workday tenant acme-prod
            isDefault: true
            identifiers:
              - identifierId: 6b1c4c89-dfe0-4ce2-b8a4-2e1d57343a6c
                identifierType: DNS_NAME
                value: hr.example.com
                isPrimary: true
                isVerified: true
        endpoints:
          - endpointId: 27d8bfc5-6c75-4e4e-a78a-63ad7a924cb1
            endpointRole: data
            accessProtocol: HTTPS
            uri: https://hr.example.com/api/v1
            isPrimary: true
        credentials:
          - bindingMode: SECRET_REF
            secretRef: secret://tenant/acme/connectors/workday/oauth-client
            credentialType: oauth2-client
            label: Workday OAuth client
        configBindings:
          - settingsScope: service-instance
            settingsKeyPrefix: connector.workday.acme-prod
        metadata:
          owner_team: people-ops
        createdAt: '2026-06-18T08:30:00Z'
        updatedAt: '2026-06-18T08:45:00Z'

    ConnectorIdentityInput:
      type: object
      description: Identity assignment for the connector Party. Use existingIdentityId to link an existing Identity, or provide displayName and identifiers to create a connector-specific Identity.
      required:
        - identityRole
      properties:
        identityRole:
          type: string
          description: Role of this Identity for the connector Party, for example technical-account, issuer, relying-party, or external-system.
        displayName:
          type: string
          description: Display name for the connector identity.
          example: Workday tenant acme-prod
        existingIdentityId:
          $ref: '#/components/schemas/IdentityId'
        isDefault:
          type: boolean
          description: Whether this identity is the default identity for connector operations that do not select a specific identity.
          default: false
          example: true
        identifiers:
          type: array
          description: Identifiers attached to this Identity. Identifiers are not attached directly to the connector.
          minItems: 1
          items:
            $ref: '#/components/schemas/ConnectorIdentifierInput'
      example:
        identityRole: external-system
        displayName: Workday tenant acme-prod
        isDefault: true
        identifiers:
          - identifierType: DNS_NAME
            value: hr.example.com
            isPrimary: true
            isVerified: true
          - identifierType: SYSTEM_ID
            value: workday:acme-prod
            isPrimary: false
            isVerified: true

    ConnectorIdentity:
      type: object
      description: Identity assigned to the connector Party, including its nested identifiers.
      required:
        - identityId
        - identityRole
        - isDefault
      properties:
        identityId:
          $ref: '#/components/schemas/IdentityId'
        identityRole:
          type: string
          description: Role of this Identity for the connector Party.
          example: external-system
        displayName:
          type: string
          description: Display name for the connector identity.
          example: Workday tenant acme-prod
        isDefault:
          type: boolean
          description: Whether this is the default identity for the connector.
          example: true
        identifiers:
          type: array
          description: Identifiers attached to this Identity.
          items:
            $ref: '#/components/schemas/ConnectorIdentifier'
      example:
        identityId: 3a5cf979-2d89-4057-a721-c7ab884f0c68
        identityRole: external-system
        displayName: Workday tenant acme-prod
        isDefault: true
        identifiers:
          - identifierId: 6b1c4c89-dfe0-4ce2-b8a4-2e1d57343a6c
            identifierType: DNS_NAME
            value: hr.example.com
            isPrimary: true
            isVerified: true

    ConnectorIdentifierInput:
      type: object
      description: Identifier attached to a connector Identity. Use this for DNS names, URLs, DID identifiers, OIDC issuers, client ids, system ids, or other Party identifier types.
      required:
        - identifierType
        - value
      properties:
        identifierType:
          type: string
          description: Existing Party Identifier type, for example DNS_NAME, URL, DID, OIDC_ISSUER, EMAIL, CLIENT_ID, or SYSTEM_ID.
        value:
          type: string
          description: Identifier value.
          example: hr.example.com
        isPrimary:
          type: boolean
          description: Whether this is the preferred identifier for its type on the Identity.
          default: false
          example: true
        isVerified:
          type: boolean
          description: Whether the platform has verified or administratively accepted this identifier.
          default: false
          example: true
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        identifierType: DNS_NAME
        value: hr.example.com
        isPrimary: true
        isVerified: true
        metadata:
          verification_method: dns-control

    ConnectorIdentifier:
      description: Stored identifier attached to a connector Identity.
      allOf:
        - $ref: '#/components/schemas/ConnectorIdentifierInput'
        - type: object
          required:
            - identifierId
          properties:
            identifierId:
              $ref: '#/components/schemas/IdentifierId'
      example:
        identifierId: 6b1c4c89-dfe0-4ce2-b8a4-2e1d57343a6c
        identifierType: DNS_NAME
        value: hr.example.com
        isPrimary: true
        isVerified: true

    ConnectorEndpointInput:
      type: object
      description: Endpoint or address used by a connector. The endpoint says how to reach the connector; resource descriptors say what data is exchanged.
      required:
        - accessProtocol
      properties:
        endpointRole:
          type: string
          description: Role of this endpoint, for example management, data, discovery, callback, token, or webhook.
        accessProtocol:
          $ref: '#/components/schemas/AccessProtocol'
        uri:
          type: string
          description: Endpoint URI, JDBC URL, bucket URI, file root, queue address, or connector-specific locator.
          example: https://hr.example.com/api/v1
        isPrimary:
          type: boolean
          description: Whether this endpoint is the default endpoint for its role.
          default: false
          example: true
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        endpointRole: data
        accessProtocol: HTTPS
        uri: https://hr.example.com/api/v1
        isPrimary: true
        metadata:
          region: eu-west

    ConnectorEndpoint:
      description: Stored connector endpoint.
      allOf:
        - $ref: '#/components/schemas/ConnectorEndpointInput'
        - type: object
          required:
            - endpointId
          properties:
            endpointId:
              type: string
              format: uuid
              description: Stable endpoint identifier.
              example: 27d8bfc5-6c75-4e4e-a78a-63ad7a924cb1
      example:
        endpointId: 27d8bfc5-6c75-4e4e-a78a-63ad7a924cb1
        endpointRole: data
        accessProtocol: HTTPS
        uri: https://hr.example.com/api/v1
        isPrimary: true

    ConnectorCredentialRef:
      type: object
      description: Reference to credential material used by a connector. The referenced secret can live in platform settings, vault, KMS-backed storage, or an external secret manager.
      required:
        - bindingMode
      properties:
        bindingMode:
          $ref: '#/components/schemas/SecretBindingMode'
        credentialId:
          type: string
          format: uuid
          description: Optional platform credential identifier when credentials are first-class resources.
          example: 8cd48897-9fb2-4a1a-a044-bd71a3e86e61
        secretRef:
          type: string
          description: Opaque platform secret reference, not a secret value.
          example: secret://tenant/acme/connectors/workday/oauth-client
        externalSecretRef:
          type: string
          description: External secret-manager reference when the platform does not own the secret.
          example: aws-secretsmanager://prod/acme/workday/oauth-client
        credentialType:
          type: string
          description: Connector-specific credential type, for example oauth2-client, api-key, username-password, ssh-key, certificate, or service-account.
          example: oauth2-client
        label:
          type: string
          description: Administrative label for the credential reference.
          example: Workday OAuth client
        keyAlias:
          type: string
          description: Optional KMS or vault key alias used by the connector.
          example: tenant-acme-workday-client-key
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        bindingMode: SECRET_REF
        secretRef: secret://tenant/acme/connectors/workday/oauth-client
        credentialType: oauth2-client
        label: Workday OAuth client
        metadata:
          rotation: managed-by-security

    ConnectorConfigBindingRef:
      type: object
      description: Reference to platform settings used by the connector. Use this for non-secret configuration and as the durable pointer to secret key prefixes.
      properties:
        configBindingId:
          type: string
          format: uuid
          description: Stable settings/configuration binding identifier.
          example: 5724bdf7-a83f-42c6-b336-bf5ee98be529
        settingsScope:
          type: string
          description: Platform settings scope used by the connector, for example tenant, service, instance, or route.
          example: service-instance
        settingsKeyPrefix:
          type: string
          description: Prefix under which connector settings are stored.
          example: connector.workday.acme-prod
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        configBindingId: 5724bdf7-a83f-42c6-b336-bf5ee98be529
        settingsScope: service-instance
        settingsKeyPrefix: connector.workday.acme-prod

    ResourceDescriptorCreateRequest:
      type: object
      description: Request to describe a resource shape independently from any connector instance or transport. A descriptor can later be attached to one or more connectors.
      required:
        - displayName
        - resourceKind
        - representationKind
      properties:
        displayName:
          type: string
          description: Human-readable resource descriptor name.
          example: Employee profile CSV row
        description:
          type: string
          description: Description of the logical resource and intended use.
          example: Tabular employee profile data used for employee credential claim mapping.
        resourceKind:
          $ref: '#/components/schemas/ResourceKind'
        representationKind:
          $ref: '#/components/schemas/RepresentationKind'
        shapeKind:
          $ref: '#/components/schemas/ShapeKind'
        contract:
          $ref: '#/components/schemas/ContractRef'
        fields:
          type: array
          description: Field-level shape, validation, semantic, and retention information.
          items:
            $ref: '#/components/schemas/FieldDescriptorInput'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        displayName: Employee profile CSV row
        description: Tabular employee profile data used for employee credential claim mapping.
        resourceKind: TABULAR
        representationKind: CSV
        shapeKind: CSV_HEADER
        contract:
          contractKind: CSV_PROFILE
          uri: vault://imports/license-batches/employee-license-v1.csv.profile.json
          version: '1.0'
        fields:
          - fieldPath: employee_id
            displayName: Employee id
            valueType: string
            required: true
          - fieldPath: email
            displayName: Work email
            valueType: string
            required: true
            semanticAttributeId: 3cb996ce-9d68-4959-b8c4-c97e39258fae
          - fieldPath: license_type
            displayName: License type
            valueType: string
            required: true
        metadata:
          domain: employee-licensing

    ResourceDescriptorUpdateRequest:
      type: object
      description: Partial update for a resource descriptor. Omitted fields remain unchanged.
      properties:
        displayName:
          type: string
          description: Updated resource descriptor name.
          example: Employee profile CSV row
        description:
          type: string
          description: Updated resource descriptor description.
          example: Employee profile rows imported from a customer CSV upload.
        resourceKind:
          $ref: '#/components/schemas/ResourceKind'
        representationKind:
          $ref: '#/components/schemas/RepresentationKind'
        shapeKind:
          $ref: '#/components/schemas/ShapeKind'
        contract:
          $ref: '#/components/schemas/ContractRef'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        description: Employee profile rows imported from a customer CSV upload.
        metadata:
          domain: employee-licensing
          steward: people-ops

    ResourceDescriptor:
      description: Stored resource descriptor with field definitions and audit timestamps.
      allOf:
        - $ref: '#/components/schemas/ResourceDescriptorCreateRequest'
        - type: object
          required:
            - resourceDescriptorId
            - createdAt
            - updatedAt
          properties:
            resourceDescriptorId:
              $ref: '#/components/schemas/ResourceDescriptorId'
            fields:
              type: array
              description: Stored field descriptors for this resource descriptor.
              items:
                $ref: '#/components/schemas/FieldDescriptor'
            createdAt:
              type: string
              format: date-time
              description: Creation timestamp.
              example: '2026-06-18T09:00:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Last update timestamp.
              example: '2026-06-18T09:10:00Z'
      example:
        resourceDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
        displayName: Employee profile CSV row
        description: Tabular employee profile data used for employee credential claim mapping.
        resourceKind: TABULAR
        representationKind: CSV
        shapeKind: CSV_HEADER
        contract:
          contractKind: CSV_PROFILE
          uri: vault://imports/license-batches/employee-license-v1.csv.profile.json
          version: '1.0'
        fields:
          - fieldDescriptorId: f00b9edc-5498-483f-9b91-a42ef080b909
            fieldPath: email
            displayName: Work email
            valueType: string
            required: true
            multiValued: false
            semanticAttributeId: 3cb996ce-9d68-4959-b8c4-c97e39258fae
            sensitivity: personal-data
        metadata:
          domain: employee-licensing
        createdAt: '2026-06-18T09:00:00Z'
        updatedAt: '2026-06-18T09:10:00Z'

    FieldDescriptorInput:
      type: object
      description: Field definition for a resource descriptor. A field can carry semantic meaning, validation hints, sensitivity, and retention metadata.
      required:
        - fieldPath
        - valueType
      properties:
        fieldPath:
          type: string
          description: Path or column name within the resource representation.
          example: email
        displayName:
          type: string
          description: Human-readable field name.
          example: Work email
        valueType:
          type: string
          description: Logical value type, for example string, number, boolean, date, datetime, object, array, or binary.
          example: string
        required:
          type: boolean
          description: Whether the field is required for validation and mapping.
          default: false
          example: true
        multiValued:
          type: boolean
          description: Whether the field can hold multiple values.
          default: false
          example: false
        semanticAttributeId:
          type: string
          format: uuid
          description: Optional semantic attribute binding used for validation, governance, and policy.
          example: 3cb996ce-9d68-4959-b8c4-c97e39258fae
        sensitivity:
          type: string
          description: Optional sensitivity or classification label used by governance and policy checks.
          example: personal-data
        retention:
          $ref: '#/components/schemas/RetentionSpec'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        fieldPath: email
        displayName: Work email
        valueType: string
        required: true
        multiValued: false
        semanticAttributeId: 3cb996ce-9d68-4959-b8c4-c97e39258fae
        sensitivity: personal-data
        retention:
          purpose: credential-issuance
          legalBasis: contract
          retentionPeriod: P30D
          deleteAction: DELETE

    FieldDescriptor:
      description: Stored field descriptor.
      allOf:
        - $ref: '#/components/schemas/FieldDescriptorInput'
        - type: object
          required:
            - fieldDescriptorId
          properties:
            fieldDescriptorId:
              $ref: '#/components/schemas/FieldDescriptorId'
      example:
        fieldDescriptorId: f00b9edc-5498-483f-9b91-a42ef080b909
        fieldPath: email
        displayName: Work email
        valueType: string
        required: true
        multiValued: false
        semanticAttributeId: 3cb996ce-9d68-4959-b8c4-c97e39258fae
        sensitivity: personal-data

    ContractRef:
      type: object
      description: Reference to the schema, contract, or discovery document that defines or constrains a resource. The contract is descriptive; transport is still represented by AccessProtocol.
      required:
        - contractKind
      properties:
        contractKind:
          $ref: '#/components/schemas/ContractKind'
        uri:
          type: string
          description: URI or locator for the contract document.
          example: https://hr.example.com/.well-known/openapi.json
        version:
          type: string
          description: Contract version understood by the connector.
          example: '2026-06'
        contentHash:
          type: string
          description: Optional hash of the contract content for integrity and drift detection.
          example: sha256:9a0adf3e15f6c8c9b30b41f34f92de2c4f41ceea6c4e9c027c9f8f83f6a741b7
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        contractKind: OPENAPI
        uri: https://hr.example.com/.well-known/openapi.json
        version: '2026-06'
        contentHash: sha256:9a0adf3e15f6c8c9b30b41f34f92de2c4f41ceea6c4e9c027c9f8f83f6a741b7

    AttachConnectorResourceRequest:
      type: object
      description: Request to attach a resource descriptor to a connector instance for a specific data-flow role.
      required:
        - resourceDescriptorId
        - role
      properties:
        resourceDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        role:
          $ref: '#/components/schemas/DataFlowRole'
        externalResourceName:
          type: string
          description: Connector-local table, endpoint, bucket, object, claim set, form, topic, or collection name.
        accessProtocol:
          $ref: '#/components/schemas/AccessProtocol'
        endpointId:
          type: string
          format: uuid
          description: Optional connector endpoint used to access this resource.
          example: 27d8bfc5-6c75-4e4e-a78a-63ad7a924cb1
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        resourceDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
        role: SOURCE
        externalResourceName: /employees/{employee_id}
        accessProtocol: HTTPS
        endpointId: 27d8bfc5-6c75-4e4e-a78a-63ad7a924cb1
        metadata:
          operation_group: employee-profile

    ConnectorResource:
      description: Resource descriptor attached to a connector instance. This creates the bridge between a durable connector and a logical resource shape.
      allOf:
        - $ref: '#/components/schemas/AttachConnectorResourceRequest'
        - type: object
          required:
            - connectorResourceId
            - connectorInstanceId
          properties:
            connectorResourceId:
              $ref: '#/components/schemas/ConnectorResourceId'
            connectorInstanceId:
              $ref: '#/components/schemas/ConnectorInstanceId'
      example:
        connectorResourceId: b4cf21b1-0292-4803-8d32-9ebf9f5359a2
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        resourceDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
        role: SOURCE
        externalResourceName: /employees/{employee_id}
        accessProtocol: HTTPS
        endpointId: 27d8bfc5-6c75-4e4e-a78a-63ad7a924cb1

    OperationBindingCreateRequest:
      type: object
      description: Request to bind a connector resource to a logical operation. The binding connects connector instance, attached resource, logical operation, transfer mode, protocol, operation name, optional transformation, and destination delivery policy.
      required:
        - connectorInstanceId
        - connectorResourceId
        - operationKind
      properties:
        connectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        connectorResourceId:
          $ref: '#/components/schemas/ConnectorResourceId'
        operationKind:
          $ref: '#/components/schemas/OperationKind'
        transferMode:
          $ref: '#/components/schemas/OperationTransferMode'
        direction:
          $ref: '#/components/schemas/BindingDirection'
        accessProtocol:
          $ref: '#/components/schemas/AccessProtocol'
        operationName:
          type: string
          description: Connector-local operation name, for example OpenAPI operationId, SQL statement name, file action, or vault operation.
          example: getEmployeeProfile
        requestDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        responseDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        transformationId:
          $ref: '#/components/schemas/TransformationId'
        delivery:
          $ref: '#/components/schemas/DestinationDelivery'
        egressPolicy:
          $ref: '#/components/schemas/EgressPolicy'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        connectorResourceId: b4cf21b1-0292-4803-8d32-9ebf9f5359a2
        operationKind: READ
        transferMode: SINGLE
        direction: INBOUND
        accessProtocol: HTTPS
        operationName: getEmployeeProfile
        responseDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
        egressPolicy:
          allowedHosts: [hr.example.com]
          allowedProtocols: [HTTPS]
          maxPayloadBytes: 1048576
          requiresTenantBoundary: true
        metadata:
          source_lookup_key: employee_id

    OperationBindingUpdateRequest:
      type: object
      description: Partial update for an operation binding. Use this to adjust operation metadata, transformation, delivery, or policy without changing unrelated fields.
      properties:
        operationKind:
          $ref: '#/components/schemas/OperationKind'
        transferMode:
          $ref: '#/components/schemas/OperationTransferMode'
        direction:
          $ref: '#/components/schemas/BindingDirection'
        accessProtocol:
          $ref: '#/components/schemas/AccessProtocol'
        operationName:
          type: string
          description: Updated connector-local operation name.
          example: getEmployeeProfile
        requestDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        responseDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        transformationId:
          $ref: '#/components/schemas/TransformationId'
        delivery:
          $ref: '#/components/schemas/DestinationDelivery'
        egressPolicy:
          $ref: '#/components/schemas/EgressPolicy'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        transformationId: 0e60abcc-41b5-4cc5-bec2-f0047f129341
        egressPolicy:
          allowedHosts: [hr.example.com]
          allowedProtocols: [HTTPS]
          maxPayloadBytes: 1048576

    OperationBinding:
      description: Stored operation binding. A route composes one source binding and one destination binding.
      allOf:
        - $ref: '#/components/schemas/OperationBindingCreateRequest'
        - type: object
          required:
            - bindingId
            - createdAt
            - updatedAt
          properties:
            bindingId:
              $ref: '#/components/schemas/OperationBindingId'
            createdAt:
              type: string
              format: date-time
              description: Creation timestamp.
              example: '2026-06-18T09:20:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Last update timestamp.
              example: '2026-06-18T09:25:00Z'
      example:
        bindingId: 2777417e-82ce-4d3e-b96c-94e00a4d9a93
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        connectorResourceId: b4cf21b1-0292-4803-8d32-9ebf9f5359a2
        operationKind: READ
        transferMode: SINGLE
        direction: INBOUND
        accessProtocol: HTTPS
        operationName: getEmployeeProfile
        responseDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
        createdAt: '2026-06-18T09:20:00Z'
        updatedAt: '2026-06-18T09:25:00Z'

    SemanticConnectorBindingCreateRequest:
      type: object
      description: 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.
      required:
        - resourceDescriptorId
        - bindingKind
      properties:
        connectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        resourceDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        fieldDescriptorId:
          $ref: '#/components/schemas/FieldDescriptorId'
        bindingKind:
          type: string
          description: Binding type, for example ATTRIBUTE, ATTRIBUTE_PROFILE, PARTY_ROLE, RELATIONSHIP_TYPE, POLICY_CLASSIFICATION, or VOCABULARY_TERM.
          example: ATTRIBUTE
        semanticReference:
          $ref: '#/components/schemas/SemanticReference'
        validationMode:
          type: string
          description: Whether semantic validation is advisory, enforced, or disabled for this binding.
          enum:
            - NONE
            - WARN
            - ENFORCE
          example: ENFORCE
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        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

    SemanticConnectorBinding:
      description: Stored semantic binding for connector resource data.
      allOf:
        - $ref: '#/components/schemas/SemanticConnectorBindingCreateRequest'
        - type: object
          required:
            - semanticBindingId
            - createdAt
            - updatedAt
          properties:
            semanticBindingId:
              $ref: '#/components/schemas/SemanticBindingId'
            createdAt:
              type: string
              format: date-time
              description: Creation timestamp.
              example: '2026-06-18T09:30:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Last update timestamp.
              example: '2026-06-18T09:30:00Z'
      example:
        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'

    SemanticReference:
      type: object
      description: Reference to a semantic catalog, profile, attribute, relationship type, policy classification, or vocabulary term.
      required:
        - referenceType
        - referenceId
      properties:
        referenceType:
          type: string
          description: Semantic model reference type.
          example: semantic-attribute
        referenceId:
          type: string
          description: Stable semantic reference id.
          example: employee.email
        iri:
          type: string
          description: Optional IRI for RDF/JSON-LD and vocabulary alignment.
          example: https://vocab.example.com/employee#email
        version:
          type: string
          description: Optional semantic reference version.
          example: '1.0'
      example:
        referenceType: semantic-attribute
        referenceId: employee.email
        iri: https://vocab.example.com/employee#email
        version: '1.0'

    ConnectorInvocationBindingCreateRequest:
      type: object
      description: Request to persist a connector invocation binding.
      required:
        - binding
      properties:
        binding:
          $ref: '#/components/schemas/ConnectorInvocationBinding'
      example:
        binding:
          invocationBindingId: issuer-config-1:credential-request:hr-profile
          ownerSurface: OID4VCI
          ownerReference: issuer-config-1
          stage: OID4VCI_CREDENTIAL_REQUEST
          role: ENRICHMENT_SOURCE
          target:
            routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
          exchangeMode: PLATFORM_INITIATED_PULL
          dataDirection: INBOUND
          initiationSide: PLATFORM
          logicalContext:
            tenantId: acme
            organizationUnitId: nl-ops
            brandId: brand-a
          logicalConnectionBindingId: brand-a-hr-profile
          physicalConnectorInstanceId: 8a7f09af-7ac9-4d96-91f9-a2a252f4aa4b

    ConnectorInvocationBinding:
      type: object
      description: Persisted binding from an owning product/protocol lifecycle stage to a connector target, logical context, governance envelope, and execution policy.
      required:
        - invocationBindingId
        - ownerSurface
        - ownerReference
        - stage
        - role
        - target
        - exchangeMode
        - logicalContext
      properties:
        invocationBindingId:
          $ref: '#/components/schemas/ConnectorInvocationBindingId'
        ownerSurface:
          $ref: '#/components/schemas/ConnectorOwnerSurface'
        ownerReference:
          type: string
          description: Owner-specific reference such as issuer configuration id, verifier profile id, form id, portal flow id, or workflow id.
          example: issuer-config-1
        stage:
          $ref: '#/components/schemas/ConnectorInvocationStage'
        role:
          $ref: '#/components/schemas/ConnectorInvocationRole'
        target:
          $ref: '#/components/schemas/ConnectorInvocationTarget'
        exchangeMode:
          $ref: '#/components/schemas/ConnectorExchangeMode'
        dataDirection:
          $ref: '#/components/schemas/ConnectorDataDirection'
        initiationSide:
          $ref: '#/components/schemas/ConnectorInitiationSide'
        subsetMapping:
          $ref: '#/components/schemas/ConnectorSubsetMapping'
        logicalContext:
          $ref: '#/components/schemas/ConnectorLogicalContext'
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        physicalConnectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        executionPolicy:
          $ref: '#/components/schemas/ConnectorInvocationExecutionPolicy'
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        vaultProfile:
          $ref: '#/components/schemas/ConnectorVaultRetentionProfile'
        partyAnchors:
          $ref: '#/components/schemas/ConnectorPartyAnchorSet'
        materializationPolicy:
          $ref: '#/components/schemas/MaterializationPolicy'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        invocationBindingId: issuer-config-1:credential-request:hr-profile
        ownerSurface: OID4VCI
        ownerReference: issuer-config-1
        stage: OID4VCI_CREDENTIAL_REQUEST
        role: ENRICHMENT_SOURCE
        target:
          routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
        exchangeMode: PLATFORM_INITIATED_PULL
        dataDirection: INBOUND
        initiationSide: PLATFORM
        logicalContext:
          tenantId: acme
          organizationUnitId: nl-ops
          brandId: brand-a
        logicalConnectionBindingId: brand-a-hr-profile
        physicalConnectorInstanceId: 8a7f09af-7ac9-4d96-91f9-a2a252f4aa4b

    ConnectorInvocationTarget:
      type: object
      description: Registry target selected by an invocation binding.
      properties:
        routeId:
          $ref: '#/components/schemas/ConnectorRouteId'
        connectorId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        operationBindingId:
          $ref: '#/components/schemas/OperationBindingId'
      example:
        routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f

    ConnectorLogicalContext:
      type: object
      description: Tenant, OU, brand, legal entity, channel, product, and discriminator context used to resolve a logical connector binding.
      required:
        - tenantId
      properties:
        tenantId:
          $ref: '#/components/schemas/TenantId'
        organizationUnitId:
          type: string
          example: nl-ops
        brandId:
          type: string
          example: brand-a
        legalEntityId:
          type: string
          example: legal-entity-a
        channel:
          type: string
          example: web
        productId:
          type: string
          example: employee-license
        discriminators:
          $ref: '#/components/schemas/StringMap'
      example:
        tenantId: acme
        organizationUnitId: nl-ops
        brandId: brand-a
        discriminators:
          jurisdiction: NL

    ConnectorSubsetMapping:
      type: object
      description: Field selection, lookup, output mapping, provenance, and minimization rules used by an invocation or exposure.
      properties:
        inputFields:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorFieldSelector'
        selectedFields:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorFieldSelector'
        producedFields:
          type: array
          description: Fields an invocation is expected to produce for later connector or protocol stages.
          items:
            $ref: '#/components/schemas/ConnectorFieldSelector'
        outputMappings:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorFieldMapping'
        sourceProvenanceFields:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorFieldSelector'
        qualityStatusFields:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorFieldSelector'
        redactionProfileId:
          type: string
          example: redact-proof-source
        minimizationProfileId:
          type: string
          example: min-proof-source
      example:
        inputFields:
          - protocolClaimPath: credential_subject.id
        selectedFields:
          - canonicalFieldPath: proof.status
        minimizationProfileId: min-proof-source

    ConnectorFieldSelector:
      type: object
      description: Selector for a canonical, protocol, form, proof, status, source, data product, or semantic field.
      properties:
        canonicalFieldPath:
          type: string
          example: proof.status
        connectorField:
          type: string
          example: employee_id
        protocolClaimPath:
          type: string
          example: credential_subject.email
        dcqlCredentialQueryId:
          type: string
          example: employeeCredential
        dcqlClaimId:
          type: string
          example: email
        formFieldPath:
          type: string
          example: applicant.email
        proofRef:
          type: string
          example: proof://presentation/1
        statusRef:
          type: string
          example: status://credential/1
        tokenRef:
          type: string
          example: token://access/1
        sourceFieldPath:
          type: string
          example: worker.email
        dataProductFieldScope:
          type: string
          example: dpp.asset.serial
        contractAgreementTargetRef:
          type: string
          example: contract-target-1
        semanticReference:
          $ref: '#/components/schemas/SemanticReference'
        required:
          type: boolean
          default: true
          example: true

    ConnectorFieldMapping:
      type: object
      description: Mapping from a source selector to a target selector.
      required:
        - source
        - target
      properties:
        source:
          $ref: '#/components/schemas/ConnectorFieldSelector'
        target:
          $ref: '#/components/schemas/ConnectorFieldSelector'
        required:
          type: boolean
          default: true
          example: true

    ConnectorInvocationExecutionPolicy:
      type: object
      description: Timing, retry, idempotency, and correlation policy for an invocation binding.
      properties:
        timing:
          $ref: '#/components/schemas/ConnectorExecutionTiming'
        failureEffect:
          $ref: '#/components/schemas/ConnectorFailureEffect'
        timeoutMillis:
          type: integer
          format: int64
          minimum: 0
          example: 30000
        syncWaitWindowMillis:
          type: integer
          format: int64
          minimum: 0
          example: 5000
        retryPolicy:
          $ref: '#/components/schemas/RetryPolicy'
        idempotencyKey:
          type: string
          example: issuer-config-1:offer-123
        correlationId:
          type: string
          example: protocol-correlation-1
      example:
        timing: INLINE_REQUIRED
        failureEffect: FAIL_PROTOCOL
        timeoutMillis: 30000

    LogicalConnectionBindingCreateRequest:
      type: object
      description: Request to persist a logical connection binding.
      required:
        - binding
      properties:
        binding:
          $ref: '#/components/schemas/LogicalConnectionBinding'
      example:
        binding:
          logicalConnectionBindingId: brand-a-proof-vault
          physicalConnectorInstanceId: 8a7f09af-7ac9-4d96-91f9-a2a252f4aa4b
          logicalContext:
            tenantId: acme
            organizationUnitId: nl-ops
            brandId: brand-a

    LogicalConnectionBinding:
      type: object
      description: Logical usage binding for a physical connector instance, including caller context, discriminator rules, auth overlay, grants, governance defaults, and system catalog projection metadata.
      required:
        - logicalConnectionBindingId
        - physicalConnectorInstanceId
        - logicalContext
      properties:
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        physicalConnectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        logicalContext:
          $ref: '#/components/schemas/ConnectorLogicalContext'
        callerParty:
          $ref: '#/components/schemas/PartyRef'
        beneficiaryParty:
          $ref: '#/components/schemas/PartyRef'
        discriminatorRules:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorDiscriminatorRule'
        authOverlay:
          $ref: '#/components/schemas/ConnectorAuthOverlay'
        grants:
          type: array
          items:
            $ref: '#/components/schemas/LogicalConnectionGrant'
        allowedOperations:
          type: array
          items:
            $ref: '#/components/schemas/OperationKind'
        defaultSubsetMapping:
          $ref: '#/components/schemas/ConnectorSubsetMapping'
        defaultGovernance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        defaultMaterializationPolicy:
          $ref: '#/components/schemas/MaterializationPolicy'
        systemCatalog:
          $ref: '#/components/schemas/SystemCatalogProjectionMetadata'
      example:
        logicalConnectionBindingId: brand-a-proof-vault
        physicalConnectorInstanceId: 8a7f09af-7ac9-4d96-91f9-a2a252f4aa4b
        logicalContext:
          tenantId: acme
          organizationUnitId: nl-ops
          brandId: brand-a
        authOverlay:
          mode: TENANT_SECRET_REF
          secretRef: vault://tenant/acme/connectors/proof-vault
        allowedOperations: [READ, WRITE]

    ConnectorDiscriminatorRule:
      type: object
      description: Rule for deriving and placing a discriminator value when resolving or invoking a logical connector binding.
      required:
        - source
        - sourceKey
        - targetKey
        - placement
      properties:
        source:
          $ref: '#/components/schemas/ConnectorDiscriminatorSource'
        sourceKey:
          type: string
          example: brandId
        targetKey:
          type: string
          example: X-Brand-Id
        placement:
          $ref: '#/components/schemas/ConnectorDiscriminatorPlacement'
        required:
          type: boolean
          default: true
          example: true
        staticValue:
          type: string
          example: brand-a

    ConnectorAuthOverlay:
      type: object
      description: Logical authentication overlay applied on top of the physical connector configuration.
      properties:
        mode:
          $ref: '#/components/schemas/ConnectorAuthOverlayMode'
        secretRef:
          type: string
          example: vault://tenant/acme/connectors/proof-vault
        oauthClientRef:
          type: string
          example: oauth-client://issuer-proof-vault
        mtlsIdentityRef:
          type: string
          example: mtls://identity/issuer-proof-vault
        credentialSelector:
          type: string
          example: tenant-default
      example:
        mode: TENANT_SECRET_REF
        secretRef: vault://tenant/acme/connectors/proof-vault

    LogicalConnectionGrant:
      type: object
      description: Grant that allows another tenant or caller context to use a logical connection binding.
      required:
        - grantId
        - grantedToTenantId
      properties:
        grantId:
          type: string
          example: grant-proof-vault-to-supplier
        grantedToTenantId:
          $ref: '#/components/schemas/TenantId'
        grantedBy:
          $ref: '#/components/schemas/PartyRef'
        allowedOperations:
          type: array
          items:
            $ref: '#/components/schemas/OperationKind'
        active:
          type: boolean
          default: true
          example: true

    SystemCatalogProjectionMetadata:
      type: object
      description: Party and deployment metadata projected from a logical connection binding into system catalog or governance views.
      properties:
        operatorParty:
          $ref: '#/components/schemas/PartyRef'
        vendorSupplierParty:
          $ref: '#/components/schemas/PartyRef'
        deploymentRegion:
          type: string
          example: eu-west-1
        managementMode:
          $ref: '#/components/schemas/ConnectorManagementMode'
        runtimeMode:
          $ref: '#/components/schemas/ConnectorRuntimeMode'
        deploymentMode:
          $ref: '#/components/schemas/ConnectorDeploymentMode'
        dataCategoriesTouched:
          type: array
          items:
            type: string
          example: [proof-status]
        downstreamRecipients:
          type: array
          items:
            $ref: '#/components/schemas/PartyRef'
        processorRefs:
          type: array
          items:
            $ref: '#/components/schemas/PartyRef'

    RouteExposureDescriptorCreateRequest:
      type: object
      description: Request to persist a route exposure descriptor.
      required:
        - exposure
      properties:
        exposure:
          $ref: '#/components/schemas/RouteExposureDescriptor'
      example:
        exposure:
          exposureDescriptorId: proof-vault-read-exposure
          exposedCapabilityId: proof-vault-read
          owningTenantId: acme
          logicalConnectionBindingId: brand-a-proof-vault
          exchangeMode: EXTERNALLY_INITIATED_READ
          allowedOperation: READ
          acceptedAuthMethods: [bearer, mtls]

    RouteExposureGrantStatus:
      type: string
      enum: [ACTIVE, SUSPENDED, REVOKED, EXPIRED]
    RouteExposureThrottlePolicy:
      type: object
      required: [maxRequests, windowSeconds]
      properties:
        maxRequests:
          type: integer
          format: int64
          minimum: 1
        windowSeconds:
          type: integer
          format: int64
          minimum: 1
        throttleKey:
          type: string
    RouteExposureGrantCreateRequest:
      type: object
      required: [callerParty]
      additionalProperties: false
      properties:
        callerParty:
          $ref: '#/components/schemas/PartyRef'
        grantedBy:
          $ref: '#/components/schemas/PartyRef'
        allowedAuthMethods:
          type: array
          items: { type: string }
        allowedOperations:
          type: array
          items:
            $ref: '#/components/schemas/OperationKind'
        status:
          $ref: '#/components/schemas/RouteExposureGrantStatus'
          default: ACTIVE
        validFrom:
          type: string
          format: date-time
        validUntil:
          type: string
          format: date-time
        maxUses:
          type: integer
          format: int64
          minimum: 1
        throttlePolicy:
          $ref: '#/components/schemas/RouteExposureThrottlePolicy'
        metadata:
          type: object
          additionalProperties: { type: string }
    RouteExposureGrant:
      type: object
      required: [grantId, exposureDescriptorId, owningTenantId, callerParty, status, useCount]
      properties:
        grantId: { $ref: '#/components/schemas/RouteExposureGrantId' }
        exposureDescriptorId: { $ref: '#/components/schemas/RouteExposureDescriptorId' }
        owningTenantId: { $ref: '#/components/schemas/TenantId' }
        callerParty: { $ref: '#/components/schemas/PartyRef' }
        grantedBy: { $ref: '#/components/schemas/PartyRef' }
        allowedAuthMethods: { type: array, items: { type: string } }
        allowedOperations: { type: array, items: { $ref: '#/components/schemas/OperationKind' } }
        status: { $ref: '#/components/schemas/RouteExposureGrantStatus' }
        validFrom: { type: string, format: date-time }
        validUntil: { type: string, format: date-time }
        maxUses: { type: integer, format: int64 }
        useCount: { type: integer, format: int64, minimum: 0 }
        throttlePolicy: { $ref: '#/components/schemas/RouteExposureThrottlePolicy' }
        metadata: { type: object, additionalProperties: { type: string } }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    RouteExposureGrantPage:
      allOf:
        - $ref: './common-components.yml#/components/schemas/PageResponse'
        - type: object
          properties:
            items:
              type: array
              items: { $ref: '#/components/schemas/RouteExposureGrant' }

    RouteExposureDescriptor:
      type: object
      description: Externally callable connector route capability and its caller, schema, subset, payload, rate, and audit constraints.
      required:
        - exposureDescriptorId
        - exposedCapabilityId
        - owningTenantId
        - logicalConnectionBindingId
        - exchangeMode
        - allowedOperation
        - acceptedAuthMethods
      properties:
        exposureDescriptorId:
          $ref: '#/components/schemas/RouteExposureDescriptorId'
        exposedCapabilityId:
          type: string
          example: proof-vault-read
        owningTenantId:
          $ref: '#/components/schemas/TenantId'
        organizationUnitId:
          type: string
          example: nl-ops
        brandId:
          type: string
          example: brand-a
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        exchangeMode:
          $ref: '#/components/schemas/ConnectorExchangeMode'
        allowedOperation:
          $ref: '#/components/schemas/OperationKind'
        acceptedAuthMethods:
          type: array
          items:
            type: string
          example: [bearer, mtls]
        callerPartyConstraints:
          type: array
          items:
            $ref: '#/components/schemas/PartyRef'
        callerRelationshipConstraints:
          type: array
          items:
            $ref: '#/components/schemas/RelationshipRef'
        requestSchemaRef:
          type: string
          example: schema://proof-vault/read-request
        responseSchemaRef:
          type: string
          example: schema://proof-vault/read-response
        subsetMapping:
          $ref: '#/components/schemas/ConnectorSubsetMapping'
        cursorStrategy:
          type: string
          example: opaque-page-token
        idempotencyKeyStrategy:
          type: string
          example: header:X-Idempotency-Key
        payloadLimitBytes:
          type: integer
          format: int64
          minimum: 0
          example: 1048576
        rateLimitKey:
          type: string
          example: tenant:caller
        auditCategory:
          $ref: '#/components/schemas/ConnectorAuditCategory'
      example:
        exposureDescriptorId: proof-vault-read-exposure
        exposedCapabilityId: proof-vault-read
        owningTenantId: acme
        organizationUnitId: nl-ops
        brandId: brand-a
        logicalConnectionBindingId: brand-a-proof-vault
        exchangeMode: EXTERNALLY_INITIATED_READ
        allowedOperation: READ
        acceptedAuthMethods: [bearer, mtls]
        payloadLimitBytes: 1048576
        auditCategory: EXTERNAL_EXCHANGE

    RouteExposureExternalReadRequest:
      type: object
      description: Governed request envelope for an externally initiated read through a route exposure descriptor.
      required:
        - authMethod
        - callerParty
        - canonicalFields
      properties:
        authMethod:
          type: string
          description: Auth or trust method accepted by the exposure descriptor.
          example: bearer
        callerParty:
          $ref: '#/components/schemas/PartyRef'
        canonicalFields:
          type: object
          description: Canonical field values eligible for projection through the governed exposure.
          additionalProperties: true
          example:
            proof.status: valid
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        cursor:
          $ref: '#/components/schemas/ConnectorCursor'
      example:
        authMethod: bearer
        callerParty:
          partyId: party-consumer
        canonicalFields:
          proof.status: valid
        governance:
          classification: confidential
          legalBasis: dpv:Contract
          purpose: dpv:Audit
          auditCategory: EXTERNAL_EXCHANGE
        cursor:
          value: page-1

    RouteExposureExternalWriteRequest:
      type: object
      description: Governed request envelope for an externally initiated write through a route exposure descriptor.
      required:
        - authMethod
        - callerParty
        - payload
        - fieldMappings
      properties:
        authMethod:
          type: string
          description: Auth or trust method accepted by the exposure descriptor.
          example: bearer
        callerParty:
          $ref: '#/components/schemas/PartyRef'
        payload:
          type: object
          description: External payload values supplied by the caller.
          additionalProperties: true
          example:
            supplierStatus: valid
        fieldMappings:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorFieldMapping'
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        idempotencyKey:
          type: string
          example: supplier-status-1
        partyProjectionCandidates:
          type: array
          items:
            $ref: '#/components/schemas/PartyProjectionCandidate'
      example:
        authMethod: bearer
        callerParty:
          partyId: party-supplier
        payload:
          supplierStatus: valid
        fieldMappings:
          - source:
              sourceFieldPath: supplierStatus
            target:
              canonicalFieldPath: evidence.status
        governance:
          classification: confidential
          legalBasis: dpv:Contract
          purpose: dpv:Audit
          auditCategory: EXTERNAL_EXCHANGE
        idempotencyKey: supplier-status-1

    ConnectorExternalReadResponse:
      type: object
      description: Approved governed view returned by an externally initiated read exposure.
      required:
        - state
        - exposureDescriptorId
        - logicalConnectionBindingId
        - policyDecisionId
        - selectedFieldPaths
        - manifest
      properties:
        state:
          type: string
          example: APPROVED_VIEW
        runId:
          $ref: '#/components/schemas/ConnectorRunId'
        exposureDescriptorId:
          $ref: '#/components/schemas/RouteExposureDescriptorId'
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        policyDecisionId:
          type: string
          example: policy-external-read
        selectedFieldPaths:
          type: array
          items:
            type: string
          example: [proof.status]
        manifest:
          $ref: '#/components/schemas/ConnectorExportManifest'
        cursor:
          $ref: '#/components/schemas/ConnectorCursor'
        sourceSurface:
          type: string
          example: route-exposure

    ConnectorExternalWriteReceipt:
      type: object
      description: Governed-ingress receipt returned by an externally initiated write exposure.
      required:
        - state
        - exposureDescriptorId
        - logicalConnectionBindingId
        - canonicalFields
        - projectionCandidateIds
        - policyDecisionId
        - idempotencyResult
        - payloadHash
        - laterUseAvailabilityScope
      properties:
        state:
          $ref: '#/components/schemas/ConnectorGovernedIngressStatus'
        runId:
          $ref: '#/components/schemas/ConnectorRunId'
        exposureDescriptorId:
          $ref: '#/components/schemas/RouteExposureDescriptorId'
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        canonicalFields:
          type: object
          description: Canonical fields produced after mapping the external payload.
          additionalProperties: true
          example:
            evidence.status: valid
        projectionCandidateIds:
          type: array
          items:
            type: string
          example: [supplier-party-1]
        policyDecisionId:
          type: string
          example: policy-external-write
        idempotencyResult:
          type: string
          example: accepted:supplier-status-1
        payloadHash:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
          example: sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
        laterUseAvailabilityScope:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorOwnerSurface'
          example: [FORM, OID4VCI, OID4VP, WORKFLOW]

    ConnectorPolicyDecision:
      type: object
      description: Trusted server-produced policy decision consumed by governed connector processing and returned as lineage. It is never accepted as request authority.
      required:
        - decisionId
        - outcome
      properties:
        decisionId:
          type: string
          example: policy-external-read
        outcome:
          $ref: '#/components/schemas/ConnectorPolicyOutcome'
        reason:
          type: string
          example: Purpose, agreement, and caller constraints permit the external exchange.
        metadata:
          $ref: '#/components/schemas/StringMap'

    ConnectorPolicyEnforcementPoint:
      type: string
      description: Closed Phase 5 policy enforcement vocabulary for governed connector operations.
      enum:
        - GOVERNED_INGRESS
        - EGRESS_EXPORT
        - ROUTE_EXPOSURE_READ
        - ROUTE_EXPOSURE_WRITE
        - CONTROL_OPERATION
      example: EGRESS_EXPORT

    ConnectorPolicyEvaluationContext:
      type: object
      description: Neutral, value-free connector policy context built from trusted operation coordinates. Raw payloads, credentials, presentations, tokens, and secrets are excluded.
      required:
        - enforcementPoint
        - resourceType
        - resourceId
        - fieldPaths
        - fieldPathDigests
      properties:
        enforcementPoint:
          $ref: '#/components/schemas/ConnectorPolicyEnforcementPoint'
        resourceType:
          type: string
          example: connector.route-exposure
        resourceId:
          type: string
          example: proof-vault-read-exposure
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        partyAnchors:
          $ref: '#/components/schemas/ConnectorPartyAnchorSet'
        callerParty:
          $ref: '#/components/schemas/PartyRef'
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        physicalConnectorInstanceId:
          $ref: '#/components/schemas/ConnectorId'
        exposureDescriptorId:
          $ref: '#/components/schemas/RouteExposureDescriptorId'
        ownerSurface:
          $ref: '#/components/schemas/ConnectorOwnerSurface'
        stage:
          $ref: '#/components/schemas/ConnectorInvocationStage'
        fieldPaths:
          type: array
          description: Canonical field paths resolved from server-stored, authoring-validated connector authority.
          default: []
          items:
            type: string
          example: [proof.status]
        fieldPathDigests:
          type: array
          description: Domain-separated, type-tagged SHA-256 digests of runtime-controlled field coordinates that must not be disclosed to policy as canonical paths.
          default: []
          items:
            type: string
            pattern: '^field-path-sha256:[0-9a-f]{64}$'
        classifications:
          type: array
          items:
            type: string
          example: [confidential]
        integrityHashes:
          $ref: '#/components/schemas/StringMap'
        operationFacts:
          $ref: '#/components/schemas/StringMap'

    ConnectorGovernedIngressRequest:
      type: object
      description: Governed ingress operation input. The trusted policy decision is supplied only by the server-side execution seam.
      required:
        - record
        - fieldMappings
      properties:
        record:
          $ref: '#/components/schemas/ConnectorRecord'
        fieldMappings:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorFieldMapping'
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        requireGovernance:
          type: boolean
          default: true

    ConnectorEgressPreparationRequest:
      type: object
      description: Governed egress preparation input. The trusted policy decision is supplied only by the server-side execution seam.
      required:
        - canonicalFields
        - selectedFieldPaths
        - destinationIdentity
        - mappingVersion
      properties:
        canonicalFields:
          type: object
          additionalProperties: true
        selectedFieldPaths:
          type: array
          items:
            type: string
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        destinationIdentity:
          type: string
        mappingVersion:
          type: string
        mappingProvenance:
          type: string
        redactedFieldPaths:
          type: array
          items:
            type: string
        minimizedFieldPaths:
          type: array
          items:
            type: string

    ConnectorControlOperationRequest:
      type: object
      description: Control authorization input. A policy result is never accepted from the caller and authorization does not execute a control runtime.
      required:
        - targetExternalEntityRef
        - requestedAction
      properties:
        targetExternalEntityRef:
          type: string
        requestedAction:
          type: string
        actor:
          $ref: '#/components/schemas/PartyRef'
        reason:
          type: string
        dryRun:
          type: boolean
          default: true

    ConnectorPolicyOutcome:
      type: string
      description: Outcome returned by the governing policy layer for a connector exchange.
      enum:
        - PERMIT
        - DENY
        - MINIMIZE
        - REDACT
        - QUARANTINE
        - REQUIRE_SECOND_SOURCE
        - REQUIRE_HUMAN_REVIEW
        - REQUIRE_WALLET_PROOF
        - REQUIRE_STEP_UP
      example: PERMIT

    ConnectorGovernedIngressStatus:
      type: string
      description: Result state for governed external write ingress.
      enum:
        - ACCEPTED
        - MINIMIZED
        - REDACTED
        - QUARANTINED
        - REJECTED
      example: ACCEPTED

    ConnectorCursor:
      type: object
      description: Opaque cursor or watermark returned by connector runtimes and external exposure reads.
      required:
        - value
      properties:
        value:
          type: string
          example: page-1
        metadata:
          $ref: '#/components/schemas/StringMap'

    ConnectorExportedField:
      type: object
      description: A field included in an external-read manifest, with minimization and integrity metadata.
      required:
        - fieldPath
        - integrityHash
      properties:
        fieldPath:
          type: string
          example: proof.status
        value:
          type: object
          additionalProperties: true
          nullable: true
        redacted:
          type: boolean
          default: false
          example: false
        minimized:
          type: boolean
          default: false
          example: false
        integrityHash:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
          example: sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

    ConnectorExportManifest:
      type: object
      description: Governed egress manifest for an external-read response.
      required:
        - manifestId
        - destinationIdentity
        - selectedFields
        - mappingVersion
        - policyDecisionId
        - retentionProfileId
        - manifestHash
      properties:
        manifestId:
          type: string
          example: manifest-external-read
        destinationIdentity:
          type: string
          example: party-consumer
        selectedFields:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorExportedField'
        mappingVersion:
          type: string
          example: external-read:proof-vault-read
        mappingProvenance:
          type: string
          example: route-exposure-subset
        policyDecisionId:
          type: string
          example: policy-external-read
        retentionProfileId:
          type: string
          example: retention-proof
        agreementRef:
          type: object
          additionalProperties: true
        participantIdentity:
          type: object
          additionalProperties: true
        transferProcess:
          type: object
          additionalProperties: true
        obligations:
          type: array
          items:
            type: object
            additionalProperties: true
        manifestHash:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
          example: sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc

    PartyProjectionCandidate:
      type: object
      description: Candidate Party projection emitted by discovery, governed ingress, or external-write execution.
      required:
        - candidateId
        - entityKind
      properties:
        candidateId:
          type: string
          example: supplier-party-1
        entityKind:
          type: string
          example: asset
        party:
          $ref: '#/components/schemas/PartyRef'
        relationships:
          type: array
          items:
            $ref: '#/components/schemas/RelationshipCandidate'
        materializationIntent:
          $ref: '#/components/schemas/ConnectorEntityMaterializationIntent'
        semanticClassifications:
          type: array
          items:
            type: object
            additionalProperties: true
        canonicalFields:
          type: object
          additionalProperties: true

    RelationshipCandidate:
      type: object
      description: Directional Party relationship candidate that remains non-authoritative until the VDX projection command accepts it.
      required:
        - relationshipType
        - fromParty
        - toParty
      properties:
        relationshipType:
          type: string
          minLength: 1
          maxLength: 191
          example: OWNERSHIP
        fromParty:
          $ref: '#/components/schemas/PartyRef'
        toParty:
          $ref: '#/components/schemas/PartyRef'
        confidence:
          type: string
          example: authoritative-source
        sourceRef:
          type: string
          example: discovery:asset-registry:42

    ConnectorSourceStalenessState:
      type: string
      description: Current state of the source observation. Stale and missing candidates never delete or mutate governed Party data.
      enum:
        - ACTIVE
        - STALE
        - MISSING
      example: ACTIVE

    ConnectorPartyProjectionSource:
      type: string
      description: Connector path that produced the Party projection candidate.
      enum:
        - DISCOVERY
        - GOVERNED_INGRESS
        - EXTERNAL_WRITE
      example: DISCOVERY

    ConnectorPartyMaterializationDecision:
      type: string
      description: Explicit operator or reconciliation decision authorizing Party materialization.
      enum:
        - ACCEPT
        - RECONCILE
      example: ACCEPT

    ConnectorPartyProjectionEntry:
      type: object
      description: One explicitly decided Party projection candidate and its current source state.
      required:
        - source
        - decision
        - candidate
        - stalenessState
      properties:
        source:
          $ref: '#/components/schemas/ConnectorPartyProjectionSource'
        decision:
          $ref: '#/components/schemas/ConnectorPartyMaterializationDecision'
        candidate:
          $ref: '#/components/schemas/PartyProjectionCandidate'
        stalenessState:
          $ref: '#/components/schemas/ConnectorSourceStalenessState'

    ConnectorPartyProjectionRequest:
      type: object
      description: Tenant-scoped VDX Party projection command input. Tenant identity is supplied only by the command session.
      required:
        - entries
      properties:
        entries:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ConnectorPartyProjectionEntry'
        relationshipCandidates:
          type: array
          items:
            $ref: '#/components/schemas/RelationshipCandidate'

    ConnectorPartyProjectionCandidateStatus:
      type: string
      enum:
        - CREATED
        - REAPPLIED
        - RECONCILED
        - SKIPPED_STALE
      example: CREATED

    ConnectorPartyProjectionCandidateResult:
      type: object
      description: Resolution outcome for one candidate entry.
      required:
        - candidateId
        - status
      properties:
        candidateId:
          type: string
          example: asset-candidate-42
        partyId:
          type: string
          format: uuid
          example: 346b93a1-8042-46dc-ac1b-8d1261190fe0
        canonicalExternalIdentity:
          type: string
          example: urn:factory:asset:42
        status:
          $ref: '#/components/schemas/ConnectorPartyProjectionCandidateStatus'

    ConnectorPartyProjectionRelationshipStatus:
      type: string
      enum:
        - CREATED
        - REAPPLIED
      example: CREATED

    ConnectorPartyProjectionRelationshipResult:
      type: object
      description: Authoritative ordered Party relationship resolution outcome.
      required:
        - relationshipId
        - relationshipType
        - fromPartyId
        - toPartyId
        - status
      properties:
        relationshipId:
          type: string
          format: uuid
          example: 501bd0e2-218f-4665-8c75-5c48c17228e4
        relationshipType:
          type: string
          example: OWNERSHIP
        fromPartyId:
          type: string
          format: uuid
          example: 346b93a1-8042-46dc-ac1b-8d1261190fe0
        toPartyId:
          type: string
          format: uuid
          example: 1c3d351c-0fac-4d4a-8df0-e08360ed524b
        status:
          $ref: '#/components/schemas/ConnectorPartyProjectionRelationshipStatus'

    ConnectorPartyProjectionResult:
      type: object
      description: Aggregate result of one atomic Party and relationship projection command.
      required:
        - candidateResults
        - relationshipResults
      properties:
        candidateResults:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorPartyProjectionCandidateResult'
        relationshipResults:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorPartyProjectionRelationshipResult'

    ConnectorEntityMaterializationIntent:
      type: string
      description: How a governed external write or discovery record may materialize into durable Party, relationship, semantic, event, or DPP records.
      enum:
        - REFERENCE_ONLY
        - EXISTING_PARTY
        - NEW_PARTY_CANDIDATE
        - RELATIONSHIP_CANDIDATE
        - SEMANTIC_VALUE
        - EVENT
        - DPP_RECORD
      example: NEW_PARTY_CANDIDATE

    ConnectorDataProductDescriptorCreateRequest:
      type: object
      description: Request to persist a connector data product descriptor.
      required:
        - descriptor
      properties:
        descriptor:
          $ref: '#/components/schemas/ConnectorDataProductDescriptor'
      example:
        descriptor:
          dataProductId: dp-proof-status
          providerParty:
            partyId: party-provider
            displayName: Proof provider
          physicalConnectorInstanceId: 8a7f09af-7ac9-4d96-91f9-a2a252f4aa4b
          logicalConnectionBindingId: brand-a-proof-vault
          datasetResourceIds: [41436f49-040c-4f5f-9c7f-657f43762e2b]
          title: Proof status product
          canonicalFieldScopes: [proof.status]
          distributionTransferTypes: [HTTPS_PULL]
          catalogOfferRefs:
            - offerId: offer-proof-status
              policy:
                profileId: dpv-odrl
                policyType: OFFER
                policyUid: policy-proof-status

    ConnectorDataProductDescriptor:
      type: object
      description: Dataspace/data-use-contract-ready descriptor for a product exposed from a connector route or logical binding. It carries provider/consumer Party refs, dataset resource refs, field scopes, governance scope, transfer type, and catalog offer/policy refs without implementing DSP/DCAT wire behavior.
      required:
        - dataProductId
        - providerParty
        - physicalConnectorInstanceId
        - logicalConnectionBindingId
        - datasetResourceIds
        - title
        - distributionTransferTypes
        - catalogOfferRefs
      properties:
        dataProductId:
          $ref: '#/components/schemas/ConnectorDataProductId'
        providerParty:
          $ref: '#/components/schemas/PartyRef'
        consumerParty:
          $ref: '#/components/schemas/PartyRef'
        physicalConnectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        datasetResourceIds:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ResourceDescriptorId'
        title:
          type: string
          minLength: 1
          example: Proof status product
        description:
          type: string
          example: Governed proof status view exposed from the proof-vault route.
        version:
          type: string
          example: '1.0'
        canonicalFieldScopes:
          type: array
          items:
            type: string
          example: [proof.status]
        schemaRefs:
          type: array
          items:
            type: string
          example: [schema://proof-status]
        freshness:
          type: string
          example: PT5M
        quality:
          type: string
          example: verified
        distributionTransferTypes:
          type: array
          minItems: 1
          items:
            type: string
          example: [HTTPS_PULL]
        residency:
          type: string
          example: EU
        classification:
          type: string
          example: confidential
        governanceScope:
          type: string
          example: proof-status
        catalogOfferRefs:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ConnectorCatalogOfferRef'
        partyAnchors:
          $ref: '#/components/schemas/ConnectorPartyAnchorSet'
      example:
        dataProductId: dp-proof-status
        providerParty:
          partyId: party-provider
          displayName: Proof provider
        physicalConnectorInstanceId: 8a7f09af-7ac9-4d96-91f9-a2a252f4aa4b
        logicalConnectionBindingId: brand-a-proof-vault
        datasetResourceIds: [41436f49-040c-4f5f-9c7f-657f43762e2b]
        title: Proof status product
        canonicalFieldScopes: [proof.status]
        distributionTransferTypes: [HTTPS_PULL]
        governanceScope: proof-status
        catalogOfferRefs:
          - offerId: offer-proof-status
            policy:
              profileId: dpv-odrl
              policyType: OFFER
              policyUid: policy-proof-status

    ConnectorCatalogOfferRef:
      type: object
      description: Reference to a catalog offer and the ODRL policy attached to it.
      required:
        - offerId
        - policy
      properties:
        offerId:
          $ref: '#/components/schemas/ConnectorCatalogOfferId'
        policy:
          $ref: '#/components/schemas/ConnectorOdrlPolicyRef'
        projectionHint:
          type: string
          example: public-catalog

    ConnectorCatalogOfferId:
      type: string
      description: Stable catalog offer identifier associated with a connector data product.
      example: offer-proof-status

    ConnectorOdrlPolicyType:
      type: string
      description: ODRL policy reference type.
      enum:
        - SET
        - OFFER
        - AGREEMENT
      example: OFFER

    ConnectorOdrlPolicyRef:
      type: object
      description: ODRL policy reference associated with a data product catalog offer.
      required:
        - profileId
        - policyType
        - policyUid
      properties:
        profileId:
          type: string
          example: dpv-odrl
        policyType:
          $ref: '#/components/schemas/ConnectorOdrlPolicyType'
        policyUid:
          type: string
          example: policy-proof-status
        targetRefs:
          type: array
          items:
            type: string
          example: [proof.status]
        assigner:
          $ref: '#/components/schemas/PartyRef'
        assignee:
          $ref: '#/components/schemas/PartyRef'
        permissionRefs:
          type: array
          items:
            type: string
        prohibitionRefs:
          type: array
          items:
            type: string
        dutyRefs:
          type: array
          items:
            type: string

    TransformationCreateRequest:
      type: object
      description: Request to define a reusable transformation from one resource descriptor to another. Attribute mapper steps can coexist with expression-based transformations.
      required:
        - displayName
        - language
      properties:
        displayName:
          type: string
          description: Human-readable transformation name.
          example: Employee profile to license invitation
        description:
          type: string
          description: Transformation purpose and scope.
          example: Maps HR employee attributes into the invitation payload used by the license issuance flow.
        language:
          $ref: '#/components/schemas/TransformationLanguage'
        sourceDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        targetDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        steps:
          type: array
          description: Ordered transformation steps for step-based languages.
          items:
            $ref: '#/components/schemas/TransformationStep'
        expression:
          type: string
          description: Transformation expression for expression-based languages.
          example: 'employee.{ "email": email, "subject": givenName & " " & familyName }'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        displayName: Employee profile to license invitation
        description: Maps HR employee attributes into the invitation payload used by the license issuance flow.
        language: ATTRIBUTE_MAPPER
        sourceDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
        targetDescriptorId: 7a44f0de-e4d9-44ef-9211-372433933a88
        steps:
          - stepType: MAP
            sourcePath: email
            targetPath: recipient.email
          - stepType: MAP
            sourcePath: license_type
            targetPath: credential.licenseType
          - stepType: CONSTANT
            targetPath: invitation.channel
            value: email
        metadata:
          mapper_version: '1'

    TransformationUpdateRequest:
      type: object
      description: Partial update for a transformation definition.
      properties:
        displayName:
          type: string
          description: Updated transformation name.
          example: Employee profile to license invitation
        description:
          type: string
          description: Updated transformation description.
          example: Maps employee profile rows into the current license invitation payload.
        language:
          $ref: '#/components/schemas/TransformationLanguage'
        sourceDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        targetDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/TransformationStep'
        expression:
          type: string
          description: Updated expression for expression-based transformations.
          example: $.employee
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        description: Maps employee profile rows into the current license invitation payload.
        steps:
          - stepType: MAP
            sourcePath: email
            targetPath: recipient.email
          - stepType: DEFAULT
            targetPath: invitation.locale
            value: en-US

    TransformationDefinition:
      description: Stored transformation definition.
      allOf:
        - $ref: '#/components/schemas/TransformationCreateRequest'
        - type: object
          required:
            - transformationId
            - createdAt
            - updatedAt
          properties:
            transformationId:
              $ref: '#/components/schemas/TransformationId'
            createdAt:
              type: string
              format: date-time
              description: Creation timestamp.
              example: '2026-06-18T09:35:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Last update timestamp.
              example: '2026-06-18T09:40:00Z'
      example:
        transformationId: 0e60abcc-41b5-4cc5-bec2-f0047f129341
        displayName: Employee profile to license invitation
        description: Maps HR employee attributes into the invitation payload used by the license issuance flow.
        language: ATTRIBUTE_MAPPER
        sourceDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
        targetDescriptorId: 7a44f0de-e4d9-44ef-9211-372433933a88
        steps:
          - stepType: MAP
            sourcePath: email
            targetPath: recipient.email
          - stepType: MAP
            sourcePath: license_type
            targetPath: credential.licenseType
        createdAt: '2026-06-18T09:35:00Z'
        updatedAt: '2026-06-18T09:40:00Z'

    TransformationStep:
      type: object
      description: One step in a transformation pipeline. Step semantics are intentionally generic so existing attribute mappers and future expression engines can share the route model.
      required:
        - stepType
      properties:
        stepType:
          type: string
          description: Transformation step operation.
          enum:
            - MAP
            - CONSTANT
            - DEFAULT
            - REQUIRE
            - REDACT
            - HASH
            - LOOKUP
            - CUSTOM
          example: MAP
        sourcePath:
          type: string
          description: Source path or field used by this step.
          example: email
        targetPath:
          type: string
          description: Target path or field written by this step.
          example: recipient.email
        value:
          description: Literal value used by CONSTANT or DEFAULT steps.
          nullable: true
          example: email
        expression:
          type: string
          description: Optional expression used by LOOKUP, CUSTOM, or expression-based steps.
          example: lower($.email)
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        stepType: MAP
        sourcePath: email
        targetPath: recipient.email

    ConnectorRouteCreateRequest:
      type: object
      description: Request to compose one or more source operation bindings, one or more destination operation bindings, optional transformation, trigger, and execution policies.
      required:
        - displayName
        - sourceBindingIds
        - destinationBindingIds
      properties:
        displayName:
          type: string
          description: Human-readable route name.
          example: Employee CSV to license invitations
        description:
          type: string
          description: Route purpose and operational boundaries.
          example: Imports employee rows, maps them to invitation payloads, and writes them to the invitation service.
        sourceBindingIds:
          type: array
          minItems: 1
          description: Source operation bindings that feed this route. More than one source supports enrichment and reference-data joins.
          items:
            $ref: '#/components/schemas/OperationBindingId'
        destinationBindingIds:
          type: array
          minItems: 1
          description: Destination operation bindings written by this route. More than one destination supports fan-out.
          items:
            $ref: '#/components/schemas/OperationBindingId'
        transformationId:
          $ref: '#/components/schemas/TransformationId'
        trigger:
          $ref: '#/components/schemas/ConnectorTrigger'
        atomicity:
          $ref: '#/components/schemas/RouteAtomicity'
        purpose:
          type: string
          description: Processing purpose captured at route design time for audit and future governance checks.
          example: credential-issuance
        legalBasis:
          type: string
          description: Legal, contractual, or policy basis for the route's data movement.
          example: contract
        enabled:
          type: boolean
          description: Whether this route is eligible for scheduled, event, webhook, or on-demand execution.
          default: true
          example: true
        egressPolicy:
          $ref: '#/components/schemas/EgressPolicy'
        materializationPolicy:
          description: |
            Route-level materialization policy. When omitted by the caller, the platform applies the
            safe default `mode: NONE`, meaning values are not retained unless a route explicitly opts in.
          $ref: '#/components/schemas/MaterializationPolicy'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        displayName: Employee CSV to license invitations
        description: Imports employee rows, maps them to invitation payloads, and writes them to the invitation service.
        sourceBindingIds:
          - 2777417e-82ce-4d3e-b96c-94e00a4d9a93
        destinationBindingIds:
          - b1313b55-ee8c-41d1-8f4f-f4fe2c15e3be
        transformationId: 0e60abcc-41b5-4cc5-bec2-f0047f129341
        trigger:
          triggerType: ON_DEMAND
        atomicity: PER_RECORD
        purpose: credential-issuance
        legalBasis: contract
        enabled: true
        materializationPolicy:
          mode: NONE

    ConnectorRouteUpdateRequest:
      type: object
      description: Partial update for a connector route. Use this to adjust bindings, transformation, trigger, or policy.
      properties:
        displayName:
          type: string
          description: Updated route name.
          example: Employee CSV to license invitations
        description:
          type: string
          description: Updated route description.
          example: Imports employee rows from the latest customer CSV upload.
        sourceBindingIds:
          type: array
          minItems: 1
          description: Replacement list of source operation bindings.
          items:
            $ref: '#/components/schemas/OperationBindingId'
        destinationBindingIds:
          type: array
          minItems: 1
          description: Replacement list of destination operation bindings.
          items:
            $ref: '#/components/schemas/OperationBindingId'
        transformationId:
          $ref: '#/components/schemas/TransformationId'
        trigger:
          $ref: '#/components/schemas/ConnectorTrigger'
        atomicity:
          $ref: '#/components/schemas/RouteAtomicity'
        purpose:
          type: string
          description: Updated processing purpose.
          example: credential-issuance
        legalBasis:
          type: string
          description: Updated legal, contractual, or policy basis.
          example: contract
        enabled:
          type: boolean
          description: Whether this route is eligible for execution.
          example: true
        egressPolicy:
          $ref: '#/components/schemas/EgressPolicy'
        materializationPolicy:
          $ref: '#/components/schemas/MaterializationPolicy'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        trigger:
          triggerType: SCHEDULE
          schedule: 0 2 * * *
        atomicity: ALL_OR_NOTHING

    ConnectorRoute:
      description: Stored connector route definition.
      allOf:
        - $ref: '#/components/schemas/ConnectorRouteCreateRequest'
        - type: object
          required:
            - routeId
            - materializationPolicy
            - createdAt
            - updatedAt
          properties:
            routeId:
              $ref: '#/components/schemas/ConnectorRouteId'
            createdAt:
              type: string
              format: date-time
              description: Creation timestamp.
              example: '2026-06-18T10:00:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Last update timestamp.
              example: '2026-06-18T10:05:00Z'
            createdByUserId:
              type: string
              description: Optional user id that created the route.
              example: platform-admin
            updatedByUserId:
              type: string
              description: Optional user id that last updated the route.
              example: platform-admin
            deletedAt:
              type: string
              format: date-time
              description: Soft-delete timestamp. Deleted routes are hidden from normal route lookup and listing but retained for run lineage.
              example: '2026-06-19T10:05:00Z'
      example:
        routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
        displayName: Employee CSV to license invitations
        description: Imports employee rows, maps them to invitation payloads, and writes them to the invitation service.
        sourceBindingIds:
          - 2777417e-82ce-4d3e-b96c-94e00a4d9a93
        destinationBindingIds:
          - b1313b55-ee8c-41d1-8f4f-f4fe2c15e3be
        transformationId: 0e60abcc-41b5-4cc5-bec2-f0047f129341
        trigger:
          triggerType: ON_DEMAND
        atomicity: PER_RECORD
        purpose: credential-issuance
        legalBasis: contract
        enabled: true
        materializationPolicy:
          mode: NONE
        createdAt: '2026-06-18T10:00:00Z'
        updatedAt: '2026-06-18T10:05:00Z'

    ConnectorTrigger:
      type: object
      description: Trigger policy for starting a route. Triggers are declarative; actual scheduling, event subscriptions, and pipeline wiring are runtime concerns.
      required:
        - triggerType
      properties:
        triggerType:
          type: string
          description: Trigger mechanism for the route.
          enum:
            - ON_DEMAND
            - SCHEDULE
            - EVENT
            - WEBHOOK
            - PIPELINE
          example: ON_DEMAND
        schedule:
          type: string
          description: Cron expression for scheduled triggers.
          example: 0 2 * * *
        eventType:
          type: string
          description: Event type that starts an event-triggered route.
          example: connector.import.uploaded
        pipelineRef:
          type: string
          description: Reference to a platform pipeline, workflow, or orchestration definition that starts the route.
          example: pipeline://issuance/employee-license
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        triggerType: ON_DEMAND
        metadata:
          initiated_by: platform-admin

    DestinationDelivery:
      type: object
      description: Delivery requirements for destination bindings, including acknowledgement and retry behavior.
      properties:
        deliveryMode:
          $ref: '#/components/schemas/DestinationDeliveryMode'
        ackMode:
          $ref: '#/components/schemas/DestinationAckMode'
        idempotencyKeyPath:
          type: string
          description: Path in the outgoing payload used as idempotency key.
          example: recipient.email
        retryPolicy:
          $ref: '#/components/schemas/RetryPolicy'
      example:
        deliveryMode: BATCH
        ackMode: COMMITTED
        idempotencyKeyPath: recipient.email
        retryPolicy:
          maxAttempts: 5
          backoffMillis: 30000
          deadLetterEnabled: true

    RetryPolicy:
      type: object
      description: Retry and dead-letter behavior for connector operations.
      properties:
        maxAttempts:
          type: integer
          description: Maximum number of attempts, including the initial attempt. Zero means no retry after the initial failure.
          minimum: 0
          example: 5
        backoffMillis:
          type: integer
          format: int64
          description: Delay between attempts in milliseconds. Runtime implementations may apply jitter.
          minimum: 0
          example: 30000
        deadLetterEnabled:
          type: boolean
          description: Whether failed items should be written to the route dead-letter store when retries are exhausted.
          default: true
          example: true
      example:
        maxAttempts: 5
        backoffMillis: 30000
        deadLetterEnabled: true

    EgressPolicy:
      type: object
      description: |
        Network and payload egress limits for connector operations. This is the connector policy
        hook for SSRF protection, tenant boundary checks, and later semantic/compliance checks.
        Runtime adapters should resolve names before connecting and pass the resolved address to
        the evaluator when DNS pinning is enabled.
      properties:
        allowedHosts:
          type: array
          description: Hostnames or wildcard host patterns the connector is allowed to contact. Use `*.example.com` for one-or-more subdomains.
          items:
            type: string
          example: [hr.example.com]
        blockedHosts:
          type: array
          description: Hostnames or wildcard host patterns that are always denied, even when they also match an allowed host pattern.
          items:
            type: string
          example: [metadata.example.com, localhost]
        allowedCidrs:
          type: array
          description: IPv4 CIDR ranges the connector may contact when the target or resolved address is an IP address.
          items:
            type: string
          example: [203.0.113.0/24]
        allowedProtocols:
          type: array
          description: Access protocols allowed by this connector or operation.
          items:
            $ref: '#/components/schemas/AccessProtocol'
          example: [HTTPS]
        allowedPorts:
          type: array
          description: Network ports allowed by this connector or operation. Empty means protocol defaults are allowed unless another policy blocks the target.
          items:
            type: integer
            minimum: 1
            maximum: 65535
          example: [443]
        blockPrivateNetworks:
          type: boolean
          description: Whether private, loopback, link-local, local, multicast, and cloud metadata targets are denied by default.
          default: true
          example: true
        pinResolvedAddress:
          type: boolean
          description: Whether runtime adapters should connect to the already-validated resolved address to reduce DNS rebinding risk.
          default: true
          example: true
        maxPayloadBytes:
          type: integer
          format: int64
          description: Maximum allowed request or response payload size in bytes.
          minimum: 0
          example: 1048576
        requiresTenantBoundary:
          type: boolean
          description: Whether route execution must enforce tenant boundary checks before egress.
          default: true
          example: true
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        allowedHosts: [hr.example.com]
        blockedHosts: [localhost, 169.254.169.254]
        allowedCidrs: [203.0.113.0/24]
        allowedProtocols: [HTTPS]
        allowedPorts: [443]
        blockPrivateNetworks: true
        pinResolvedAddress: true
        maxPayloadBytes: 1048576
        requiresTenantBoundary: true

    MaterializationPolicy:
      type: object
      description: Policy for retaining, caching, indexing, or mirroring data touched by connector routes.
      properties:
        mode:
          $ref: '#/components/schemas/MaterializationMode'
        ttlSeconds:
          type: integer
          format: int64
          description: Time to live for materialized data in seconds.
          minimum: 0
          example: 2592000
        storageResourceDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        retention:
          $ref: '#/components/schemas/RetentionSpec'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        mode: PERSIST
        ttlSeconds: 2592000
        retention:
          purpose: credential-issuance
          legalBasis: contract
          retentionPeriod: P30D
          deleteAction: DELETE

    RetentionSpec:
      type: object
      description: Retention metadata used by governance and future compliance checks. It can be applied to fields, resources, materialized data, or dead-letter payloads.
      properties:
        purpose:
          type: string
          description: Processing purpose.
          example: credential-issuance
        legalBasis:
          type: string
          description: Legal or contractual basis for retention.
          example: contract
        retentionPeriod:
          type: string
          description: ISO-8601 duration, for example P30D or P7Y.
          example: P30D
        deleteAction:
          $ref: '#/components/schemas/RetentionDeleteAction'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        purpose: credential-issuance
        legalBasis: contract
        retentionPeriod: P30D
        deleteAction: DELETE

    DiscoverResourcesRequest:
      type: object
      description: Request to ask a connector to discover available resources, fields, and operations. Discovery is advisory and returns suggested descriptors that still need to be persisted explicitly.
      properties:
        includeFields:
          type: boolean
          description: Whether discovery should include field-level descriptors when available.
          default: true
          example: true
        includeOperations:
          type: boolean
          description: Whether discovery should include operation hints such as OpenAPI operation ids or database read/write capabilities.
          default: true
          example: true
        schemaDriftPolicy:
          $ref: '#/components/schemas/SchemaDriftPolicy'
        filters:
          $ref: '#/components/schemas/StringMap'
      example:
        includeFields: true
        includeOperations: true
        schemaDriftPolicy: WARN
        filters:
          path_prefix: /employees

    SchemaDriftPolicy:
      type: string
      description: Action to apply when a live discovered contract hash differs from the persisted resource descriptor contract hash. IGNORE suppresses drift findings, WARN returns findings, and FAIL rejects discovery.
      enum:
        - IGNORE
        - WARN
        - FAIL
      default: WARN
      example: WARN

    SchemaDriftFinding:
      type: object
      description: Governance fact emitted when a discovered resource contract no longer matches the pinned resource descriptor contract hash.
      required:
        - resourceDescriptorId
        - expectedContentHash
        - discoveredContentHash
      properties:
        resourceDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        externalResourceName:
          type: string
          description: Connector-local resource name associated with the drift, when available.
          example: /employees/{employee_id}
        expectedContentHash:
          type: string
          description: Persisted/pinned contract hash from the resource descriptor.
          example: sha256:pinned
        discoveredContentHash:
          type: string
          description: Hash reported by live connector discovery.
          example: sha256:runtime
        expectedContractVersion:
          type: string
          description: Version from the persisted contract reference.
          example: '2026-06'
        discoveredContractVersion:
          type: string
          description: Version from the live discovered contract reference.
          example: '2026-07'
        policy:
          $ref: '#/components/schemas/SchemaDriftPolicy'
        detectedAt:
          type: string
          format: date-time
          description: Timestamp when drift was detected.
          example: '2026-06-18T10:10:00Z'
        message:
          type: string
          description: Human-readable drift summary.
          example: Discovered contract hash differs from the pinned resource descriptor contract hash.
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        resourceDescriptorId: 9f70b114-35a6-4700-a8a3-7ad0c2d81202
        externalResourceName: /employees/{employee_id}
        expectedContentHash: sha256:pinned
        discoveredContentHash: sha256:runtime
        expectedContractVersion: '2026-06'
        discoveredContractVersion: '2026-07'
        policy: WARN
        detectedAt: '2026-06-18T10:10:00Z'

    DiscoveryResult:
      type: object
      description: Discovery result returned by a connector. Suggested descriptors are not persisted until the caller creates them through the resource descriptor API.
      required:
        - connectorInstanceId
        - resources
      properties:
        connectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        resources:
          type: array
          description: Resources discovered from the connector.
          items:
            $ref: '#/components/schemas/DiscoveredResource'
        schemaDrift:
          type: array
          description: Contract-hash drift findings detected while comparing live discovery with persisted resource descriptors.
          items:
            $ref: '#/components/schemas/SchemaDriftFinding'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        resources:
          - externalResourceName: /employees/{employee_id}
            resourceKind: OBJECT
            representationKind: JSON
            supportedOperations: [READ, QUERY]
            suggestedDescriptor:
              resourceDescriptorId: 9f70b114-35a6-4700-a8a3-7ad0c2d81202
              displayName: Workday employee profile response
              resourceKind: OBJECT
              representationKind: JSON
              shapeKind: OPENAPI_SCHEMA
              contract:
                contractKind: OPENAPI
                uri: https://hr.example.com/.well-known/openapi.json
              createdAt: '2026-06-18T10:10:00Z'
              updatedAt: '2026-06-18T10:10:00Z'
        schemaDrift: []
        metadata:
          discovered_at: '2026-06-18T10:10:00Z'

    DiscoveredResource:
      type: object
      description: One resource discovered from an external system or connector runtime.
      properties:
        externalResourceName:
          type: string
          description: Connector-local resource name such as path, table, bucket key, claim set, topic, or collection.
          example: /employees/{employee_id}
        resourceKind:
          $ref: '#/components/schemas/ResourceKind'
        representationKind:
          $ref: '#/components/schemas/RepresentationKind'
        suggestedDescriptor:
          $ref: '#/components/schemas/ResourceDescriptor'
        supportedOperations:
          type: array
          description: Logical operations suggested by discovery.
          items:
            $ref: '#/components/schemas/OperationKind'
          example: [READ, QUERY]
        schemaDrift:
          $ref: '#/components/schemas/SchemaDriftFinding'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        externalResourceName: /employees/{employee_id}
        resourceKind: OBJECT
        representationKind: JSON
        supportedOperations: [READ, QUERY]
        suggestedDescriptor:
          resourceDescriptorId: 9f70b114-35a6-4700-a8a3-7ad0c2d81202
          displayName: Workday employee profile response
          resourceKind: OBJECT
          representationKind: JSON
          shapeKind: OPENAPI_SCHEMA
          createdAt: '2026-06-18T10:10:00Z'
          updatedAt: '2026-06-18T10:10:00Z'

    HealthCheckRequest:
      type: object
      description: Request to run a connector health check. The check can be scoped to dependencies or an operation kind.
      properties:
        includeDependencies:
          type: boolean
          description: Whether dependency checks such as endpoint reachability, credential validity, and contract availability should be included.
          default: true
          example: true
        operationKind:
          $ref: '#/components/schemas/OperationKind'
      example:
        includeDependencies: true
        operationKind: READ

    ConnectorHealth:
      type: object
      description: Connector health result for one connector instance.
      required:
        - connectorInstanceId
        - status
        - checkedAt
      properties:
        connectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        status:
          type: string
          description: Overall health status.
          enum:
            - HEALTHY
            - DEGRADED
            - UNHEALTHY
            - UNKNOWN
          example: DEGRADED
        checkedAt:
          type: string
          format: date-time
          description: Timestamp when the health check completed.
          example: '2026-06-18T10:15:00Z'
        details:
          type: array
          description: Dependency-level health details.
          items:
            $ref: '#/components/schemas/HealthDetail'
      example:
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        status: DEGRADED
        checkedAt: '2026-06-18T10:15:00Z'
        details:
          - name: openapi-contract
            status: HEALTHY
            message: Contract document resolved.
          - name: oauth-token
            status: DEGRADED
            message: Token expires within the warning window.

    HealthDetail:
      type: object
      description: Dependency-level or operation-level health detail.
      properties:
        name:
          type: string
          description: Dependency or check name.
          example: oauth-token
        status:
          type: string
          description: Status of the dependency or check.
          example: DEGRADED
        message:
          type: string
          description: Human-readable health message.
          example: Token expires within the warning window.
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        name: oauth-token
        status: DEGRADED
        message: Token expires within the warning window.

    StartConnectorRouteRunRequest:
      type: object
      description: Request to start a route run. The input object is connector- and route-specific; the route's source binding decides how it is interpreted.
      properties:
        input:
          description: Optional input payload, connector fields, or batch reference passed to the route.
          nullable: true
          example:
            employee_id: E12345
            batch_ref: vault://imports/license-batches/batch-2026-06-18.csv
        dryRun:
          type: boolean
          description: Whether the run should validate and transform without committing destination writes.
          default: false
          example: false
        invocationBindingId:
          $ref: '#/components/schemas/ConnectorInvocationBindingId'
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        physicalConnectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        exchangeMode:
          $ref: '#/components/schemas/ConnectorExchangeMode'
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        partyAnchors:
          $ref: '#/components/schemas/ConnectorPartyAnchorSet'
        protocolContext:
          $ref: '#/components/schemas/ConnectorProtocolEventContext'
        correlationId:
          type: string
          description: Caller-provided correlation id for logs, run events, and downstream traceability.
          example: import-2026-06-18-001
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        input:
          batch_ref: vault://imports/license-batches/batch-2026-06-18.csv
        dryRun: false
        correlationId: import-2026-06-18-001
        metadata:
          initiated_by: admin@example.com

    ConnectorRun:
      type: object
      description: Execution record for a connector route or operation. Counts are item-level where the connector runtime can report item-level progress.
      required:
        - runId
        - status
        - startedAt
      properties:
        runId:
          $ref: '#/components/schemas/ConnectorRunId'
        routeId:
          $ref: '#/components/schemas/ConnectorRouteId'
        bindingId:
          $ref: '#/components/schemas/OperationBindingId'
        connectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        invocationBindingId:
          $ref: '#/components/schemas/ConnectorInvocationBindingId'
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        physicalConnectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        exchangeMode:
          $ref: '#/components/schemas/ConnectorExchangeMode'
        dataDirection:
          $ref: '#/components/schemas/ConnectorDataDirection'
        initiationSide:
          $ref: '#/components/schemas/ConnectorInitiationSide'
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        partyAnchors:
          $ref: '#/components/schemas/ConnectorPartyAnchorSet'
        protocolContext:
          $ref: '#/components/schemas/ConnectorProtocolEventContext'
        connectorResourceId:
          $ref: '#/components/schemas/ConnectorResourceId'
        operationKind:
          $ref: '#/components/schemas/OperationKind'
        triggerKind:
          type: string
          description: Mechanism that initiated the run.
          enum:
            - INLINE
            - ON_DEMAND
            - SCHEDULED
            - EVENT
            - WEBHOOK
            - PIPELINE
          example: ON_DEMAND
        status:
          $ref: '#/components/schemas/ConnectorRunStatus'
        startedAt:
          type: string
          format: date-time
          description: Timestamp when execution started.
          example: '2026-06-18T10:20:00Z'
        finishedAt:
          type: string
          format: date-time
          description: Timestamp when execution finished, if complete.
          example: '2026-06-18T10:21:12Z'
        itemCount:
          type: integer
          format: int64
          description: Number of input items seen by the run.
          minimum: 0
          example: 250
        successCount:
          type: integer
          format: int64
          description: Number of items processed successfully.
          minimum: 0
          example: 247
        failureCount:
          type: integer
          format: int64
          description: Number of items that failed after retries or validation.
          minimum: 0
          example: 3
        correlationId:
          type: string
          description: Caller-provided or runtime-generated correlation id.
          example: import-2026-06-18-001
        error:
          $ref: './common-components.yml#/components/schemas/ApiError'
        metadata:
          $ref: '#/components/schemas/StringMap'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp for this run record.
          example: '2026-06-18T10:21:12Z'
        createdByUserId:
          type: string
          description: Optional user id that initiated or created the run record.
          example: admin@example.com
        updatedByUserId:
          type: string
          description: Optional user id that last updated the run record.
          example: connector-runtime
        deletedAt:
          type: string
          format: date-time
          description: Soft-delete timestamp, if the run record is hidden from normal queries.
          example: '2026-07-18T10:21:12Z'
      example:
        runId: 9a785884-63ea-4b07-9976-264a1fc595f1
        routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        connectorResourceId: 8d228f50-a86c-4d5f-9eb4-83fdad7d75fa
        operationKind: READ
        triggerKind: ON_DEMAND
        status: PARTIALLY_FAILED
        startedAt: '2026-06-18T10:20:00Z'
        finishedAt: '2026-06-18T10:21:12Z'
        itemCount: 250
        successCount: 247
        failureCount: 3
        correlationId: import-2026-06-18-001
        metadata:
          batch_ref: vault://imports/license-batches/batch-2026-06-18.csv

    ConnectorRunEvent:
      type: object
      description: Timestamped event emitted during route or operation execution.
      required:
        - eventId
        - runId
        - level
        - message
        - occurredAt
      properties:
        eventId:
          type: string
          format: uuid
          description: Stable run event identifier.
          example: 524d8a98-c4a4-4982-b414-e29679b41eaf
        runId:
          $ref: '#/components/schemas/ConnectorRunId'
        routeId:
          $ref: '#/components/schemas/ConnectorRouteId'
        connectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        bindingId:
          $ref: '#/components/schemas/OperationBindingId'
        connectorResourceId:
          $ref: '#/components/schemas/ConnectorResourceId'
        operationKind:
          $ref: '#/components/schemas/OperationKind'
        level:
          type: string
          description: Event severity.
          enum:
            - DEBUG
            - INFO
            - WARN
            - ERROR
          example: WARN
        message:
          type: string
          description: Human-readable event message.
          example: Three rows failed validation and were written to dead letters.
        occurredAt:
          type: string
          format: date-time
          description: Event timestamp.
          example: '2026-06-18T10:21:10Z'
        metadata:
          $ref: '#/components/schemas/StringMap'
      example:
        eventId: 524d8a98-c4a4-4982-b414-e29679b41eaf
        runId: 9a785884-63ea-4b07-9976-264a1fc595f1
        routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        bindingId: 2777417e-82ce-4d3e-b96c-94e00a4d9a93
        connectorResourceId: 8d228f50-a86c-4d5f-9eb4-83fdad7d75fa
        operationKind: READ
        level: WARN
        message: Three rows failed validation and were written to dead letters.
        occurredAt: '2026-06-18T10:21:10Z'
        metadata:
          failed_rows: '3'

    ConnectorDeadLetter:
      type: object
      description: Failed item captured after validation, transformation, or destination delivery failure. Payloads are referenced, not necessarily embedded, so retention policy can control storage.
      required:
        - deadLetterId
        - runId
        - reason
        - createdAt
      properties:
        deadLetterId:
          type: string
          format: uuid
          description: Stable dead-letter identifier.
          example: a7d38149-19d4-4d0e-8af7-f7f8891f73bb
        runId:
          $ref: '#/components/schemas/ConnectorRunId'
        routeId:
          $ref: '#/components/schemas/ConnectorRouteId'
        connectorInstanceId:
          $ref: '#/components/schemas/ConnectorInstanceId'
        bindingId:
          $ref: '#/components/schemas/OperationBindingId'
        connectorResourceId:
          $ref: '#/components/schemas/ConnectorResourceId'
        operationKind:
          $ref: '#/components/schemas/OperationKind'
        reason:
          type: string
          description: Failure reason captured by the connector runtime.
          example: Missing required field recipient.email.
        payloadRef:
          type: string
          description: Reference to a retained failed payload, if storage policy allows it.
          example: vault://connector-runs/9a785884-63ea-4b07-9976-264a1fc595f1/deadletters/row-42.json
        createdAt:
          type: string
          format: date-time
          description: Dead-letter creation timestamp.
          example: '2026-06-18T10:21:11Z'
        metadata:
          $ref: '#/components/schemas/StringMap'
        createdByUserId:
          type: string
          description: Optional user id associated with the failed item capture.
          example: connector-runtime
        deletedAt:
          type: string
          format: date-time
          description: Soft-delete timestamp, if the dead letter is hidden after retention handling.
          example: '2026-07-18T10:21:11Z'
      example:
        deadLetterId: a7d38149-19d4-4d0e-8af7-f7f8891f73bb
        runId: 9a785884-63ea-4b07-9976-264a1fc595f1
        routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
        connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
        bindingId: 2777417e-82ce-4d3e-b96c-94e00a4d9a93
        connectorResourceId: 8d228f50-a86c-4d5f-9eb4-83fdad7d75fa
        operationKind: READ
        reason: Missing required field recipient.email.
        payloadRef: vault://connector-runs/9a785884-63ea-4b07-9976-264a1fc595f1/deadletters/row-42.json
        createdAt: '2026-06-18T10:21:11Z'
        metadata:
          row_number: '42'

    ConnectorInstancePage:
      type: object
      description: Page of connector instances.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorInstance'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
            partyId: f9c97b4e-e756-4b70-b230-6f1d9f81b426
            displayName: Workday employee profile API
            connectorType: http.openapi
            lifecycleStatus: ACTIVE
            supportedRoles: [SOURCE]
            createdAt: '2026-06-18T08:30:00Z'
            updatedAt: '2026-06-18T08:45:00Z'
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ConnectorIdentityPage:
      type: object
      description: Page of connector identities.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorIdentity'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - identityId: 3a5cf979-2d89-4057-a721-c7ab884f0c68
            identityRole: external-system
            displayName: Workday tenant acme-prod
            isDefault: true
            identifiers: []
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ConnectorResourcePage:
      type: object
      description: Page of resources attached to connectors.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorResource'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - connectorResourceId: b4cf21b1-0292-4803-8d32-9ebf9f5359a2
            connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
            resourceDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
            role: SOURCE
            externalResourceName: /employees/{employee_id}
            accessProtocol: HTTPS
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ResourceDescriptorPage:
      type: object
      description: Page of resource descriptors.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ResourceDescriptor'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - resourceDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
            displayName: Employee profile CSV row
            resourceKind: TABULAR
            representationKind: CSV
            createdAt: '2026-06-18T09:00:00Z'
            updatedAt: '2026-06-18T09:10:00Z'
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    FieldDescriptorPage:
      type: object
      description: Page of field descriptors.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FieldDescriptor'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - fieldDescriptorId: f00b9edc-5498-483f-9b91-a42ef080b909
            fieldPath: email
            displayName: Work email
            valueType: string
            required: true
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    OperationBindingPage:
      type: object
      description: Page of operation bindings.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OperationBinding'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - bindingId: 2777417e-82ce-4d3e-b96c-94e00a4d9a93
            connectorInstanceId: 3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5
            connectorResourceId: b4cf21b1-0292-4803-8d32-9ebf9f5359a2
            operationKind: READ
            direction: INBOUND
            accessProtocol: HTTPS
            operationName: getEmployeeProfile
            createdAt: '2026-06-18T09:20:00Z'
            updatedAt: '2026-06-18T09:25:00Z'
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    SemanticConnectorBindingPage:
      type: object
      description: Page of semantic connector bindings.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SemanticConnectorBinding'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - semanticBindingId: 20392e94-3b35-4a77-afc2-5e552a0a4023
            resourceDescriptorId: 41436f49-040c-4f5f-9c7f-657f43762e2b
            fieldDescriptorId: f00b9edc-5498-483f-9b91-a42ef080b909
            bindingKind: ATTRIBUTE
            validationMode: ENFORCE
            createdAt: '2026-06-18T09:30:00Z'
            updatedAt: '2026-06-18T09:30:00Z'
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ConnectorInvocationBindingPage:
      type: object
      description: Page of connector invocation bindings.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorInvocationBinding'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - invocationBindingId: issuer-config-1:credential-request:hr-profile
            ownerSurface: OID4VCI
            ownerReference: issuer-config-1
            stage: OID4VCI_CREDENTIAL_REQUEST
            role: ENRICHMENT_SOURCE
            target:
              routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
            exchangeMode: PLATFORM_INITIATED_PULL
            logicalContext:
              tenantId: acme
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    LogicalConnectionBindingPage:
      type: object
      description: Page of logical connection bindings.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LogicalConnectionBinding'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - logicalConnectionBindingId: brand-a-proof-vault
            physicalConnectorInstanceId: 8a7f09af-7ac9-4d96-91f9-a2a252f4aa4b
            logicalContext:
              tenantId: acme
              organizationUnitId: nl-ops
              brandId: brand-a
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    RouteExposureDescriptorPage:
      type: object
      description: Page of route exposure descriptors.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RouteExposureDescriptor'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - exposureDescriptorId: proof-vault-read-exposure
            exposedCapabilityId: proof-vault-read
            owningTenantId: acme
            logicalConnectionBindingId: brand-a-proof-vault
            exchangeMode: EXTERNALLY_INITIATED_READ
            allowedOperation: READ
            acceptedAuthMethods: [bearer, mtls]
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ConnectorDataProductDescriptorPage:
      type: object
      description: Page of connector data product descriptors.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorDataProductDescriptor'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - dataProductId: dp-proof-status
            providerParty:
              partyId: party-provider
            physicalConnectorInstanceId: 8a7f09af-7ac9-4d96-91f9-a2a252f4aa4b
            logicalConnectionBindingId: brand-a-proof-vault
            datasetResourceIds: [41436f49-040c-4f5f-9c7f-657f43762e2b]
            title: Proof status product
            distributionTransferTypes: [HTTPS_PULL]
            catalogOfferRefs:
              - offerId: offer-proof-status
                policy:
                  profileId: dpv-odrl
                  policyType: OFFER
                  policyUid: policy-proof-status
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    TransformationPage:
      type: object
      description: Page of transformation definitions.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TransformationDefinition'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - transformationId: 0e60abcc-41b5-4cc5-bec2-f0047f129341
            displayName: Employee profile to license invitation
            language: ATTRIBUTE_MAPPER
            createdAt: '2026-06-18T09:35:00Z'
            updatedAt: '2026-06-18T09:40:00Z'
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ConnectorRoutePage:
      type: object
      description: Page of connector routes.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorRoute'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
            displayName: Employee CSV to license invitations
            sourceBindingIds:
              - 2777417e-82ce-4d3e-b96c-94e00a4d9a93
            destinationBindingIds:
              - b1313b55-ee8c-41d1-8f4f-f4fe2c15e3be
            atomicity: PER_RECORD
            createdAt: '2026-06-18T10:00:00Z'
            updatedAt: '2026-06-18T10:05:00Z'
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ConnectorRunPage:
      type: object
      description: Page of connector runs.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorRun'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - runId: 9a785884-63ea-4b07-9976-264a1fc595f1
            routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
            status: PARTIALLY_FAILED
            startedAt: '2026-06-18T10:20:00Z'
            finishedAt: '2026-06-18T10:21:12Z'
            itemCount: 250
            successCount: 247
            failureCount: 3
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ConnectorRunEventPage:
      type: object
      description: Page of connector run events.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorRunEvent'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - eventId: 524d8a98-c4a4-4982-b414-e29679b41eaf
            runId: 9a785884-63ea-4b07-9976-264a1fc595f1
            level: WARN
            message: Three rows failed validation and were written to dead letters.
            occurredAt: '2026-06-18T10:21:10Z'
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false
    ConnectorDeadLetterPage:
      type: object
      description: Page of connector dead letters.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorDeadLetter'
        pagination:
          $ref: '#/components/schemas/Page'
      example:
        data:
          - deadLetterId: a7d38149-19d4-4d0e-8af7-f7f8891f73bb
            runId: 9a785884-63ea-4b07-9976-264a1fc595f1
            routeId: 1e8ff011-2274-4f16-a7dd-bf0b4fd5262f
            reason: Missing required field recipient.email.
            createdAt: '2026-06-18T10:21:11Z'
        pagination:
          limit: 20
          offset: 0
          page: 0
          size: 20
          total: 1
          totalPages: 1
          hasMore: false

    Page:
      type: object
      description: Pagination metadata emitted with each paged response under the `pagination` property.
      required:
        - limit
        - offset
        - page
        - size
        - total
        - totalPages
        - hasMore
      properties:
        limit:
          type: integer
          description: Maximum number of records requested for this page.
          minimum: 0
          example: 20
        offset:
          type: integer
          description: Zero-based offset of the first record in this page.
          minimum: 0
          example: 0
        page:
          type: integer
          description: Zero-based page index derived from offset and limit.
          minimum: 0
          example: 0
        size:
          type: integer
          description: Effective page size.
          minimum: 0
          example: 20
        total:
          type: integer
          format: int64
          description: Total number of matching records.
          minimum: 0
          example: 1
        totalPages:
          type: integer
          description: Total number of available pages.
          minimum: 0
          example: 1
        hasMore:
          type: boolean
          description: Whether another page is available after this page.
          example: false
      example:
        limit: 20
        offset: 0
        page: 0
        size: 20
        total: 1
        totalPages: 1
        hasMore: false

    ConnectorIntegrityReference:
      type: object
      description: Integrity and evidence references carried with governed connector ingress, egress, and run lineage.
      properties:
        originalPayloadHash:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
          example: sha256:1111111111111111111111111111111111111111111111111111111111111111
        canonicalPayloadHash:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
          example: sha256:2222222222222222222222222222222222222222222222222222222222222222
        transformationHash:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
          example: sha256:3333333333333333333333333333333333333333333333333333333333333333
        evidenceRef:
          type: string
          example: vault://evidence/connector-run-1
        vaultRef:
          type: string
          example: vault://proofs/proof-1
        signatureRef:
          type: string
          example: jades://signature-1
        sealRef:
          type: string
          example: seal://qualified-seal-1
        timestampRef:
          type: string
          example: timestamp://tsa-1
        sourceAuthenticityVerdict:
          type: string
          example: VERIFIED
        outputManifestHash:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
          example: sha256:4444444444444444444444444444444444444444444444444444444444444444

    ConnectorGovernanceEnvelope:
      type: object
      description: Governance metadata attached to connector records, invocations, and runs before data crosses a protocol, form, vault, dataspace, or external-exchange boundary.
      properties:
        classification:
          type: string
          example: confidential
        sensitivity:
          type: string
          example: high
        specialCategory:
          type: boolean
          default: false
        legalBasis:
          type: string
          example: dpv:Contract
        purpose:
          type: string
          example: dpv:Audit
        b2bUsagePurpose:
          type: string
          description: B2B or dataspace usage purpose, separate from privacy legal basis and processing purpose.
          example: predictive-maintenance
        frameworkAgreementRef:
          type: string
          example: catena-x:framework:1
        contractReference:
          type: string
          example: agreement-2026-001
        minimizationStatus:
          type: string
          enum:
            - NOT_EVALUATED
            - MINIMIZED
            - REDACTED
            - FULL_DATASET
            - EXCESSIVE
          example: MINIMIZED
        retentionProfileId:
          type: string
          example: retention-proof
        retention:
          $ref: '#/components/schemas/RetentionSpec'
        crossBorderRestriction:
          type: string
          enum:
            - NONE
            - SAME_COUNTRY
            - EEA_ONLY
            - APPROVED_COUNTRIES
            - CONTRACT_REQUIRED
            - BLOCKED
          example: EEA_ONLY
        encryptionRequirement:
          type: string
          enum:
            - NONE
            - IN_TRANSIT
            - AT_REST
            - AT_REST_AND_IN_TRANSIT
            - CUSTOMER_MANAGED_KEY
          example: AT_REST_AND_IN_TRANSIT
        dpiaRequired:
          type: boolean
          default: false
        integrity:
          $ref: '#/components/schemas/ConnectorIntegrityReference'
        policyDecisionId:
          type: string
          example: policy-connector-run
        relianceVerdict:
          type: string
          enum:
            - NOT_EVALUATED
            - RELIABLE
            - CONDITIONAL
            - NOT_RELIABLE
          example: RELIABLE
        auditCategory:
          type: string
          enum:
            - PROTOCOL_ISSUANCE
            - PROTOCOL_VERIFICATION
            - FORM
            - PORTAL
            - WORKFLOW
            - DATASPACE
            - INDUSTRIAL
            - EXTERNAL_EXCHANGE
            - VAULT
            - SYSTEM_CATALOG
          example: PROTOCOL_ISSUANCE

    PartyRef:
      type: object
      description: Neutral Party reference carried by EDK connector envelopes without importing the VDX Party repository.
      properties:
        partyId:
          type: string
          example: party-subject
        externalId:
          type: string
          example: urn:external:asset:press-1
        partyType:
          type: string
          example: organization
        displayName:
          type: string
          example: Example BV
        metadata:
          $ref: '#/components/schemas/StringMap'

    RelationshipRef:
      type: object
      description: Neutral Party relationship reference used by connector exposure caller constraints without importing the VDX Party repository.
      required:
        - relationshipType
        - fromParty
        - toParty
      properties:
        relationshipId:
          type: string
          example: rel-supplier-acme
        relationshipType:
          type: string
          example: supplierOf
        fromParty:
          $ref: '#/components/schemas/PartyRef'
        toParty:
          $ref: '#/components/schemas/PartyRef'

    ConnectorPartyAnchor:
      type: object
      description: Role-specific Party anchor used for governed durable connector entities.
      properties:
        role:
          type: string
          example: SUBJECT
        party:
          $ref: '#/components/schemas/PartyRef'
        relationships:
          type: array
          items:
            type: object
            additionalProperties: true

    ConnectorPartyAnchorSet:
      type: object
      description: Party, relationship, and projection candidates attached to connector invocation/run lineage.
      properties:
        anchors:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorPartyAnchor'
        relationshipCandidates:
          type: array
          items:
            type: object
            additionalProperties: true
        projectionCandidates:
          type: array
          items:
            type: object
            additionalProperties: true

    ConnectorProtocolEventContext:
      type: object
      description: Canonical protocol, form, portal, or workflow event context mapped into connector run lineage.
      properties:
        tenantId:
          type: string
          example: acme
        organizationUnitId:
          type: string
          example: nl-ops
        brandId:
          type: string
          example: brand-a
        legalEntityId:
          type: string
          example: legal-entity-a
        actor:
          $ref: '#/components/schemas/PartyRef'
        protocolSurface:
          type: string
          enum:
            - OID4VCI
            - OID4VP
            - FORM
            - PORTAL
            - WORKFLOW
            - APPLICATION
          example: OID4VCI
        ownerReference:
          type: string
          example: issuer-config-1
        stage:
          type: string
          example: OID4VCI_CREDENTIAL_REQUEST
        sessionId:
          type: string
          example: protocol-session-1
        transactionId:
          type: string
          example: protocol-transaction-1
        correlationId:
          type: string
          example: protocol-correlation-1

    ConnectorRecordPayload:
      type: object
      description: Connector record payload. Inline payloads carry a value; reference payloads carry a URI or resource descriptor reference.
      properties:
        value:
          description: Inline payload value.
        representationKind:
          $ref: '#/components/schemas/RepresentationKind'
        contentType:
          type: string
          example: application/json
        uri:
          type: string
          example: https://hr.example.test/employees/E1042
        resourceDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        contentHash:
          type: string
          example: sha256:4bf4...
        length:
          type: integer
          format: int64
          example: 4096
        metadata:
          type: object
          additionalProperties:
            type: string

    ConnectorRecord:
      type: object
      description: Runtime connector record emitted by a source connector or passed to a destination connector.
      required:
        - recordId
        - payload
      properties:
        recordId:
          type: string
          example: hr:E1042
        payload:
          $ref: '#/components/schemas/ConnectorRecordPayload'
        invocationBindingId:
          $ref: '#/components/schemas/ConnectorInvocationBindingId'
        logicalConnectionBindingId:
          $ref: '#/components/schemas/LogicalConnectionBindingId'
        physicalConnectorInstanceId:
          $ref: '#/components/schemas/ConnectorId'
        exchangeMode:
          $ref: '#/components/schemas/ConnectorExchangeMode'
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'
        semanticCoordinates:
          type: array
          items:
            type: object
            additionalProperties: true
        partyAnchors:
          $ref: '#/components/schemas/ConnectorPartyAnchorSet'
        industrialDiscovery:
          type: object
          additionalProperties: true
        industrialObservation:
          type: object
          additionalProperties: true
        dataspace:
          type: object
          additionalProperties: true
        protocolContext:
          $ref: '#/components/schemas/ConnectorProtocolEventContext'
        integrity:
          $ref: '#/components/schemas/ConnectorIntegrityReference'
        cursor:
          $ref: '#/components/schemas/ConnectorCursor'
        connectorResourceId:
          $ref: '#/components/schemas/ConnectorResourceId'
        resourceDescriptorId:
          $ref: '#/components/schemas/ResourceDescriptorId'
        operationBindingId:
          $ref: '#/components/schemas/OperationBindingId'
        occurredAt:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties:
            type: string

    ConnectorWriteStatus:
      type: string
      description: Aggregate or per-record destination write status.
      enum:
        - ACCEPTED
        - COMMITTED
        - DEFERRED
        - PARTIAL
        - FAILED
      example: COMMITTED

    ConnectorRecordWriteOutcome:
      type: object
      description: Per-record delivery outcome reported by a destination runtime.
      required:
        - recordId
        - status
      properties:
        recordId:
          type: string
          example: hr:E1042
        status:
          $ref: '#/components/schemas/ConnectorWriteStatus'
        metadata:
          type: object
          additionalProperties:
            type: string

    ConnectorWriteResult:
      type: object
      description: Destination connector write result, including aggregate and optional per-record outcomes.
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/ConnectorWriteStatus'
        recordsAccepted:
          type: integer
          format: int64
          default: 0
          example: 1
        recordsCommitted:
          type: integer
          format: int64
          default: 0
          example: 1
        externalRunRef:
          type: string
          example: hr-export-20260705-001
        lastCursor:
          $ref: '#/components/schemas/ConnectorCursor'
        recordOutcomes:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorRecordWriteOutcome'
        metadata:
          type: object
          additionalProperties:
            type: string

    ConnectorInvocationRequest:
      type: object
      description: Runtime request passed from a protocol, form, portal, or workflow stage. The serialized binding supplies lookup identity and an exact snapshot assertion only. VDX independently resolves the current tenant-scoped registry or server-configuration authority before policy evaluation and route execution.
      required:
        - binding
      properties:
        binding:
          $ref: '#/components/schemas/ConnectorInvocationBinding'
          description: Non-authoritative lookup identity and exact snapshot assertion. Inline binding facts never select policy or route execution authority.
        fields:
          type: object
          description: Canonical and protocol field values available to the connector invocation.
          additionalProperties: true
        protocolContext:
          $ref: '#/components/schemas/ConnectorProtocolEventContext'
        record:
          $ref: '#/components/schemas/ConnectorRecord'
        vaultWrite:
          $ref: '#/components/schemas/ConnectorVaultWrite'

    ConnectorRunCorrelation:
      type: object
      description: Route-run lineage produced by connector invocation execution.
      properties:
        runId:
          $ref: '#/components/schemas/ConnectorRunId'
        externalRunRef:
          type: string
          example: run-issuer-config-1-proof-vault
        routeId:
          $ref: '#/components/schemas/ConnectorRouteId'

    ConnectorVaultRetentionProfile:
      type: string
      description: Vault retention profile requested by a connector invocation result.
      enum:
        - ISSUANCE_PROOF
        - CANONICAL_SUBJECT_DATA
        - RECEIVED_CUSTOMER_DATA
      example: ISSUANCE_PROOF

    ConnectorVaultWrite:
      type: object
      description: Idempotent vault write requested by a connector invocation after protocol completion.
      required:
        - vaultProfile
        - idempotentUpsertKey
        - governance
      properties:
        vaultProfile:
          $ref: '#/components/schemas/ConnectorVaultRetentionProfile'
        idempotentUpsertKey:
          type: string
          example: proof:offer-123:E-100
        subjectCorrelationHandle:
          type: string
          example: subject:E-100
        revocationReissueConnectorField:
          type: string
          example: reissue:E-100
        selectedFields:
          type: object
          additionalProperties: true
        proofRef:
          type: string
          example: proof-ref
        statusHandle:
          type: string
          example: status-ref
        auditLineage:
          $ref: '#/components/schemas/ConnectorRunCorrelation'
        governance:
          $ref: '#/components/schemas/ConnectorGovernanceEnvelope'

    ConnectorInvocationDispatchStatus:
      type: string
      description: Dispatch outcome of one connector invocation binding within a protocol phase.
      default: SUCCEEDED
      enum:
        - SUCCEEDED
        - FAILED_CONTINUED
        - DEAD_LETTERED
        - QUARANTINED
      example: SUCCEEDED

    ConnectorInvocationResult:
      type: object
      description: Runtime result emitted by a connector invocation, including produced fields, written records, route lineage, and vault writes.
      properties:
        invocationBindingId:
          $ref: '#/components/schemas/ConnectorInvocationBindingId'
        dispatchStatus:
          $ref: '#/components/schemas/ConnectorInvocationDispatchStatus'
        failureReason:
          type: string
          description: Sanitized failure summary for a failed-but-continued invocation. Never echoes payload data.
          example: Connector destination is unavailable.
        producedFields:
          type: object
          additionalProperties: true
        records:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorRecord'
        writeResult:
          $ref: '#/components/schemas/ConnectorWriteResult'
        runCorrelation:
          $ref: '#/components/schemas/ConnectorRunCorrelation'
        vaultWrites:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorVaultWrite'

    Oid4vciConnectorPipelineRequest:
      type: object
      description: EDK-neutral OID4VCI connector pipeline request used to run connector-native enrichment, export, notification, route, or vault-retention bindings at any issuance stage.
      required:
        - protocolContext
        - initialFields
        - bindings
        - stages
      properties:
        protocolContext:
          $ref: '#/components/schemas/ConnectorProtocolEventContext'
        initialFields:
          type: object
          additionalProperties: true
        bindings:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorInvocationBinding'
        stages:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorInvocationStage'

    Oid4vciConnectorPipelineResult:
      type: object
      description: Result of an OID4VCI connector pipeline run, including accumulated fields, invocation lineage, and vault writes.
      required:
        - fields
        - invocationResults
      properties:
        fields:
          type: object
          additionalProperties: true
        invocationResults:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorInvocationResult'
        vaultWrites:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorVaultWrite'

    StringMap:
      type: object
      description: Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
      additionalProperties:
        type: string
      example:
        owner_team: people-ops
        domain: employee-licensing