Charmcraft (SchemaStore) JSON Schema

Type	PlatformCharm \| BasesCharm
File match	`charmcraft.yaml`
Schema URL	https://catalog.lintel.tools/schemas/schemastore/charmcraft/latest.json
Source	https://raw.githubusercontent.com/canonical/charmcraft/main/schema/charmcraft.json

Validate with Lintel

npx @lintel/lintel check

Type: PlatformCharm | BasesCharm

One of

1. PlatformCharm object

2. BasesCharm object

Definitions

AnalysisConfig object

Definition of analysis configuration.

ignore object

Definition of analysis.ignore configuration.

2 nested properties

attributes string[]

Default:

[]

linters string[]

Default:

[]

Base object

Represents a base.

name string required

channel string required

architectures string[]

Default:

[
  "amd64"
]

BasesCharm object

A charm using the deprecated bases keyword.

This type of charm only supports the following bases: - Ubuntu 18.04 - Ubuntu 20.04 - Ubuntu 22.04 - Alma Linux 9

name string required

The name of the project on Charmhub.

This value will be used both in the URL of the charm on Charmhub and when deploying the charm with juju.

Charms should follow the charm naming guidelines <https://juju.is/docs/sdk/naming>_.

Examples: "mysql", "mysql-k8s"

minLength=1maxLength=40

summary string required

A brief (one-line) summary of your charm.

maxLength=200

description string required

A multi-line summary of your charm.

type string required

Constant: "charm"

bases BasesConfiguration[] required

minItems=1

title string | null

Default: null

base null

Default: null

build-base string | null

Default: null

adopt-info string | null

Selects a part to inherit metadata from.

Default: null

Examples: "foo-part"

parts Record<string, object>

Configures the various mechanisms to obtain, process and prepare data from different sources that end up being a part of the final charm.

Keys are user-defined part names. The value of each key is a map where keys are part names.

Example::

parts:
  libs:
    plugin: dump
    source: /usr/local/lib/
    organize:
      "libxxx.so*": lib/
    prime:
      - lib/

Default:

{
  "charm": {
    "plugin": "charm",
    "source": "."
  }
}

package-repositories object[] | null

The package repositories to use for build and stage packages.

Default: null

Examples:

"[{type: apt,                components: [main],                suites: [xenial],                key-id: 78E1918602959B9C59103100F1831DDAFC42E99D,                url: http://ppa.launchpad.net/snappy-dev/snapcraft-daily/ubuntu}]"

analysis AnalysisConfig | null

How analysis done on the charm will behave.

Currently the only options are to ignore attributes or linters.

Default: null

charmhub Charmhub | null

(DEPRECATED): Configuration for accessing charmhub.

Default: null

charm-libs CharmLib[]

actions object | null

Defines one or more actions.

This key is equivalent to the actions.yaml file <https://juju.is/docs/sdk/actions-yaml>_.

Default: null

assumes string | object[] | null

Explicitly state features a Juju model must be able to provide for a successful deployment of this charm. When a charm includes such requirements, Juju performs a pre-deployment check and displays user-friendly error messages if a feature requirement cannot be met by the model that the user is trying to deploy the charm to. If the assumes section of the charm metadata is omitted, Juju will make a best-effort attempt to deploy the charm, and users must rely on the output of juju status to figure out whether the deployment was successful.

The key consists of a list of features that can be given either directly or, depending on the complexity of the condition you want to enforce, nested under one or both of the boolean expressions any-of or all-of, as shown below. In order for a charm to be deployed, all entries in the assumes block must be satisfied.

Structure::

assumes:
  - <feature-1>
  - any-of:
    - <feature-2>
    - <feature-3>
  - all-of:
    - <feature-4>
    - <feature-5>

Juju version requirements can be specified with a string such as juju >= 3.5 or juju < 4.0. A full list of supported features can be found in the Juju documentation <https://juju.is/docs/juju/supported-features>_.

Default: null

charm-user string | null

Specifies that the charm code does not need to be run as root. Possible values are:

root: the charm will run as root
sudoer: the charm will run as a non-root user with access to root privileges using sudo.
non-root: the charm will run as a non-root user without sudo.

