CAMEL-22987: Add canonical YAML DSL JSON Schema variant by gnodet · Pull Request #22059 · apache/camel

gnodet · 2026-03-17T16:13:39Z

Summary

Adds a canonical variant of the Camel YAML DSL JSON Schema (camelYamlDsl-canonical.json) that removes all oneOf/anyOf/not constructs and implicit patterns. This results in a schema ~25% smaller that is significantly easier for tooling (IDEs, code generators, AI assistants) to process.

The canonical form is a strict subset of the classic form: any YAML file that validates against the canonical schema will also validate against the classic schema and work with the Camel runtime.

Changes

Schema generator: New canonical parameter in GenerateYamlSchemaMojo that suppresses inline shorthands, oneOf grouping, and __extends merging
Canonical schema: Generated at schema/camelYamlDsl-canonical.json alongside the existing classic schema
Validator: YamlValidator supports both schemas via new YamlValidator(canonical) constructor
JBang camel validate yaml --canonical: Validates YAML routes against the canonical schema (rejects shorthands/implicit expressions)
JBang camel validate normalize: Rewrites YAML routes from shorthand to canonical form (loads routes via CamelContext, dumps back via ModelToYAMLDumper)
Documentation:
- Schema Variants section in yaml-dsl.adoc with 5 tabbed side-by-side classic vs canonical examples
- IDE usage guide with canonical schema URL
- Standalone command reference pages for validate yaml and validate normalize with usage examples and sample output

Naming

Renamed from "strict" to "canonical" based on review feedback — "canonical" better conveys "the explicit, unambiguous form" rather than implying the classic form is "wrong."

Schema Store

The classic schema is already registered in SchemaStore for *.camel.yaml / *.camelk.yaml. A follow-up PR to SchemaStore can register the canonical variant URL once this is merged.

Default schema

The classic schema remains the default everywhere:

SchemaStore (IDE auto-detection for *.camel.yaml)
YamlValidator() no-arg constructor
camel validate yaml command (without --canonical flag)
Maven validator plugin (ValidateMojo)
MCP tools (TransformTools)

Whether to make canonical the default (e.g., in a future major version) is an open community discussion.

Test plan

YamlCanonicalValidatorTest — validates canonical schema accepts explicit forms, rejects shorthands
Existing YamlValidatorTest — ensures classic schema still works
Build with regeneration of all downstream artifacts
Code formatting verified
CI green on JDK 17, 21, 25

github-actions · 2026-03-17T16:37:00Z

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

First-time contributors require MANUAL approval for the GitHub Actions to run
You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
You can label PRs using build-all, build-dependents, skip-tests and test-dependents to fine-tune the checks executed by this PR.
Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

github-actions · 2026-03-17T16:53:07Z

🧪 CI tested the following changed modules:

docs
dsl/camel-jbang/camel-jbang-plugin-validate
dsl/camel-yaml-dsl/camel-yaml-dsl
dsl/camel-yaml-dsl/camel-yaml-dsl-maven-plugin
dsl/camel-yaml-dsl/camel-yaml-dsl-validator
dsl/camel-yaml-dsl/camel-yaml-dsl

All tested modules (40 modules)

Camel :: Coverage
Camel :: Coverage [pom]
Camel :: Docs
Camel :: Docs [pom]
Camel :: JBang :: Core
Camel :: JBang :: Core [jar]
Camel :: JBang :: Integration tests
Camel :: JBang :: Integration tests [jar]
Camel :: JBang :: MCP
Camel :: JBang :: MCP [jar]
Camel :: JBang :: Main
Camel :: JBang :: Main [jar]
Camel :: JBang :: Plugin :: Edit
Camel :: JBang :: Plugin :: Edit [jar]
Camel :: JBang :: Plugin :: Generate
Camel :: JBang :: Plugin :: Generate [jar]
Camel :: JBang :: Plugin :: Kubernetes
Camel :: JBang :: Plugin :: Kubernetes [jar]
Camel :: JBang :: Plugin :: Route Parser
Camel :: JBang :: Plugin :: Route Parser [jar]
Camel :: JBang :: Plugin :: Testing
Camel :: JBang :: Plugin :: Testing [jar]
Camel :: JBang :: Plugin :: Validate
Camel :: JBang :: Plugin :: Validate [jar]
Camel :: Kamelet Main
Camel :: Kamelet Main [jar]
Camel :: Launcher
Camel :: Launcher [jar]
Camel :: Launcher :: Container
Camel :: Launcher :: Container [pom]
Camel :: YAML DSL
Camel :: YAML DSL [jar]
Camel :: YAML DSL :: Deserializers
Camel :: YAML DSL :: Deserializers [jar]
Camel :: YAML DSL :: Maven Plugins
Camel :: YAML DSL :: Maven Plugins [maven-plugin]
Camel :: YAML DSL :: Validator
Camel :: YAML DSL :: Validator [jar]
Camel :: YAML DSL :: Validator Maven Plugin
Camel :: YAML DSL :: Validator Maven Plugin [maven-plugin]

