CNAB (Cloud Native Application Bundle) is a specification for packaging and distributing cloud-native applications. The API manages bundle lifecycle including installation, upgrading, and uninstalling bundled applications across cloud environments.
openapi: 3.1.0
info:
title: Application Research CNAB Bundle 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
tags:
- name: Bundles
description: Operations for managing CNAB bundle descriptors
- name: Claim Results
description: Operations for managing claim execution results
- name: Claims
description: Operations for managing installation claims
- name: Status
description: Operations for querying installation status
paths:
/bundles:
get:
tags:
- Bundles
summary: Application Research List all bundles
operationId: listBundles
parameters:
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/OffsetParam'
- name: keyword
in: query
description: Filter bundles by keyword
schema:
type: string
responses:
'200':
description: List of bundles
content:
application/json:
schema:
$ref: '#/components/schemas/BundleListResponse'
examples:
bundleList:
$ref: '#/components/examples/BundleListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
post:
tags:
- Bundles
summary: Application Research Create a new bundle
operationId: createBundle
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Bundle'
examples:
wordpress:
$ref: '#/components/examples/WordPressBundle'
cassandra:
$ref: '#/components/examples/CassandraBundle'
mlInference:
$ref: '#/components/examples/MLInferenceBundle'
responses:
'201':
description: Bundle created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Bundle'
examples:
wordpress:
$ref: '#/components/examples/WordPressBundle'
'400':
$ref: '#/components/responses/BadRequest'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalError'
/bundles/{name}:
parameters:
- $ref: '#/components/parameters/BundleNameParam'
get:
tags:
- Bundles
summary: Application Research Get a bundle by name
operationId: getBundle
parameters:
- $ref: '#/components/parameters/VersionQueryParam'
responses:
'200':
description: Bundle details
content:
application/json:
schema:
$ref: '#/components/schemas/Bundle'
examples:
wordpress:
$ref: '#/components/examples/WordPressBundle'
cassandra:
$ref: '#/components/examples/CassandraBundle'
mlInference:
$ref: '#/components/examples/MLInferenceBundle'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
put:
tags:
- Bundles
summary: Application Research Update an existing bundle
operationId: updateBundle
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Bundle'
examples:
wordpress:
$ref: '#/components/examples/WordPressBundle'
responses:
'200':
description: Bundle updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Bundle'
examples:
wordpress:
$ref: '#/components/examples/WordPressBundle'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
delete:
tags:
- Bundles
summary: Application Research Delete a bundle
operationId: deleteBundle
parameters:
- $ref: '#/components/parameters/VersionQueryParam'
responses:
'204':
description: Bundle deleted successfully
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/bundles/{name}/actions/{action}:
post:
tags:
- Bundles
summary: Application Research Execute a bundle action
operationId: executeBundleAction
parameters:
- $ref: '#/components/parameters/BundleNameParam'
- $ref: '#/components/parameters/ActionParam'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ActionExecutionRequest'
examples:
installWordPress:
$ref: '#/components/examples/ActionExecutionRequest'
responses:
'202':
description: Action accepted for execution
content:
application/json:
schema:
$ref: '#/components/schemas/Claim'
examples:
installClaim:
$ref: '#/components/examples/ClaimInstall'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/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'
/claims/{id}/results:
parameters:
- $ref: '#/components/parameters/ClaimIdParam'
get:
tags:
- Claim Results
summary: Application Research List results for a claim
operationId: listClaimResults
responses:
'200':
description: List of claim results
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimResultListResponse'
examples:
resultList:
$ref: '#/components/examples/ClaimResultListResponse'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/results/{id}:
get:
tags:
- Claim Results
summary: Application Research Get a claim result by ID
operationId: getClaimResult
parameters:
- $ref: '#/components/parameters/ResultIdParam'
responses:
'200':
description: Claim result details
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimResult'
examples:
successResult:
$ref: '#/components/examples/ClaimResultSuccess'
failedResult:
$ref: '#/components/examples/ClaimResultFailed'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/installations:
get:
tags:
- Status
summary: Application Research List all installations
operationId: listInstallations
responses:
'200':
description: List of installations with status
content:
application/json:
schema:
$ref: '#/components/schemas/StatusListResponse'
examples:
installationList:
$ref: '#/components/examples/StatusListResponse'
'500':
$ref: '#/components/responses/InternalError'
/installations/{name}/status:
get:
tags:
- Status
summary: Application Research Get installation status
operationId: getInstallationStatus
parameters:
- $ref: '#/components/parameters/InstallationNameParam'
responses:
'200':
description: Installation status
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
examples:
readyStatus:
$ref: '#/components/examples/StatusReady'
pendingStatus:
$ref: '#/components/examples/StatusPending'
failedStatus:
$ref: '#/components/examples/StatusFailed'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
LimitParam:
name: limit
in: query
description: Maximum number of items to return
schema:
type: integer
minimum: 1
maximum: 100
default: 20
OffsetParam:
name: offset
in: query
description: Number of items to skip
schema:
type: integer
minimum: 0
default: 0
BundleNameParam:
name: name
in: path
required: true
description: Bundle name
schema:
type: string
VersionQueryParam:
name: version
in: query
description: Specific version to retrieve
schema:
type: string
ActionParam:
name: action
in: path
required: true
description: Action to execute (install, upgrade, uninstall, or custom action)
schema:
type: string
ClaimIdParam:
name: id
in: path
required: true
description: Claim ID (ULID)
schema:
type: string
ResultIdParam:
name: id
in: path
required: true
description: Result ID (ULID)
schema:
type: string
InstallationNameParam:
name: name
in: path
required: true
description: Installation name
schema:
type: string
schemas:
# List Response Wrappers
BundleListResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Bundle'
total:
type: integer
description: Total number of bundles
limit:
type: integer
description: Number of items per page
offset:
type: integer
description: Current offset
ClaimListResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Claim'
total:
type: integer
description: Total number of claims
ClaimResultListResponse:
type: array
items:
$ref: '#/components/schemas/ClaimResult'
StatusListResponse:
type: array
items:
$ref: '#/components/schemas/Status'
# Action Execution
ActionExecutionRequest:
type: object
properties:
parameters:
type: object
description: Parameter values for the action
additionalProperties: true
credentials:
type: object
description: Credential values for the action
additionalProperties:
type: string
# Core CNAB Schemas
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
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
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
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
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
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
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
SimpleType:
type: string
enum:
- array
- boolean
- integer
- 'null'
- number
- object
- string
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
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
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
ClaimResult:
type: object
description: CNAB Claim Result representing the outcome of an action
required:
- id
- claimId
- status
- created
properties:
id:
type: string
description: The result ID (ULID)
claimId:
type: string
description: The associated claim ID
status:
$ref: '#/components/schemas/ClaimResultStatus'
message:
type: string
description: The last message from the invocation image or runtime
created:
type: string
format: date-time
description: The date created (ISO-8601)
outputs:
type: object
description: Map of outputs generated by the operation
additionalProperties:
$ref: '#/components/schemas/ClaimResultOutput'
custom:
type: object
description: Reserved for custom extensions
additionalProperties: true
ClaimResultStatus:
type: string
description: The status of the operation
enum:
- canceled
- failed
- succeeded
- pending
- running
- unknown
ClaimResultOutput:
type: object
description: An output value from a claim result
properties:
contentDigest:
type: string
description: A cryptographic hash digest of the output contents
additionalProperties: true
Status:
type: object
description: Overall status of a CNAB installation
properties:
status:
type: string
description: Status identifier (Ready, Pending, Failed are well known)
message:
type: string
description: Details about the current status
components:
type: object
description: Map of component names to their status
additionalProperties:
$ref: '#/components/schemas/StatusComponent'
additionalProperties: true
StatusComponent:
type: object
description: Status of a component in a CNAB installation
properties:
status:
type: string
description: Status identifier
message:
type: string
description: Details about the current status
components:
type: object
description: Nested components with their own status
additionalProperties:
$ref: '#/components/schemas/StatusComponent'
additionalProperties: true
Dependencies:
type: object
description: CNAB Dependencies extension
properties:
requires:
type: object
description: Dependent bundles required by this bundle
additionalProperties:
$ref: '#/components/schemas/Dependency'
minProperties: 1
minProperties: 1
Dependency:
type: object
description: A dependency on another bundle
required:
- bundle
properties:
bundle:
type: string
description: A reference to a bundle (REGISTRY/NAME format)
version:
$ref: '#/components/schemas/DependencyVersion'
DependencyVersion:
type: object
description: Version criteria for selecting a dependency
minProperties: 1
properties:
ranges:
type: array
description: Array of allowed version ranges (semver format)
items:
type: string
minItems: 1
prereleases:
type: boolean
description: Whether prerelease versions are allowed
default: false
ParameterSources:
type: object
description: CNAB Parameter Sources extension
additionalProperties:
$ref: '#/components/schemas/ParameterSource'
minProperties: 1
ParameterSource:
type: object
description: Defines how a parameter value should be sourced
minProperties: 1
properties:
priority:
type: array
description: Source types in priority order
items:
type: string
enum:
- output
minItems: 1
sources:
type: object
description: Source definitions for the parameter
properties:
output:
$ref: '#/components/schemas/ParameterSourceOutput'
minProperties: 1
ParameterSourceOutput:
type: object
description: Specifies that the source is an output
required:
- name
properties:
name:
type: string
description: The name of the source output
minLength: 1
RelocationMapping:
type: object
description: Mapping of original image references to relocated destinations
additionalProperties:
type: string
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
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'
Conflict:
description: Resource already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
conflict:
$ref: '#/components/examples/ErrorConflict'
Internal
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/application-research/refs/heads/main/openapi/cloud-native-application-bundle-openapi.yml