Skip to content

docs: correct schema-mode default to fail and document Java field finders#187

Merged
zantvoort merged 2 commits into
mainfrom
docs/schema-validation-default-and-java-finders
Jul 6, 2026
Merged

docs: correct schema-mode default to fail and document Java field finders#187
zantvoort merged 2 commits into
mainfrom
docs/schema-validation-default-and-java-finders

Conversation

@zantvoort

@zantvoort zantvoort commented Jul 6, 2026

Copy link
Copy Markdown
Collaborator

Summary

Follow-up to the 1.12.0 release. Two doc gaps surfaced when re-checking the adoption items against what actually shipped:

1. Schema-validation default is documented wrong. As of 1.12.0 schema validation defaults to fail in the Spring Boot starters and the Ktor plugin (StormAutoConfiguration.java:84, .kt:80, and Storm.kt:93 all ?: "fail", with tests asserting "validation must run in fail mode by default"). Several docs still said the default is none, so a new adopter whose schema does not match would hit a boot failure the docs told them could not happen. Aligned every stale spot with the shipped behavior and with the canonical configuration.md#schema-validation section (which was already correct):

  • configuration.md — properties table, YAML/HOCON default examples, and the Production Hardening note.
  • spring-integration.md — schema-mode YAML default and prose.
  • validation.md — YAML comment, mode-table ordering, and properties table (also Spring Boot only -> Spring Boot and Ktor).
  • ktor-integration.md — schema-validation prose and mode table.

2. Java field-based finders were undocumented. 1.12 added findBy / findAllBy / getBy (plus Ref and findRefBy/getRefBy variants) on the Java EntityRepository, keyed on any Metamodel<E, V> field rather than only unique keys (findAllBy supports single value, Ref, and IN-list). queries.md only showed the Kotlin/unique-key form. The Java examples now use these finders in place of the verbose select().where(...).getResultList() boilerplate they replace.

Note on visibility

Both docs/ (serves /docs/next) and the frozen versioned_docs/version-1.12.0/ snapshot (serves the live /docs/*) are updated, so the schema-mode correction reaches the live site without waiting for a 1.12.1 release. Touching a versioned snapshot is a deliberate one-time exception to the normally-frozen rule, justified because this is a live-facing accuracy fix rather than new content. The snapshot files were byte-identical to the pre-edit docs/ sources, so the two commits apply exactly the same changes.

Verification

  • grep confirms no remaining "default: none" / "skipped (default)" schema claims and no "Spring Boot only" for schema_mode in docs/ or the snapshot.
  • Method signatures verified against storm-java21/src/main/java/st/orm/repository/EntityRepository.java (@since 1.12).

zantvoort added 2 commits July 6, 2026 17:18
…ders

Schema validation defaults to `fail` in the Spring Boot starters and the
Ktor plugin as of 1.12.0, but several docs still described the default as
`none`. Align them with the shipped behavior (and with the canonical
configuration.md#schema-validation section, which was already correct):

- configuration.md: properties table, YAML/HOCON default examples, and the
  Production Hardening note.
- spring-integration.md: schema-mode YAML default and surrounding prose.
- validation.md: YAML comment, mode-table ordering, and properties table
  (also "Spring Boot only" -> "Spring Boot and Ktor").
- ktor-integration.md: schema-validation prose and mode table.

Also document the 1.12 Java field-based finders in queries.md: findBy /
findAllBy (single value and IN) and getBy now work on any Metamodel field,
not just unique keys. The Java examples use them in place of the verbose
select().where(...).getResultList() boilerplate.
Normally versioned_docs snapshots stay frozen, but the schema-mode default
correction is a live-facing accuracy fix: /docs/* serves the 1.12.0
snapshot, so without this the wrong `none` default would remain live until
the next release. Applying the same edits to version-1.12.0 as a deliberate
one-time exception so the fix reaches the live site now.

The snapshot files were byte-identical to the pre-edit docs/ sources, so
these are exactly the same changes as the previous commit.
@zantvoort zantvoort merged commit bb263bd into main Jul 6, 2026
6 checks passed
@zantvoort zantvoort deleted the docs/schema-validation-default-and-java-finders branch July 6, 2026 15:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant