Add @JsonProperty.isRequired (#285)

Author: cowtowncoder

release-notes/VERSION-2.x

@@ -16,6 +16,8 @@ NOTE: Annotations module will never contain changes in patch versions,
 #280: Minor change to `module-info.java`: use "open module"
 #281: [gradle-module-metadata-maven-plugin] update to version 1.0
  (contributed by @jjohannes)
+#284: Add `OptBoolean` valued `@JsonProperty.isRequired` to
+  (eventually) replace `@JsonProperty.required`
 
 2.18.0 (26-Sep-2024)
 

src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java

@@ -92,15 +92,31 @@ public enum MyEnum {
     String namespace() default "";
 
     /**
-     * Property that indicates whether a value (which may be explicit
-     * null) is expected for property during deserialization or not.
-     * If expected, <code>BeanDeserialized</code> should indicate
+     * Property similar to {@link #isRequired}, but one that only
+     * allows two values ({@code true} and {@code false}), defaulting
+     * to {@code false}.
+     *<p>
+     * NOTE: as of Jackson 2.19, there is newer property, {@link #isRequired()},
+     * to be used instead.
+     *
+     * @since 2.0
+     */
+    boolean required() default false;
+
+    /**
+     * Property that MAY indicate whether a value (which may be explicit
+     * null) is required for a property during deserialization or not.
+     * If required ({code OptBoolean.TRUE}), {@code Deserializer} should indicate
      * this as a validity problem (usually by throwing an exception,
      * but this may be sent via problem handlers that can try to
-     * rectify the problem, for example, by supplying a default
-     * value).
+     * rectify the problem, for example, by supplying a default value) if no
+     * value is present in incoming content. If not required ({code OptBoolean.FALSE}),
+     * no checking is to be done.
+     * If not specified ({code OptBoolean.DEFAULT}) checking depends on higher
+     * level settings (some modules may specify default "required-ness" for certain
+     * kinds of properties).
      *<p>
-     * Note that as of 2.6, this property is only used for Creator
+     * Note that as of 2.19, this property is only used for Creator
      * Properties, to ensure existence of property value in JSON:
      * for other properties (ones injected using a setter or mutable
      * field), no validation is performed. Support for those cases
@@ -116,11 +132,18 @@ public enum MyEnum {
      * this property should be set to {@code false}. This is important because
      * validation of {@code required} properties occurs before the application of
      * secondary sources.
+     *<p>
+     * Default value ({@link OptBoolean#DEFAULT}) means that "required-ness"
+     * is not specified by this annotation -- it is up to more general settings
+     * (per-class, global) to determine whether the property is required or not.
+     *<p>
+     * NOTE: as of Jackson 2.19, the older property, {@link #required()},
+     * is considered deprecated and should not be used.
      *
-     * @since 2.0
+     * @since 2.19
      */
-    boolean required() default false;
-
+    OptBoolean isRequired() default OptBoolean.DEFAULT;
+    
     /**
      * Property that indicates numerical index of this property (relative
      * to other properties specified for the Object). This index