Currently the documentation explains that:
“The merge is recursive for nested objects”
earlier than the section that explains array behavior.
Because “recursive merge” is often interpreted as “deep merge” (including arrays) in JSON/YAML tooling ecosystems, readers may initially assume arrays are merged recursively or index-wise.
Later, the docs correctly clarify:
“arrays are not merged—a child array replaces the parent array completely.”
Suggestion:
Mention object vs array semantics together near the first explanation of inheritance/merge behavior.
For example:
Objects are recursively merged.
`Arrays` are never merged; they are always replaced entirely by the child value.
Or a small table:
| Type |
Behavior |
| Object |
Recursive merge |
| Array |
Replace entirely |
| Scalar |
Override |
This would make the behavior easier to understand on first read.
Currently the documentation explains that:
earlier than the section that explains array behavior.
Because “recursive merge” is often interpreted as “deep merge” (including arrays) in JSON/YAML tooling ecosystems, readers may initially assume arrays are merged recursively or index-wise.
Later, the docs correctly clarify:
Suggestion:
Mention object vs array semantics together near the first explanation of inheritance/merge behavior.
For example:
Or a small table:
This would make the behavior easier to understand on first read.