attribute-source-components.yml

# ============================================================================
# Reusable schemas, enums, and parameters for the Attribute Source API.
#
# The attribute-source-openapi.yml root re-exports the entity schemas it needs
# as thin stubs and references these definitions. Shared errors, bearer auth,
# and query pagination parameters live in ./common-components.yml.
#
# Every schema here is grounded in the Kotlin DTOs from the EDK attribute-source
# public module (package com.sphereon.attribute.source). Field names,
# nullability, defaults, and enum values match the serializable data classes.
# ============================================================================
openapi: 3.0.4
info:
  title: Attribute Source API - Components
  version: 0.1.0
  description: Reusable component schemas for tenant-scoped EDK attribute-source definitions exposed by VDX.
paths: {}
components:
  parameters:
    SourceId:
      name: sourceId
      in: path
      required: true
      description: |
        Stable EDK attribute-source id. This is the same value used by
        `AttributeSourceBinding.sourceInstanceId` in issuer pipeline configuration.
      schema:
        type: string
        example: hr-workday-profile

  schemas:
    # ---- Enums --------------------------------------------------------------

    AttributeSourceKind:
      type: string
      description: |
        Connector family for the source definition.
          - `REST_API`: a JSON REST integration with a service-specific endpoint contract.
          - `HTTP`: a generic HTTP source where the concrete verb, path, or payload is configured elsewhere.
          - `DATABASE`: a relational or queryable store reached through EDK or a remote connector.
          - `TABULAR`: a CSV, spreadsheet, batch roster, or other row/column input.
          - `VAULT`: a secret or claims vault integration.
          - `IAM`: an identity and access management directory or user-info source.
      enum: [REST_API, DATABASE, TABULAR, VAULT, IAM, HTTP]

    AttributeSourceLifecycleStatus:
      type: string
      description: |
        Operational status of the source.
          - `ACTIVE`: available for new or existing pipeline bindings.
          - `SUSPENDED`: retained in the registry but should not be selected for new runs.
          - `DECOMMISSIONED`: kept for audit or documentation only.
      enum: [ACTIVE, SUSPENDED, DECOMMISSIONED]

    AttributeSourceManagementMode:
      type: string
      description: |
        Who owns the source integration lifecycle.
          - `MANAGED`: VDX/EDK owns the integration configuration and lifecycle.
          - `EXTERNAL`: the source is operated by another system and only referenced here.
          - `HYBRID`: VDX/EDK owns registry metadata while another service owns the runtime connector.
      enum: [MANAGED, EXTERNAL, HYBRID]

    AttributeSourceRuntimeMode:
      type: string
      description: |
        Where runtime lookups are expected to execute.
          - `VDX_MANAGED`: executed by the VDX deployment.
          - `REMOTE_EDK`: executed by a connected EDK runtime.
          - `THIRD_PARTY`: executed by a third-party system addressed through a connector reference.
      enum: [VDX_MANAGED, REMOTE_EDK, THIRD_PARTY]

    # ---- Source contract ----------------------------------------------------

    ProducedAttribute:
      type: object
      description: |
        One logical attribute the source can produce. `path` is the pipeline-facing or
        credential-facing attribute path. `nativeName` records the field name as it appears in the
        source system, so a profile claim such as `employee.givenName` can be traced back to
        `first_name` in an HR API response.
      required: [path]
      example:
        path: employee.givenName
        nativeName: first_name
        nativeType: string
        label: Given name
      properties:
        path:
          type: string
          description: Logical attribute path used by the pipeline and optional semantic binding.
          example: employee.givenName
        nativeName:
          type: string
          nullable: true
          description: Field, column, claim, or JSON property name in the source system.
          example: first_name
        nativeType:
          type: string
          nullable: true
          description: Source-native value type, for example `string`, `varchar`, `date`, or `boolean`.
          example: string
        label:
          type: string
          nullable: true
          description: Human-readable label for documentation and operator views.
          example: Given name

    AttributeSourceConnectionRef:
      type: object
      description: |
        Reference to connection material. Endpoint locations and configuration namespaces may be
        recorded here, but credentials and secrets are never inlined. Runtime connectors resolve
        `configKeyPrefix` through the deployment's configuration or secret store.
      example:
        endpointUrl: https://hr.example.com/api/employees
        configKeyPrefix: attribute-source.hr-workday
        backingSourceId: workday.employee-profile
      properties:
        endpointUrl:
          type: string
          nullable: true
          format: uri
          description: Endpoint template or base URL for the integration when exposing it is safe.
          example: https://hr.example.com/api/employees
        configKeyPrefix:
          type: string
          nullable: true
          description: Prefix used by the runtime connector to resolve credentials and non-public settings.
          example: attribute-source.hr-workday
        backingSourceId:
          type: string
          nullable: true
          description: Connector-specific backing id, such as a table, view, dataset, or upstream source name.
          example: workday.employee-profile

    AttributeSourceDefinition:
      type: object
      description: |
        Persisted tenant-scoped source definition returned by the EDK attribute-source registry.
        The REST layer obtains tenant context from the session; the `tenantId` in the response is
        assigned by the command implementation.
      required:
        - sourceId
        - tenantId
        - displayName
        - kind
        - lifecycleStatus
        - managementMode
        - consumedLookupKeys
        - producedAttributes
        - createdAt
        - updatedAt
      example:
        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'
      properties:
        sourceId:
          type: string
          description: Stable source id used by registry lookups and pipeline bindings.
          example: hr-workday-profile
        tenantId:
          type: string
          description: Tenant that owns this source definition.
          example: acme
        displayName:
          type: string
          description: Operator-facing source name.
          example: Workday profile lookup
        description:
          type: string
          nullable: true
          description: Short explanation of what the source contributes and when it is used.
        kind:
          $ref: '#/components/schemas/AttributeSourceKind'
        lifecycleStatus:
          $ref: '#/components/schemas/AttributeSourceLifecycleStatus'
        managementMode:
          $ref: '#/components/schemas/AttributeSourceManagementMode'
        runtimeMode:
          description: Runtime execution location. Optional in the Kotlin DTO and may be omitted when unknown.
          $ref: '#/components/schemas/AttributeSourceRuntimeMode'
        consumedLookupKeys:
          type: array
          description: Lookup keys the pipeline must provide before this source can be queried.
          items:
            type: string
          example: [employee_id]
        producedAttributes:
          type: array
          description: Attribute contract exposed to pipeline steps and optional semantic bindings.
          items:
            $ref: '#/components/schemas/ProducedAttribute'
        connectionRef:
          description: Optional pointer to endpoint and connector configuration material.
          $ref: '#/components/schemas/AttributeSourceConnectionRef'
        createdAt:
          type: string
          format: date-time
          description: Registry creation timestamp assigned by the command implementation.
        updatedAt:
          type: string
          format: date-time
          description: Last registry update timestamp assigned by the command implementation.

    CreateAttributeSourceRequest:
      type: object
      description: |
        Input for creating an attribute source. Maps directly to `CreateAttributeSourceArgs`.
        Defaults are applied by the Kotlin DTO: `managementMode` defaults to `EXTERNAL`,
        `consumedLookupKeys` and `producedAttributes` default to empty lists, and `runtimeMode` and
        `connectionRef` may be omitted.
      required: [displayName, kind]
      example:
        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
        connectionRef:
          endpointUrl: https://hr.example.com/api/employees
          configKeyPrefix: attribute-source.hr-workday
      properties:
        sourceId:
          type: string
          nullable: true
          description: Optional caller-chosen id. Omit to let the command assign one.
          example: hr-workday-profile
        displayName:
          type: string
          description: Operator-facing source name.
          example: Workday profile lookup
        description:
          type: string
          nullable: true
          description: Short explanation of what the source contributes and when it is used.
        kind:
          $ref: '#/components/schemas/AttributeSourceKind'
        managementMode:
          $ref: '#/components/schemas/AttributeSourceManagementMode'
        runtimeMode:
          description: Runtime execution location. Optional in the Kotlin DTO and may be omitted when unknown.
          $ref: '#/components/schemas/AttributeSourceRuntimeMode'
        consumedLookupKeys:
          type: array
          description: Lookup keys required from session, credential, or upstream pipeline context.
          items:
            type: string
          example: [employee_id]
        producedAttributes:
          type: array
          description: Fields the source can contribute to the pipeline.
          items:
            $ref: '#/components/schemas/ProducedAttribute'
        connectionRef:
          description: Optional pointer to endpoint and connector configuration material.
          $ref: '#/components/schemas/AttributeSourceConnectionRef'

    UpdateAttributeSourceRequest:
      type: object
      description: |
        Input for updating the mutable fields of an attribute source. Maps directly to
        `UpdateAttributeSourceArgs`; omitted fields are left unchanged. The path `{sourceId}` is
        authoritative and the REST command copies it into the command args.
      example:
        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: employment.jobTitle
            nativeName: job_title
            nativeType: string
            label: Job title
      properties:
        sourceId:
          type: string
          description: Ignored when present; the path `sourceId` is authoritative.
          example: hr-workday-profile
        displayName:
          type: string
          description: Replacement operator-facing source name.
        description:
          type: string
          nullable: true
          description: Replacement source description.
        lifecycleStatus:
          $ref: '#/components/schemas/AttributeSourceLifecycleStatus'
        managementMode:
          $ref: '#/components/schemas/AttributeSourceManagementMode'
        runtimeMode:
          description: Runtime execution location. Optional in the Kotlin DTO and may be omitted when unchanged or unknown.
          $ref: '#/components/schemas/AttributeSourceRuntimeMode'
        consumedLookupKeys:
          type: array
          description: Replacement lookup key contract.
          items:
            type: string
        producedAttributes:
          type: array
          description: Replacement produced-attribute contract.
          items:
            $ref: '#/components/schemas/ProducedAttribute'
        connectionRef:
          description: Optional pointer to endpoint and connector configuration material.
          $ref: '#/components/schemas/AttributeSourceConnectionRef'

    AttributeSourcePage:
      type: object
      description: |
        Direct serialization of `Page<AttributeSourceDefinition>` from
        `com.sphereon.core.api.pagination.Page`. This endpoint intentionally does not use the VDX
        `data`/`pagination` response envelope because the HTTP command delegates the EDK page
        result directly.
      required: [items, total_count, limit, offset]
      example:
        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
            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
      properties:
        items:
          type: array
          description: Attribute sources in this page.
          items:
            $ref: '#/components/schemas/AttributeSourceDefinition'
        total_count:
          type: integer
          format: int64
          description: Total count of matching sources across all pages.
          minimum: 0
        limit:
          type: integer
          description: Page size used by the command.
          minimum: 0
        offset:
          type: integer
          description: Offset used by the command.
          minimum: 0
        has_more:
          type: boolean
          description: True when more items exist after this page.
        page_number:
          type: integer
          description: Zero-based page number derived from `offset / limit`.
          minimum: 0
        total_pages:
          type: integer
          description: Total number of pages derived from `total_count` and `limit`.
          minimum: 0

    # ---- Semantic bindings -------------------------------------------------

    SemanticBindingInput:
      type: object
      description: |
        Authored semantic binding for one native source field. The source can operate without these
        bindings; when present, they describe what semantic catalog/profile/set attribute a native
        field contributes.
      required: [attributePath]
      example:
        catalogId: employee-core
        profileId: employee-credential-profile
        setId: employment-credential-set
        attributePath: employee.givenName
        nativeField: first_name
      properties:
        catalogId:
          type: string
          nullable: true
          description: Semantic catalog id that defines the attribute path.
          example: employee-core
        profileId:
          type: string
          nullable: true
          description: Profile id when the binding is specific to a credential or use-case profile.
          example: employee-credential-profile
        setId:
          type: string
          nullable: true
          description: Attribute set id within the profile, when applicable.
          example: employment-credential-set
        attributePath:
          type: string
          description: Semantic or profile attribute path contributed by the native field.
          example: employee.givenName
        nativeField:
          type: string
          nullable: true
          description: Source-native field name that produces the semantic attribute.
          example: first_name

    AttributeSourceSemanticBinding:
      allOf:
        - $ref: '#/components/schemas/SemanticBindingInput'
        - type: object
          description: Persisted semantic binding with registry identity and timestamps assigned by the command.
          required: [bindingId, tenantId, sourceId, createdAt, updatedAt]
          properties:
            bindingId:
              type: string
              description: Server-assigned binding id.
              example: bnd-hr-first-name
            tenantId:
              type: string
              description: Tenant that owns the binding.
              example: acme
            sourceId:
              type: string
              description: Source this binding belongs to.
              example: hr-workday-profile
            createdAt:
              type: string
              format: date-time
              description: Binding creation timestamp assigned by the command implementation.
              example: '2026-06-10T08:45:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Last binding update timestamp assigned by the command implementation.
              example: '2026-06-10T08:45:00Z'
      example:
        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'