Publish devcontainer.json schema #14

Activity

1. greggroth commented on Mar 22, 2022

   

   Greggory Rothmeier (greggroth)

   on Mar 22, 2022

   More actions

   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?
2. Chuxel commented on Mar 23, 2022

   

   Chuck Lantz (Chuxel)

   on Mar 23, 2022

   Last edited by Chuxel

   Member

   More actions

   Greggory Rothmeier (@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.

   Christof Marti (@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.
3. chrmarti commented on Mar 24, 2022

   

   Christof Marti (chrmarti)

   on Mar 24, 2022

   ContributorAuthor

   More actions

   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.

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

   Correct.

   Martin Aeschlimann (@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).
4. aeschli commented on Mar 24, 2022

   

   Martin Aeschlimann (aeschli)

   on Mar 24, 2022

   Contributor

   More actions

   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.

   👍React with 👍1Reacted by Christof Marti
5. chrmarti commented on Mar 25, 2022

   

   Christof Marti (chrmarti)

   on Mar 25, 2022

   ContributorAuthor

   More actions

   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.
6. Alexandru Dima (alexdima)

   assigned

   Martin Aeschlimann (aeschli)

   on Jul 14, 2022
7. Alexandru Dima (alexdima)

   added

   active

   on Jul 14, 2022
8. aeschli commented on Jul 15, 2022

   

   Martin Aeschlimann (aeschli)

   on Jul 15, 2022

   Contributor

   More actions

   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

   👍React with 👍3Reacted by Christof Marti, Brigit Murtaugh and Edmundo Gonzalez
9. Alexandru Dima (alexdima)

   added this to the July 2022 milestone on Jul 18, 2022
10. Alexandru Dima (alexdima)

    removed

    active

    on Jul 18, 2022
11. Christof Marti (chrmarti)

    added

    proposalStill under discussion, collecting feedbackStill under discussion, collecting feedback

    active

    on Jul 19, 2022
12. Brigit Murtaugh (bamurtaugh)

    modified the milestones: July 2022, August 2022 on Jul 28, 2022
13. Brigit Murtaugh (bamurtaugh)

    assigned

    Brigit Murtaugh (bamurtaugh)

    and unassigned

    Martin Aeschlimann (aeschli)

    on Aug 5, 2022
14. bamurtaugh commented on Aug 5, 2022

    

    Brigit Murtaugh (bamurtaugh)

    on Aug 5, 2022

    Member

    More actions

    Assigning to myself to update our documentation (containers.dev).
15. Brigit Murtaugh (bamurtaugh)

    closed this as completedin devcontainers.github.io#20on Aug 5, 2022