openapi: 3.1.0
info:
  title: Application Research CNAB Bundle API Resources Claims 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: Claims
  description: Operations for managing installation claims
paths:
  /claims:
    get:
      tags:
      - Claims
      summary: Application Research List all claims
      operationId: listClaims
      parameters:
      - name: installation
        in: query
        description: Filter by installation name
        schema:
          type: string
      - name: action
        in: query
        description: Filter by action type
        schema:
          type: string
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      responses:
        '200':
          description: List of claims
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimListResponse'
              examples:
                claimList:
                  $ref: '#/components/examples/ClaimListResponse'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - Claims
      summary: Application Research Create a new claim
      operationId: createClaim
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Claim'
            examples:
              installClaim:
                $ref: '#/components/examples/ClaimInstall'
      responses:
        '201':
          description: Claim created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
              examples:
                installClaim:
                  $ref: '#/components/examples/ClaimInstall'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /claims/{id}:
    parameters:
    - $ref: '#/components/parameters/ClaimIdParam'
    get:
      tags:
      - Claims
      summary: Application Research Get a claim by ID
      operationId: getClaim
      responses:
        '200':
          description: Claim details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
              examples:
                installClaim:
                  $ref: '#/components/examples/ClaimInstall'
                upgradeClaim:
                  $ref: '#/components/examples/ClaimUpgrade'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    BundleOutput:
      type: object
      description: A value produced by running an invocation image
      required:
      - definition
      - path
      properties:
        definition:
          type: string
          description: The name of a definition describing the schema
        description:
          type: string
          description: A user-friendly description of this output
        path:
          type: string
          description: The path inside the invocation image where output is written
          pattern: ^/cnab/app/outputs/.+$
        applyTo:
          type: array
          description: An optional list of actions producing this output
          items:
            type: string
    Claim:
      type: object
      description: CNAB Claim representing an installation action
      required:
      - id
      - installation
      - action
      - bundle
      - revision
      - created
      properties:
        id:
          type: string
          description: The claim ID (ULID)
        installation:
          type: string
          description: The name of the installation
        action:
          type: string
          description: The name of the action (install, uninstall, upgrade, or custom)
        bundle:
          $ref: '#/components/schemas/Bundle'
        bundleReference:
          type: string
          description: A canonical reference to the bundle used
        revision:
          type: string
          description: The revision ID (ULID)
        created:
          type: string
          format: date-time
          description: The date created (ISO-8601)
        parameters:
          type: object
          description: Key/value pairs of parameter name to value
          additionalProperties: true
        custom:
          type: object
          description: Reserved for custom extensions
          additionalProperties: true
    Credential:
      type: object
      description: Defines a credential and where it should be placed
      properties:
        description:
          type: string
          description: A user-friendly description of this credential
        env:
          type: string
          description: The environment variable name for this credential
        path:
          type: string
          description: The path inside the invocation image for mounting credentials
        required:
          type: boolean
          description: Indicates whether this credential must be supplied
          default: false
        applyTo:
          type: array
          description: An optional list of actions handling this credential
          items:
            type: string
    InvocationImage:
      type: object
      description: A bootstrapping image for the CNAB bundle
      required:
      - image
      properties:
        image:
          type: string
          description: A resolvable reference to the image
        imageType:
          type: string
          description: The type of image
          default: oci
        contentDigest:
          type: string
          description: A cryptographic hash digest of the image contents
        size:
          type: integer
          description: The image size in bytes
        mediaType:
          type: string
          description: The media type of the image
        labels:
          type: object
          description: Key/value pairs for identifying attributes
          additionalProperties:
            type: string
    ClaimListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Claim'
        total:
          type: integer
          description: Total number of claims
    Action:
      type: object
      description: A custom action that can be triggered on the bundle
      properties:
        title:
          type: string
          description: A human-readable name for this action
        description:
          type: string
          description: A description of the purpose of this action
        modifies:
          type: boolean
          description: Whether the action can change any managed resource
        stateless:
          type: boolean
          description: Whether the action is purely informational
          default: false
    Bundle:
      type: object
      description: Cloud Native Application Bundle Descriptor (CNAB v1)
      required:
      - schemaVersion
      - name
      - version
      - invocationImages
      properties:
        schemaVersion:
          type: string
          description: The version of the CNAB specification
          const: v1
        name:
          type: string
          description: The name of this bundle
          examples:
          - my-wordpress-bundle
        version:
          type: string
          description: A SemVer2 version for this bundle
          pattern: ^v?([0-9]+)(\.[0-9]+)?(\.[0-9]+)?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?$
          examples:
          - 1.2.3
          - 2.0.1-beta.1
        description:
          type: string
          description: A description of this bundle, intended for users
        keywords:
          type: array
          description: A list of keywords describing the bundle
          items:
            type: string
          examples:
          - - wordpress
            - blog
            - cms
        maintainers:
          type: array
          description: A list of parties responsible for this bundle
          items:
            $ref: '#/components/schemas/Maintainer'
        license:
          type: string
          description: The SPDX license code or proprietary license name
          examples:
          - Apache-2.0
          - MIT
        invocationImages:
          type: array
          description: The array of invocation image definitions
          minItems: 1
          items:
            $ref: '#/components/schemas/InvocationImage'
        images:
          type: object
          description: Images used by this bundle
          additionalProperties:
            $ref: '#/components/schemas/Image'
        credentials:
          type: object
          description: Credentials to be injected into the invocation image
          additionalProperties:
            $ref: '#/components/schemas/Credential'
        parameters:
          type: object
          description: Parameters that can be injected into the invocation image
          additionalProperties:
            $ref: '#/components/schemas/Parameter'
        definitions:
          type: object
          description: JSON Schema definitions for parameters and outputs
          additionalProperties:
            $ref: '#/components/schemas/Definition'
        outputs:
          type: object
          description: Values produced by executing the invocation image
          additionalProperties:
            $ref: '#/components/schemas/BundleOutput'
        actions:
          type: object
          description: Custom actions that can be triggered on this bundle
          additionalProperties:
            $ref: '#/components/schemas/Action'
        requiredExtensions:
          type: array
          description: Extensions required for this bundle
          items:
            type: string
        custom:
          type: object
          description: Reserved for custom extensions
          additionalProperties: true
    Maintainer:
      type: object
      description: Information about a bundle maintainer
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the maintainer
        email:
          type: string
          format: email
          description: Email address of the maintainer
        url:
          type: string
          format: uri
          description: URL for the maintainer
    Definition:
      type:
      - object
      - boolean
      description: JSON Schema definition for a parameter or output
      properties:
        $id:
          type: string
          format: uri-reference
        $schema:
          type: string
          format: uri
        $ref:
          type: string
          format: uri-reference
        $comment:
          type: string
        title:
          type: string
        description:
          type: string
        type:
          oneOf:
          - $ref: '#/components/schemas/SimpleType'
          - type: array
            items:
              $ref: '#/components/schemas/SimpleType'
            minItems: 1
            uniqueItems: true
        default: true
        examples:
          type: array
        enum:
          type: array
          minItems: 1
          uniqueItems: true
        const: true
        format:
          type: string
        pattern:
          type: string
          format: regex
        minLength:
          type: integer
          minimum: 0
        maxLength:
          type: integer
          minimum: 0
        minimum:
          type: integer
        maximum:
          type: integer
        exclusiveMinimum:
          type: integer
        exclusiveMaximum:
          type: integer
        multipleOf:
          type: integer
          exclusiveMinimum: 0
        minItems:
          type: integer
          minimum: 0
        maxItems:
          type: integer
          minimum: 0
        uniqueItems:
          type: boolean
          default: false
        minProperties:
          type: integer
          minimum: 0
        maxProperties:
          type: integer
          minimum: 0
        required:
          type: array
          items:
            type: string
          uniqueItems: true
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Definition'
        additionalProperties:
          oneOf:
          - type: boolean
          - $ref: '#/components/schemas/Definition'
        items:
          oneOf:
          - $ref: '#/components/schemas/Definition'
          - type: array
            items:
              $ref: '#/components/schemas/Definition'
            minItems: 1
    Error:
      type: object
      description: Error response
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Parameter:
      type: object
      description: A parameter that can be passed into the invocation image
      required:
      - definition
      - destination
      properties:
        definition:
          type: string
          description: The name of a definition describing the schema
        description:
          type: string
          description: A user-friendly description of this parameter
        destination:
          $ref: '#/components/schemas/ParameterDestination'
        required:
          type: boolean
          description: Indicates whether this parameter must be supplied
          default: false
        applyTo:
          type: array
          description: An optional list of actions handling this parameter
          items:
            type: string
    SimpleType:
      type: string
      enum:
      - array
      - boolean
      - integer
      - 'null'
      - number
      - object
      - string
    Image:
      type: object
      description: An application image for this CNAB bundle
      required:
      - image
      properties:
        image:
          type: string
          description: A resolvable reference to the image
        imageType:
          type: string
          description: The type of image
          default: oci
        description:
          type: string
          description: A description of the purpose of this image
        contentDigest:
          type: string
          description: A cryptographic hash digest of the image contents
        size:
          type: integer
          description: The image size in bytes
        mediaType:
          type: string
          description: The media type of the image
        labels:
          type: object
          description: Key/value pairs for identifying attributes
          additionalProperties:
            type: string
    ParameterDestination:
      type: object
      description: Where the parameter value should be placed
      properties:
        env:
          type: string
          description: The environment variable name for the parameter value
        path:
          type: string
          description: The path inside the invocation image for the parameter
  examples:
    ErrorNotFound:
      summary: Not found error
      description: Example error when resource is not found
      value:
        code: NOT_FOUND
        message: Bundle 'my-bundle' not found
    ErrorBadRequest:
      summary: Bad request error
      description: Example error for invalid input
      value:
        code: BAD_REQUEST
        message: Invalid bundle schema
        details:
          field: version
          error: Version must follow SemVer2 format
    ClaimListResponse:
      summary: Claim list response
      description: Example response for listing claims
      value:
        items:
        - id: 01HQXYZ123456789ABCDEFGH
          installation: my-wordpress-prod
          action: install
          revision: 01HQXYZ123456789ABCDEFGI
          created: '2024-01-15T10:30:00Z'
        - id: 01HQXYZ223456789ABCDEFGH
          installation: my-wordpress-prod
          action: upgrade
          revision: 01HQXYZ223456789ABCDEFGI
          created: '2024-02-20T14:45:00Z'
        total: 2
    ClaimUpgrade:
      summary: Upgrade claim example
      description: Example claim for an upgrade action
      value:
        id: 01HQXYZ223456789ABCDEFGH
        installation: my-wordpress-prod
        action: upgrade
        bundle:
          schemaVersion: v1
          name: my-wordpress-bundle
          version: 1.3.0
          invocationImages:
          - image: example.com/my-wordpress-bundle:1.3.0
            imageType: oci
        bundleReference: example.com/my-wordpress-bundle:1.3.0
        revision: 01HQXYZ223456789ABCDEFGI
        created: '2024-02-20T14:45:00Z'
        parameters:
          site-name: My Production Blog
          replica-count: 5
    ErrorInternal:
      summary: Internal error
      description: Example internal server error
      value:
        code: INTERNAL_ERROR
        message: An unexpected error occurred
        details:
          requestId: req-123456
    ClaimInstall:
      summary: Install claim example
      description: Example claim for an install action
      value:
        id: 01HQXYZ123456789ABCDEFGH
        installation: my-wordpress-prod
        action: install
        bundle:
          schemaVersion: v1
          name: my-wordpress-bundle
          version: 1.2.3
          invocationImages:
          - image: example.com/my-wordpress-bundle:1.2.3
            imageType: oci
        bundleReference: example.com/my-wordpress-bundle:1.2.3
        revision: 01HQXYZ123456789ABCDEFGI
        created: '2024-01-15T10:30:00Z'
        parameters:
          site-name: My Production Blog
          replica-count: 3
  responses:
    BadRequest:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidSchema:
              $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:
    OffsetParam:
      name: offset
      in: query
      description: Number of items to skip
      schema:
        type: integer
        minimum: 0
        default: 0
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    ClaimIdParam:
      name: id
      in: path
      required: true
      description: Claim ID (ULID)
      schema:
        type: string
  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