attribute-source-openapi.yml

openapi: 3.0.4
info:
  title: Attribute Source API
  version: 0.1.0
  x-products: [vdx]
  description: |
    Register the attribute sources that an issuer pipeline can read from when it prepares
    credential subject data. The registry is owned by the EDK attribute-source commands
    (`CreateAttributeSourceArgs`, `UpdateAttributeSourceArgs`, `ListAttributeSourcesArgs`, and
    `SemanticBindingInput`); this VDX API is the product REST facade mounted at
    `/api/attribute-source/v1`.

    An attribute source describes a real integration target, not a credential definition. Typical
    entries are an HR profile REST endpoint keyed by `employee_id`, an employee directory database
    table keyed by `person_id`, or a managed batch file source keyed by `student_number`. The
    `sourceId` returned by this API is the value a pipeline binding can place in
    `AttributeSourceBinding.sourceInstanceId`, so OID4VCI and other credential pipelines can reuse
    the same registered source without introducing an OID4VCI-specific semantic channel.

    The registry deliberately separates three concerns:

      - `kind`, `managementMode`, and `runtimeMode` classify how the source is operated. They do
        not contain connector credentials.
      - `consumedLookupKeys` and `producedAttributes` document the runtime contract that pipeline
        steps rely on: which lookup keys must be available and which fields the source can return.
      - `connectionRef` points at endpoint and configuration material. Secrets are referenced by
        configuration key prefix and are never sent inline through this API.

    Semantic bindings are optional. A source can be used by a pipeline without semantic metadata;
    when bindings are supplied, they describe which catalog/profile/set attribute each native field
    contributes. That allows VDX documentation, governance, and service-capability views to explain
    the source in the same semantic language as credential designs and credential channels.

    The list endpoint returns the shared EDK `Page<AttributeSourceDefinition>` shape directly:
    `items`, `total_count`, `limit`, `offset`, plus computed navigation fields emitted by the
    serializer. It is not wrapped in a VDX `data`/`pagination` envelope.
  contact:
    name: Sphereon International B.V.
    email: support@sphereon.com
    url: https://sphereon.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://api.example.com/api/attribute-source/v1
    description: Production server.
  - url: http://localhost:8080/api/attribute-source/v1
    description: Local development server.

security:
  - bearer: []

tags:
  - name: AttributeSources
    description: Register EDK attribute-source definitions and optionally bind their native fields to semantic attributes.

