Skip to content

Commit 96e6f85

Browse files
VerdentVerdent
authored
JSON Schema documentation (#10748)
JSON Schema documentation Signed-off-by: David Kral <[email protected]>
1 parent 8b27b99 commit 96e6f85

File tree

5 files changed

+208
-0
lines changed

5 files changed

+208
-0
lines changed

‎docs/src/main/asciidoc/includes/attributes.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,7 @@ endif::[]
243243
:tracing-javadoc-base-url: {javadoc-base-url}/io.helidon.tracing
244244
:tracing-otel-provider-javadoc-base-url: {javadoc-base-url}/io.helidon.tracing.providers.opentelemetry
245245
:types-javadoc-base-url: {javadoc-base-url}/io.helidon.common.types
246+
:json-schema-base-url: {javadoc-base-url}/io.helidon.json.schema
246247
247248
:webclient-javadoc-base-url: {javadoc-base-url}/io.helidon.webclient
248249
:webclient-api-javadoc-base-url: {javadoc-base-url}/io.helidon.webclient.api

‎docs/src/main/asciidoc/se/introduction.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,15 @@ Expose health statuses of your applications.
8585
--
8686
Use of the Helidon injection in your applications.
8787
--
88+
89+
//JSON Schema
90+
[CARD]
91+
.JSON Schema
92+
[icon=colorize,link=json/schema.adoc]
93+
--
94+
Creation of the JSON Schema in your applications.
95+
--
96+
8897
//Metrics
8998
[CARD]
9099
.Metrics

‎docs/src/main/asciidoc/se/json/schema.adoc‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
///////////////////////////////////////////////////////////////////////////////
2+
3+
Copyright (c) 2025 Oracle and/or its affiliates.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
17+
///////////////////////////////////////////////////////////////////////////////
18+
19+
= JSON Schema
20+
:description: Helidon JSON Schema
21+
:keywords: helidon, json, schema, java, se
22+
:feature-name: JSON Schema
23+
:rootdir: {docdir}/../..
24+
25+
include::{rootdir}/includes/se.adoc[]
26+
27+
== Contents
28+
29+
- <<Overview, Overview>>
30+
- <<Maven Coordinates, Maven Coordinates>>
31+
- <<Usage, Usage>>
32+
** <<Imperative Schema Creation, Imperative Schema Creation>>
33+
** <<Declarative Schema Creation, Declarative Schema Creation>>
34+
35+
== Overview
36+
37+
JSON Schema is a specification for describing the structure and validation rules of JSON data.
38+
It lets you define what properties are required, their types, allowed values, and more.
39+
By using JSON Schema, you can validate that incoming or outgoing JSON matches the expected contract,
40+
provide clear documentation for APIs, and enable tooling support such as code generation and
41+
auto-completion.
42+
43+
Helidon provides two complementary ways to work with JSON Schema.
44+
45+
* In the declarative approach, you describe the schema using annotations in a
46+
link:{json-schema-base-url}/io/helidon/json/schema/JsonSchema.html[`JsonSchema`] class.
47+
* In the imperative approach, you build the schema programmatically with the fluent
48+
link:{json-schema-base-url}/io/helidon/json/schema/Schema.html[`Schema`] builder API.
49+
50+
Helidon currently supports only schema generation.
51+
52+
include::{rootdir}/includes/dependencies.adoc[]
53+
54+
[source,xml]
55+
----
56+
<dependency>
57+
<groupId>io.helidon.json.schema</groupId>
58+
<artifactId>helidon-json-schema</artifactId>
59+
</dependency>
60+
----
61+
62+
== Usage
63+
64+
=== Imperative Schema Creation
65+
The entry point for each runtime JSON schema creation is a
66+
link:{json-schema-base-url}/io/helidon/json/schema/Schema.html[`Schema`] class.
67+
The imperative approach gives you full programmatic control over JSON Schema creation.
68+
Using the fluent Schema builder API, you can construct schemas step by step, configure properties,
69+
and apply constraints directly in code.
70+
This is useful when schemas need to be generated dynamically or when fine-grained customization is required.
71+
72+
[source,java]
73+
----
74+
include::{sourcedir}/se/json/JsonSchemaSnippets.java[tag=snippet_1, indent=0]
75+
----
76+
77+
Once the link:{json-schema-base-url}/io/helidon/json/schema/Schema.html[`Schema`] object is created,
78+
you can generate the JSON Schema as a String. The result looks like this:
79+
80+
[source,json]
81+
----
82+
{
83+
"$schema": "https://json-schema.org/draft/2020-12/schema",
84+
"description": "Example JSON Schema",
85+
"type": "object",
86+
"properties": {
87+
"exampleProperty": {
88+
"type": "integer",
89+
"minimum": 0
90+
}
91+
}
92+
}
93+
----
94+
95+
=== Declarative Schema Creation
96+
The declarative approach lets you define JSON Schema through annotations in a
97+
link:{json-schema-base-url}/io/helidon/json/schema/JsonSchema.html[`JsonSchema`] class.
98+
At compile time, the `helidon-json-schema-codegen` generator processes these annotations and produces a class containing the schema definition.
99+
This approach keeps your schema definitions close to your data model and ensures schemas are
100+
generated automatically without manual coding.
101+
102+
[source,java]
103+
----
104+
include::{sourcedir}/se/json/JsonSchemaSnippets.java[tag=snippet_2, indent=0]
105+
----
106+
<1> Schema defining annotation. Without this annotation the class/record will not be processed as a JSON schema
107+
108+
In addition, the following section must be added to the `build` of the Maven `pom.xml` to enable annotation processors that generate the necessary code:
109+
110+
[source,xml]
111+
----
112+
<plugins>
113+
<plugin>
114+
<groupId>org.apache.maven.plugins</groupId>
115+
<artifactId>maven-compiler-plugin</artifactId>
116+
<configuration>
117+
<annotationProcessorPaths>
118+
<path>
119+
<groupId>io.helidon.bundles</groupId>
120+
<artifactId>helidon-bundles-apt</artifactId>
121+
<version>${helidon.version}</version>
122+
</path>
123+
</annotationProcessorPaths>
124+
</configuration>
125+
</plugin>
126+
</plugins>
127+
----
128+
129+
Once compiled, the class with the following name will be generated `ExampleSchema__JsonSchema`.
130+
This class contains the String format of the schema and is automatically discovered via ServiceRegistry.
131+
Because of that, it is possible to inject the
132+
link:{json-schema-base-url}/io/helidon/json/schema/Schema.html[`Schema`] with the
133+
link:{service-registry-base-url}/io/helidon/service/registry/Service.Named.html[`@Service.Named`] and
134+
desired class (such as `ExampleSchema.class`) as a value.
135+
136+
[source,java]
137+
----
138+
public void myMethod(@Service.Named(ExampleSchema.class) Schema schema) {
139+
//...
140+
}
141+
----
142+
143+
Or obtain it over the static `find` method on the
144+
link:{json-schema-base-url}/io/helidon/json/schema/Schema.html[`Schema`] class. This methods searches the ServiceRegistry
145+
for a Schema bound to the provided class over the parameter.
146+
147+
[source,java]
148+
----
149+
Schema.find(MyClass.class);
150+
----
151+

‎docs/src/main/asciidoc/sitegen.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -452,6 +452,14 @@ backend:
452452
sources:
453453
- "injection.adoc"
454454
- "declarative.adoc"
455+
- type: "MENU"
456+
title: "JSON"
457+
dir: "json"
458+
glyph:
459+
type: "icon"
460+
value: "data_object"
461+
sources:
462+
- "schema.adoc"
455463
- type: "MENU"
456464
title: "JSON-RPC"
457465
dir: "jsonrpc"

‎docs/src/main/java/io/helidon/docs/se/json/JsonSchemaSnippets.java‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/*
2+
* Copyright (c) 2025 Oracle and/or its affiliates.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.helidon.docs.se.json;
17+
18+
import io.helidon.json.schema.JsonSchema;
19+
import io.helidon.json.schema.Schema;
20+
21+
class JsonSchemaSnippets {
22+
23+
void jsonSchemaProgrammaticSnippet() {
24+
// tag::snippet_1[]
25+
Schema.builder()
26+
.rootObject(builder -> builder.description("Example JSON Schema")
27+
.addIntegerProperty("exampleProperty", intBuilder -> intBuilder.minimum(0)))
28+
.build();
29+
// end::snippet_1[]
30+
}
31+
32+
// tag::snippet_2[]
33+
@JsonSchema.Schema // <1>
34+
@JsonSchema.Description("Example JSON Schema")
35+
public record ExampleSchema(@JsonSchema.Integer.Minimum(0) int exampleProperty) {
36+
}
37+
// end::snippet_2[]
38+
39+
}

0 commit comments

Comments
 (0)