github-actions · 2026-03-17T16:55:31Z

✅ Parent POM dependency changes: targeted tests passed

Changed properties: smallrye-fault-tolerance-version

Affected modules (1)

:camel-microprofile-fault-tolerance

gnodet · 2026-03-18T16:08:41Z

The CI failure here is caused by flaky camel-smb integration tests (unrelated to this PR). The SMB module was pulled into the incremental build by CI dependency detection and failed first in the reactor, causing all YAML DSL modules to be skipped.

This should be fixed by #22081 which addresses the SMB test issues. Once that's merged, re-running CI here should go green.

apupier

I think it will be worthy that some people from Kaoto review also this PR to see if the strict way is matching what is supported currently, or at least if there is no blocker to support it easily.

//cc @lordrip

Note that we will need to change the default when exporting from Camel JBang, updating most examples and publish it along the other one in Json schemastore

lordrip · 2026-03-20T08:29:09Z

Hi @apupier, thanks for the heads up 🙏

From our side, given that we still need to keep backward compatibility, we'll continue generating the catalogs out of the previous schema (full one). Nevertheless, this is a very interesting change for introducing a "strict mode" in Kaoto were all the shorthand will be flaggeg.

Food for thought, @gnodet, do you think this could be the standard for a new major version? I know it would be a breaking change, but the syntax will thank you 😄

apupier · 2026-04-01T07:52:51Z

Food for thought, @gnodet, do you think this could be the standard for a new major version? I know it would be a breaking change, but the syntax will thank you

@gnodet ^

apupier

based on @lordrip comment, there won't be any problems with Kaoto (even be simpler)

it remains all the surroundings to have it useful in practice (json schema store, when to change the default?, update all examples?, provide migration steps?)

given the age of the PR and that there is genrated code based on the model, i think it will be worthy to rebase the PR to avoid breaking the main branch due to uncommitted change)

Add a strict JSON Schema variant (camelYamlDsl-strict.json) that removes all implicit patterns from the YAML DSL schema: - No string shorthands (e.g. log: "${body}" must be log: { message: ... }) - No inline expressions (e.g. setBody: { simple: ... } must use expression wrapper) - No oneOf/anyOf/not constructs This results in a ~25% smaller schema that is significantly easier for tooling (IDEs, code generators, AI assistants) to process. Changes: - GenerateYamlSchemaMojo: add strict parameter to skip inline, __extends, oneOf - pom.xml: add second execution to generate strict schema - YamlValidator: add strict constructor to validate against strict schema - 7 new tests validating strict vs classic schema behavior - Documentation in yaml-dsl.adoc and upgrade guide Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… normalize command - Rename "strict" to "canonical" throughout: schema filename, Java API, tests, docs, and upgrade guide - Add --canonical flag to `camel validate yaml` command - Add `camel validate normalize` command that rewrites YAML routes from shorthand to canonical (explicit) form - Update documentation with normalize and validate --canonical examples Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…hema examples - Add JBang command docs: camel-jbang-validate, validate-yaml, validate-normalize - Register validate command in the JBang commands reference index - Expand yaml-dsl.adoc with side-by-side classic vs canonical examples for log, setBody, setHeader, choice/when, and complete route patterns - Document how to use the canonical schema with IDEs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The camel-jbang-commands.adoc is auto-generated by camel-package-maven-plugin. Manual edits get overwritten during build, causing CI to fail with "uncommitted changes". The validate command docs are cross-referenced from the yaml-dsl.adoc documentation instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…assic Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…mand docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gnodet · 2026-04-01T13:23:00Z

@apupier Thanks for the review and approval! Since your review, the PR has been significantly expanded based on your feedback and further discussion:

Changes since your last review:

Renamed "strict" → "canonical" — better conveys "the explicit, unambiguous form" without implying the classic form is wrong
Added camel validate yaml --canonical flag — validates YAML routes against the canonical schema, reporting shorthands and implicit expressions as errors
Added camel validate normalize command — rewrites YAML routes from classic shorthand form to canonical explicit form (parses via CamelContext, dumps via ModelToYAMLDumper)
Added comprehensive documentation in yaml-dsl.adoc:
- 5 tabbed side-by-side examples (log, setBody, setHeader, choice/when, complete route)
- IDE usage guide with canonical schema URL
- Standalone command reference pages for both new commands with before/after examples and sample output
Clarified the subset relationship — the canonical form is a strict subset of the classic form (any canonical-valid YAML also validates against the classic schema)