paths:
  /sources:
    get:
      operationId: listAttributeSources
      summary: List attribute sources
      description: |
        Lists the registered attribute sources for the caller's tenant. Use `kind` to find sources
        by connector family, for example `REST_API` during OID4VCI session enrichment or `DATABASE`
        for a directory-backed issuer pipeline. Use `lifecycleStatus=ACTIVE` when selecting sources
        that are eligible for new pipeline bindings.
      tags: [AttributeSources]
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - name: kind
          in: query
          description: Optional connector family filter.
          schema:
            $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceKind'
        - name: lifecycleStatus
          in: query
          description: Optional lifecycle filter.
          schema:
            $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceLifecycleStatus'
        - $ref: './common-components.yml#/components/parameters/Page'
        - $ref: './common-components.yml#/components/parameters/Size'
      responses:
        '200':
          description: Paged EDK attribute-source definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeSourcePage'
              examples:
                hrSources:
                  summary: HR and directory sources registered for issuer pipelines
                  value:
                    items:
                      - sourceId: hr-workday-profile
                        tenantId: acme
                        displayName: Workday profile lookup
                        description: Resolves employee credential claims from the HR profile API by employee_id.
                        kind: REST_API
                        lifecycleStatus: ACTIVE
                        managementMode: EXTERNAL
                        runtimeMode: THIRD_PARTY
                        consumedLookupKeys: [employee_id]
                        producedAttributes:
                          - path: employee.givenName
                            nativeName: first_name
                            nativeType: string
                            label: Given name
                          - path: employee.familyName
                            nativeName: last_name
                            nativeType: string
                            label: Family name
                          - path: employment.department
                            nativeName: department_code
                            nativeType: string
                            label: Department
                        connectionRef:
                          endpointUrl: https://hr.example.com/api/employees
                          configKeyPrefix: attribute-source.hr-workday
                        createdAt: '2026-06-10T08:30:00Z'
                        updatedAt: '2026-06-10T08:30:00Z'
                    total_count: 1
                    limit: 20
                    offset: 0
                    has_more: false
                    page_number: 0
                    total_pages: 1
        '400':
          $ref: './common-components.yml#/components/responses/ValidationError'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
    post:
      operationId: createAttributeSource
      summary: Create an attribute source
      description: |
        Creates the tenant-scoped source definition that EDK persistence and pipeline bindings use.
        Provide `sourceId` when the integration needs a stable, human-readable id in configuration;
        omit it when the service should assign one. The request body maps directly to
        `CreateAttributeSourceArgs`.
      tags: [AttributeSources]
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAttributeSourceRequest'
            examples:
              hrRestSource:
                summary: REST source used during employee credential issuance
                value:
                  sourceId: hr-workday-profile
                  displayName: Workday profile lookup
                  description: Resolves employee credential claims from the HR profile API by employee_id.
                  kind: REST_API
                  managementMode: EXTERNAL
                  runtimeMode: THIRD_PARTY
                  consumedLookupKeys: [employee_id]
                  producedAttributes:
                    - path: employee.givenName
                      nativeName: first_name
                      nativeType: string
                      label: Given name
                    - path: employee.familyName
                      nativeName: last_name
                      nativeType: string
                      label: Family name
                    - path: employment.department
                      nativeName: department_code
                      nativeType: string
                      label: Department
                  connectionRef:
                    endpointUrl: https://hr.example.com/api/employees
                    configKeyPrefix: attribute-source.hr-workday
              directoryDatabase:
                summary: Database source for a directory-backed pipeline
                value:
                  sourceId: employee-directory
                  displayName: Employee directory table
                  description: Reads stable employee attributes from the directory database by person_id.
                  kind: DATABASE
                  managementMode: HYBRID
                  runtimeMode: REMOTE_EDK
                  consumedLookupKeys: [person_id]
                  producedAttributes:
                    - path: employee.email
                      nativeName: email_address
                      nativeType: varchar
                      label: Work email
                    - path: employment.costCenter
                      nativeName: cost_center
                      nativeType: varchar
                      label: Cost center
                  connectionRef:
                    configKeyPrefix: attribute-source.employee-directory
                    backingSourceId: directory.employee_profile
      responses:
        '201':
          description: Attribute source created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeSourceDefinition'
        '400':
          $ref: './common-components.yml#/components/responses/ValidationError'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'

  /sources/{sourceId}:
    get:
      operationId: getAttributeSource
      summary: Get an attribute source
      description: |
        Reads one source definition by the registry id used in pipeline bindings. The id is the
        EDK attribute-source id, not a VDX party id and not a credential configuration id.
      tags: [AttributeSources]
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './attribute-source-components.yml#/components/parameters/SourceId'
      responses:
        '200':
          description: Attribute source definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeSourceDefinition'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '404':
          $ref: './common-components.yml#/components/responses/NotFound'
    put:
      operationId: updateAttributeSource
      summary: Update an attribute source
      description: |
        Updates mutable source metadata and runtime contract fields. The `{sourceId}` path value is
        authoritative and is copied into `UpdateAttributeSourceArgs.sourceId`; any `sourceId` in
        the body is ignored by the REST command.
      tags: [AttributeSources]
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './attribute-source-components.yml#/components/parameters/SourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAttributeSourceRequest'
            examples:
              addEmploymentFields:
                summary: Add fields returned by the HR profile endpoint
                value:
                  description: Resolves employee credential and employment claims from the HR profile API by employee_id.
                  producedAttributes:
                    - path: employee.givenName
                      nativeName: first_name
                      nativeType: string
                      label: Given name
                    - path: employee.familyName
                      nativeName: last_name
                      nativeType: string
                      label: Family name
                    - path: employment.department
                      nativeName: department_code
                      nativeType: string
                      label: Department
                    - path: employment.jobTitle
                      nativeName: job_title
                      nativeType: string
                      label: Job title
              suspendSource:
                summary: Temporarily stop new pipeline use
                value:
                  lifecycleStatus: SUSPENDED
      responses:
        '200':
          description: Attribute source updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeSourceDefinition'
        '400':
          $ref: './common-components.yml#/components/responses/ValidationError'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '404':
          $ref: './common-components.yml#/components/responses/NotFound'
    delete:
      operationId: deleteAttributeSource
      summary: Delete an attribute source
      description: |
        Deletes the source definition for this tenant. Existing pipeline configuration should stop
        referencing the `sourceId` before deletion; the endpoint returns `204` when the command
        succeeds.
      tags: [AttributeSources]
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './attribute-source-components.yml#/components/parameters/SourceId'
      responses:
        '204':
          description: Attribute source deleted.
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '404':
          $ref: './common-components.yml#/components/responses/NotFound'

  /sources/{sourceId}/semantic-bindings:
    get:
      operationId: listAttributeSourceSemanticBindings
      summary: List semantic bindings for an attribute source
      description: |
        Lists the optional semantic annotations for the source's native fields. These records are
        separate from the source definition so an integration can first be registered and used by a
        pipeline, then enriched with catalog/profile meaning when that semantic model is available.
      tags: [AttributeSources]
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './attribute-source-components.yml#/components/parameters/SourceId'
      responses:
        '200':
          description: Semantic bindings for native fields produced by the source.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AttributeSourceSemanticBinding'
              examples:
                employeeCredentialBindings:
                  summary: Native HR fields bound to employee credential semantics
                  value:
                    - bindingId: bnd-hr-first-name
                      tenantId: acme
                      sourceId: hr-workday-profile
                      catalogId: employee-core
                      profileId: employee-credential-profile
                      setId: employment-credential-set
                      attributePath: employee.givenName
                      nativeField: first_name
                      createdAt: '2026-06-10T08:45:00Z'
                      updatedAt: '2026-06-10T08:45:00Z'
                    - bindingId: bnd-hr-department
                      tenantId: acme
                      sourceId: hr-workday-profile
                      catalogId: employee-core
                      profileId: employee-credential-profile
                      setId: employment-credential-set
                      attributePath: employment.department
                      nativeField: department_code
                      createdAt: '2026-06-10T08:45:00Z'
                      updatedAt: '2026-06-10T08:45:00Z'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '404':
          $ref: './common-components.yml#/components/responses/NotFound'
    put:
      operationId: setAttributeSourceSemanticBindings
      summary: Replace semantic bindings for an attribute source
      description: |
        Replaces the complete binding set for the source. Send every semantic binding that should
        remain active. The command stores tenant, source id, binding id, and timestamps; the request
        body only contains the authored `SemanticBindingInput` fields.
      tags: [AttributeSources]
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './attribute-source-components.yml#/components/parameters/SourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SemanticBindingInput'
            examples:
              employeeCredentialBindings:
                summary: Bind HR fields to the employee credential profile
                value:
                  - catalogId: employee-core
                    profileId: employee-credential-profile
                    setId: employment-credential-set
                    attributePath: employee.givenName
                    nativeField: first_name
                  - catalogId: employee-core
                    profileId: employee-credential-profile
                    setId: employment-credential-set
                    attributePath: employee.familyName
                    nativeField: last_name
                  - catalogId: employee-core
                    profileId: employee-credential-profile
                    setId: employment-credential-set
                    attributePath: employment.department
                    nativeField: department_code
      responses:
        '200':
          description: Semantic bindings replaced.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AttributeSourceSemanticBinding'
        '400':
          $ref: './common-components.yml#/components/responses/ValidationError'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '404':
          $ref: './common-components.yml#/components/responses/NotFound'