Only affects Kubernetes charms on Juju 3.6.0 or later. If not specified, Juju will use its default behaviour <https://juju.is/docs/sdk/metadata-yaml#heading--charm-user>_.

Default: null

containers object | null

Define a map of containers to be created adjacent to the charm (as a sidecar, in the same pod).

This is required for Kubernetes charms.

This key consists of a dictionary mapping container names to their specifications. Each container can be specified in terms of resource, bases and mounts, where one of either the resource or the bases subkeys must be defined and mounts is optional.

resource is the name of an OCI image resource used to create the container (that you will then define further in the resources block).
bases is a list of bases to be used for resolving a container image, in descending order of preference. To use it, specify a base name (for example, ubuntu or almalinux), a channel and an architecture.
mounts is a list of mounted storage volumes for this container. To use it, specify the name of the storage to mount from the charm storage and, optionally, the location where to mount the storage.

Structure::

containers:
  <container name>:
    resource: <resource name>
    bases:
      - name: <base name>
        channel: <track[/risk][/branch]>
        architectures:
          - <architecture>
    mounts:
      - storage: <storage name>
        location: <path>

Default: null

Examples: {"super-app":{"mounts":[{"location":"/logs","storage":"logs"}],"resource":"super-app-image"}}

devices object | null

Devices the charm needs.

Structure::

devices:
  <device name>:
    type: gpu | nvidia.com/gpu | amd.com/gpu
    description: <Optional description>
    countmin: <Optional minimum number requested>
    countmax: <Optional maximum number requested>

Default: null

Examples:

{"amd-gpu":{"countmax":100,"countmin":1,"description":"Some sweet AMD GPU","type":"amd.com/gpu"},"nvidia-gpu":{"countmin":20,"description":"Some NVIDIA GPUs","type":"nvidia.com/gpu"}}

, {"gpus":{"countmax":40,"countmin":2,"description":"A bunch of GPUs","type":"gpu"}}

extra-bindings object | null

A key-only mapping representing extra bindings needed.

Default: null

peers object | null

A map of peer relations.

Structure::

peers:
  <endpoint name>:
    interface: <Required interface name>
    limit: <Optional: maximum number of supported connections
    optional: <Informational only - whether the relation is required.>
    scope: <"global" or "container" - the relation scope.>

For more information, see the Juju documentation <https://juju.is/docs/juju/relation>_.

Default: null

Examples: {"friend":{"interface":"life","limit":150,"optional":true,"scope":"container"}}

provides object | null

A map of interfaces this charm provides.

Structure::

provides:
  <endpoint name>:
    interface: <Required interface name>
    limit: <Optional: maximum number of supported connections
    optional: <Informational only - whether the relation is required.>
    scope: <"global" or "container" - the relation scope.>

For more information, see the Juju documentation <https://juju.is/docs/juju/relation>_.

Default: null

Examples: {"self":{"interface":"identity"}}

requires object | null

A map of relations this charm requires.

Structure::

requires:
  <endpoint name>:
    interface: <Required interface name>
    limit: <Optional: maximum number of supported connections
    optional: <Informational only - whether the relation is required.>
    scope: <"global" or "container" - the relation scope.>

For more information, see the Juju documentation <https://juju.is/docs/juju/relation>_.

Default: null

Examples: {"parent":{"interface":"birth","limit":2,"optional":false,"scope":"global"}}

resources object | null

A mapping of resources that accompany the charm.

See first: Juju | Charm resource <https://juju.is/docs/juju/charm-resource>_

Each resource is made available when the charm is deployed. NOTE: Kubernetes charms must declare an oci-image type resource for each container declared in containers.

Structure::

# (Optional) Additional resources that accompany the charm
resources:
  <resource name>:
    # (Required) The type of the resource
    type: file | oci-image

    # (Optional) Description of the resource and its purpose
    description: <description>

    # (Required: when type:file) The filename of the resource as it
    # should appear in the filesystem.
    filename: <filename>

Default: null

Examples: {"water":{"filename":"/dev/h2o","type":"file"}}, {"super-app-image":{"description":"My app!","type":"oci-image"}}

storage object | null

Storage devices requested by the charm.

Structure::

