Skip to content

Add descriptive documentation to compose schema properties #776

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

Merged
merged 1 commit into from
Apr 27, 2025
Merged

Add descriptive documentation to compose schema properties #776

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
67 changes: 39 additions & 28 deletions schema/compose-spec.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@
"$ref": "#/definitions/service"
}
},
"additionalProperties": false
"additionalProperties": false,
"description": "The services in your project"
},

"networks": {
Expand All @@ -40,7 +41,8 @@
"^[a-zA-Z0-9._-]+$": {
"$ref": "#/definitions/network"
}
}
},
"description": "Networks that are shared among multiple services"
},

"volumes": {
Expand All @@ -50,7 +52,8 @@
"$ref": "#/definitions/volume"
}
},
"additionalProperties": false
"additionalProperties": false,
"description": "Named volumes that are shared among multiple services"
},

"secrets": {
Expand All @@ -60,7 +63,8 @@
"$ref": "#/definitions/secret"
}
},
"additionalProperties": false
"additionalProperties": false,
"description": "Secrets that are shared among multiple services"
},

"configs": {
Expand All @@ -70,7 +74,8 @@
"$ref": "#/definitions/config"
}
},
"additionalProperties": false
"additionalProperties": false,
"description": "Configurations for services in the project"
}
},

Expand All @@ -93,11 +98,11 @@
{
"type": "object",
"properties": {
"context": {"type": "string"},
"dockerfile": {"type": "string"},
"context": {"type": "string", "description": "The context used for building the image"},
"dockerfile": {"type": "string", "description": "The Dockerfile used for building the image"},
"dockerfile_inline": {"type": "string"},
"entitlements": {"type": "array", "items": {"type": "string"}},
"args": {"$ref": "#/definitions/list_or_dict"},
"args": {"$ref": "#/definitions/list_or_dict", "description": "Arguments used during the image build process"},
"ssh": {"$ref": "#/definitions/list_or_dict"},
"labels": {"$ref": "#/definitions/list_or_dict"},
"cache_from": {"type": "array", "items": {"type": "string"}},
Expand Down Expand Up @@ -152,9 +157,9 @@
"cap_drop": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
"cgroup": {"type": "string", "enum": ["host", "private"]},
"cgroup_parent": {"type": "string"},
"command": {"$ref": "#/definitions/command"},
"command": {"$ref": "#/definitions/command", "description": "The command that will be run in the container"},
"configs": {"$ref": "#/definitions/service_config_or_secret"},
"container_name": {"type": "string"},
"container_name": {"type": "string", "description": "The name that will be given to the container"},
"cpu_count": {"oneOf": [
{"type": "string"},
{"type": "integer", "minimum": 0}
Expand Down Expand Up @@ -206,7 +211,8 @@
}
}
}
]
],
"description": "Other services that this service depends on, which will be started before this one"
},
"device_cgroup_rules": {"$ref": "#/definitions/list_of_strings"},
"devices": {
Expand All @@ -232,17 +238,18 @@
"dns_opt": {"type": "array","items": {"type": "string"}, "uniqueItems": true},
"dns_search": {"$ref": "#/definitions/string_or_list"},
"domainname": {"type": "string"},
"entrypoint": {"$ref": "#/definitions/command"},
"env_file": {"$ref": "#/definitions/env_file"},
"entrypoint": {"$ref": "#/definitions/command", "description": "The entrypoint to the application in the container"},
"env_file": {"$ref": "#/definitions/env_file", "description": "Files containing environment variables that will be included"},
"label_file": {"$ref": "#/definitions/label_file"},
"environment": {"$ref": "#/definitions/list_or_dict"},
"environment": {"$ref": "#/definitions/list_or_dict", "description": "Environment variables that will be included"},

"expose": {
"type": "array",
"items": {
"type": ["string", "number"]
},
"uniqueItems": true
"uniqueItems": true,
"description": "Ports exposed to the other services but not to the host machine"
},
"extends": {
"oneOf": [
Expand Down Expand Up @@ -283,13 +290,13 @@
},
"uniqueItems": true
},
"healthcheck": {"$ref": "#/definitions/healthcheck"},
"healthcheck": {"$ref": "#/definitions/healthcheck", "description": "A command for checking if the container is healthy"},
"hostname": {"type": "string"},
"image": {"type": "string"},
"image": {"type": "string", "description": "The image that will be pulled for the service. If `build` is specified, the built image will be given this tag."},
"init": {"type": ["boolean", "string"]},
"ipc": {"type": "string"},
"isolation": {"type": "string"},
"labels": {"$ref": "#/definitions/list_or_dict"},
"labels": {"$ref": "#/definitions/list_or_dict", "description": "Labels that will be given to the container"},
"links": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
"logging": {
"type": "object",
Expand All @@ -303,7 +310,8 @@
}
},
"additionalProperties": false,
"patternProperties": {"^x-": {}}
"patternProperties": {"^x-": {}},
"description": "Settings for logging for this service"
},
"mac_address": {"type": "string"},
"mem_limit": {"type": ["number", "string"]},
Expand Down Expand Up @@ -346,7 +354,8 @@
},
"additionalProperties": false
}
]
],
"description": "The service will be included in these networks, allowing it to reach other containers on the same network"
},
"oom_kill_disable": {"type": ["boolean", "string"]},
"oom_score_adj": {"oneOf": [
Expand Down Expand Up @@ -378,12 +387,13 @@
}
]
},
"uniqueItems": true
"uniqueItems": true,
"description": "Ports that will be exposed to the host"
},
"post_start": {"type": "array", "items": {"$ref": "#/definitions/service_hook"}},
"pre_stop": {"type": "array", "items": {"$ref": "#/definitions/service_hook"}},
"privileged": {"type": ["boolean", "string"]},
"profiles": {"$ref": "#/definitions/list_of_strings"},
"profiles": {"$ref": "#/definitions/list_of_strings", "description": "Profiles that this service is a part of. When the profile is started, this service will be started."},
"pull_policy": {"type": "string",
"pattern": "always|never|build|if_not_present|missing|refresh|daily|weekly|every_([0-9]+[wdhms])+"
},
Expand All @@ -398,7 +408,7 @@
},
"security_opt": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
"shm_size": {"type": ["number", "string"]},
"secrets": {"$ref": "#/definitions/service_config_or_secret"},
"secrets": {"$ref": "#/definitions/service_config_or_secret", "description": "Secrets the service will have access to"},
"sysctls": {"$ref": "#/definitions/list_or_dict"},
"stdin_open": {"type": ["boolean", "string"]},
"stop_grace_period": {"type": "string"},
Expand All @@ -407,7 +417,7 @@
"tmpfs": {"$ref": "#/definitions/string_or_list"},
"tty": {"type": ["boolean", "string"]},
"ulimits": {"$ref": "#/definitions/ulimits"},
"user": {"type": "string"},
"user": {"type": "string", "description": "The username under which the app in the container will be started"},
"uts": {"type": "string"},
"userns_mode": {"type": "string"},
"volumes": {
Expand Down Expand Up @@ -475,14 +485,15 @@
}
]
},
"uniqueItems": true
"uniqueItems": true,
"description": "Named volumes and paths on the host mapped to paths in the container"
},
"volumes_from": {
"type": "array",
"items": {"type": "string"},
"uniqueItems": true
},
"working_dir": {"type": "string"}
"working_dir": {"type": "string", "description": "The working directory in which the entrypoint or command will be run"}
},
"patternProperties": {"^x-": {}},
"additionalProperties": false
Expand Down Expand Up @@ -710,7 +721,7 @@
"type": ["object", "null"],
"properties": {
"name": {"type": "string"},
"driver": {"type": "string"},
"driver": {"type": "string", "description": "The driver used for this network"},
"driver_opts": {
"type": "object",
"patternProperties": {
Expand Down Expand Up @@ -773,7 +784,7 @@
"type": ["object", "null"],
"properties": {
"name": {"type": "string"},
"driver": {"type": "string"},
"driver": {"type": "string", "description": "The driver used for this volume"},
"driver_opts": {
"type": "object",
"patternProperties": {
Expand Down