components:
  securitySchemes:
    bearer:
      $ref: './common-components.yml#/components/securitySchemes/bearer'
  schemas:
    AttributeSourceKind:
      $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceKind'
    AttributeSourceLifecycleStatus:
      $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceLifecycleStatus'
    AttributeSourceManagementMode:
      $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceManagementMode'
    AttributeSourceRuntimeMode:
      $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceRuntimeMode'
    ProducedAttribute:
      $ref: './attribute-source-components.yml#/components/schemas/ProducedAttribute'
    AttributeSourceConnectionRef:
      $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceConnectionRef'
    AttributeSourceDefinition:
      $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceDefinition'
    CreateAttributeSourceRequest:
      $ref: './attribute-source-components.yml#/components/schemas/CreateAttributeSourceRequest'
    UpdateAttributeSourceRequest:
      $ref: './attribute-source-components.yml#/components/schemas/UpdateAttributeSourceRequest'
    AttributeSourcePage:
      $ref: './attribute-source-components.yml#/components/schemas/AttributeSourcePage'
    SemanticBindingInput:
      $ref: './attribute-source-components.yml#/components/schemas/SemanticBindingInput'
    AttributeSourceSemanticBinding:
      $ref: './attribute-source-components.yml#/components/schemas/AttributeSourceSemanticBinding'