Re: "when to make canonical the default?" — the classic schema remains the default everywhere (SchemaStore, YamlValidator(), CLI commands, Maven plugin, MCP tools). Whether to make canonical the default is an open community discussion, likely for a future major version.

Would appreciate a re-review of the expanded changeset when you get a chance!

Claude Code on behalf of Guillaume Nodet

...te/src/main/java/org/apache/camel/dsl/jbang/core/commands/validate/YamlNormalizeCommand.java

- Use printErr for error messages instead of stdout - Continue processing remaining files on error instead of aborting - Use try-with-resources for CamelContext - Extract type converter registry to local variable - Use camelCase property names instead of dashed notation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sonarqubecloud · 2026-04-07T08:27:01Z

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)
13.8% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

…ml-schema # Conflicts: # dsl/camel-yaml-dsl/camel-yaml-dsl-validator/src/main/java/org/apache/camel/dsl/yaml/validator/YamlValidator.java

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ml-schema

… main Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions bot added docs dsl labels Mar 17, 2026

gnodet force-pushed the CAMEL-22987-strict-yaml-schema branch from 2ea6aa0 to 81903c5 Compare March 18, 2026 06:51

gnodet marked this pull request as ready for review March 19, 2026 07:29

apupier reviewed Mar 19, 2026

View reviewed changes

apupier approved these changes Apr 1, 2026

View reviewed changes

gnodet force-pushed the CAMEL-22987-strict-yaml-schema branch from cd56b88 to db987f9 Compare April 1, 2026 08:42

gnodet force-pushed the CAMEL-22987-strict-yaml-schema branch from db987f9 to d2ee856 Compare April 1, 2026 09:04

gnodet and others added 2 commits April 1, 2026 11:52

gnodet changed the title ~~CAMEL-22987: Add strict YAML DSL JSON Schema variant~~ CAMEL-22987: Add canonical YAML DSL JSON Schema variant Apr 1, 2026

gnodet and others added 2 commits April 1, 2026 14:53

CAMEL-22987: Clarify that canonical YAML DSL is a strict subset of cl…

ce0e9f7

…assic Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CAMEL-22987: Add before/after and sample output examples to JBang com…

7e4992a

…mand docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gnodet requested a review from apupier April 1, 2026 13:23

apupier reviewed Apr 3, 2026

View reviewed changes

gnodet and others added 4 commits April 9, 2026 15:03

Merge remote-tracking branch 'origin/main' into CAMEL-22987-strict-ya…

d3c187f

…ml-schema # Conflicts: # dsl/camel-yaml-dsl/camel-yaml-dsl-validator/src/main/java/org/apache/camel/dsl/yaml/validator/YamlValidator.java

CAMEL-22987: Regenerate canonical YAML DSL schema after merge

e62f856

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into CAMEL-22987-strict-ya…

11fb69e

…ml-schema

CAMEL-22987: Regenerate canonical YAML DSL schema after re-merge with…

ea9a7be

… main Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gnodet mentioned this pull request Apr 9, 2026

ci: fix incremental build exclusion conflict with primary modules #22525

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CAMEL-22987: Add canonical YAML DSL JSON Schema variant#22059

CAMEL-22987: Add canonical YAML DSL JSON Schema variant#22059
gnodet wants to merge 11 commits intomainfrom
CAMEL-22987-strict-yaml-schema

gnodet commented Mar 17, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

github-actions bot commented Mar 17, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

gnodet commented Mar 18, 2026

Uh oh!

apupier left a comment

Uh oh!

lordrip commented Mar 20, 2026 •

edited

Loading

Uh oh!

apupier commented Apr 1, 2026

Uh oh!

apupier left a comment •

edited

Loading

Uh oh!

gnodet commented Apr 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

gnodet commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Naming

Schema Store

Default schema

Test plan

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

github-actions bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

gnodet commented Mar 18, 2026

Uh oh!

apupier left a comment

Choose a reason for hiding this comment

Uh oh!

lordrip commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apupier commented Apr 1, 2026

Uh oh!

apupier left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gnodet commented Apr 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Apr 7, 2026

Quality Gate failed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gnodet commented Mar 17, 2026 •

edited

Loading

github-actions bot commented Mar 17, 2026 •

edited

Loading

lordrip commented Mar 20, 2026 •

edited

Loading

apupier left a comment •

edited

Loading