From 4dfd528df98d8d441d09b04efde6011fb601761d Mon Sep 17 00:00:00 2001 From: Ion Gireada Date: Mon, 8 Dec 2025 13:59:37 +0200 Subject: [PATCH 1/2] feat(schema)!: Require 'cli' property at the root level Added the `"required": ["cli"]` keyword to the root of `cli.schema.json`. This change explicitly enforces that every CLI definition must include a top-level `cli` object. This strengthens the schema's validation, ensuring that all instances properly define the core CLI structure and preventing partially defined configurations. As a consequence, any existing `cli.schema.json` instance that previously omitted the top-level `cli` property (even if semantically incomplete) will now fail validation, thus requiring all instances to conform to this stricter rule. A comma was also added for correct JSON syntax before the new `required` property. BREAKING CHANGE: This commit introduces breaking changes. --- schema/cli.schema.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/schema/cli.schema.json b/schema/cli.schema.json index 506bf21..df76f78 100644 --- a/schema/cli.schema.json +++ b/schema/cli.schema.json @@ -126,5 +126,6 @@ ], "additionalProperties": false } - } + }, + "required": ["cli"] } From 099617af549fd24ad92cdd44e4dfd0a81b60fc8e Mon Sep 17 00:00:00 2001 From: Ion Gireada Date: Mon, 8 Dec 2025 14:06:13 +0200 Subject: [PATCH 2/2] docs(examples)!: update examples and README for required 'cli' root object The example CLI definitions in `EXAMPLES.md` and `examples/cli-schema.definition.yml` have been updated to include the mandatory top-level `cli` object. All previously root-level properties, such as `command`, `description`, `version`, `arguments`, and `options`, are now correctly nested under this `cli` key. Additionally, the `README.md` has been updated under the 'Schema Reference' section to explicitly state that all CLI definitions must be nested under a top-level `cli` object. These changes ensure that all provided examples and documentation align with the latest schema requirements, which mandate the `cli` property at the root of every CLI definition. BREAKING CHANGE: This commit introduces breaking changes. --- EXAMPLES.md | 51 +++++++++++++++--------------- README.md | 2 ++ examples/cli-schema.definition.yml | 47 +++++++++++++-------------- 3 files changed, 52 insertions(+), 48 deletions(-) diff --git a/EXAMPLES.md b/EXAMPLES.md index b5bd670..1c26157 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -20,31 +20,32 @@ This file provides a self-referential example, defining the `cli-schema` command ```yaml # This file defines the 'cli-schema' command-line tool itself, # using the canonical schema. -command: cli-schema -description: Canonical JSON Schema for declarative CLI definitions -version: '1.0.6' - -# Defines the positional arguments for the command. -arguments: - - name: filesToValidate - description: One or more files to validate against the schema. - type: string - # 'required: false' makes this argument optional, equivalent to [files...]. - # If this was 'required: true', it would be equivalent to . - required: false - variadic: true - -# Defines the options (flags) for the command. -# These are standard options automatically provided by commander.js. -options: - - name: help - short: h - description: Display help for command - type: boolean - - name: version - short: V - description: Output the version number - type: boolean +cli: + command: cli-schema + description: Canonical JSON Schema for declarative CLI definitions + version: '1.0.6' + + # Defines the positional arguments for the command. + arguments: + - name: filesToValidate + description: One or more files to validate against the schema. + type: string + # 'required: false' makes this argument optional, equivalent to [files...]. + # If this was 'required: true', it would be equivalent to . + required: false + variadic: true + + # Defines the options (flags) for the command. + # These are standard options automatically provided by commander.js. + options: + - name: help + short: h + description: Display help for command + type: boolean + - name: version + short: V + description: Output the version number + type: boolean ``` --- diff --git a/README.md b/README.md index 2a7e570..7c8a912 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,8 @@ While the examples show a simple command, the schema is designed to handle enter ## Schema Reference +All CLI definitions must be nested under a top-level `cli` object. This root object contains all the commands, arguments, and options that define your command-line interface. + The `cli-schema` defines the structure for your CLI definition file. Here are the main building blocks: ### The `command` Object diff --git a/examples/cli-schema.definition.yml b/examples/cli-schema.definition.yml index e3edaea..4ba78c2 100644 --- a/examples/cli-schema.definition.yml +++ b/examples/cli-schema.definition.yml @@ -1,27 +1,28 @@ # This file defines the 'cli-schema' command-line tool itself, # using the canonical schema. -command: cli-schema -description: Canonical JSON Schema for declarative CLI definitions -version: '1.0.6' +cli: + command: cli-schema + description: Canonical JSON Schema for declarative CLI definitions + version: '1.0.6' -# Defines the positional arguments for the command. -arguments: - - name: filesToValidate - description: One or more files to validate against the schema. - type: string - # 'required: false' makes this argument optional, equivalent to [files...]. - # If this was 'required: true', it would be equivalent to . - required: false - variadic: true + # Defines the positional arguments for the command. + arguments: + - name: filesToValidate + description: One or more files to validate against the schema. + type: string + # 'required: false' makes this argument optional, equivalent to [files...]. + # If this was 'required: true', it would be equivalent to . + required: false + variadic: true -# Defines the options (flags) for the command. -# These are standard options automatically provided by commander.js. -options: - - name: help - alias: h - description: display help for command - type: boolean - - name: version - alias: V - description: output the version number - type: boolean + # Defines the options (flags) for the command. + # These are standard options automatically provided by commander.js. + options: + - name: help + alias: h + description: display help for command + type: boolean + - name: version + alias: V + description: output the version number + type: boolean