add description to all compose-spec.json attributes by glours · Pull Request #782 · compose-spec/compose-go

glours · 2025-05-06T10:01:05Z

it will give more details to Language Server Protocol tools

https://docker.atlassian.net/browse/APCLI-1107

glours · 2025-05-06T10:03:20Z

@rcjsuen if you want to take a look also

rcjsuen · 2025-05-06T10:35:47Z

schema/compose-spec.json

+            "weight": {
+              "type": ["integer", "string"],
+              "description": "Block IO weight (relative weight) for the service, between 10 and 1000."


I was able to set this value to 0. Is that intentional?

Should we set a minimum and maximum for this similar to cpu_percent?

I keep this one for a follow up PR

schema/compose-spec.json

rcjsuen · 2025-05-06T10:44:38Z

schema/compose-spec.json

+        },
+        "mem_swappiness": {
+          "type": ["integer", "string"],
+          "description": "Container memory swappiness as percentage (0 to 100)."


Suggested change

"description": "Container memory swappiness as percentage (0 to 100)."

"description": "Container memory swappiness as a percentage (0 to 100)."

Should we set a minimum and maximum here? I was able to set this value to -1 but Docker Compose still seemed to work. 🤔

I guess there are many places where such min/max could be defined. We should consider adding them as a follow-up

Yep, we'll do follow-up PR to manage this kind of improvement

rcjsuen · 2025-05-06T11:10:07Z

schema/compose-spec.json

+              "count": {
+                "type": ["string", "integer"],
+                "description": "Number of GPUs to use."


Should we specify a minimum value here?

rcjsuen · 2025-05-06T11:10:55Z

schema/compose-spec.json

+        "driver": {
+          "type": "string",
+          "description": "Specify which driver should be used for this network. Default is 'bridge'."


Should we declare the default attribute here?

rcjsuen · 2025-05-06T11:15:33Z

schema/compose-spec.json

+          "description": "A dictionary mapping keys to values.",
          "patternProperties": {
            ".+": {
-              "type": ["string", "number", "boolean", "null"]
+              "type": ["string", "number", "boolean", "null"],
+              "description": "Value for the key, which can be a string, number, boolean, or null."


Could someone help clarify to me as to why we allow a key to be null? 🤔

key only (no value) means "use same value from host env variables, and if not set remove variable"

rcjsuen · 2025-05-06T11:16:40Z

schema/compose-spec.json

+        "rate": {
+          "type": ["integer", "string"],
+          "description": "Rate limit in bytes per second or IO operations per second."


Should we set a minimum for this attribute?

rcjsuen · 2025-05-06T11:16:58Z

schema/compose-spec.json

+        "weight": {
+          "type": ["integer", "string"],
+          "description": "Relative weight for the device, between 10 and 1000."


Should we set a minimum and maximum for this attribute?

schema/compose-spec.json

ndeloof · 2025-05-06T12:47:24Z

schema/compose-spec.json

+        },
+        "mem_swappiness": {
+          "type": ["integer", "string"],
+          "description": "Container memory swappiness as percentage (0 to 100)."


I guess there are many places where such min/max could be defined. We should consider adding them as a follow-up

schema/compose-spec.json

ndeloof · 2025-05-06T12:59:24Z

schema/compose-spec.json

+            "failure_action": {
+              "type": "string",
+              "description": "Action to take if a rollback fails: 'continue', 'pause'."


only exists for swarm mode, low priority imho

ndeloof · 2025-05-06T13:03:38Z

schema/compose-spec.json

+          "description": "A dictionary mapping keys to values.",
          "patternProperties": {
            ".+": {
-              "type": ["string", "number", "boolean", "null"]
+              "type": ["string", "number", "boolean", "null"],
+              "description": "Value for the key, which can be a string, number, boolean, or null."


key only (no value) means "use same value from host env variables, and if not set remove variable"

schema/compose-spec.json

glours · 2025-05-06T14:40:42Z

@rcjsuen @ndeloof thanks, if you don't have any objection I'll merge it as this and we'll address the other comments as follow-up PRs, is that ok for you?

it will give more details to Language Server Protocol tools Signed-off-by: Guillaume Lours <[email protected]>

rcjsuen · 2025-05-06T14:53:32Z

if you don't have any objection I'll merge it as this and we'll address the other comments as follow-up PRs, is that ok for you?

No problem. Makes sense to me. 👍

glours requested a review from ndeloof as a code owner May 6, 2025 10:01

glours self-assigned this May 6, 2025

glours force-pushed the add-description-spec-json branch from e4f44b6 to 8020eb6 Compare May 6, 2025 10:15

rcjsuen reviewed May 6, 2025

View reviewed changes

glours force-pushed the add-description-spec-json branch from 8020eb6 to d3f0e2a Compare May 6, 2025 11:58

ndeloof approved these changes May 6, 2025

View reviewed changes

ndeloof reviewed May 6, 2025

View reviewed changes

schema/compose-spec.json Show resolved Hide resolved

add description to all compose-spec.json attributes

3977667

it will give more details to Language Server Protocol tools Signed-off-by: Guillaume Lours <[email protected]>

glours force-pushed the add-description-spec-json branch from a48bc5b to 3977667 Compare May 6, 2025 14:52

glours enabled auto-merge (rebase) May 6, 2025 14:54

glours merged commit 9fb79a6 into compose-spec:main May 6, 2025
8 checks passed

glours deleted the add-description-spec-json branch May 6, 2025 14:55

	"description": "Container memory swappiness as percentage (0 to 100)."
	"description": "Container memory swappiness as a percentage (0 to 100)."

Conversation

glours commented May 6, 2025

Uh oh!

glours commented May 6, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

glours commented May 6, 2025

Uh oh!

rcjsuen commented May 6, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants