Publish devcontainer.json schema

[chrmarti]

Currently hosted in the VS Code repo, the source should move to the reference implementation when that becomes available.

Similarly to the tsconfig.json schema, we could submit a PR to https://github.com/SchemaStore/schemastore to make it available at schemastore.org.

[greggroth]

Is this referring to the JSON Schema doc in https://github.com/microsoft/vscode/tree/main/extensions/configuration-editing/schemas? Perhaps related to #1, it would be handy if that schema didn't include VS Code references that schema from being used to strictly verify a devcontainer.json file. There are also properties like allowComments and allowTrailingCommas that aren't part of the JSON Schema spec. Are those something VS Code supports as an extension to the spec?

[Chuxel]

@greggroth Yeah the devcontainer.json file is "json5 / jsonc / json with comments" which is an extension of the base json format. I'm not aware of an official way to denote that in a json schema. That particular copy is the one used in production by VS Code and Codespaces today, which also predates the refactoring being discussed here. The ref is for a property that would move with #1 (specifically, that's VS Code settings which has a schema of its own).

I do think it would be reasonable, however to allow people to submit PRs to the spec's copy of the schema that would be located here that would include refs to an externally defined tool/service specific schema not maintained in this repository. e.g. customizations.vscode points to one thing, customizations.jetbrains another, customizations.codespaces another, customizations.gitpod another, etc. That would allow for better validation than just marking these as any.

@chrmarti was this how you were thinking about getting the schema in shape for the spec?

We can also house both a common schema description and a separate page with tool/service specific properties. Here again, any tool/service would be welcome to contribute to that. Right now the only reference we have includes VS Code properties and descriptions and includes references to VS Code specific instructions. This PR has some content to try to alleviate that for a reference that would be included here.

[chrmarti]

I do think it would be reasonable, however to allow people to submit PRs to the spec's copy of the schema that would be located here that would include refs to an externally defined tool/service specific schema not maintained in this repository. e.g. customizations.vscode points to one thing, customizations.jetbrains another, customizations.codespaces another, customizations.gitpod another, etc. That would allow for better validation than just marking these as any.

@chrmarti was this how you were thinking about getting the schema in shape for the spec?

Correct.

@aeschli Could you advise if this makes sense: We would like to publish the devcontainer.json schema at schemastore.org (like TypeScript for tsconfig.json does) and have it reference other tools-specific parts using "$ref". The goal is to have a tools-independent schema that references tools-specific schema parts and make all that available to other tools/editors. E.g., VS Code would then just reference the devcontainer.json schema on schemastore.org (like it does for the tsconfig.json schema).

[aeschli]

The problem of the $ref would be that the base schema would have to know all possible extensions. That's not very practical.

In VS Code we allow that a file or file extension can be associated with multiple schemas. These are independent schemas each describing a seperate part of the JSON structure. The schmeas are not referencing each other. The schema service in the editor combines all of these with 'allOf'.
So it will be the editors job to bring the various schemas together. In VS Code, schema associations can done with user settings or by extensions. E.g. the codespace extension would associate its schema for the codespace specific parts of devcontainer.json.

[chrmarti]

Makes sense. One disadvantage might be that other editors will not offer IntelliSense for the VS Code and Codespaces parts, but that might be fine.

[aeschli]

I suggest the following structure for the schema:

Document name	Purpose	Hosted on
devContainer.schema.json	master schema consisting only of references to the schemas below (base schema as well as all schemas containing vendor specific properties)	github.com/devcontainers/spec
devContainer.base.schema.json	schema describing all base properties as documented here	github.com/devcontainers/spec
devContainer.vscode.schema.json	schema describing vscode specific properties	github.com/Microsoft/vscode
devContainer.codespaces.schema.json	schema describing codespaces specific properties	github.com/github/codespaces or similar
devContainer.vendorFoo.schema.json	schema describing 'vendor foo' specific properties	location provided by 'vendor foo'

• The catalog file at schemastore.org will get an entry to the master schema:

    {
      "name": "Dev Container configuration file",
      "description": "The devcontainer.json file contains any needed metadata and settings required to configurate a development container for a given well-defined tool and runtime stack",
      "fileMatch": ["devcontainer.json", ".devcontainer.json"],
      "url": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json"
    }

• Vendors such as VS Code, Codespace, GitPod, Foo.. are free to choose any hosting location (can also be on schemastore.org)
• The master schema is just a collection of $refs that are and'ed: allOf: [ { $ref: devContainer.base.json, $ref: ..., $ref .... } ].
• For a new vendor to add a new $ref to the master schema, a PR against devcontainers/spec/ needs to be made. We will need to come up with a policy that decides which contributions can be accepted.

I imagine the policy to accept a new $ref would be:

• the newly added properties need to follow certain naming guidelines (camelCase, dot separated, ect...)
• all properties need to be documented
• a global link to documentation/spec needs to be provided so it can be added to the devcontainers/spec documentation as well

[bamurtaugh]

Assigning to myself to update our documentation (containers.dev).