feat: include standard formats in plain JSON preset by default (#401)

CHANGELOG.md

@@ -4,7 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-*-*
+## [Unreleased]
+### `jsonschema-generator`
+#### Added
+- new `Option.STANDARD_FORMATS` includes standard `"format"` values to some types considered by `Option.ADDITIONAL_FIXED_TYPES`
+
+#### Changed
+- include new `Option.STANDARD_FORMATS` in `OptionPreset.PLAIN_JSON` by default
 
 ## [4.32.0] - 2023-10-27
 ### `jsonschema-generator`

jsonschema-examples/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-parent</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-parent/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-examples</artifactId>

jsonschema-examples/src/test/resources/com/github/victools/jsonschema/examples/JacksonDescriptionAsTitleExample-result.json

@@ -8,6 +8,7 @@
         },
         "id" : {
             "type" : "string",
+            "format" : "uuid",
             "title" : "Method Title"
         }
     },

jsonschema-generator-bom/pom.xml

@@ -8,7 +8,7 @@
 
     <groupId>com.github.victools</groupId>
     <artifactId>jsonschema-generator-bom</artifactId>
-    <version>4.32.1-SNAPSHOT</version>
+    <version>4.33.0-SNAPSHOT</version>
     <packaging>pom</packaging>
 
     <properties>

jsonschema-generator-parent/pom.xml

@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-bom</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-bom/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-generator-parent</artifactId>
@@ -113,6 +113,13 @@
                 <role>Provided PR #388 (allowing configuration of Maven plugin serialization behavior)</role>
             </roles>
         </contributor>
+        <contributor>
+            <name>Daniel Gómez-Sánchez</name>
+            <url>https://github.com/magicDGS</url>
+            <roles>
+                <role>Provided PR #300 (introducing support for standard "format" values via Option)</role>
+            </roles>
+        </contributor>
     </contributors>
 
     <properties>

jsonschema-generator/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-parent</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-parent/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-generator</artifactId>

jsonschema-generator/src/main/java/com/github/victools/jsonschema/generator/Option.java

@@ -286,18 +286,14 @@ public enum Option {
      * @since 4.11.0
      */
     PLAIN_DEFINITION_KEYS(null, null),
-
     /**
-     * For the "format" attribute, JSON Schema defines various built-in supported values.
+     * For the "format" attribute, JSON Schema defines various supported values.
      * <br>
-     * Some of those data-types would be handed if either {@link #ADDITIONAL_FIXED_TYPES}
-     * or a custom {@link SimpleTypeModule} (i.e., {@link SimpleTypeModule#forPrimitiveTypes()})
-     * are added.
-     * In that case, by enabling this option these standard built-in "format" values would be added.
-     * Note that if {@link #EXTRA_OPEN_API_FORMAT_VALUES} is enabled, it overrides this option as
-     * it include extra "format" attributes.
+     * Some of those data-types would be included if either {@link #ADDITIONAL_FIXED_TYPES} is enabled or a custom {@link SimpleTypeModule} are added.
+     * By enabling this option, only the standard built-in "format" values would be added, which is a subset of the values considered with the
+     * {@link #EXTRA_OPEN_API_FORMAT_VALUES} being enabled.
      *
-     * @since 4.32.1
+     * @since 4.33.0
      */
     STANDARD_FORMATS(null, null),
     /**

jsonschema-generator/src/main/java/com/github/victools/jsonschema/generator/OptionPreset.java

@@ -55,6 +55,7 @@ public class OptionPreset {
     public static final OptionPreset PLAIN_JSON = new OptionPreset(
             Option.SCHEMA_VERSION_INDICATOR,
             Option.ADDITIONAL_FIXED_TYPES,
+            Option.STANDARD_FORMATS,
             Option.FLATTENED_ENUMS,
             Option.FLATTENED_OPTIONALS,
             Option.FLATTENED_SUPPLIERS,

jsonschema-generator/src/main/java/com/github/victools/jsonschema/generator/impl/module/SimpleTypeModule.java

@@ -23,15 +23,16 @@
 import com.github.victools.jsonschema.generator.MemberScope;
 import com.github.victools.jsonschema.generator.Module;
 import com.github.victools.jsonschema.generator.SchemaGenerationContext;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfig;
 import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
 import com.github.victools.jsonschema.generator.SchemaKeyword;
 import com.github.victools.jsonschema.generator.TypeScope;
 import java.lang.reflect.Type;
-import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
-import java.util.List;
+import java.util.HashSet;
 import java.util.Map;
+import java.util.Set;
 import java.util.stream.Stream;
 
 /**
@@ -104,8 +105,8 @@ public static SimpleTypeModule forPrimitiveAndAdditionalTypes() {
     }
 
     private final Map<Class<?>, SchemaKeyword> fixedJsonSchemaTypes = new HashMap<>();
-    private final List<Class<?>> standardFormats = new ArrayList<>();
-    private final Map<Class<?>, String> extraOpenApiFormatValues = new HashMap<>();
+    private final Set<Class<?>> typesWithStandardFormats = new HashSet<>();
+    private final Map<Class<?>, String> formatValues = new HashMap<>();
 
     /**
      * Add the given mapping for a (simple) java class to its JSON schema equivalent "type" attribute.
@@ -118,7 +119,7 @@ public static SimpleTypeModule forPrimitiveAndAdditionalTypes() {
     private SimpleTypeModule with(Class<?> javaType, SchemaKeyword jsonSchemaTypeValue, String openApiFormat) {
         this.fixedJsonSchemaTypes.put(javaType, jsonSchemaTypeValue);
         if (openApiFormat != null) {
-            this.extraOpenApiFormatValues.put(javaType, openApiFormat);
+            this.formatValues.put(javaType, openApiFormat);
         }
         return this;
     }
@@ -166,10 +167,16 @@ public final SimpleTypeModule withStringType(Class<?> javaType, String openApiFo
         return this.with(javaType, SchemaKeyword.TAG_TYPE_STRING, openApiFormat);
     }
 
-    private final SimpleTypeModule withStandardStringType(Class<?> javaType, final String format) {
-        // track as a standard format
-        this.standardFormats.add(javaType);
-        return this.withStringType(javaType, format);
+    /**
+     * Add the given mapping for a (simple) java class to its JSON schema equivalent "type" attribute: "{@link SchemaKeyword#TAG_TYPE_STRING}".
+     *
+     * @param javaType java class to map to a fixed JSON schema definition
+     * @param standardFormat optional {@link SchemaKeyword#TAG_FORMAT} value, to set if one of the respective Options is enabled
+     * @return this module instance (for chaining)
+     */
+    public final SimpleTypeModule withStandardStringType(Class<?> javaType, final String standardFormat) {
+        this.typesWithStandardFormats.add(javaType);
+        return this.withStringType(javaType, standardFormat);
     }
 
     /**
@@ -254,8 +261,7 @@ public void applyToConfigBuilder(SchemaGeneratorConfigBuilder builder) {
      * @return either {@code Object.class} to cause omission of the "additionalProperties" keyword or null to leave it up to following configurations
      */
     private Type resolveAdditionalProperties(TypeScope scope) {
-        if (scope.getType().getTypeParameters().isEmpty()
-                && SchemaKeyword.TAG_TYPE_NULL == this.fixedJsonSchemaTypes.get(scope.getType().getErasedType())) {
+        if (this.shouldHaveEmptySchema(scope)) {
             // indicate no specific additionalProperties type - thereby causing it to be omitted from the generated schema
             return Object.class;
         }
@@ -269,14 +275,17 @@ private Type resolveAdditionalProperties(TypeScope scope) {
      * @return either an empty map to cause omission of the "patternProperties" keyword or null to leave it up to following configurations
      */
     private Map<String, Type> resolvePatternProperties(TypeScope scope) {
-        if (scope.getType().getTypeParameters().isEmpty()
-                && SchemaKeyword.TAG_TYPE_NULL == this.fixedJsonSchemaTypes.get(scope.getType().getErasedType())) {
+        if (this.shouldHaveEmptySchema(scope)) {
             // indicate no specific patternProperties - thereby causing it to be omitted from the generated schema
             return Collections.emptyMap();
         }
         return null;
     }
 
+    private boolean shouldHaveEmptySchema(TypeScope scope) {
+        return SchemaKeyword.TAG_TYPE_NULL == this.fixedJsonSchemaTypes.get(scope.getType().getErasedType());
+    }
+
     /**
      * Implementation of the {@link CustomDefinitionProviderV2} interface for applying fixed schema definitions for simple java types.
      */
@@ -296,21 +305,20 @@ public CustomDefinition provideCustomSchemaDefinition(ResolvedType javaType, Sch
             if (jsonSchemaTypeValue != SchemaKeyword.TAG_TYPE_NULL) {
                 customSchema.put(context.getKeyword(SchemaKeyword.TAG_TYPE), context.getKeyword(jsonSchemaTypeValue));
             }
-            if (shouldAddFormatTag(javaType, context)) {
-                String formatValue = SimpleTypeModule.this.extraOpenApiFormatValues.get(javaType.getErasedType());
+            if (this.shouldAddFormatTag(javaType, context.getGeneratorConfig())) {
+                String formatValue = SimpleTypeModule.this.formatValues.get(javaType.getErasedType());
                 if (formatValue != null) {
                     customSchema.put(context.getKeyword(SchemaKeyword.TAG_FORMAT), formatValue);
                 }
             }
-            // set true as second parameter to indicate simple types to be always in-lined (i.e. not put into definitions)
             return new CustomDefinition(customSchema, CustomDefinition.DefinitionType.INLINE, CustomDefinition.AttributeInclusion.YES);
         }
 
-        private boolean shouldAddFormatTag(final ResolvedType javaType, final SchemaGenerationContext context) {
+        private boolean shouldAddFormatTag(final ResolvedType javaType, final SchemaGeneratorConfig config) {
             // either OpenAPI extra formats or standard-formats that are registered
-            return context.getGeneratorConfig().shouldIncludeExtraOpenApiFormatValues()
-                    || (context.getGeneratorConfig().shouldIncludeStandardFormatValues()
-                            && standardFormats.contains(javaType.getErasedType()));
+            return config.shouldIncludeExtraOpenApiFormatValues()
+                    || (config.shouldIncludeStandardFormatValues()
+                        && SimpleTypeModule.this.typesWithStandardFormats.contains(javaType.getErasedType()));
         }
     }
 }

jsonschema-generator/src/test/java/com/github/victools/jsonschema/generator/SchemaGeneratorSimpleTypesTest.java

@@ -49,10 +49,10 @@ static Stream<Arguments> getSimpleTypeCombinations() {
             Arguments.of(long.class, SchemaKeyword.TAG_TYPE_INTEGER, "int64", null),
             Arguments.of(Short.class, SchemaKeyword.TAG_TYPE_INTEGER, null, null),
             Arguments.of(short.class, SchemaKeyword.TAG_TYPE_INTEGER, null, null),
-            Arguments.of(Double.class, SchemaKeyword.TAG_TYPE_NUMBER, "double", null, null),
-            Arguments.of(double.class, SchemaKeyword.TAG_TYPE_NUMBER, "double", null, null),
-            Arguments.of(Float.class, SchemaKeyword.TAG_TYPE_NUMBER, "float", null, null),
-            Arguments.of(float.class, SchemaKeyword.TAG_TYPE_NUMBER, "float", null, null),
+            Arguments.of(Double.class, SchemaKeyword.TAG_TYPE_NUMBER, "double", null),
+            Arguments.of(double.class, SchemaKeyword.TAG_TYPE_NUMBER, "double", null),
+            Arguments.of(Float.class, SchemaKeyword.TAG_TYPE_NUMBER, "float", null),
+            Arguments.of(float.class, SchemaKeyword.TAG_TYPE_NUMBER, "float", null),
             Arguments.of(java.time.LocalDate.class, SchemaKeyword.TAG_TYPE_STRING, "date", "date"),
             Arguments.of(java.time.LocalDateTime.class, SchemaKeyword.TAG_TYPE_STRING, "date-time", "date-time"),
             Arguments.of(java.time.LocalTime.class, SchemaKeyword.TAG_TYPE_STRING, "time", "time"),
@@ -155,7 +155,7 @@ public void testGenerateSchema_SimpleType_withAdditionalPropertiesOption(Class<?
     @ParameterizedTest
     @MethodSource("parametersForTestGenerateSchema_SimpleTypeWithStandardFormat")
     public void testGenerateSchema_SimpleTypeWithStandardFormat(Class<?> targetType, SchemaKeyword expectedJsonSchemaType, String expectedFormat,
-                                                        SchemaVersion schemaVersion) throws Exception {
+            SchemaVersion schemaVersion) throws Exception {
         SchemaGeneratorConfig config = new SchemaGeneratorConfigBuilder(schemaVersion)
                 .with(Option.ADDITIONAL_FIXED_TYPES, Option.STANDARD_FORMATS)
                 .build();

jsonschema-maven-plugin/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-parent</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-parent/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-maven-plugin</artifactId>

jsonschema-module-jackson/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-parent</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-parent/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-module-jackson</artifactId>

jsonschema-module-jakarta-validation/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-parent</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-parent/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-module-jakarta-validation</artifactId>

jsonschema-module-javax-validation/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-parent</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-parent/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-module-javax-validation</artifactId>

jsonschema-module-swagger-1.5/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-parent</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-parent/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-module-swagger-1.5</artifactId>

jsonschema-module-swagger-2/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>com.github.victools</groupId>
         <artifactId>jsonschema-generator-parent</artifactId>
-        <version>4.32.1-SNAPSHOT</version>
+        <version>4.33.0-SNAPSHOT</version>
         <relativePath>../jsonschema-generator-parent/pom.xml</relativePath>
     </parent>
     <artifactId>jsonschema-module-swagger-2</artifactId>

pom.xml

@@ -3,7 +3,7 @@
 
     <groupId>com.github.victools</groupId>
     <artifactId>jsonschema-generator-reactor</artifactId>
-    <version>4.32.1-SNAPSHOT</version>
+    <version>4.33.0-SNAPSHOT</version>
     <packaging>pom</packaging>
 
     <name>Java JSON Schema Generator (Reactor)</name>