Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add JSON schema for Development Container Template Metadata #350

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add JSON schema for Development Container Template Metadata #350

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0ac9754
Add JSON schema for Development Container Template Metadata
benblank Dec 14, 2023
4e19083
Allow optional "$schema" property in devcontainer-feature.json
benblank Dec 21, 2023
b7c3ce4
Update JSON schemas based on PR feedback.
benblank Jan 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions schemas/devContainerFeature.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@
"Feature": {
"additionalProperties": false,
"properties": {
"$schema": {
"description": "The JSON schema of the `devcontainer-feature.json` file.",
"type": "string",
"format": "uri"
},
"capAdd": {
"description": "Passes docker capabilities to include when creating the dev container.",
"examples": [
Expand Down Expand Up @@ -211,7 +216,7 @@
"type": "object"
},
"FeatureOption": {
"anyOf": [
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"oneOf": [
{
"description": "Option value is represented with a boolean value.",
"additionalProperties": false,
Expand Down Expand Up @@ -333,4 +338,4 @@
"$ref": "#/definitions/Feature"
}
]
}
}
179 changes: 179 additions & 0 deletions schemas/devContainerTemplate.schema.json
View file
Open in desktop
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thankful, please advise

Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Development Container Template Metadata",
"description": "Development Container Template Metadata (devcontainer-template.json). See https://containers.dev/implementors/templates/ for more information.",
"definitions": {
"Template": {
"type": "object",
"additionalProperties": false,
"properties": {
"$schema": {
chrmarti marked this conversation as resolved.
Show resolved Hide resolved
"description": "The JSON schema of the `devcontainer-template.json` file.",
"type": "string",
"format": "uri"
},
"description": {
"description": "Description of the Template.",
"type": "string"
},
"documentationURL": {
"description": "Url that points to the documentation of the Template.",
"type": "string",
"format": "uri"
},
"id": {
"description": "ID of the Template. The id should be unique in the context of the repository/published package where the Template exists and must match the name of the directory where the devcontainer-template.json resides.",
"type": "string"
},
"keywords": {
"description": "List of strings relevant to a user that would search for this Template.",
"type": "array",
"items": {
"type": "string"
}
},
"licenseURL": {
"description": "Url that points to the license of the Template.",
"type": "string",
"format": "uri"
},
"name": {
"description": "Name of the Template.",
"type": "string"
},
"options": {
"description": "A map of options that the supporting tools should use to populate different configuration options for the Template.",
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/Option"
}
},
"platforms": {
"description": "Languages and platforms supported by the Template.",
"type": "array",
"items": {
"type": "string"
}
},
"publisher": {
"description": "Name of the publisher/maintainer of the Template.",
"type": "string"
},
"version": {
"description": "The semantic version of the Template.",
"type": "string"
}
},
"required": [
"id",
"name",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is name required? It might be, but we don't have it written down it seems. It is optional for features.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm. It isn't marked as required in devContainerFeature.schema.json now that I look at it, but it is on the implementors page. I'm not yet familiar enough with the spec to know which is accurate, but I suppose the other should be updated to match. 🙂

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joshspicer Should we make name required in the features schema? Would a feature work if it had no name currently? If not, we would know that making it required in the schema won't break anyone. :)

Copy link
Member

@joshspicer joshspicer Jan 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the tooling name is not required. For example when we build the READMEs in devcontainers/action it will use id if name is not available.

That said, we should probably just make it required since it's useful as a display name in our tooling and it's provided by default in our devcontainers/feature-starter template.

One thing to note - if we add name as required in the schema for Features, this validation code when publishing with the devcontainers/action will fail if the Feature is missing name.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems safer to update the spec to make it optional then. We could break existing features as you point out.

One advantage of not making it required is that it is easier to write one-off features for prototyping or testing. We would still want features going into the index to have good names for the UI. 🤷‍♂️

"version"
]
},
"Option": {
"description": "An option that the supporting tools should use to populate different configuration options for the Template.",
"type": "object",
"properties": {
"default": {
"description": "Default value for the option.",
"type": [
"boolean",
"string"
]
},
"description": {
"description": "Description for the option.",
"type": "string"
},
"type": {
"description": "Type of the option. Valid types are currently: boolean, string",
"type": "string",
"enum": [
"boolean",
"string"
]
}
},
"required": [
"default",
"description",
"type"
],
"oneOf": [
chrmarti marked this conversation as resolved.
Show resolved Hide resolved
{
"type": "object",
"additionalProperties": false,
"properties": {
"default": {
"type": "boolean"
},
"description": true,
"type": {
"type": "string",
"const": "boolean"
}
},
"required": [
"default",
"type"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"default": {
"type": "string"
},
"description": true,
"enum": true,
"proposals": true,
"type": {
"type": "string",
"const": "string"
}
},
"required": [
"default",
"type"
],
"oneOf": [
{
"type": "object",
"properties": {
"enum": {
"description": "A strict list of allowed string values. Free-form values are not allowed. Omit when using optionId.proposals.",
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
}
},
"required": [
"enum"
]
},
{
"type": "object",
"properties": {
"proposals": {
"description": "A list of suggested string values. Free-form values are allowed. Omit when using optionId.enum.",
"type": "array",
"items": {
"type": "string"
}
}
}
}
]
}
]
}
},
"oneOf": [
{
"$ref": "#/definitions/Template"
}
]
}