storage:
  # Each key represents the name of the storage
  <storage name>:

    # (Required) Type of the requested storage
    type: filesystem | block

    # (Optional) Description of the storage requested
    description: <description>

    # (Optional) The mount location for filesystem stores. For
    # multi-stores the location acts as the parent directory for each
    # mounted store.
    location: <location>

    # Indicates if the storage should be made read-only (where
    # possible). Defaults to false
    read-only: true | false

    # (Optional) The number of storage instances to be requested
    multiple:
      range: <n> | <n>-<m> | <n>- | <n>+

    # (Optional) Minimum size of requested storage in forms G, GiB, GB.
    # Size multipliers are M, G, T, P, E, Z or Y. With no multiplier
    # supplied, M is implied.
    minimum-size: <n> | <n><multiplier>

    # (Optional) List of properties, only supported value is "transient"
    properties:
      - transient

Default: null

Examples: {"jbod":{"description":"A block storage to use as swap space","properties":["transient"],"type":"block"}}

subordinate boolean | null

Optional boolean to declare the charm subordinate.

Default: null

Examples: true

terms string[] | null

A list of terms to which the user agree by using the charm. These terms are not enforced by the charm, Juju or Canonical.

Default: null

Examples: "Post cat pictures on Mastodon", "Tag your cat pictures with #caturday"

links Links | null

(Recommended) Links to various additional information used by Charmhub.

Default: null

Examples:

{"contact":"Please send your answer to Old Pink, care of the Funny Farm, Chalfont","documentation":"https://discourse.charmhub.io/t/traefik-k8s-docs-index/10778","issues":"https://github.com/canonical/traefik-k8s-operator/issues","source":"https://github.com/canonical/traefik-k8s-operator","website":"https://charmed-kubeflow.io/"}

config object | null

One or more configuration options for your charm.

Structure::

config:
  options:
    # Each option name is the name by which the charm will query the option.
    <option name>:
      # (Required) The type of the option
      type: string | int | float | boolean | secret
      # (Optional) The default value of the option
      default: <a reasonable default value of the same type as the option>
      # (Optional): A string describing the option. Also appears on charmhub.io
      description: <description string>

Default: null

Examples:

{"options":{"name":{"default":"Wiki","description":"The name or title of the Wiki","type":"string"},"skin":{"default":"vector","description":"Skin to use for the wiki","type":"string"}}}

BasesConfiguration object

Definition of build-on/run-on combinations.

Example::

bases:
  - build-on:
      - name: ubuntu
        channel: "20.04"
        architectures: [amd64, arm64]
    run-on:
      - name: ubuntu
        channel: "20.04"
        architectures: [amd64, arm64]
      - name: ubuntu
        channel: "22.04"
        architectures: [amd64, arm64]

build-on Base[] required

run-on Base[] required

CharmLib object

A Charm library dependency for this charm.

lib string required

pattern=[a-z][a-z0-9_-]+\.[a-z][a-z0-9_]+

version string required

pattern=[0-9]+(\.[0-9]+)?

Charmhub object

Definition of Charmhub endpoint configuration.

api-url string

Default: "https://api.charmhub.io"

format=uriminLength=1maxLength=2083

storage-url string

Default: "https://storage.snapcraftcontent.com"

format=uriminLength=1maxLength=2083

registry-url string

Default: "https://registry.jujucharms.com"

format=uriminLength=1maxLength=2083

Ignore object

Definition of analysis.ignore configuration.

attributes string[]

Default:

[]

linters string[]

Default:

[]

Links object

Definition of links in metadata.

contact string | string[] | null

Default: null

documentation string | null

Default: null

issues string | string[] | null

Default: null

source string | string[] | null

Default: null

website string | string[] | null

Default: null

Platform object

A single platform entry in the platforms dictionary.

This model defines how a single value under the platforms key works for a project.

build-on string[] | string required

Examples: "amd64", ["arm64","riscv64"]

minLength=1

build-for string[] | string required

Examples: "amd64", ["riscv64"]

PlatformCharm object

Model for defining a charm using Platforms.

name string required

The name of the project on Charmhub.

This value will be used both in the URL of the charm on Charmhub and when deploying the charm with juju.

Charms should follow the charm naming guidelines <https://juju.is/docs/sdk/naming>_.

Examples: "mysql", "mysql-k8s"

minLength=1maxLength=40

summary string required

A brief (one-line) summary of your charm.

maxLength=200

description string required

A multi-line summary of your charm.

platforms Record<string, object> required

parts Record<string, object> required

Configures the various mechanisms to obtain, process and prepare data from different sources that end up being a part of the final charm.

Keys are user-defined part names. The value of each key is a map where keys are part names.

Example::

parts:
  libs:
    plugin: dump
    source: /usr/local/lib/
    organize:
      "libxxx.so*": lib/
    prime:
      - lib/

type string required

Constant: "charm"

title string | null

Default: null

base string | string | null

Default: null

build-base string | string | null

Default: null

adopt-info string | null

Selects a part to inherit metadata from.

Default: null

Examples: "foo-part"

package-repositories object[] | null

The package repositories to use for build and stage packages.

Default: null

Examples:

"[{type: apt,                components: [main],                suites: [xenial],                key-id: 78E1918602959B9C59103100F1831DDAFC42E99D,                url: http://ppa.launchpad.net/snappy-dev/snapcraft-daily/ubuntu}]"

analysis AnalysisConfig | null

How analysis done on the charm will behave.

Currently the only options are to ignore attributes or linters.

Default: null

charmhub Charmhub | null

(DEPRECATED): Configuration for accessing charmhub.

Default: null

charm-libs CharmLib[]

actions object | null

Defines one or more actions.

This key is equivalent to the actions.yaml file <https://juju.is/docs/sdk/actions-yaml>_.

Default: null

assumes string | object[] | null

Structure::

assumes:
  - <feature-1>
  - any-of:
    - <feature-2>
    - <feature-3>
  - all-of:
    - <feature-4>
    - <feature-5>

Default: null

charm-user string | null

Specifies that the charm code does not need to be run as root. Possible values are:

root: the charm will run as root
sudoer: the charm will run as a non-root user with access to root privileges using sudo.
non-root: the charm will run as a non-root user without sudo.

Only affects Kubernetes charms on Juju 3.6.0 or later. If not specified, Juju will use its default behaviour <https://juju.is/docs/sdk/metadata-yaml#heading--charm-user>_.

Default: null

containers object | null

Define a map of containers to be created adjacent to the charm (as a sidecar, in the same pod).

This is required for Kubernetes charms.

resource is the name of an OCI image resource used to create the container (that you will then define further in the resources block).
bases is a list of bases to be used for resolving a container image, in descending order of preference. To use it, specify a base name (for example, ubuntu or almalinux), a channel and an architecture.
mounts is a list of mounted storage volumes for this container. To use it, specify the name of the storage to mount from the charm storage and, optionally, the location where to mount the storage.

Structure::

containers:
  <container name>:
    resource: <resource name>
    bases:
      - name: <base name>
        channel: <track[/risk][/branch]>
        architectures:
          - <architecture>
    mounts:
      - storage: <storage name>
        location: <path>

Default: null

Examples: {"super-app":{"mounts":[{"location":"/logs","storage":"logs"}],"resource":"super-app-image"}}

devices object | null

Devices the charm needs.

Structure::

devices:
  <device name>:
    type: gpu | nvidia.com/gpu | amd.com/gpu
    description: <Optional description>
    countmin: <Optional minimum number requested>
    countmax: <Optional maximum number requested>

Default: null

Examples:

{"amd-gpu":{"countmax":100,"countmin":1,"description":"Some sweet AMD GPU","type":"amd.com/gpu"},"nvidia-gpu":{"countmin":20,"description":"Some NVIDIA GPUs","type":"nvidia.com/gpu"}}

, {"gpus":{"countmax":40,"countmin":2,"description":"A bunch of GPUs","type":"gpu"}}

extra-bindings object | null

A key-only mapping representing extra bindings needed.

Default: null

peers object | null

A map of peer relations.

Structure::

peers:
  <endpoint name>:
    interface: <Required interface name>
    limit: <Optional: maximum number of supported connections
    optional: <Informational only - whether the relation is required.>
    scope: <"global" or "container" - the relation scope.>

For more information, see the Juju documentation <https://juju.is/docs/juju/relation>_.

Default: null

Examples: {"friend":{"interface":"life","limit":150,"optional":true,"scope":"container"}}

provides object | null

A map of interfaces this charm provides.

Structure::

provides:
  <endpoint name>:
    interface: <Required interface name>
    limit: <Optional: maximum number of supported connections
    optional: <Informational only - whether the relation is required.>
    scope: <"global" or "container" - the relation scope.>

For more information, see the Juju documentation <https://juju.is/docs/juju/relation>_.

Default: null

Examples: {"self":{"interface":"identity"}}

requires object | null

A map of relations this charm requires.

Structure::

requires:
  <endpoint name>:
    interface: <Required interface name>
    limit: <Optional: maximum number of supported connections
    optional: <Informational only - whether the relation is required.>
    scope: <"global" or "container" - the relation scope.>

For more information, see the Juju documentation <https://juju.is/docs/juju/relation>_.

Default: null

Examples: {"parent":{"interface":"birth","limit":2,"optional":false,"scope":"global"}}

resources object | null

A mapping of resources that accompany the charm.

See first: Juju | Charm resource <https://juju.is/docs/juju/charm-resource>_

Each resource is made available when the charm is deployed. NOTE: Kubernetes charms must declare an oci-image type resource for each container declared in containers.

Structure::

# (Optional) Additional resources that accompany the charm
resources:
  <resource name>:
    # (Required) The type of the resource
    type: file | oci-image

    # (Optional) Description of the resource and its purpose
    description: <description>

    # (Required: when type:file) The filename of the resource as it
    # should appear in the filesystem.
    filename: <filename>

Default: null

Examples: {"water":{"filename":"/dev/h2o","type":"file"}}, {"super-app-image":{"description":"My app!","type":"oci-image"}}

storage object | null

Storage devices requested by the charm.

Structure::

storage:
  # Each key represents the name of the storage
  <storage name>:

    # (Required) Type of the requested storage
    type: filesystem | block

    # (Optional) Description of the storage requested
    description: <description>

    # (Optional) The mount location for filesystem stores. For
    # multi-stores the location acts as the parent directory for each
    # mounted store.
    location: <location>

    # Indicates if the storage should be made read-only (where
    # possible). Defaults to false
    read-only: true | false

    # (Optional) The number of storage instances to be requested
    multiple:
      range: <n> | <n>-<m> | <n>- | <n>+

    # (Optional) Minimum size of requested storage in forms G, GiB, GB.
    # Size multipliers are M, G, T, P, E, Z or Y. With no multiplier
    # supplied, M is implied.
    minimum-size: <n> | <n><multiplier>

    # (Optional) List of properties, only supported value is "transient"
    properties:
      - transient

Default: null

Examples: {"jbod":{"description":"A block storage to use as swap space","properties":["transient"],"type":"block"}}

subordinate boolean | null

Optional boolean to declare the charm subordinate.

Default: null

Examples: true

terms string[] | null

A list of terms to which the user agree by using the charm. These terms are not enforced by the charm, Juju or Canonical.

Default: null

Examples: "Post cat pictures on Mastodon", "Tag your cat pictures with #caturday"

links Links | null

(Recommended) Links to various additional information used by Charmhub.

Default: null

Examples:

{"contact":"Please send your answer to Old Pink, care of the Funny Farm, Chalfont","documentation":"https://discourse.charmhub.io/t/traefik-k8s-docs-index/10778","issues":"https://github.com/canonical/traefik-k8s-operator/issues","source":"https://github.com/canonical/traefik-k8s-operator","website":"https://charmed-kubeflow.io/"}

config object | null

One or more configuration options for your charm.

Structure::

config:
  options:
    # Each option name is the name by which the charm will query the option.
    <option name>:
      # (Required) The type of the option
      type: string | int | float | boolean | secret
      # (Optional) The default value of the option
      default: <a reasonable default value of the same type as the option>
      # (Optional): A string describing the option. Also appears on charmhub.io
      description: <description string>

Default: null

Examples:

{"options":{"name":{"default":"Wiki","description":"The name or title of the Wiki","type":"string"},"skin":{"default":"vector","description":"Skin to use for the wiki","type":"string"}}}