CAMEL-22987: Add canonical YAML DSL JSON Schema variant

docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_19.adoc

@@ -249,6 +249,21 @@ After:
 
 This applies to all `camel-test-infra-*` artifacts, including `camel-test-infra-common`.
 
+=== camel-yaml-dsl
+
+A new canonical JSON Schema variant (`camelYamlDsl-canonical.json`) has been added alongside the existing classic
+schema (`camelYamlDsl.json`). The canonical schema removes all implicit patterns (string shorthands, inline
+expressions, `oneOf`/`anyOf`/`not` constructs) to provide a simpler, more predictable schema for tooling
+such as IDEs, code generators, and AI assistants. See the xref:components:others:yaml-dsl.adoc[YAML DSL]
+documentation for details.
+
+The `YamlValidator` class now accepts a `boolean canonical` constructor parameter to validate against the
+canonical schema.
+
+A new `camel yaml normalize` command has been added to Camel JBang. It rewrites YAML routes from the
+classic (shorthand) form to the canonical (explicit) form. The `camel validate yaml` command also
+supports a new `--canonical` flag to validate against the canonical schema.
+
 === camel-yaml-io / camel-xml-io
 
 In the YAML DSL we have renamed `routePolicy` to `routePolicyRef` on the `route` node,

docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-validate-normalize.adoc

@@ -0,0 +1,86 @@
+= camel validate normalize
+
+Normalize YAML routes to canonical (explicit) form.
+
+This command parses YAML routes and rewrites them in canonical form, expanding all shorthands and
+implicit expressions. For example, `log: "$\{body}"` becomes `log: { message: "$\{body}" }` and
+`setBody: { simple: "Hello" }` becomes `setBody: { expression: { simple: { expression: "Hello" } } }`.
+
+The normalized output is valid against both the classic and canonical schemas.
+
+See the xref:components:others:yaml-dsl.adoc#_schema_variants[YAML DSL Schema Variants] documentation for details
+on the differences between the classic and canonical schemas.
+
+
+== Usage
+
+[source,bash]
+----
+camel validate normalize [options] <files>
+----
+
+
+== Options
+
+[cols="2,5,1,2",options="header"]
+|===
+| Option | Description | Default | Type
+| `--output` | File or directory to write normalized output. If not specified, output is printed to console. |  | String
+| `-h,--help` | Display the help and sub-commands |  | boolean
+|===
+
+
+== Examples
+
+Normalize a YAML route and print to console:
+[source,bash]
+----
+camel validate normalize myroute.yaml
+----
+
+Normalize and write to a file:
+[source,bash]
+----
+camel validate normalize --output normalized.yaml myroute.yaml
+----
+
+Normalize multiple files into a directory:
+[source,bash]
+----
+camel validate normalize --output normalized/ routes/*.yaml
+----
+
+=== Before and after
+
+Given the following YAML route using classic shorthands:
+
+[source,yaml]
+----
+- route:
+    from:
+      uri: timer:yaml
+      steps:
+        - setBody:
+            simple: "Hello Camel from ${routeId}"
+        - log: "${body}"
+----
+
+Running `camel validate normalize myroute.yaml` produces the canonical form:
+
+[source,yaml]
+----
+- route:
+    from:
+      uri: timer:yaml
+      steps:
+        - setBody:
+            expression:
+              simple:
+                expression: "Hello Camel from ${routeId}"
+        - log:
+            message: "${body}"
+----
+
+All shorthands and implicit expressions are expanded to their explicit equivalents.
+The output is valid against both the classic and canonical schemas.
+

docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-validate-yaml.adoc

@@ -0,0 +1,71 @@
+= camel validate yaml
+
+Parse and validate YAML routes against the Camel YAML DSL schema.
+
+By default, routes are validated against the classic schema which accepts both shorthand and explicit forms.
+Use the `--canonical` flag to validate against the canonical schema, which rejects shorthands and implicit expressions.
+
+See the xref:components:others:yaml-dsl.adoc#_schema_variants[YAML DSL Schema Variants] documentation for details
+on the differences between the classic and canonical schemas.
+
+
+== Usage
+
+[source,bash]
+----
+camel validate yaml [options] <files>
+----
+
+
+== Options
+
+[cols="2,5,1,2",options="header"]
+|===
+| Option | Description | Default | Type
+| `--canonical` | Validate against the canonical schema (rejects shorthands and implicit expressions) | false | boolean
+| `-h,--help` | Display the help and sub-commands |  | boolean
+|===
+
+
+== Examples
+
+Validate YAML routes against the classic schema:
+[source,bash]
+----
+camel validate yaml myroute.yaml
+----
+
+Validate against the canonical schema (rejects shorthands):
+[source,bash]
+----
+camel validate yaml --canonical myroute.yaml
+----
+
+Validate multiple files:
+[source,bash]
+----
+camel validate yaml routes/*.yaml
+----
+
+=== Sample output
+
+Given a YAML route using the shorthand `log: "$\{body}"`, validating with `--canonical` will report errors
+because the canonical schema requires the explicit object form:
+
+[source,bash]
+----
+$ camel validate yaml --canonical myroute.yaml
+myroute.yaml: INVALID
+  - $.from.steps[0].log: string found, object expected
+----
+
+The same file validates successfully against the classic schema (the default):
+
+[source,bash]
+----
+$ camel validate yaml myroute.yaml
+myroute.yaml: VALID
+----
+
+Use `camel validate normalize` to convert the file to canonical form before re-validating.
+

docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-validate.adoc

@@ -0,0 +1,32 @@
+= camel validate
+
+Validate Camel source code
+
+
+== Usage
+
+[source,bash]
+----
+camel validate [options]
+----
+
+
+== Subcommands
+
+[cols="2,5",options="header"]
+|===
+| Subcommand | Description
+| xref:jbang-commands/camel-jbang-validate-yaml.adoc[yaml] | Parse and validate YAML routes
+| xref:jbang-commands/camel-jbang-validate-normalize.adoc[normalize] | Normalize YAML routes to canonical (explicit) form
+|===
+
+
+
+== Options
+
+[cols="2,5,1,2",options="header"]
+|===
+| Option | Description | Default | Type
+| `-h,--help` | Display the help and sub-commands |  | boolean
+|===
+

dsl/camel-jbang/camel-jbang-plugin-validate/pom.xml

@@ -49,5 +49,9 @@
             <groupId>org.apache.camel</groupId>
             <artifactId>camel-yaml-dsl-validator</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.apache.camel</groupId>
+            <artifactId>camel-yaml-io</artifactId>
+        </dependency>
     </dependencies>
 </project>

dsl/camel-jbang/camel-jbang-plugin-validate/src/main/java/org/apache/camel/dsl/jbang/core/commands/validate/ValidatePlugin.java

@@ -27,7 +27,8 @@ public class ValidatePlugin implements Plugin {
     @Override
     public void customize(CommandLine commandLine, CamelJBangMain main) {
         var cmd = new CommandLine(new ValidateCommand(main))
-                .addSubcommand("yaml", new CommandLine(new YamlValidateCommand(main)));
+                .addSubcommand("yaml", new CommandLine(new YamlValidateCommand(main)))
+                .addSubcommand("normalize", new CommandLine(new YamlNormalizeCommand(main)));
 
         commandLine.addSubcommand("validate", cmd);
     }