Add JSON schema for work-in-progress features.json

[joshspicer]

Authors of "feature-sets" will need to know all of the properties available to them when crafting their own features.json. Adding a JSON schema to the configurationSupport to be shared across the vscode-remote-containers and codespaces extensions will allow vscode to suggest hints, as well as provide user-facing documentation before the "real" documentation is released/finalized.

[joshspicer]

cc @Chuxel @chrmarti @2percentsilk

[GavinRay97]

Maybe this is useful, as a start?
I took the types I wrote by hand here:

• https://github.com/GavinRay97/vscode-devcontainer-feature-eject-parser/blob/master/src/features.types.ts

And used quicktype to convert to JSON Schema. It needs comments (easier to comment the TS types and re-generate than write them in the JSON Schema IMO) but better than nothing:

user@MSI:~/tmp$ npx quicktype --src features.types.ts --src-lang ts --lang schema --top-level Feature --out features.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {
        "Feature": {
            "title": "Feature",
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "title": "id"
                },
                "name": {
                    "type": "string",
                    "title": "name"
                },
                "options": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "string"
                    },
                    "title": "options"
                },
                "buildArg": {
                    "type": "string",
                    "title": "buildArg"
                },
                "entrypoint": {
                    "type": "string",
                    "title": "entrypoint"
                },
                "privileged": {
                    "type": "boolean",
                    "title": "privileged"
                },
                "init": {
                    "type": "boolean",
                    "title": "init"
                },
                "containerEnv": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "string"
                    },
                    "title": "containerEnv"
                },
                "extensions": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "title": "extensions"
                },
                "mounts": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Mount"
                    },
                    "title": "mounts"
                },
                "include": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "title": "include"
                },
                "settings": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "string"
                    },
                    "title": "settings"
                },
                "capAdd": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "title": "capAdd"
                },
                "securityOpt": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "title": "securityOpt"
                }
            },
            "required": [
                "buildArg",
                "id",
                "include",
                "name",
                "options"
            ]
        },
        "Mount": {
            "title": "Mount",
            "type": "object",
            "properties": {
                "source": {
                    "type": "string",
                    "title": "source"
                },
                "target": {
                    "type": "string",
                    "title": "target"
                },
                "type": {
                    "type": "string",
                    "title": "type"
                }
            },
            "required": [
                "source",
                "target",
                "type"
            ]
        }
    }
}

[joshspicer]

Thanks @GavinRay97 - I used a similar tool with my first pass, too :)

[chrmarti]

Adding the JSON schema for devcontainer-features.json to avoid having it apply to other random features.json files. Is that name fine or would dev-container-features.json (or something else) be better? Since devcontainer.json doesn't have a dash, I didn't want to add one, in documentation we use 'dev container'.

I haven't changed the filename we read from in code, but will do so when agree on the name.

+ @bamurtaugh

[bamurtaugh]

devcontainer-features.json makes sense to me and is in-line with our naming convention for the devcontainer CLI (where we also don't introduce a dash or use a space).

[Chuxel]

@joshspicer @chrmarti Isn't this a breaking change? Or will we emit both files?

EDIT: Nevermind - see that we're emitting both in code. 👍

[chrmarti]

@Chuxel Emitting both (features.env and devcontainer-features.env I assume) is temporary. @joshspicer is updating test features and vscode-dev-containers.

[joshspicer]

I've merged the changes for the action and the template, so we're in kinda of a weird position right now (but better get people on the right path, then have it "work" for now and have it break tomorrow)

[chrmarti]

I assumed we could just do the rename everywhere and be done. Are there others involved who would need to update too?

[joshspicer]

It's just that codespaces will need to be updated with your CLI change, so before that the GitHub Action and template aren't totally aligning with what codespaces will try to do.

[Chuxel]

@Chuxel Emitting both (features.env and devcontainer-features.env I assume) is temporary. @joshspicer is updating test features and vscode-dev-containers.

I've merged the changes for the action and the template, so we're in kinda of a weird position right now (but better get people on the right path, then have it "work" for now and have it break tomorrow)

@chrmarti @joshspicer Yep - agreed. I just don't want to punish early adopters if we can help it.

[chrmarti]

Are there early adopters beyond ourselves? (I see @joshspicer updating explorations for GitHub.)

[Chuxel]

See community/community#7807 (comment)