openapi: 3.1.0
info:
  title: Application Research CNAB Bundle API Resources Sources API
  version: 1.0.0
  description: 'API for managing Cloud Native Application Bundles (CNAB).


    This API provides endpoints for managing CNAB bundles, claims, claim results,

    dependencies, parameter sources, relocation mappings, and installation status.

    '
  contact:
    name: CNAB Specification
    url: https://cnab.io
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.example.com/v1
  description: Production server
- url: https://staging-api.example.com/v1
  description: Staging server
security:
- bearerAuth: []
- apiKey: []
tags:
- name: Sources
  description: Operations for managing component sources
paths:
  /components/{name}/sources:
    parameters:
    - $ref: '#/components/parameters/ComponentNameParam'
    get:
      tags:
      - Sources
      summary: Application Research List sources for a component
      operationId: listComponentSources
      parameters:
      - $ref: '#/components/parameters/VersionQueryParam'
      responses:
        '200':
          description: List of component sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceListResponse'
              examples:
                sourceList:
                  $ref: '#/components/examples/SourceListResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - Sources
      summary: Application Research Add a source to a component
      operationId: addComponentSource
      parameters:
      - $ref: '#/components/parameters/VersionQueryParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Source'
            examples:
              gitSource:
                $ref: '#/components/examples/GitHubSource'
      responses:
        '201':
          description: Source added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
              examples:
                gitSource:
                  $ref: '#/components/examples/GitHubSource'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ComponentName:
      type: string
      description: Fully qualified component name
      maxLength: 255
      pattern: ^[a-z][-a-z0-9]*([.][a-z][-a-z0-9]*)*[.][a-z]{2,}(/[a-z][-a-z0-9_]*([.][a-z][-a-z0-9_]*)*)+$
      examples:
      - github.com/acme.org/web-application
      - github.com/ailab.org/model-training-pipeline
    SourceListResponse:
      type: array
      items:
        $ref: '#/components/schemas/Source'
    Source:
      type: object
      description: Component source
      required:
      - name
      - type
      properties:
        name:
          $ref: '#/components/schemas/ElementName'
        type:
          type: string
          description: Source type
          examples:
          - git
          - helmChart
          - yaml
        extraIdentity:
          $ref: '#/components/schemas/IdentityAttribute'
        version:
          $ref: '#/components/schemas/Version'
        labels:
          $ref: '#/components/schemas/Labels'
        access:
          $ref: '#/components/schemas/Access'
        input:
          $ref: '#/components/schemas/Input'
    Labels:
      type: array
      items:
        $ref: '#/components/schemas/Label'
    Access:
      type: object
      description: Access specification for resources and sources
      required:
      - type
      properties:
        type:
          type: string
          description: Access type identifier
      discriminator:
        propertyName: type
        mapping:
          localBlob: '#/components/schemas/LocalBlobAccess'
          ociArtifact: '#/components/schemas/OciArtifactAccess'
          ociBlob: '#/components/schemas/OciBlobAccess'
          helm: '#/components/schemas/HelmAccess'
          gitHub: '#/components/schemas/GitHubAccess'
          github: '#/components/schemas/GitHubAccess'
          s3: '#/components/schemas/S3Access'
          npm: '#/components/schemas/NpmAccess'
          wget: '#/components/schemas/WgetAccess'
          http: '#/components/schemas/HttpAccess'
    Error:
      type: object
      description: Error response
      required:
      - code
      - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true
    Input:
      type: object
      description: Input specification for local resources
      required:
      - type
      properties:
        type:
          type: string
    Version:
      type: string
      description: Semantic version string
      pattern: ^[v]?(0|[1-9]\d*)(?:\.(0|[1-9]\d*))?(?:\.(0|[1-9]\d*))?(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
      examples:
      - 1.0.0
      - 2.5.1
      - v1.0.0-beta.1
    ElementName:
      type: string
      description: Element name for resources and sources
      minLength: 2
      pattern: ^[a-z0-9]([-_+a-z0-9]*[a-z0-9])?$
      examples:
      - frontend-image
      - backend-image
      - helm-chart
    Label:
      type: object
      description: A label with name-value pair
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: Label name
        value: {}
        version:
          type: string
          pattern: ^v[0-9]+$
        signing:
          type: boolean
          description: Whether this label should be included in signing
        merge:
          $ref: '#/components/schemas/Merge'
    IdentityAttribute:
      type: object
      description: Identity attributes for element identification
      additionalProperties:
        type: string
    Merge:
      type: object
      properties:
        algorithm:
          type: string
          pattern: ^[a-z][a-z0-9/_-]+$
        config: {}
  examples:
    ErrorNotFound:
      summary: Not Found Error
      description: Example not found error
      value:
        code: NOT_FOUND
        message: Component 'github.com/acme.org/unknown-component' not found
    ErrorBadRequest:
      summary: Bad Request Error
      description: Example bad request error
      value:
        code: BAD_REQUEST
        message: Invalid component name format
        details:
          field: component.name
          pattern: ^[a-z][-a-z0-9]*([.][a-z][-a-z0-9]*)*[.][a-z]{2,}(/[a-z][-a-z0-9_]*([.][a-z][-a-z0-9_]*)*)+$
    SourceListResponse:
      summary: Source list
      description: Example list of component sources
      value:
      - name: application-source
        type: git
        version: 2.5.1
        access:
          type: gitHub
          repoUrl: https://github.com/acme-org/web-application
          commit: a7f8d9e1c2b3a4f5e6d7c8b9a0f1e2d3c4b5a6f7
      - name: deployment-manifests
        type: helmChart
        version: 1.2.0
        access:
          type: helm
          helmRepository: https://charts.acme.org
          helmChart: web-app:1.2.0
    ErrorInternal:
      summary: Internal Error
      description: Example internal server error
      value:
        code: INTERNAL_ERROR
        message: An unexpected error occurred
        details:
          requestId: req-xyz789
    GitHubSource:
      summary: GitHub Source
      description: Example GitHub source
      value:
        name: application-source
        type: git
        version: 2.5.1
        access:
          type: gitHub
          repoUrl: https://github.com/acme-org/web-application
          commit: a7f8d9e1c2b3a4f5e6d7c8b9a0f1e2d3c4b5a6f7
        labels:
        - name: language
          value: javascript
  responses:
    BadRequest:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            badRequest:
              $ref: '#/components/examples/ErrorBadRequest'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notFound:
              $ref: '#/components/examples/ErrorNotFound'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internalError:
              $ref: '#/components/examples/ErrorInternal'
  parameters:
    VersionQueryParam:
      name: version
      in: query
      description: Component version (semver)
      schema:
        $ref: '#/components/schemas/Version'
    ComponentNameParam:
      name: name
      in: path
      required: true
      description: Component name (e.g., github.com/acme.org/web-application)
      schema:
        $ref: '#/components/schemas/ComponentName'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT-based authentication
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication