Skip to content

Add content for the "Built-in options" section #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexander-yevsyukov merged 16 commits into from
Mar 2, 2026
Merged

Add content for the "Built-in options" section #274

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
2d1db6b
Bump minimatch from 10.1.1 to 10.2.4 in /docs/_preview
dependabot[bot] Feb 27, 2026
aec24f3
Bump version -> `2.0.0-SNAPSHOT.400`
alexander-yevsyukov Feb 27, 2026
ea821e8
Add details for the `build-in-options-plan.md`
alexander-yevsyukov Feb 27, 2026
60f7ece
Update the plan for "Built-in options"
alexander-yevsyukov Feb 27, 2026
fecedfa
Update `_examples` ref.
alexander-yevsyukov Feb 27, 2026
c8204fe
Add text for "Built-in options" section
alexander-yevsyukov Feb 27, 2026
b3e5ff6
Makr "Built-in options" section done
alexander-yevsyukov Feb 27, 2026
e5e2b65
Update dependency reports
alexander-yevsyukov Feb 27, 2026
9f968cf
Merge remote-tracking branch 'origin/dependabot/npm_and_yarn/docs/_pr…
alexander-yevsyukov Feb 27, 2026
da8ae13
Update Validation version
alexander-yevsyukov Feb 27, 2026
5f875f2
Avoid braces in the text
alexander-yevsyukov Feb 27, 2026
70bdd1e
Remove extra empty lines
alexander-yevsyukov Mar 2, 2026
f9ec802
Condense wording in `oneof-fields.md`
alexander-yevsyukov Mar 2, 2026
6bfa7c1
Link back to `oneof-fields.md`
alexander-yevsyukov Mar 2, 2026
85e9c86
Improve wording in `field-level-options.md`
alexander-yevsyukov Mar 2, 2026
738b7bc
Add missing space
alexander-yevsyukov Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions .agents/tasks/archive/built-in-options-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Task: Publish a reference set on built-in validation options

## Goal

Publish an actionable catalog of built-in *validation-related* options, organized by where
the option can be declared (field, `oneof`, message), and optimized for selecting the right
option for a use case.

## Placement and structure

- Placement: the "Built-in options" section comes after the "Concepts" section.
- Structure: implement "Built-in options" as a folder with a landing page and 4 child pages
(not a single long page).
- Avoid having a separate page per option.

Proposed doc files under `docs/content/docs/validation/03-built-in-options/`:

- `docs/content/docs/validation/03-built-in-options/_index.md` (landing page)
- `docs/content/docs/validation/03-built-in-options/field-level-options.md`
- Title: "Field-level options"
- `docs/content/docs/validation/03-built-in-options/oneof-fields.md`
- Title: "Options for `oneof` fields"
- `docs/content/docs/validation/03-built-in-options/message-level-options.md`
- Title: "Message-level options"
- `docs/content/docs/validation/03-built-in-options/repeated-and-map-fields.md`
- Title: "Options for `repeated` and `map` fields"

Order of pages: exactly as listed above.

## Scope and source of truth

- Source of truth for what exists: `docs/_options/options.proto`.
- Scope: validation-related options only.
- Exclude non-validation options (API annotations, entity metadata, etc.).
- Exclude deprecated options (do not document them; do not add “deprecated catalogs”).
- Do not duplicate the full option documentation from `spine/options.proto`.
- Prefer short, “how to choose” descriptions, and link out for authoritative details.

## Content principles (what each page should contain)

Each page should:

- Start with “When to use this page” and a small “Choose an option” list (use case → option).
- Group options by intent (presence, range, pattern, uniqueness, recursion, dependencies),
not by field number order.
- Include 1–2 minimal examples per group (copy-pasteable `.proto` snippets).
- Include “Applies to” and “Common combinations / gotchas” where the behavior is easy to
misunderstand (e.g., `(validate)` + default instances, uniqueness for collections, etc.).
- Link to `spine/options.proto` on GitHub when referencing the canonical definition.

## What options to cover (high-level checklist)

The catalog should cover (non-deprecated) validation-related options defined in
`docs/_options/options.proto`, including:

- Field-level:
- Presence: `(required)`, `(if_missing)`
- Numeric constraints: `(min)`, `(max)`, `(range)`
- String/bytes constraints: `(pattern)`
- Nested validation: `(validate)`
- Cross-field dependency: `(goes)`
- Immutability: `(set_once)`, `(if_set_again)`
- Uniqueness for collections: `(distinct)`, `(if_has_duplicates)`
- `oneof`:
- Required selection: `(choice)`
- Message-level:
- Field-group requirements: `(require)`

Note: keep this list aligned with `docs/_options/options.proto` and update it if the proto
changes.

## External links

- Link to canonical `spine/options.proto` where appropriate:
- https://github.com/SpineEventEngine/base-libraries/blob/master/base/src/main/proto/spine/options.proto
7 changes: 0 additions & 7 deletions .agents/tasks/built-in-options-plan.md
View file
Open in desktop

This file was deleted.

1 change: 1 addition & 0 deletions .agents/tasks/validation-documentation-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ buildable documentation set, without expanding scope unnecessarily.
- Status: DONE (2026-02-27).

5) [Built-in options](built-in-options-plan.md): publish a minimal reference set
- Status: DONE (2026-02-27).

6) [Validating third-party messages](third-party-messages-plan.md)

Expand Down
60 changes: 30 additions & 30 deletions dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@


# Dependencies of `io.spine.tools:validation-context:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-context:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
Expand Down Expand Up @@ -1139,14 +1139,14 @@

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:13 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-context-tests:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-context-tests:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
Expand Down Expand Up @@ -1731,7 +1731,7 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:02 WET 2026** using
This report was generated on **Fri Feb 27 20:33:12 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).

Expand All @@ -1752,7 +1752,7 @@ This report was generated on **Mon Feb 23 18:35:33 WET 2026** using



# Dependencies of `io.spine.tools:validation-gradle-plugin:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-gradle-plugin:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
Expand Down Expand Up @@ -2841,14 +2841,14 @@ This report was generated on **Mon Feb 23 18:35:33 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:13 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-java:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-java:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
Expand Down Expand Up @@ -3935,14 +3935,14 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:13 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-java-bundle:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-java-bundle:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.google.auto.service. **Name** : auto-service-annotations. **Version** : 1.1.1.
Expand Down Expand Up @@ -4005,14 +4005,14 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:01 WET 2026** using
This report was generated on **Fri Feb 27 20:33:11 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine:validation-jvm-runtime:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine:validation-jvm-runtime:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
Expand Down Expand Up @@ -4845,14 +4845,14 @@ This report was generated on **Thu Feb 26 22:11:01 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:13 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-ksp:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-ksp:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.google.auto.service. **Name** : auto-service-annotations. **Version** : 1.1.1.
Expand Down Expand Up @@ -5781,14 +5781,14 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:13 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-consumer:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-consumer:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
Expand Down Expand Up @@ -6379,14 +6379,14 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:01 WET 2026** using
This report was generated on **Fri Feb 27 20:33:12 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-consumer-dependency:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-consumer-dependency:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
Expand Down Expand Up @@ -6897,14 +6897,14 @@ This report was generated on **Thu Feb 26 22:11:01 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:13 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-extensions:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-extensions:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
Expand Down Expand Up @@ -7588,14 +7588,14 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:12 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-runtime:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-runtime:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
Expand Down Expand Up @@ -8217,14 +8217,14 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:13 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-validating:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-validating:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
Expand Down Expand Up @@ -8889,14 +8889,14 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:03 WET 2026** using
This report was generated on **Fri Feb 27 20:33:13 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-validator:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-validator:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
Expand Down Expand Up @@ -9647,14 +9647,14 @@ This report was generated on **Thu Feb 26 22:11:03 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:02 WET 2026** using
This report was generated on **Fri Feb 27 20:33:12 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-validator-dependency:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-validator-dependency:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
Expand Down Expand Up @@ -9924,14 +9924,14 @@ This report was generated on **Thu Feb 26 22:11:02 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:02 WET 2026** using
This report was generated on **Fri Feb 27 20:33:12 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).




# Dependencies of `io.spine.tools:validation-vanilla:2.0.0-SNAPSHOT.399`
# Dependencies of `io.spine.tools:validation-vanilla:2.0.0-SNAPSHOT.400`

## Runtime
1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
Expand Down Expand Up @@ -10282,6 +10282,6 @@ This report was generated on **Thu Feb 26 22:11:02 WET 2026** using

The dependencies distributed under several licenses, are used according their commercial-use-friendly license.

This report was generated on **Thu Feb 26 22:11:01 WET 2026** using
This report was generated on **Fri Feb 27 20:33:12 WET 2026** using
[Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under
[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
2 changes: 1 addition & 1 deletion docs/_examples
Open in desktop
Submodule _examples updated 1 files
+1 −1 first-model/build.gradle.kts
Loading
Loading