diff --git a/docs/specs/devcontainer-features-distribution.md b/docs/specs/devcontainer-features-distribution.md index 7b4d29b4..9d326959 100644 --- a/docs/specs/devcontainer-features-distribution.md +++ b/docs/specs/devcontainer-features-distribution.md @@ -83,6 +83,8 @@ Each features's `devcontainer-feature.json` metadata file is appended into the ` There are several supported ways to distribute Features. Distribution is handled by the implementing packaging tool such as the [Dev Container CLI](https://github.com/devcontainers/cli) or [Dev Container Publish GitHub Action](https://github.com/marketplace/actions/dev-container-publish). See the [quick start repository](https://github.com/devcontainers/feature-template) for a full working example. +> Feature identifiers should be provided lowercase by an author. If not, an implementing packaging tool should normalize the identifier into lowercase for any internal representation. + A user references a distributed feature in a `devcontainer.json` as defined in ['referencing a feature'](./devcontainer-features.md#Referencing-a-feature). ### OCI Registry @@ -91,7 +93,7 @@ An OCI registry that implements the [OCI Artifact Distribution Specification](ht Each packaged feature is pushed to the registry following the naming convention `//[:version]`, where version is the major, minor, and patch version of the feature, according to the semver specification. -> **Note:** The `namespace` is a unique indentifier for the collection of features. There are no strict rules for the `namespace`; however, one pattern is to set `namespace` equal to source repository's `/`. +> **Note:** The `namespace` is a unique indentifier for the collection of features. There are no strict rules for the `namespace`; however, one pattern is to set `namespace` equal to source repository's `/`. The `namespace` should be lowercase, following [the regex provided in the OCI specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-manifests). A custom media type `application/vnd.devcontainers` and `application/vnd.devcontainers.layer.v1+tar` are used as demonstrated below. diff --git a/docs/specs/devcontainer-features.md b/docs/specs/devcontainer-features.md index 7c5d6ecd..af37c6bd 100644 --- a/docs/specs/devcontainer-features.md +++ b/docs/specs/devcontainer-features.md @@ -29,7 +29,7 @@ All properties are optional **except for `id`, `version`, and `name`**. | Property | Type | Description | | :--- | :--- | :--- | -| `id` | string | **Required**: Identifier of the Feature. Must be unique in the context of the repository where the Feature exists and must match the name of the directory where the `devcontainer-feature.json` resides. | +| `id` | string | **Required**: Identifier of the Feature. Must be unique in the context of the repository where the Feature exists and must match the name of the directory where the `devcontainer-feature.json` resides. ID should be provided lowercase. | | `version` | string | **Required**: The semantic version of the Feature (e.g: `1.0.0`). | | `name` | string | **Required**: A "human-friendly" display name for the Feature. | | `description` | string | Description of the Feature. | @@ -218,6 +218,8 @@ The `id` format specified dictates how a supporting tool will locate and downloa | `https://` | Direct HTTPS URI to a tarball. | `https://github.com/user/repo/releases/devcontainer-feature-go.tgz` | | `./`| A relative directory(**) to folder containing a devcontainer-feature.json. | `./myGoFeature` | +Feature identifiers should be assumed to be case-insensitive and should be normalized to lowercase. + (*) OCI registry must implement the [OCI Artifact Distribution Specification](https://github.com/opencontainers/distribution-spec). Some implementors can be [found here](https://oras.land/implementors/). (**) The provided path is always relative to the folder containing the `devcontainer.json`. Further requirements are outlined in the [Locally Referenced Addendum](./devcontainer-features-distribution.md#locally-referenced-features)