/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.marshall.httppart;

import static java.util.Collections.*;
import static org.apache.juneau.commons.httppart.HttpPartDataType.*;
import static org.apache.juneau.commons.httppart.HttpPartFormat.*;
import static org.apache.juneau.commons.reflect.ReflectionUtils.*;
import static org.apache.juneau.commons.utils.ClassUtils.*;
import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.CollectionUtils.list;
import static org.apache.juneau.commons.utils.ObjectUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.Shorts.neq;
import static org.apache.juneau.commons.utils.Shorts.eq;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.commons.utils.StringUtils.isEmpty;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;
import static org.apache.juneau.marshall.Constants.*;

import java.lang.annotation.*;
import java.lang.reflect.*;
import java.math.*;
import java.util.*;
import java.util.concurrent.atomic.*;
import java.util.function.*;
import java.util.regex.*;

import org.apache.juneau.commons.*;
import org.apache.juneau.commons.BasicRuntimeException;
import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.httppart.*;
import org.apache.juneau.commons.lang.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.commons.utils.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.parser.*;

/**
 * Represents an OpenAPI schema definition.
 *
 * <p>
 * The schema definition can be applied to any HTTP parts such as bodies, headers, query/form parameters, and URL path parts.
 * <br>The API is generic enough to apply to any path part although some attributes may only applicable for certain parts.
 *
 * <p>
 * Schema objects are created via builders instantiated through the {@link #create()} method.
 *
 * <h5 class='section'>Jakarta Bean Validation Support:</h5>
 * <p>
 * As of 9.2.0, this class supports Jakarta Bean Validation constraint annotations (e.g., <c>@NotNull</c>, <c>@Size</c>, <c>@Min</c>, <c>@Max</c>).
 * When these annotations are encountered during schema building, they are automatically mapped to corresponding OpenAPI schema properties:
 * <ul>
 *    <li><c>@NotNull</c> → <c>required(true)</c>
 *    <li><c>@Size(min=x, max=y)</c> → <c>minLength/maxLength</c> and <c>minItems/maxItems</c>
 *    <li><c>@Min(value)</c> → <c>minimum(value)</c>
 *    <li><c>@Max(value)</c> → <c>maximum(value)</c>
 *    <li><c>@Pattern(regexp)</c> → <c>pattern(regexp)</c>
 *    <li><c>@Email</c> → <c>format("email")</c>
 *    <li><c>@Positive/@PositiveOrZero/@Negative/@NegativeOrZero</c> → Corresponding min/max constraints
 *    <li><c>@NotEmpty</c> → <c>required(true) + minLength(1)/minItems(1)</c>
 *    <li><c>@NotBlank</c> → <c>required(true) + minLength(1) + pattern</c>
 *    <li><c>@DecimalMin/@DecimalMax</c> → <c>minimum/maximum</c> with optional <c>exclusiveMinimum/exclusiveMaximum</c>
 * </ul>
 * <p>
 * This integration uses pure reflection and does not require <c>jakarta.validation-api</c> as a dependency.
 * The annotations are detected and processed automatically when present.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='note'>This class is thread safe and reusable.
 * </ul>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/OpenApiSupport">OpenApi</a>
 * </ul>
 */
@SuppressWarnings({
   "java:S100", // Builder methods const_, default_ and enum_ use a trailing underscore to avoid Java keyword clashes with the OpenAPI keywords
   "java:S115", // Constants use UPPER_camelCase convention (e.g., ANN_inclusive)
   "java:S116", // Field names use trailing underscores (default_, enum_, const_) to avoid Java keyword conflicts
   "java:S1168", // Builder helpers (toNumber, toSet, joinnlOrNull, getAnnotationString) return null as the absent-value sentinel that callers test for
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S1452", // Wildcard required for parsed type metadata
   "java:S3776", // The HttpPartSchema(Builder) constructor and annotation-applying code branch over every OpenAPI type/format/constraint combination
   "java:S5843", // Complex regex patterns needed for RFC compliance (IPv6, ISO 8601 duration, date-time formats)
   "java:S6539", // Monster class; HttpPartSchema is intentionally a single cohesive OpenAPI/HTTP-part schema model+validator
   "java:S6541", // The HttpPartSchema(Builder) constructor runs the full per-type validation switch in one place
   "unused" // Method kept for future use or API completeness
})
public class HttpPartSchema {

   private static final AnnotationProvider AP = AnnotationProvider.INSTANCE;

   /**
    * Builder class.
    */
   public static class Builder {
      String name;
      String default_;
      Set<Integer> codes;
      Set<String> enum_;
      Boolean allowEmptyValue;
      Boolean exclusiveMaximum;
      Boolean exclusiveMinimum;
      Boolean required;
      Boolean uniqueItems;
      Boolean skipIfEmpty;
      HttpPartCollectionFormat collectionFormat = HttpPartCollectionFormat.NO_COLLECTION_FORMAT;
      HttpPartDataType type = HttpPartDataType.NO_TYPE;
      HttpPartFormat format = HttpPartFormat.NO_FORMAT;
      Pattern pattern;
      Number maximum;
      Number minimum;
      Number multipleOf;
      Long maxLength;
      Long minLength;
      Long maxItems;
      Long minItems;
      Long maxProperties;
      Long minProperties;
      Map<String,Object> properties;
      Object items;
      Object additionalProperties;
      boolean noValidate;
      Class<?> parser;
      Class<?> serializer;
      // JSON Schema Draft 2020-12 properties
      String const_;
      String[] examples;
      Boolean deprecated;
      Number exclusiveMaximumValue;
      Number exclusiveMinimumValue;

      /**
       * <mk>const</mk> field (JSON Schema Draft 2020-12).
       *
       * <p>
       * Defines a constant value for this schema.
       * The instance must be equal to this value to validate.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder const_(String value) {
         const_ = value;
         return this;
      }

      /**
       * <mk>default</mk> field.
       *
       * <p>
       * Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request.
       * <br>(Note: "default" has no meaning for required parameters.)
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder default_(String value) {
         if (ine(value))
            default_ = value;
         return this;
      }

      /**
       * <mk>enum</mk> field.
       *
       * <p>
       * If specified, the input validates successfully if it is equal to one of the elements in this array.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or an empty set.
       * @return This object.
       */
      public Builder enum_(Set<String> value) {
         if (nn(value) && ! value.isEmpty())
            enum_ = value;
         return this;
      }

      /**
       * <mk>enum</mk> field.
       *
       * <p>
       * Same as {@link #enum_(Set)} but takes in a var-args array.
       *
       * @param values
       *    The new values for this property.
       *    <br>Ignored if value is empty.
       * @return This object.
       */
      public Builder enum_(String...values) {
         return enum_(set(values));
      }

      /**
       * <mk>additionalProperties</mk> field.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder additionalProperties(Builder value) {
         if (nn(value))
            additionalProperties = value;
         return this;
      }

      /**
       * <mk>additionalProperties</mk> field.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder additionalProperties(HttpPartSchema value) {
         if (nn(value))
            additionalProperties = value;
         return this;
      }

      /**
       * Synonym for {@link #allowEmptyValue()}.
       *
       * @return This object.
       */
      public Builder aev() {
         return allowEmptyValue(true);
      }

      /**
       * Synonym for {@link #allowEmptyValue(Boolean)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder aev(Boolean value) {
         return allowEmptyValue(value);
      }

      /**
       * Synonym for {@link #allowEmptyValue(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder aev(String value) {
         return allowEmptyValue(value);
      }

      /**
       * <mk>allowEmptyValue</mk> field.
       *
       * <p>
       * Shortcut for calling <code>allowEmptyValue(<jk>true</jk>);</code>.
       *
       * @return This object.
       */
      public Builder allowEmptyValue() {
         return allowEmptyValue(true);
      }

      /**
       * <mk>allowEmptyValue</mk> field.
       *
       * <p>
       * Sets the ability to pass empty-valued parameters.
       * <br>This is valid only for either query or formData parameters and allows you to send a parameter with a name only or an empty value.
       * <br>The default value is <jk>false</jk>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder allowEmptyValue(Boolean value) {
         allowEmptyValue = resolve(value, allowEmptyValue);
         return this;
      }

      /**
       * <mk>allowEmptyValue</mk> field.
       *
       * <p>
       * Same as {@link #allowEmptyValue(Boolean)} but takes in a string boolean value.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder allowEmptyValue(String value) {
         allowEmptyValue = resolve(value, allowEmptyValue);
         return this;
      }

      /**
       * Shortcut for <c>additionalProperties(value)</c>
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder ap(Builder value) {
         return additionalProperties(value);
      }

      /**
       * Shortcut for <c>additionalProperties(value)</c>
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder ap(HttpPartSchema value) {
         return additionalProperties(value);
      }

      /**
       * Apply the specified annotation to this schema.
       *
       * @param a The annotation to apply.  Must not be <jk>null</jk>.
       * @return This object.
      */
      public Builder apply(Annotation a) {
         if (a instanceof Schema a2)
            return apply(a2);
         if (a instanceof Items a2)
            return apply(a2);
         if (a instanceof SubItems a2)
            return apply(a2);
         if (a instanceof HttpPartMarshalling a2)
            return apply(a2);
         if (cn(a.annotationType()).startsWith("jakarta.validation.constraints.")) {
            applyJakartaValidation(a);
            return this;
         }
         return applyHttpAnnotation(a);
      }

      /**
       * Instantiates a new {@link HttpPartSchema} object based on the configuration of this builder.
       *
       * <p>
       * This method can be called multiple times to produce new schema objects.
       *
       * @return
       *    A new {@link HttpPartSchema} object.
       *    <br>Never <jk>null</jk>.
       */
      public HttpPartSchema build() {
         return new HttpPartSchema(this);
      }

      /**
       * Synonym for {@link #collectionFormat(HttpPartCollectionFormat)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder cf(HttpPartCollectionFormat value) {
         return collectionFormat(value);
      }

      /**
       * Synonym for {@link #collectionFormat(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder cf(String value) {
         return collectionFormat(value);
      }

      /**
       * Shortcut for <c>collectionFormat(HttpPartCollectionFormat.CSV)</c>.
       *
       * @return This object.
       */
      public Builder cfCsv() {
         return collectionFormat(HttpPartCollectionFormat.CSV);
      }

      /**
       * Shortcut for <c>collectionFormat(HttpPartCollectionFormat.MULTI)</c>.
       *
       * @return This object.
       */
      public Builder cfMulti() {
         return collectionFormat(HttpPartCollectionFormat.MULTI);
      }

      /**
       * Shortcut for <c>collectionFormat(HttpPartCollectionFormat.NO_COLLECTION_FORMAT)</c>.
       *
       * @return This object.
       */
      public Builder cfNone() {
         return collectionFormat(HttpPartCollectionFormat.NO_COLLECTION_FORMAT);
      }

      /**
       * Shortcut for <c>collectionFormat(HttpPartCollectionFormat.PIPES)</c>.
       *
       * @return This object.
       */
      public Builder cfPipes() {
         return collectionFormat(HttpPartCollectionFormat.PIPES);
      }

      /**
       * Shortcut for <c>collectionFormat(HttpPartCollectionFormat.SSV)</c>.
       *
       * @return This object.
       */
      public Builder cfSsv() {
         return collectionFormat(HttpPartCollectionFormat.SSV);
      }

      /**
       * Shortcut for <c>collectionFormat(HttpPartCollectionFormat.TSV)</c>.
       *
       * @return This object.
       */
      public Builder cfTsv() {
         return collectionFormat(HttpPartCollectionFormat.TSV);
      }

      /**
       * Shortcut for <c>collectionFormat(HttpPartCollectionFormat.UONC)</c>.
       *
       * @return This object.
       */
      public Builder cfUon() {
         return collectionFormat(HttpPartCollectionFormat.UONC);
      }

      /**
       * <mk>httpStatusCode</mk> key.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#responsesObject">Responses</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <c>0</c>.
       * @return This object.
       */
      public Builder code(int value) {
         if (value != 0) {
            if (codes == null)
               codes = new TreeSet<>();
            codes.add(value);
         }
         return this;
      }

      /**
       * <mk>httpStatusCode</mk> key.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#responsesObject">Responses</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if <jk>null</jk> or an empty array.
       * @return This object.
       */
      public Builder codes(int[] value) {
         if (nn(value) && value.length != 0)
            for (var v : value)
               code(v);
         return this;
      }

      /**
       * <mk>collectionFormat</mk> field.
       *
       * <p>
       * Determines the format of the array if <c>type</c> <js>"array"</js> is used.
       * <br>Can only be used if <c>type</c> is <js>"array"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * <p>
       * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.
       *
       * <ul class='values javatree'>
       *    <ul class='jc'>{@link HttpPartCollectionFormat}
       *    <ul>
       *       <li>
       *          {@link HttpPartCollectionFormat#CSV CSV} (default) - Comma-separated values (e.g. <js>"foo,bar"</js>).
       *       <li>
       *          {@link HttpPartCollectionFormat#SSV SSV} - Space-separated values (e.g. <js>"foo bar"</js>).
       *       <li>
       *          {@link HttpPartCollectionFormat#TSV TSV} - Tab-separated values (e.g. <js>"foo\tbar"</js>).
       *       <li>
       *          {@link HttpPartCollectionFormat#PIPES PIPES} - Pipe-separated values (e.g. <js>"foo|bar"</js>).
       *       <li>
       *          {@link HttpPartCollectionFormat#MULTI MULTI} - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&amp;foo=baz"</js>).
       *       <li>
       *          {@link HttpPartCollectionFormat#UONC UONC} - UON collection notation (e.g. <js>"@(foo,bar)"</js>).
       *    </ul>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder collectionFormat(HttpPartCollectionFormat value) {
         // Guard null for parity with the String overload (which ine()-guards); a null must not overwrite the field.
         if (value != null)
            collectionFormat = value;
         return this;
      }

      /**
       * <mk>collectionFormat</mk> field.
       *
       * <p>
       * Determines the format of the array if <c>type</c> <js>"array"</js> is used.
       * <br>Can only be used if <c>type</c> is <js>"array"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * <p>
       * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.
       *
       * <ul class='values'>
       *    <li>
       *       <js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>).
       *    <li>
       *       <js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>).
       *    <li>
       *       <js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>).
       *    <li>
       *       <js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>).
       *    <li>
       *       <js>"multi"</js> - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&amp;foo=baz"</js>).
       *    <li>
       *       <js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>).
       *    <li>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder collectionFormat(String value) {
         try {
            if (ine(value))
               this.collectionFormat = HttpPartCollectionFormat.fromString(value);
         } catch (Exception e) {
            throw new BasicRuntimeException(e, "Invalid value '%s' passed in as collectionFormat value.  Valid values: %s", value, HttpPartCollectionFormat.values());
         }
         return this;
      }

      /**
       * <mk>deprecated</mk> field (JSON Schema Draft 2020-12).
       *
       * <p>
       * Indicates that applications should refrain from usage of this property.
       * This is used for documentation purposes only and does not affect validation.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder deprecated(Boolean value) {
         deprecated = resolve(value, deprecated);
         return this;
      }

      /**
       * Synonym for {@link #default_(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder df(String value) {
         return default_(value);
      }

      /**
       * Synonym for {@link #enum_(Set)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder e(Set<String> value) {
         return enum_(value);
      }

      /**
       * Synonym for {@link #enum_(String...)}.
       *
       * @param values
       *    The new values for this property.
       * @return This object.
       */
      public Builder e(String...values) {
         return enum_(values);
      }

      /**
       * Synonym for {@link #exclusiveMaximum()}.
       *
       * @return This object.
       */
      public Builder emax() {
         return exclusiveMaximum();
      }

      /**
       * Synonym for {@link #exclusiveMaximum(Boolean)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder emax(Boolean value) {
         return exclusiveMaximum(value);
      }

      /**
       * Synonym for {@link #exclusiveMaximum(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder emax(String value) {
         return exclusiveMaximum(value);
      }

      /**
       * Synonym for {@link #exclusiveMinimum()}.
       *
       * @return This object.
       */
      public Builder emin() {
         return exclusiveMinimum();
      }

      /**
       * Synonym for {@link #exclusiveMinimum(Boolean)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder emin(Boolean value) {
         return exclusiveMinimum(value);
      }

      /**
       * Synonym for {@link #exclusiveMinimum(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder emin(String value) {
         return exclusiveMinimum(value);
      }

      /**
       * <mk>examples</mk> field (JSON Schema Draft 2020-12).
       *
       * <p>
       * An array of example values.
       * This is used for documentation purposes only and does not affect validation.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder examples(String...value) {
         examples = value;
         return this;
      }

      /**
       * <mk>exclusiveMaximum</mk> field.
       *
       * <p>
       * Shortcut for calling <code>exclusiveMaximum(<jk>true</jk>);</code>.
       *
       * @return This object.
       */
      public Builder exclusiveMaximum() {
         return exclusiveMaximum(true);
      }

      /**
       * <mk>exclusiveMaximum</mk> field.
       *
       * <p>
       * Defines whether the maximum is matched exclusively.
       *
       * <p>
       * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
       * <br>If <jk>true</jk>, must be accompanied with <c>maximum</c>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder exclusiveMaximum(Boolean value) {
         exclusiveMaximum = resolve(value, exclusiveMaximum);
         return this;
      }

      /**
       * <mk>exclusiveMaximum</mk> field.
       *
       * <p>
       * Same as {@link #exclusiveMaximum(Boolean)} but takes in a string boolean value.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder exclusiveMaximum(String value) {
         exclusiveMaximum = resolve(value, exclusiveMaximum);
         return this;
      }

      /**
       * <mk>exclusiveMaximum</mk> field with numeric value (JSON Schema Draft 2020-12).
       *
       * <p>
       * Defines the exclusive maximum value for numeric types.
       * The instance is valid if it is strictly less than (not equal to) this value.
       *
       * <p>
       * This is the Draft 2020-12 version that uses a numeric value instead of a boolean flag.
       * If this is set, it takes precedence over the boolean {@link #exclusiveMaximum(Boolean)} property.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder exclusiveMaximumValue(Number value) {
         exclusiveMaximumValue = value;
         return this;
      }

      /**
       * <mk>exclusiveMinimum</mk> field.
       *
       * <p>
       * Shortcut for calling <code>exclusiveMinimum(<jk>true</jk>);</code>.
       *
       * @return This object.
       */
      public Builder exclusiveMinimum() {
         return exclusiveMinimum(true);
      }

      /**
       * <mk>exclusiveMinimum</mk> field.
       *
       * <p>
       * Defines whether the minimum is matched exclusively.
       *
       * <p>
       * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
       * <br>If <jk>true</jk>, must be accompanied with <c>minimum</c>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder exclusiveMinimum(Boolean value) {
         exclusiveMinimum = resolve(value, exclusiveMinimum);
         return this;
      }

      /**
       * <mk>exclusiveMinimum</mk> field.
       *
       * <p>
       * Same as {@link #exclusiveMinimum(Boolean)} but takes in a string boolean value.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder exclusiveMinimum(String value) {
         exclusiveMinimum = resolve(value, exclusiveMinimum);
         return this;
      }

      /**
       * <mk>exclusiveMinimum</mk> field with numeric value (JSON Schema Draft 2020-12).
       *
       * <p>
       * Defines the exclusive minimum value for numeric types.
       * The instance is valid if it is strictly greater than (not equal to) this value.
       *
       * <p>
       * This is the Draft 2020-12 version that uses a numeric value instead of a boolean flag.
       * If this is set, it takes precedence over the boolean {@link #exclusiveMinimum(Boolean)} property.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder exclusiveMinimumValue(Number value) {
         exclusiveMinimumValue = value;
         return this;
      }

      /**
       * Synonym for {@link #format(HttpPartFormat)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder f(HttpPartFormat value) {
         return format(value);
      }

      /**
       * Synonym for {@link #format(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder f(String value) {
         return format(value);
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.BINARY)</c>.
       *
       * @return This object.
       */
      public Builder fBinary() {
         format = HttpPartFormat.BINARY;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.BINARY_SPACED)</c>.
       *
       * @return This object.
       */
      public Builder fBinarySpaced() {
         format = HttpPartFormat.BINARY_SPACED;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.BYTE)</c>.
       *
       * @return This object.
       */
      public Builder fByte() {
         format = HttpPartFormat.BYTE;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.DATE)</c>.
       *
       * @return This object.
       */
      public Builder fDate() {
         format = HttpPartFormat.DATE;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.DATE_TIME)</c>.
       *
       * @return This object.
       */
      public Builder fDateTime() {
         format = HttpPartFormat.DATE_TIME;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.DOUBLE)</c>.
       *
       * @return This object.
       */
      public Builder fDouble() {
         format = HttpPartFormat.DOUBLE;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.FLOAT)</c>.
       *
       * @return This object.
       */
      public Builder fFloat() {
         format = HttpPartFormat.FLOAT;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.INT32)</c>.
       *
       * @return This object.
       */
      public Builder fInt32() {
         format = HttpPartFormat.INT32;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.INT64)</c>.
       *
       * @return This object.
       */
      public Builder fInt64() {
         format = HttpPartFormat.INT64;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.NO_FORMAT)</c>.
       *
       * @return This object.
       */
      public Builder fNone() {
         format = HttpPartFormat.NO_FORMAT;
         return this;
      }

      /**
       * <mk>format</mk> field.
       *
       * <p>
       * The extending format for the previously mentioned <a class="doclink" href="https://swagger.io/specification/v2#parameterType">parameter type</a>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * <ul class='values javatree'>
       *    <ul class='jc'>{@link HttpPartFormat}
       *    <ul>
       *       <li class='jf'>
       *          {@link HttpPartFormat#INT32 INT32} - Signed 32 bits.
       *          <br>Only valid with type <js>"integer"</js>.
       *       <li class='jf'>
       *          {@link HttpPartFormat#INT64 INT64} - Signed 64 bits.
       *          <br>Only valid with type <js>"integer"</js>.
       *       <li class='jf'>
       *          {@link HttpPartFormat#FLOAT FLOAT} - 32-bit floating point number.
       *          <br>Only valid with type <js>"number"</js>.
       *       <li class='jf'>
       *          {@link HttpPartFormat#DOUBLE DOUBLE} - 64-bit floating point number.
       *          <br>Only valid with type <js>"number"</js>.
       *       <li class='jf'>
       *          {@link HttpPartFormat#BYTE BYTE} - BASE-64 encoded characters.
       *          <br>Only valid with type <js>"string"</js>.
       *          <br>Parameters of type POJO convertible from string are converted after the string has been decoded.
       *       <li class='jf'>
       *          {@link HttpPartFormat#BINARY BINARY} - Hexadecimal encoded octets (e.g. <js>"00FF"</js>).
       *          <br>Only valid with type <js>"string"</js>.
       *          <br>Parameters of type POJO convertible from string are converted after the string has been decoded.
       *       <li class='jf'>
       *          {@link HttpPartFormat#BINARY_SPACED BINARY_SPACED} - Hexadecimal encoded octets, spaced (e.g. <js>"00 FF"</js>).
       *          <br>Only valid with type <js>"string"</js>.
       *          <br>Parameters of type POJO convertible from string are converted after the string has been decoded.
       *       <li class='jf'>
       *          {@link HttpPartFormat#DATE DATE} - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>.
       *          <br>Only valid with type <js>"string"</js>.
       *       <li class='jf'>
       *          {@link HttpPartFormat#DATE_TIME DATE_TIME} - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>.
       *          <br>Only valid with type <js>"string"</js>.
       *       <li class='jf'>
       *          {@link HttpPartFormat#PASSWORD PASSWORD} - Used to hint UIs the input needs to be obscured.
       *          <br>This format does not affect the serialization or parsing of the parameter.
       *       <li class='jf'>
       *          {@link HttpPartFormat#UON UON} - UON notation (e.g. <js>"(foo=bar,baz=@(qux,123))"</js>).
       *          <br>Only valid with type <js>"object"</js>.
       *          <br>If not specified, then the input is interpreted as plain-text and is converted to a POJO directly.
       *    </ul>
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder format(HttpPartFormat value) {
         // Guard null for parity with the String overload (which ine()-guards); a null must not overwrite the field.
         if (value != null)
            format = value;
         return this;
      }

      /**
       * <mk>format</mk> field.
       *
       * <p>
       * The extending format for the previously mentioned <a class="doclink" href="https://swagger.io/specification/v2#parameterType">parameter type</a>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * <ul class='values'>
       *    <li>
       *       <js>"int32"</js> - Signed 32 bits.
       *       <br>Only valid with type <js>"integer"</js>.
       *    <li>
       *       <js>"int64"</js> - Signed 64 bits.
       *       <br>Only valid with type <js>"integer"</js>.
       *    <li>
       *       <js>"float"</js> - 32-bit floating point number.
       *       <br>Only valid with type <js>"number"</js>.
       *    <li>
       *       <js>"double"</js> - 64-bit floating point number.
       *       <br>Only valid with type <js>"number"</js>.
       *    <li>
       *       <js>"byte"</js> - BASE-64 encoded characters.
       *       <br>Only valid with type <js>"string"</js>.
       *       <br>Parameters of type POJO convertible from string are converted after the string has been decoded.
       *    <li>
       *       <js>"binary"</js> - Hexadecimal encoded octets (e.g. <js>"00FF"</js>).
       *       <br>Only valid with type <js>"string"</js>.
       *       <br>Parameters of type POJO convertible from string are converted after the string has been decoded.
       *    <li>
       *       <js>"binary-spaced"</js> - Hexadecimal encoded octets, spaced (e.g. <js>"00 FF"</js>).
       *       <br>Only valid with type <js>"string"</js>.
       *       <br>Parameters of type POJO convertible from string are converted after the string has been decoded.
       *    <li>
       *       <js>"date"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>.
       *       <br>Only valid with type <js>"string"</js>.
       *    <li>
       *       <js>"date-time"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>.
       *       <br>Only valid with type <js>"string"</js>.
       *    <li>
       *       <js>"password"</js> - Used to hint UIs the input needs to be obscured.
       *       <br>This format does not affect the serialization or parsing of the parameter.
       *    <li>
       *       <js>"uon"</js> - UON notation (e.g. <js>"(foo=bar,baz=@(qux,123))"</js>).
       *       <br>Only valid with type <js>"object"</js>.
       *       <br>If not specified, then the input is interpreted as plain-text and is converted to a POJO directly.
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or an empty string.
       * @return This object.
       */
      public Builder format(String value) {
         try {
            if (ine(value))
               format = HttpPartFormat.fromString(value);
         } catch (Exception e) {
            throw new BasicRuntimeException(e, "Invalid value '%s' passed in as format value.  Valid values: %s", value, HttpPartFormat.values());
         }
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.PASSWORD)</c>.
       *
       * @return This object.
       */
      public Builder fPassword() {
         format = HttpPartFormat.PASSWORD;
         return this;
      }

      /**
       * Shortcut for <c>format(HttpPartFormat.UON)</c>.
       *
       * @return This object.
       */
      public Builder fUon() {
         format = HttpPartFormat.UON;
         return this;
      }

      /**
       * Synonym for {@link #items(HttpPartSchema.Builder)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder i(Builder value) {
         return items(value);
      }

      /**
       * Synonym for {@link #items(HttpPartSchema)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder i(HttpPartSchema value) {
         return items(value);
      }

      /**
       * <mk>items</mk> field.
       *
       * <p>
       * Describes the type of items in the array.
       * <p>
       * Required if <c>type</c> is <js>"array"</js>.
       * <br>Can only be used if <c>type</c> is <js>"array"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder items(Builder value) {
         if (nn(value))
            items = value;
         return this;
      }

      /**
       * <mk>items</mk> field.
       *
       * <p>
       * Describes the type of items in the array.
       * <p>
       * Required if <c>type</c> is <js>"array"</js>.
       * <br>Can only be used if <c>type</c> is <js>"array"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder items(HttpPartSchema value) {
         if (nn(value))
            items = value;
         return this;
      }

      /**
       * Synonym for {@link #maximum(Number)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder max(Number value) {
         return maximum(value);
      }

      /**
       * Synonym for {@link #maxItems(Long)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder maxi(Long value) {
         return maxItems(value);
      }

      /**
       * Synonym for {@link #maxItems(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder maxi(String value) {
         return maxItems(value);
      }

      /**
       * <mk>maximum</mk> field.
       *
       * <p>
       * Defines the maximum value for a parameter of numeric types.
       *
       * <p>
       * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder maximum(Number value) {
         if (nn(value))
            maximum = value;
         return this;
      }

      /**
       * <mk>maxItems</mk> field.
       *
       * <p>
       * An array or collection is valid if its size is less than, or equal to, the value of this keyword.
       *
       * <p>
       * Only allowed for the following types: <js>"array"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
       * @return This object.
       */
      public Builder maxItems(Long value) {
         maxItems = resolve(value, maxItems);
         return this;
      }

      /**
       * <mk>maxItems</mk> field.
       *
       * <p>
       * Same as {@link #maxItems(Long)} but takes in a string number.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder maxItems(String value) {
         maxItems = resolve(value, maxItems);
         return this;
      }

      /**
       * Synonym for {@link #maxLength(Long)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder maxl(Long value) {
         return maxLength(value);
      }

      /**
       * Synonym for {@link #maxLength(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder maxl(String value) {
         return maxLength(value);
      }

      /**
       * <mk>maxLength</mk> field.
       *
       * <p>
       * A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword.
       * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>.
       *
       * <p>
       * Only allowed for the following types: <js>"string"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
       * @return This object.
       */
      public Builder maxLength(Long value) {
         maxLength = resolve(value, maxLength);
         return this;
      }

      /**
       * <mk>maxLength</mk> field.
       *
       * <p>
       * Same as {@link #maxLength(Long)} but takes in a string number.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder maxLength(String value) {
         maxLength = resolve(value, maxLength);
         return this;
      }

      /**
       * Synonym for {@link #maxProperties(Long)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder maxp(Long value) {
         return maxProperties(value);
      }

      /**
       * Synonym for {@link #maxProperties(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder maxp(String value) {
         return maxProperties(value);
      }

      /**
       * <mk>mapProperties</mk> field.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
       * @return This object.
       */
      public Builder maxProperties(Long value) {
         maxProperties = resolve(value, maxProperties);
         return this;
      }

      /**
       * <mk>mapProperties</mk> field.
       *
       * <p>
       * Same as {@link #maxProperties(Long)} but takes in a string number.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder maxProperties(String value) {
         maxProperties = resolve(value, maxProperties);
         return this;
      }

      /**
       * Synonym for {@link #minimum(Number)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder min(Number value) {
         return minimum(value);
      }

      /**
       * Synonym for {@link #minItems(Long)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder mini(Long value) {
         return minItems(value);
      }

      /**
       * Synonym for {@link #minItems(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder mini(String value) {
         return minItems(value);
      }

      /**
       * <mk>minimum</mk> field.
       *
       * <p>
       * Defines the minimum value for a parameter of numeric types.
       *
       * <p>
       * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder minimum(Number value) {
         if (nn(value))
            minimum = value;
         return this;
      }

      /**
       * <mk>minItems</mk> field.
       *
       * <p>
       * An array or collection is valid if its size is greater than, or equal to, the value of this keyword.
       *
       * <p>
       * Only allowed for the following types: <js>"array"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
       * @return This object.
       */
      public Builder minItems(Long value) {
         minItems = resolve(value, minItems);
         return this;
      }

      /**
       * <mk>minItems</mk> field.
       *
       * <p>
       * Same as {@link #minItems(Long)} but takes in a string number.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder minItems(String value) {
         minItems = resolve(value, minItems);
         return this;
      }

      /**
       * Synonym for {@link #minLength(Long)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder minl(Long value) {
         return minLength(value);
      }

      /**
       * Synonym for {@link #minLength(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder minl(String value) {
         return minLength(value);
      }

      /**
       * <mk>minLength</mk> field.
       *
       * <p>
       * A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword.
       * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>.
       *
       * <p>
       * Only allowed for the following types: <js>"string"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
       * @return This object.
       */
      public Builder minLength(Long value) {
         minLength = resolve(value, minLength);
         return this;
      }

      /**
       * <mk>minLength</mk> field.
       *
       * <p>
       * Same as {@link #minLength(Long)} but takes in a string number.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder minLength(String value) {
         minLength = resolve(value, minLength);
         return this;
      }

      /**
       * Synonym for {@link #minProperties(Long)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder minp(Long value) {
         return minProperties(value);
      }

      /**
       * Synonym for {@link #minProperties(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder minp(String value) {
         return minProperties(value);
      }

      /**
       * <mk>minProperties</mk> field.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder minProperties(Long value) {
         minProperties = resolve(value, minProperties);
         return this;
      }

      /**
       * <mk>minProperties</mk> field.
       *
       * <p>
       * Same as {@link #minProperties(Long)} but takes in a string boolean.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder minProperties(String value) {
         minProperties = resolve(value, minProperties);
         return this;
      }

      /**
       * Synonym for {@link #multipleOf(Number)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder mo(Number value) {
         return multipleOf(value);
      }

      /**
       * <mk>multipleOf</mk> field.
       *
       * <p>
       * A numeric instance is valid if the result of the division of the instance by this keyword's value is an integer.
       *
       * <p>
       * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder multipleOf(Number value) {
         if (nn(value))
            multipleOf = value;
         return this;
      }

      /**
       * Synonym for {@link #name(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder n(String value) {
         return name(value);
      }

      /**
       * <mk>name</mk> field.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder name(String value) {
         if (ine(value))
            name = value;
         return this;
      }

      /**
       * Disables Swagger schema usage validation checking.
       *
       * <p>
       * Shortcut for calling <code>noValidate(<jk>true</jk>);</code>.
       *
       * @return This object.
       */
      public Builder noValidate() {
         return noValidate(true);
      }

      /**
       * Disables Swagger schema usage validation checking.
       *
       * @param value Specify <jk>true</jk> to prevent {@link BasicRuntimeException} from being thrown if invalid Swagger usage was detected.
       * @return This object.
       */
      public Builder noValidate(Boolean value) {
         if (nn(value))
            noValidate = value;
         return this;
      }

      /**
       * Synonym for {@link #pattern(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder p(String value) {
         return pattern(value);
      }

      /**
       * Shortcut for <c>property(key, value)</c>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param key
       * The property name.
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder p(String key, Builder value) {
         return property(key, value);
      }

      /**
       * Shortcut for <c>property(key, value)</c>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param key
       * The property name.
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder p(String key, HttpPartSchema value) {
         return property(key, value);
      }

      /**
       * Identifies the part parser to use for parsing this part.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or has the simple name "Void".
       * @return This object.
       */
      public Builder parser(Class<?> value) {
         if (isNotVoid(value))
            parser = value;
         return this;
      }

      /**
       * <mk>pattern</mk> field.
       *
       * <p>
       * A string input is valid if it matches the specified regular expression pattern.
       *
       * <p>
       * Only allowed for the following types: <js>"string"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder pattern(String value) {
         try {
            if (ine(value))
               this.pattern = Pattern.compile(value);
         } catch (Exception e) {
            throw new BasicRuntimeException(e, "Invalid value %s passed in as pattern value.  Must be a valid regular expression.", value);
         }
         return this;
      }

      /**
       * <mk>properties</mk> field.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param key
       * The property name.
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder property(String key, Builder value) {
         if (nn(key) && nn(value)) {
            if (properties == null)
               properties = map();
            properties.put(key, value);
         }
         return this;
      }

      /**
       * <mk>properties</mk> field.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param key
       * The property name.
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder property(String key, HttpPartSchema value) {
         if (nn(key) && nn(value)) {
            if (properties == null)
               properties = map();
            properties.put(key, value);
         }
         return this;
      }

      /**
       * Synonym for {@link #required()}.
       *
       * @return This object.
       */
      public Builder r() {
         return required();
      }

      /**
       * Synonym for {@link #required(Boolean)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder r(Boolean value) {
         return required(value);
      }

      /**
       * Synonym for {@link #required(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder r(String value) {
         return required(value);
      }

      /**
       * <mk>required</mk> field.
       *
       * <p>
       * Shortcut for calling <code>required(<jk>true</jk>);</code>.
       *
       * @return This object.
       */
      public Builder required() {
         return required(true);
      }

      /**
       * <mk>required</mk> field.
       *
       * <p>
       * Determines whether the parameter is mandatory.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder required(Boolean value) {
         required = resolve(value, required);
         return this;
      }

      /**
       * <mk>required</mk> field.
       *
       * <p>
       * Determines whether the parameter is mandatory.
       *
       * <p>
       * Same as {@link #required(Boolean)} but takes in a boolean value as a string.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder required(String value) {
         required = resolve(value, required);
         return this;
      }

      /**
       * Identifies the part serializer to use for serializing this part.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or has the simple name "Void".
       * @return This object.
       */
      public Builder serializer(Class<?> value) {
         if (isNotVoid(value))
            serializer = value;
         return this;
      }

      /**
       * Synonym for {@link #skipIfEmpty()}.
       *
       * @return This object.
       */
      public Builder sie() {
         return skipIfEmpty();
      }

      /**
       * Synonym for {@link #skipIfEmpty(Boolean)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder sie(Boolean value) {
         return skipIfEmpty(value);
      }

      /**
       * Synonym for {@link #skipIfEmpty(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder sie(String value) {
         return skipIfEmpty(value);
      }

      /**
       * Identifies whether an item should be skipped if it's empty.
       *
       * <p>
       * Shortcut for calling <code>skipIfEmpty(<jk>true</jk>);</code>.
       *
       * @return This object.
       */
      public Builder skipIfEmpty() {
         return skipIfEmpty(true);
      }

      /**
       * <mk>skipIfEmpty</mk> field.
       *
       * <p>
       * Identifies whether an item should be skipped during serialization if it's empty.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder skipIfEmpty(Boolean value) {
         skipIfEmpty = resolve(value, skipIfEmpty);
         return this;
      }

      /**
       * <mk>skipIfEmpty</mk> field.
       *
       * <p>
       * Same as {@link #skipIfEmpty(Boolean)} but takes in a string boolean.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder skipIfEmpty(String value) {
         skipIfEmpty = resolve(value, skipIfEmpty);
         return this;
      }

      /**
       * Synonym for {@link #type(HttpPartDataType)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder t(HttpPartDataType value) {
         return type(value);
      }

      /**
       * Synonym for {@link #type(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder t(String value) {
         return type(value);
      }

      /**
       * Shortcut for <c>type(HttpPartDataType.ARRAY)</c>.
       *
       * @return This object.
       */
      public Builder tArray() {
         type = HttpPartDataType.ARRAY;
         return this;
      }

      /**
       * Shortcut for <c>type(HttpPartDataType.BOOLEAN)</c>.
       *
       * @return This object.
       */
      public Builder tBoolean() {
         type = HttpPartDataType.BOOLEAN;
         return this;
      }

      /**
       * Shortcut for <c>type(HttpPartDataType.FILE)</c>.
       *
       * @return This object.
       */
      public Builder tFile() {
         type = HttpPartDataType.FILE;
         return this;
      }

      /**
       * Shortcut for <c>type(HttpPartDataType.INTEGER)</c>.
       *
       * @return This object.
       */
      public Builder tInteger() {
         type = HttpPartDataType.INTEGER;
         return this;
      }

      /**
       * Shortcut for <c>type(HttpPartDataType.NO_TYPE)</c>.
       *
       * @return This object.
       */
      public Builder tNone() {
         type = HttpPartDataType.NO_TYPE;
         return this;
      }

      /**
       * Shortcut for <c>type(HttpPartDataType.NUMBER)</c>.
       *
       * @return This object.
       */
      public Builder tNumber() {
         type = HttpPartDataType.NUMBER;
         return this;
      }

      /**
       * Shortcut for <c>type(HttpPartDataType.OBJECT)</c>.
       *
       * @return This object.
       */
      public Builder tObject() {
         type = HttpPartDataType.OBJECT;
         return this;
      }

      /**
       * Shortcut for <c>type(HttpPartDataType.STRING)</c>.
       *
       * @return This object.
       */
      public Builder tString() {
         type = HttpPartDataType.STRING;
         return this;
      }

      /**
       * <mk>type</mk> field.
       *
       * <p>
       * The type of the parameter.
       *
       * <p>
       * If the type is not specified, it will be auto-detected based on the parameter class type.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#securitySchemeObject">SecurityScheme</a>
       * </ul>
       *
       * <ul class='values javatree'>
       *    <li class='jc'>{@link HttpPartDataType}
       *    <ul>
       *       <li class='jf'>
       *          {@link HttpPartDataType#STRING STRING}
       *          <br>Parameter must be a string or a POJO convertible from a string.
       *          <li>
       *          {@link HttpPartDataType#NUMBER NUMBER}
       *          <br>Parameter must be a number primitive or number object.
       *          <br>If parameter is <c>Object</c>, creates either a <c>Float</c> or <c>Double</c> depending on the size of the number.
       *       <li class='jf'>
       *          {@link HttpPartDataType#INTEGER INTEGER}
       *          <br>Parameter must be a integer/long primitive or integer/long object.
       *          <br>If parameter is <c>Object</c>, creates either a <c>Short</c>, <c>Integer</c>, or <c>Long</c> depending on the size of the number.
       *       <li class='jf'>
       *          {@link HttpPartDataType#BOOLEAN BOOLEAN}
       *          <br>Parameter must be a boolean primitive or object.
       *       <li class='jf'>
       *          {@link HttpPartDataType#ARRAY ARRAY}
       *          <br>Parameter must be an array or collection.
       *          <br>Elements must be strings or POJOs convertible from strings.
       *          <br>If parameter is <c>Object</c>, creates an {@link JsonList}.
       *       <li class='jf'>
       *          {@link HttpPartDataType#OBJECT OBJECT}
       *          <br>Parameter must be a map or bean.
       *          <br>If parameter is <c>Object</c>, creates a map.
       *          <br>Note that this is an extension of the OpenAPI schema as Juneau allows for arbitrarily-complex POJOs to be serialized as HTTP parts.
       *       <li class='jf'>
       *          {@link HttpPartDataType#FILE FILE}
       *          <br>This type is currently not supported.
       *    </ul>
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification#dataTypes">Swagger Data Types</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder type(HttpPartDataType value) {
         // Guard null for parity with the String overload (which ine()-guards); a null must not overwrite the field.
         if (value != null)
            type = value;
         return this;
      }

      /**
       * <mk>type</mk> field.
       *
       * <p>
       * The type of the parameter.
       *
       * <p>
       * If the type is not specified, it will be auto-detected based on the parameter class type.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#securitySchemeObject">SecurityScheme</a>
       * </ul>
       *
       * <ul class='values'>
       *    <li>
       *       <js>"string"</js>
       *       <br>Parameter must be a string or a POJO convertible from a string.
       *    <li>
       *       <js>"number"</js>
       *       <br>Parameter must be a number primitive or number object.
       *       <br>If parameter is <c>Object</c>, creates either a <c>Float</c> or <c>Double</c> depending on the size of the number.
       *    <li>
       *       <js>"integer"</js>
       *       <br>Parameter must be a integer/long primitive or integer/long object.
       *       <br>If parameter is <c>Object</c>, creates either a <c>Short</c>, <c>Integer</c>, or <c>Long</c> depending on the size of the number.
       *    <li>
       *       <js>"boolean"</js>
       *       <br>Parameter must be a boolean primitive or object.
       *    <li>
       *       <js>"array"</js>
       *       <br>Parameter must be an array or collection.
       *       <br>Elements must be strings or POJOs convertible from strings.
       *       <br>If parameter is <c>Object</c>, creates an {@link JsonList}.
       *    <li>
       *       <js>"object"</js>
       *       <br>Parameter must be a map or bean.
       *       <br>If parameter is <c>Object</c>, creates a map.
       *       <br>Note that this is an extension of the OpenAPI schema as Juneau allows for arbitrarily-complex POJOs to be serialized as HTTP parts.
       *    <li>
       *       <js>"file"</js>
       *       <br>This type is currently not supported.
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification#dataTypes">Swagger Data Types</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty.
       * @return This object.
       */
      public Builder type(String value) {
         try {
            if (ine(value))
               type = HttpPartDataType.fromString(value);
         } catch (Exception e) {
            throw new BasicRuntimeException(e, "Invalid value '%s' passed in as type value.  Valid values: %s", value, HttpPartDataType.values());
         }
         return this;
      }

      /**
       * Synonym for {@link #uniqueItems()}.
       *
       * @return This object.
       */
      public Builder ui() {
         return uniqueItems();
      }

      /**
       * Synonym for {@link #uniqueItems(Boolean)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder ui(Boolean value) {
         return uniqueItems(value);
      }

      /**
       * Synonym for {@link #uniqueItems(String)}.
       *
       * @param value
       *    The new value for this property.
       * @return This object.
       */
      public Builder ui(String value) {
         return uniqueItems(value);
      }

      /**
       * <mk>uniqueItems</mk> field.
       *
       * <p>
       * Shortcut for calling <code>uniqueItems(<jk>true</jk>);</code>.
       *
       * @return This object.
       */
      public Builder uniqueItems() {
         return uniqueItems(true);
      }

      /**
       * <mk>uniqueItems</mk> field.
       *
       * <p>
       * If <jk>true</jk>, the input validates successfully if all of its elements are unique.
       *
       * <p>
       * <br>If the parameter type is a subclass of {@link Set}, this validation is skipped (since a set can only contain unique items anyway).
       * <br>Otherwise, the collection or array is checked for duplicate items.
       *
       * <p>
       * Only allowed for the following types: <js>"array"</js>.
       *
       * <p>
       * Applicable to the following Swagger schema objects:
       * <ul>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#parameterObject">Parameter</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Schema</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Items</a>
       *    <li><a class="doclink" href="https://swagger.io/specification/v2#headerObject">Header</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk>.
       * @return This object.
       */
      public Builder uniqueItems(Boolean value) {
         uniqueItems = resolve(value, uniqueItems);
         return this;
      }

      /**
       * <mk>uniqueItems</mk> field.
       *
       * <p>
       * Same as {@link #uniqueItems(Boolean)} but takes in a string boolean.
       *
       * @param value
       *    The new value for this property.
       *    <br>Ignored if value is <jk>null</jk> or empty..
       * @return This object.
       */
      public Builder uniqueItems(String value) {
         uniqueItems = resolve(value, uniqueItems);
         return this;
      }

      private static Long firstNmo(Long...l) {
         for (var ll : l)
            if (nn(ll) && ll != -1)
               return ll;
         return null;
      }

      /**
       * Helper method to safely get annotation attribute values via reflection.
       *
       * <p>
       * This allows reading Jakarta Validation annotations without requiring them on the classpath.
       *
       * @param <T> The expected return type.
       * @param a The annotation to read from.
       * @param attributeName The attribute name to read.
       * @param type The expected type of the attribute value.
       * @return The attribute value, or <jk>null</jk> if not found or not of the expected type.
       */
      private static <T> T getAnnotationValue(Annotation a, String attributeName, Class<T> type) {
         try {
            Method m = a.annotationType().getDeclaredMethod(attributeName);
            Object value = m.invoke(a);
            return type.isInstance(value) ? type.cast(value) : null;
         } catch (@SuppressWarnings("unused") Exception e) {
            return null;
         }
      }

      private static String joinnlOrNull(String[]...s) {
         for (var ss : s)
            if (ss.length > 0)
               return StringUtils.joinnl(ss);
         return null;
      }

      private static Boolean resolve(Boolean newValue, Boolean oldValue) {
         return newValue == null ? oldValue : newValue;
      }

      private static Long resolve(Long newValue, Long oldValue) {
         return (newValue == null || newValue == -1) ? oldValue : newValue;
      }

      private static Boolean resolve(String newValue, Boolean oldValue) {
         return isEmpty(newValue) ? oldValue : b(newValue);
      }

      private static Long resolve(String newValue, Long oldValue) {
         return isEmpty(newValue) ? oldValue : Long.parseLong(newValue);
      }

      private static Number toNumber(String...s) {
         return HttpPartSchema.toNumber(s);
      }

      private static Set<String> toSet(String[]...s) {
         return HttpPartSchema.toSet(s);
      }

      Builder apply(Class<? extends Annotation> c, Type t) {
         if (t instanceof Class<?> c2) {
            rstream(AP.find(c, info(c2))).forEach(x -> apply(x.inner()));
         } else if (Holder.isType(t)) {
            apply(c, Holder.getParameterType(t));
         }
         return this;
      }

      Builder apply(Class<? extends Annotation> c, Method m) {
         apply(c, m.getGenericReturnType());
         Annotation a = m.getAnnotation(c);
         if (nn(a))
            return apply(a);
         return this;
      }

      Builder apply(Class<? extends Annotation> c, ParameterInfo mpi) {
         apply(c, mpi.getParameterType().innerType());
         mpi.getAnnotations(c).forEach(x -> apply(x.inner()));
         return this;
      }

      Builder apply(HttpPartMarshalling a) {
         parser(a.parser());
         serializer(a.serializer());
         return this;
      }

      private Builder applyHttpAnnotation(Annotation a) {
         var annotationName = a.annotationType().getSimpleName();

         var schema = getAnnotationValue(a, "schema", Schema.class);
         if (schema != null && (eq(annotationName, "Response") || !SchemaAnnotation.empty(schema)))
            apply(schema);

         var aName = getAnnotationString(a, "name");
         var aValue = getAnnotationString(a, "value");

         switch (annotationName) {
            case "PathRemainder" -> {
               name("/*");
               default_(getAnnotationString(a, "def"));
               allowEmptyValue();
               required(false);
            }
            case "Path" -> {
               name(firstNonEmpty(aName, aValue));
               var def = getAnnotationString(a, "def");
               if (def != null && neq(NONE, def))
                  default_ = def;
               if (startsWith(name, '/')) {
                  allowEmptyValue();
                  required(false);
               } else if (required == null) {
                  required(def == null || eq(NONE, def));
               }
            }
            case "Response" -> {
               allowEmptyValue(true);
               required(false);
            }
            case "StatusCode" -> codes(getAnnotationIntArray(a, "value"));
            default -> {
               name(firstNonEmpty(aName, aValue));
               default_(getAnnotationString(a, "def"));
            }
         }
         return this;
      }

      private static String getAnnotationString(Annotation a, String methodName) {
         try {
            var m = a.annotationType().getMethod(methodName);
            if (m.getReturnType() == String.class)
               return (String) m.invoke(a);
         } catch (@SuppressWarnings("unused") NoSuchMethodException e) {
            // Attribute doesn't exist on this annotation -- ignore
         } catch (Exception e) {
            throw rex(e);
         }
         return null;
      }

      private static int[] getAnnotationIntArray(Annotation a, String methodName) {
         try {
            var m = a.annotationType().getMethod(methodName);
            if (m.getReturnType() == int[].class) {
               var arr = (int[]) m.invoke(a);
               return arr == null ? new int[0] : arr;
            }
         } catch (@SuppressWarnings("unused") NoSuchMethodException e) {
            // Attribute doesn't exist on this annotation -- ignore
         } catch (Exception e) {
            throw rex(e);
         }
         return new int[0];
      }

      Builder apply(Items a) {
         default_(joinnlOrNull(a.default_(), a.df()));
         enum_(toSet(a.enum_(), a.e()));
         collectionFormat(firstNonEmpty(a.collectionFormat(), a.cf()));
         exclusiveMaximum(a.exclusiveMaximum() || a.emax());
         exclusiveMinimum(a.exclusiveMinimum() || a.emin());
         format(firstNonEmpty(a.format(), a.f()));
         items(a.items());
         maximum(toNumber(a.maximum(), a.max()));
         maxItems(firstNmo(a.maxItems(), a.maxi()));
         maxLength(firstNmo(a.maxLength(), a.maxl()));
         minimum(toNumber(a.minimum(), a.min()));
         minItems(firstNmo(a.minItems(), a.mini()));
         minLength(firstNmo(a.minLength(), a.minl()));
         multipleOf(toNumber(a.multipleOf(), a.mo()));
         pattern(firstNonEmpty(a.pattern(), a.p()));
         type(firstNonEmpty(a.type(), a.t()));
         uniqueItems(a.uniqueItems() || a.ui());
         return this;
      }

      // -----------------------------------------------------------------------------------------------------------------
      // JSON Schema Draft 2020-12 property setters
      // -----------------------------------------------------------------------------------------------------------------

      // -----------------------------------------------------------------------------------------------------------------
      // Other
      // -----------------------------------------------------------------------------------------------------------------

      Builder apply(Schema a) {
         default_(joinnlOrNull(a.default_(), a.df()));
         enum_(toSet(a.enum_(), a.e()));
         allowEmptyValue(a.allowEmptyValue() || a.aev());
         collectionFormat(firstNonEmpty(a.collectionFormat(), a.cf()));

         // Handle exclusiveMaximum with fallback from Draft 2020-12 to Draft 04
         String exMaxVal = a.exclusiveMaximumValue();
         if (ine(exMaxVal)) {
            exclusiveMaximumValue(toNumber(exMaxVal));
         } else if (a.emax()) {
            exclusiveMaximum(true);
         }

         // Handle exclusiveMinimum with fallback from Draft 2020-12 to Draft 04
         String exMinVal = a.exclusiveMinimumValue();
         if (ine(exMinVal)) {
            exclusiveMinimumValue(toNumber(exMinVal));
         } else if (a.emin()) {
            exclusiveMinimum(true);
         }

         format(firstNonEmpty(a.format(), a.f()));
         items(a.items());
         maximum(toNumber(a.maximum(), a.max()));
         maxItems(firstNmo(a.maxItems(), a.maxi()));
         maxLength(firstNmo(a.maxLength(), a.maxl()));
         maxProperties(firstNmo(a.maxProperties(), a.maxp()));
         minimum(toNumber(a.minimum(), a.min()));
         minItems(firstNmo(a.minItems(), a.mini()));
         minLength(firstNmo(a.minLength(), a.minl()));
         minProperties(firstNmo(a.minProperties(), a.minp()));
         multipleOf(toNumber(a.multipleOf(), a.mo()));
         pattern(firstNonEmpty(a.pattern(), a.p()));
         required(a.required() || a.r());
         skipIfEmpty(a.skipIfEmpty() || a.sie());
         type(firstNonEmpty(a.type(), a.t()));
         uniqueItems(a.uniqueItems() || a.ui());

         // JSON Schema Draft 2020-12 properties
         const_(joinnlOrNull(a.const_()));
         examples(a.examples());
         deprecated(a.deprecated_());

         return this;
      }

      Builder apply(SubItems a) {
         default_(joinnlOrNull(a.default_(), a.df()));
         enum_(toSet(a.enum_(), a.e()));
         collectionFormat(firstNonEmpty(a.collectionFormat(), a.cf()));
         exclusiveMaximum(a.exclusiveMaximum() || a.emax());
         exclusiveMinimum(a.exclusiveMinimum() || a.emin());
         format(firstNonEmpty(a.format(), a.f()));
         maximum(toNumber(a.maximum(), a.max()));
         maxItems(firstNmo(a.maxItems(), a.maxi()));
         maxLength(firstNmo(a.maxLength(), a.maxl()));
         minimum(toNumber(a.minimum(), a.min()));
         minItems(firstNmo(a.minItems(), a.mini()));
         minLength(firstNmo(a.minLength(), a.minl()));
         multipleOf(toNumber(a.multipleOf(), a.mo()));
         pattern(firstNonEmpty(a.pattern(), a.p()));
         type(firstNonEmpty(a.type(), a.t()));
         uniqueItems(a.uniqueItems() || a.ui());
         return this;
      }

      public Builder applyAll(Class<? extends Annotation> c, Type t) {
         return apply(Schema.class, t).apply(c, t);
      }

      public Builder applyAll(Class<? extends Annotation> c, Method m) {
         return apply(Schema.class, m).apply(c, m);
      }

      public Builder applyAll(Class<? extends Annotation> c, ParameterInfo mpi) {
         return apply(Schema.class, mpi).apply(c, mpi);
      }

      /**
       * Apply Jakarta Bean Validation constraints to this schema.
       *
       * <p>
       * This method uses pure reflection to read constraint annotations, so no jakarta.validation-api
       * dependency is required. The constraints are mapped to OpenAPI schema properties where applicable.
       *
       * <p>
       * Supported constraints:
       * <ul>
       *    <li><c>@NotNull</c> → <c>required(true)</c>
       *    <li><c>@Size</c> → <c>minLength/maxLength</c> or <c>minItems/maxItems</c>
       *    <li><c>@Min</c> → <c>minimum</c>
       *    <li><c>@Max</c> → <c>maximum</c>
       *    <li><c>@DecimalMin</c> → <c>minimum + exclusiveMinimum</c>
       *    <li><c>@DecimalMax</c> → <c>maximum + exclusiveMaximum</c>
       *    <li><c>@Pattern</c> → <c>pattern</c>
       *    <li><c>@Email</c> → <c>format("email")</c>
       *    <li><c>@Positive</c> → <c>minimum(0) + exclusiveMinimum(true)</c>
       *    <li><c>@PositiveOrZero</c> → <c>minimum(0)</c>
       *    <li><c>@Negative</c> → <c>maximum(0) + exclusiveMaximum(true)</c>
       *    <li><c>@NegativeOrZero</c> → <c>maximum(0)</c>
       *    <li><c>@NotEmpty</c> → <c>required(true) + minLength(1)/minItems(1)</c>
       *    <li><c>@NotBlank</c> → <c>required(true) + minLength(1) + pattern</c>
       * </ul>
       *
       * @param a The Jakarta Validation constraint annotation.
       * @return This object.
       * @since 9.2.0
       */
      Builder applyJakartaValidation(Annotation a) {
         String simpleName = cns(a.annotationType());

         try {
            switch (simpleName) {
               case "NotNull":
                  required(true);
                  break;
               case "Size":
                  Integer min = getAnnotationValue(a, "min", Integer.class);
                  Integer max = getAnnotationValue(a, "max", Integer.class);
                  if (nn(min) && min > 0) {
                     minLength(min.longValue());
                     minItems(min.longValue());
                  }
                  if (nn(max) && max < Integer.MAX_VALUE) {
                     maxLength(max.longValue());
                     maxItems(max.longValue());
                  }
                  break;
               case "Min":
                  Long minValue = getAnnotationValue(a, "value", Long.class);
                  if (nn(minValue))
                     minimum(minValue);
                  break;
               case "Max":
                  Long maxValue = getAnnotationValue(a, "value", Long.class);
                  if (nn(maxValue))
                     maximum(maxValue);
                  break;
               case "Pattern":
                  String regexp = getAnnotationValue(a, "regexp", String.class);
                  if (nn(regexp))
                     pattern(regexp);
                  break;
               case "Email":
                  format("email");
                  break;
               case "Positive":
                  minimum(0);
                  exclusiveMinimum(true);
                  break;
               case "PositiveOrZero":
                  minimum(0);
                  break;
               case "Negative":
                  maximum(0);
                  exclusiveMaximum(true);
                  break;
               case "NegativeOrZero":
                  maximum(0);
                  break;
               case "NotEmpty":
                  required(true);
                  minLength(1L);
                  minItems(1L);
                  break;
               case "NotBlank":
                  required(true);
                  minLength(1L);
                  pattern(".*\\S.*"); // Contains at least one non-whitespace character
                  break;
               case "DecimalMin":
                  String minVal = getAnnotationValue(a, "value", String.class);
                  Boolean minInclusive = getAnnotationValue(a, "inclusive", Boolean.class);
                  if (nn(minVal)) {
                     minimum(toNumber(minVal));
                     if (isFalse(minInclusive))
                        exclusiveMinimum(true);
                  }
                  break;
               case "DecimalMax":
                  String maxVal = getAnnotationValue(a, "value", String.class);
                  Boolean maxInclusive = getAnnotationValue(a, "inclusive", Boolean.class);
                  if (nn(maxVal)) {
                     maximum(toNumber(maxVal));
                     if (isFalse(maxInclusive))
                        exclusiveMaximum(true);
                  }
                  break;
               default:
                  // Silently ignore other validation annotations we don't support yet
            }
         } catch (@SuppressWarnings("unused") Exception e) {
            // If reflection fails, just skip this annotation - it's optional
         }
         return this;
      }

      Builder items(Items value) {
         if (! ItemsAnnotation.empty(value))
            items = HttpPartSchema.create().apply(value);
         return this;
      }

      Builder items(SubItems value) {
         if (! SubItemsAnnotation.empty(value))
            items = HttpPartSchema.create().apply(value);
         return this;
      }
   }

   /** Reusable instance of this object, all default settings. */
   public static final HttpPartSchema DEFAULT = HttpPartSchema.create().allowEmptyValue(true).build();

   /** Boolean type */
   public static final HttpPartSchema T_BOOLEAN = HttpPartSchema.tBoolean().build();

   /** File type */
   public static final HttpPartSchema T_FILE = HttpPartSchema.tFile().build();

   /** Integer type */
   public static final HttpPartSchema T_INTEGER = HttpPartSchema.tInteger().build();

   /** Int32 type */
   public static final HttpPartSchema T_INT32 = HttpPartSchema.tInt32().build();

   /** Int64 type */
   public static final HttpPartSchema T_INT64 = HttpPartSchema.tInt64().build();

   /** No type */
   public static final HttpPartSchema T_NONE = HttpPartSchema.tNone().build();

   /** Number type */
   public static final HttpPartSchema T_NUMBER = HttpPartSchema.tNumber().build();

   /** Float type */
   public static final HttpPartSchema T_FLOAT = HttpPartSchema.tFloat().build();

   /** Double type */
   public static final HttpPartSchema T_DOUBLE = HttpPartSchema.tDouble().build();

   /** String type */
   public static final HttpPartSchema T_STRING = HttpPartSchema.tString().build();

   /** Byte type */
   public static final HttpPartSchema T_BYTE = HttpPartSchema.tByte().build();

   /** Binary type */
   public static final HttpPartSchema T_BINARY = HttpPartSchema.tBinary().build();

   /** Spaced binary type */
   public static final HttpPartSchema T_BINARY_SPACED = HttpPartSchema.tBinarySpaced().build();

   /** Date type */
   public static final HttpPartSchema T_DATE = HttpPartSchema.tDate().build();

   /** Date-time type */
   public static final HttpPartSchema T_DATETIME = HttpPartSchema.tDateTime().build();

   /** UON-formated simple type */
   public static final HttpPartSchema T_UON = HttpPartSchema.tUon().build();

   /** Array type */
   public static final HttpPartSchema T_ARRAY = HttpPartSchema.tArray().build();

   /** Comma-delimited array type */
   public static final HttpPartSchema T_ARRAY_CSV = HttpPartSchema.tArrayCsv().build();

   /** Pipe-delimited array type */
   public static final HttpPartSchema T_ARRAY_PIPES = HttpPartSchema.tArrayPipes().build();

   /** Space-delimited array type */
   public static final HttpPartSchema T_ARRAY_SSV = HttpPartSchema.tArraySsv().build();

   /** Tab-delimited array type */
   public static final HttpPartSchema T_ARRAY_TSV = HttpPartSchema.tArrayTsv().build();

   /** UON-formatted array type */
   public static final HttpPartSchema T_ARRAY_UON = HttpPartSchema.tArrayUon().build();

   /** Multi-part array type */
   public static final HttpPartSchema T_ARRAY_MULTI = HttpPartSchema.tArrayMulti().build();

   /** Object type */
   public static final HttpPartSchema T_OBJECT = HttpPartSchema.tObject().build();

   /** UON-formated object type */
   public static final HttpPartSchema T_OBJECT_UON = HttpPartSchema.tObjectUon().build();

   /**
    * Instantiates a new builder for this object.
    *
    * @return A new builder for this object.
    */
   public static Builder create() {
      return new Builder();
   }

   /**
    * Finds the schema information on the specified annotation.
    *
    * @param a
    *    The annotation to find the schema information on..
    *    <br>Must not be <jk>null</jk>.
    * @return The schema information found on the annotation.  Never <jk>null</jk>.
    */
   public static HttpPartSchema create(Annotation a) {
      return create().apply(a).build();
   }

   /**
    * Finds the schema information on the specified annotation.
    *
    * @param a
    *    The annotation to find the schema information on..
    *    <br>Must not be <jk>null</jk>.
    * @param defaultName The default part name if not specified on the annotation.  Can be <jk>null</jk> (the name from the annotation, if any, is left unchanged).
    * @return The schema information found on the annotation.  Never <jk>null</jk>.
    */
   public static HttpPartSchema create(Annotation a, String defaultName) {
      return create().name(defaultName).apply(a).build();
   }

   /**
    * Finds the schema information for the specified class.
    *
    * <p>
    * This method will gather all the schema information from the annotations on the class and all parent classes/interfaces.
    *
    * @param c
    *    The annotation to look for.
    *    <br>Valid values:
    *    <ul>
    *       <li><ja>@Content</ja>
    *       <li><ja>@Header</ja>
    *       <li><ja>@Query</ja>
    *       <li><ja>@FormData</ja>
    *       <li><ja>@Path</ja>
    *       <li><ja>@Response</ja>
    *       <li><ja>@HasQuery</ja>
    *       <li><ja>@HasFormData</ja>
    *    </ul>
    * @param t
    *    The class containing the parameter.
    *    <br>Can be <jk>null</jk> (no type-level annotations are applied).
    * @return The schema information about the parameter.  Never <jk>null</jk>.
    */
   public static HttpPartSchema create(Class<? extends Annotation> c, Type t) {
      return create().applyAll(c, t).build();
   }

   /**
    * Finds the schema information for the specified method return.
    *
    * <p>
    * This method will gather all the schema information from the annotations at the following locations:
    * <ul>
    *    <li>The method.
    *    <li>The method return class.
    *    <li>The method return parent classes and interfaces.
    * </ul>
    *
    * @param c
    *    The annotation to look for.
    *    <br>Valid values:
    *    <ul>
    *       <li><ja>@Content</ja>
    *       <li><ja>@Header</ja>
    *       <li><ja>@Query</ja>
    *       <li><ja>@FormData</ja>
    *       <li><ja>@Path</ja>
    *       <li><ja>@Response</ja>
    *       <li><ja>@HasQuery</ja>
    *       <li><ja>@HasFormData</ja>
    *    </ul>
    * @param m
    *    The Java method with the return type being checked.
    *    <br>Must not be <jk>null</jk>.
    * @return The schema information about the parameter.  Never <jk>null</jk>.
    */
   public static HttpPartSchema create(Class<? extends Annotation> c, Method m) {
      return create().applyAll(c, m).build();
   }

   /**
    * Finds the schema information for the specified method parameter.
    *
    * <p>
    * This method will gather all the schema information from the annotations at the following locations:
    * <ul>
    *    <li>The method parameter.
    *    <li>The method parameter class.
    *    <li>The method parameter parent classes and interfaces.
    * </ul>
    *
    * @param c
    *    The annotation to look for.
    *    <br>Valid values:
    *    <ul>
    *       <li><ja>@Content</ja>
    *       <li><ja>@Header</ja>
    *       <li><ja>@Query</ja>
    *       <li><ja>@FormData</ja>
    *       <li><ja>@Path</ja>
    *       <li><ja>@Response</ja>
    *       <li><ja>@HasQuery</ja>
    *       <li><ja>@HasFormData</ja>
    *    </ul>
    * @param mpi The Java method parameter.  Must not be <jk>null</jk>.
    * @return The schema information about the parameter.  Never <jk>null</jk>.
    */
   public static HttpPartSchema create(Class<? extends Annotation> c, ParameterInfo mpi) {
      return create().applyAll(c, mpi).build();
   }

   /**
    * Shortcut for calling <c>create().type(type);</c>
    *
    * @param type The schema type value.
    * @return A new builder.
    */
   public static Builder create(String type) {
      return create().type(type);
   }

   /**
    * Shortcut for calling <c>create().type(type).format(format);</c>
    *
    * @param type The schema type value.
    * @param format The schema format value.
    * @return A new builder.
    */
   public static Builder create(String type, String format) {
      return create().type(type).format(format);
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tArray() {
      return create().tArray();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).items(items)</c>.
    *
    * @param items The schema of the array items.
    * @return A new builder for this object.
    */
   public static Builder tArray(Builder items) {
      return create().tArray().items(items);
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>CSV</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tArrayCsv() {
      return create().tArray().cfCsv();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>CSV</jsf>).items(items)</c>.
    *
    * @param items The schema of the array items.
    * @return A new builder for this object.
    */
   public static Builder tArrayCsv(Builder items) {
      return create().tArray().cfCsv().items(items);
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>MULTI</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tArrayMulti() {
      return create().tArray().cfMulti();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>MULTI</jsf>).items(items)</c>.
    *
    * @param items The schema of the array items.
    * @return A new builder for this object.
    */
   public static Builder tArrayMulti(Builder items) {
      return create().tArray().cfMulti().items(items);
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>PIPES</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tArrayPipes() {
      return create().tArray().cfPipes();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>PIPES</jsf>).items(items)</c>.
    *
    * @param items The schema of the array items.
    * @return A new builder for this object.
    */
   public static Builder tArrayPipes(Builder items) {
      return create().tArray().cfPipes().items(items);
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>SSV</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tArraySsv() {
      return create().tArray().cfSsv();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>SSV</jsf>).items(items)</c>.
    *
    * @param items The schema of the array items.
    * @return A new builder for this object.
    */
   public static Builder tArraySsv(Builder items) {
      return create().tArray().cfSsv().items(items);
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>TSV</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tArrayTsv() {
      return create().tArray().cfTsv();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>TSV</jsf>).items(items)</c>.
    *
    * @param items The schema of the array items.
    * @return A new builder for this object.
    */
   public static Builder tArrayTsv(Builder items) {
      return create().tArray().cfTsv().items(items);
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>UONC</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tArrayUon() {
      return create().tArray().cfUon();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>ARRAY</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>UONC</jsf>).items(items)</c>.
    *
    * @param items The schema of the array items.
    * @return A new builder for this object.
    */
   public static Builder tArrayUon(Builder items) {
      return create().tArray().cfUon().items(items);
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>STRING</jsf>).format(HttpPartFormat.<jsf>BINARY</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tBinary() {
      return create().tString().fBinary();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>STRING</jsf>).format(HttpPartFormat.<jsf>BINARY_SPACED</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tBinarySpaced() {
      return create().tString().fBinarySpaced();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>BOOLEAN</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tBoolean() {
      return create().tBoolean();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>STRING</jsf>).format(HttpPartFormat.<jsf>BYTE</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tByte() {
      return create().tString().fByte();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>STRING</jsf>).format(HttpPartFormat.<jsf>DATE</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tDate() {
      return create().tString().fDate();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>STRING</jsf>).format(HttpPartFormat.<jsf>DATE_TIME</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tDateTime() {
      return create().tString().fDateTime();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>NUMBER</jsf>).format(HttpPartFormat.<jsf>DOUBLE</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tDouble() {
      return create().tNumber().fDouble();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>FILE</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tFile() {
      return create().tFile();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>NUMBER</jsf>).format(HttpPartFormat.<jsf>FLOAT</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tFloat() {
      return create().tNumber().fFloat();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>INTEGER</jsf>).format(HttpPartFormat.<jsf>INT32</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tInt32() {
      return create().tInteger().fInt32();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>INTEGER</jsf>).format(HttpPartFormat.<jsf>INT64</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tInt64() {
      return create().tInteger().fInt64();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>INTEGER</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tInteger() {
      return create().tInteger();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>NONE</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tNone() {
      return create().tNone();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>NUMBER</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tNumber() {
      return create().tNumber();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>OBJECT</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tObject() {
      return create().tObject();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>OBJECT</jsf>).collectionFormat(HttpPartCollectionFormat.<jsf>UON</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tObjectUon() {
      return create().tObject().cfUon();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>STRING</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tString() {
      return create().tString();
   }

   /**
    * Shortcut for <c><jsm>create</jsm>().type(HttpPartDataType.<jsf>STRING</jsf>).format(HttpPartFormat.<jsf>UON</jsf>)</c>.
    *
    * @return A new builder for this object.
    */
   public static Builder tUon() {
      return create().tString().fUon();
   }

   private static Map<String,HttpPartSchema> build(Map<String,Object> in, boolean noValidate) {
      if (in == null)
         return null;
      Map<String,HttpPartSchema> m = map();
      in.forEach((k, v) -> m.put(k, build(v, noValidate)));
      return u(m);
   }

   private static HttpPartSchema build(Object in, boolean noValidate) {
      if (in == null)
         return null;
      if (in instanceof HttpPartSchema in2)
         return in2;
      return ((Builder)in).noValidate(noValidate).build();
   }

   private static <T> Set<T> copy(Set<T> in) {
      return in == null ? emptySet() : u(cp(in));
   }

   static final Number toNumber(String...s) {
      try {
         for (var ss : s)
            if (ine(ss))
               return parseNumber(ss, Number.class);
         return null;
      } catch (ParseException e) {
         throw toRex(e);
      }
   }

   static final Set<String> toSet(String s) {
      if (isEmpty(s))
         return null;
      Set<String> set = set();
      StringUtils.split(s, set::add);
      return set;
   }

   static final Set<String> toSet(String[]...s) {
      var isNotEmpty = false;
      for (var ss : s)
         isNotEmpty |= ss.length > 0;
      if (! isNotEmpty)
         return null;
      Set<String> set = set();
      for (var ss : s)
         if (nn(ss))
            for (var ss2 : ss)
               StringUtils.split(ss2, set::add);
      return set.isEmpty() ? null : set;
   }

   final String name;
   final String default_;
   final Set<String> enum_;
   final Map<String,HttpPartSchema> properties;
   final boolean allowEmptyValue;
   final boolean exclusiveMaximum;
   final boolean exclusiveMinimum;
   final boolean required;
   final boolean uniqueItems;
   final boolean skipIfEmpty;
   final HttpPartCollectionFormat collectionFormat;
   final HttpPartDataType type;
   final HttpPartFormat format;
   final Pattern pattern;
   final HttpPartSchema items;
   final HttpPartSchema additionalProperties;
   final Number maximum;
   final Number minimum;
   final Number multipleOf;
   final Long maxLength;
   final Long minLength;
   final Long maxItems;
   final Long minItems;
   final Long maxProperties;
   final Long minProperties;

   final Class<?> parser;

   final Class<?> serializer;

   final Class<?> parsedType;

   // JSON Schema Draft 2020-12 fields
   final String const_;

   final String[] examples;

   final boolean deprecated;

   final Number exclusiveMaximumValue;
   final Number exclusiveMinimumValue;

   HttpPartSchema(Builder b) {
      name = b.name;
      default_ = b.default_;
      enum_ = copy(b.enum_);
      properties = build(b.properties, b.noValidate);
      allowEmptyValue = resolve(b.allowEmptyValue);
      exclusiveMaximum = resolve(b.exclusiveMaximum);
      exclusiveMinimum = resolve(b.exclusiveMinimum);
      required = resolve(b.required);
      uniqueItems = resolve(b.uniqueItems);
      skipIfEmpty = resolve(b.skipIfEmpty);
      collectionFormat = b.collectionFormat;
      type = b.type;
      format = b.format;
      pattern = b.pattern;
      items = build(b.items, b.noValidate);
      additionalProperties = build(b.additionalProperties, b.noValidate);
      maximum = b.maximum;
      minimum = b.minimum;
      multipleOf = b.multipleOf;
      maxItems = b.maxItems;
      maxLength = b.maxLength;
      maxProperties = b.maxProperties;
      minItems = b.minItems;
      minLength = b.minLength;
      minProperties = b.minProperties;
      parser = b.parser;
      serializer = b.serializer;
      // JSON Schema Draft 2020-12 fields
      const_ = b.const_;
      examples = b.examples;
      deprecated = resolve(b.deprecated);
      exclusiveMaximumValue = b.exclusiveMaximumValue;
      exclusiveMinimumValue = b.exclusiveMinimumValue;

      // Calculate parse type
      Class<?> parsedType2 = Object.class;
      if (type == ARRAY) {
         if (nn(items) && nn(items.parsedType))
            parsedType2 = Array.newInstance(items.parsedType, 0).getClass();
      } else if (type == BOOLEAN) {
         parsedType2 = Boolean.class;
      } else if (type == INTEGER) {
         if (format == INT64)
            parsedType2 = Long.class;
         else
            parsedType2 = Integer.class;
      } else if (type == NUMBER) {
         if (format == DOUBLE)
            parsedType2 = Double.class;
         else
            parsedType2 = Float.class;
      } else if (type == STRING) {
         if (format == BYTE || format == BINARY || format == BINARY_SPACED)
            parsedType2 = byte[].class;
         else if (format == DATE || format == DATE_TIME)
            parsedType2 = Calendar.class;
         else
            parsedType2 = String.class;
      }
      this.parsedType = parsedType2;

      if (b.noValidate)
         return;

      // Validation.
      var errors = list();
      var notAllowed = lb(String.class);
      var invalidFormat = false;

      // @formatter:off
      switch (type) {
         case STRING: {
            notAllowed
               .addIf(nn(properties), "properties")
               .addIf(nn(additionalProperties), "additionalProperties")
               .addIf(exclusiveMaximum, "exclusiveMaximum")
               .addIf(exclusiveMinimum, "exclusiveMinimum")
               .addIf(uniqueItems, "uniqueItems")
               .addIf(collectionFormat != HttpPartCollectionFormat.NO_COLLECTION_FORMAT, "collectionFormat")
               .addIf(nn(items), "items")
               .addIf(nn(maximum), "maximum")
               .addIf(nn(minimum), "minimum")
               .addIf(nn(multipleOf), "multipleOf")
               .addIf(nn(maxItems), "maxItems")
               .addIf(nn(minItems), "minItems")
               .addIf(nn(minProperties), "minProperties");
            invalidFormat = ! format.isOneOf(HttpPartFormat.BYTE, HttpPartFormat.BINARY, HttpPartFormat.BINARY_SPACED, HttpPartFormat.DATE, HttpPartFormat.DATE_TIME, HttpPartFormat.PASSWORD, HttpPartFormat.UON, HttpPartFormat.NO_FORMAT);
            break;
         }
         case ARRAY: {
            notAllowed.addIf(nn(properties), "properties")
               .addIf(nn(additionalProperties), "additionalProperties")
               .addIf(exclusiveMaximum, "exclusiveMaximum")
               .addIf(exclusiveMinimum, "exclusiveMinimum")
               .addIf(nn(pattern), "pattern")
               .addIf(nn(maximum), "maximum")
               .addIf(nn(minimum), "minimum")
               .addIf(nn(multipleOf), "multipleOf")
               .addIf(nn(maxLength), "maxLength")
               .addIf(nn(minLength), "minLength")
               .addIf(nn(maxProperties), "maxProperties")
               .addIf(nn(minProperties), "minProperties");
            invalidFormat = ! format.isOneOf(HttpPartFormat.NO_FORMAT, HttpPartFormat.UON);
            break;
         }
         case BOOLEAN: {
            notAllowed.addIf(! enum_.isEmpty(), "enum")
               .addIf(nn(properties), "properties")
               .addIf(nn(additionalProperties), "additionalProperties")
               .addIf(exclusiveMaximum, "exclusiveMaximum")
               .addIf(exclusiveMinimum, "exclusiveMinimum")
               .addIf(uniqueItems, "uniqueItems")
               .addIf(collectionFormat != HttpPartCollectionFormat.NO_COLLECTION_FORMAT, "collectionFormat")
               .addIf(nn(pattern), "pattern")
               .addIf(nn(items), "items")
               .addIf(nn(maximum), "maximum")
               .addIf(nn(minimum), "minimum")
               .addIf(nn(multipleOf), "multipleOf")
               .addIf(nn(maxItems), "maxItems")
               .addIf(nn(maxLength), "maxLength")
               .addIf(nn(maxProperties), "maxProperties")
               .addIf(nn(minItems), "minItems")
               .addIf(nn(minLength), "minLength")
               .addIf(nn(minProperties), "minProperties");
            invalidFormat = ! format.isOneOf(HttpPartFormat.NO_FORMAT, HttpPartFormat.UON);
            break;
         }
         case FILE: {
            break;
         }
         case INTEGER: {
            notAllowed.addIf(nn(properties), "properties")
               .addIf(nn(additionalProperties), "additionalProperties")
               .addIf(uniqueItems, "uniqueItems")
               .addIf(collectionFormat != HttpPartCollectionFormat.NO_COLLECTION_FORMAT, "collectionFormat")
               .addIf(nn(pattern), "pattern")
               .addIf(nn(items), "items")
               .addIf(nn(maxItems), "maxItems")
               .addIf(nn(maxLength), "maxLength")
               .addIf(nn(maxProperties), "maxProperties")
               .addIf(nn(minItems), "minItems")
               .addIf(nn(minLength), "minLength")
               .addIf(nn(minProperties), "minProperties");
            invalidFormat = ! format.isOneOf(HttpPartFormat.NO_FORMAT, HttpPartFormat.UON, HttpPartFormat.INT32, HttpPartFormat.INT64);
            break;
         }
         case NUMBER: {
            notAllowed.addIf(nn(properties), "properties")
               .addIf(nn(additionalProperties), "additionalProperties")
               .addIf(uniqueItems, "uniqueItems")
               .addIf(collectionFormat != HttpPartCollectionFormat.NO_COLLECTION_FORMAT, "collectionFormat")
               .addIf(nn(pattern), "pattern")
               .addIf(nn(items), "items")
               .addIf(nn(maxItems), "maxItems")
               .addIf(nn(maxLength), "maxLength")
               .addIf(nn(maxProperties), "maxProperties")
               .addIf(nn(minItems), "minItems")
               .addIf(nn(minLength), "minLength")
               .addIf(nn(minProperties), "minProperties");
            invalidFormat = ! format.isOneOf(HttpPartFormat.NO_FORMAT, HttpPartFormat.UON, HttpPartFormat.FLOAT, HttpPartFormat.DOUBLE);
            break;
         }
         case OBJECT: {
            notAllowed.addIf(exclusiveMaximum, "exclusiveMaximum")
               .addIf(exclusiveMinimum, "exclusiveMinimum")
               .addIf(uniqueItems, "uniqueItems")
               .addIf(nn(pattern), "pattern")
               .addIf(nn(items), "items")
               .addIf(nn(maximum), "maximum")
               .addIf(nn(minimum), "minimum")
               .addIf(nn(multipleOf), "multipleOf")
               .addIf(nn(maxItems), "maxItems")
               .addIf(nn(maxLength), "maxLength")
               .addIf(nn(minItems), "minItems")
               .addIf(nn(minLength), "minLength");
            invalidFormat = ! format.isOneOf(HttpPartFormat.NO_FORMAT);
            break;
         }
         default:
            break;
      }
      // @formatter:on

      List<String> notAllowed2 = notAllowed.build();
      if (! notAllowed2.isEmpty())
         errors.add("Attributes not allow for type='" + type + "': " + StringUtils.join(notAllowed2, ","));
      if (invalidFormat)
         errors.add("Invalid format for type='" + type + "': '" + format + "'");
      if (exclusiveMaximum && maximum == null)
         errors.add("Cannot specify exclusiveMaximum with maximum.");
      if (exclusiveMinimum && minimum == null)
         errors.add("Cannot specify exclusiveMinimum with minimum.");
      if (required && nn(default_))
         errors.add("Cannot specify a default value on a required value.");
      if (nn(minLength) && nn(maxLength) && maxLength < minLength)
         errors.add("maxLength cannot be less than minLength.");
      if (nn(minimum) && nn(maximum) && maximum.doubleValue() < minimum.doubleValue())
         errors.add("maximum cannot be less than minimum.");
      if (nn(minItems) && nn(maxItems) && maxItems < minItems)
         errors.add("maxItems cannot be less than minItems.");
      if (nn(minProperties) && nn(maxProperties) && maxProperties < minProperties)
         errors.add("maxProperties cannot be less than minProperties.");
      if (nn(minLength) && minLength < 0)
         errors.add("minLength cannot be less than zero.");
      if (nn(maxLength) && maxLength < 0)
         errors.add("maxLength cannot be less than zero.");
      if (nn(minItems) && minItems < 0)
         errors.add("minItems cannot be less than zero.");
      if (nn(maxItems) && maxItems < 0)
         errors.add("maxItems cannot be less than zero.");
      if (nn(minProperties) && minProperties < 0)
         errors.add("minProperties cannot be less than zero.");
      if (nn(maxProperties) && maxProperties < 0)
         errors.add("maxProperties cannot be less than zero.");
      if (type == ARRAY && nn(items) && items.getType() == OBJECT && (format != UON && format != HttpPartFormat.NO_FORMAT))
         errors.add("Cannot define an array of objects unless array format is 'uon'.");

      if (! errors.isEmpty())
         throw new BasicRuntimeException("Schema specification errors: \n\t" + StringUtils.join(errors, "\n\t"));
   }

   /**
    * Returns the <c>collectionFormat</c> field of this schema.
    *
    * @return The <c>collectionFormat</c> field of this schema.  Defaults to {@link HttpPartCollectionFormat#NO_COLLECTION_FORMAT} if not specified.
    * @see HttpPartSchema.Builder#collectionFormat(String)
    */
   public HttpPartCollectionFormat getCollectionFormat() { return collectionFormat; }

   /**
    * Returns the <c>default</c> field of this schema.
    *
    * @return The default value for this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#default_(String)
    */
   public String getDefault() { return default_; }

   /**
    * Returns the <c>enum</c> field of this schema.
    *
    * @return The <c>enum</c> field of this schema.  Never <jk>null</jk> - returns an empty set if not specified.
    * @see HttpPartSchema.Builder#enum_(Set)
    */
   public Set<String> getEnum() { return enum_; }

   /**
    * Returns the <c>format</c> field of this schema.
    *
    * @see HttpPartSchema.Builder#format(String)
    * @return The <c>format</c> field of this schema.  Defaults to {@link HttpPartFormat#NO_FORMAT} if not specified.
    */
   public HttpPartFormat getFormat() { return format; }

   /**
    * Returns the <c>format</c> field of this schema.
    *
    * @param cm
    *    The class info of the object.
    *    <br>Used to auto-detect the format if the format was not specified.
    *    <br>Must not be <jk>null</jk>.
    * @return The <c>format</c> field of this schema, or the format auto-detected from the class info, or {@link HttpPartFormat#NO_FORMAT} if not specified and not auto-detectable.
    * @see HttpPartSchema.Builder#format(String)
    */
   public HttpPartFormat getFormat(ClassInfo cm) {
      if (format != HttpPartFormat.NO_FORMAT)
         return format;
      if (cm.isNumber()) {
         if (cm.isDecimal()) {
            if (cm.isDouble())
               return HttpPartFormat.DOUBLE;
            return HttpPartFormat.FLOAT;
         }
         if (cm.isLong())
            return HttpPartFormat.INT64;
         return HttpPartFormat.INT32;
      }
      return format;
   }

   /**
    * Returns the <c>items</c> field of this schema.
    *
    * @return The schema for child items of the object represented by this schema, or <jk>null</jk> if not defined.
    * @see HttpPartSchema.Builder#items(HttpPartSchema.Builder)
    */
   public HttpPartSchema getItems() { return items; }

   /**
    * Returns the <c>maximum</c> field of this schema.
    *
    * @return The <c>maximum</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#maximum(Number)
    */
   public Number getMaximum() { return maximum; }

   /**
    * Returns the <c>maxItems</c> field of this schema.
    *
    * @return The <c>maxItems</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#maxItems(Long)
    */
   public Long getMaxItems() { return maxItems; }

   /**
    * Returns the <c>maxLength</c> field of this schema.
    *
    * @return The <c>maxLength</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#maxLength(Long)
    */
   public Long getMaxLength() { return maxLength; }

   /**
    * Returns the <c>maxProperties</c> field of this schema.
    *
    * @return The <c>maxProperties</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#maxProperties(Long)
    */
   public Long getMaxProperties() { return maxProperties; }

   /**
    * Returns the <c>minimum</c> field of this schema.
    *
    * @return The <c>minimum</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#minimum(Number)
    */
   public Number getMinimum() { return minimum; }

   /**
    * Returns the <c>minItems</c> field of this schema.
    *
    * @return The <c>minItems</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#minItems(Long)
    */
   public Long getMinItems() { return minItems; }

   /**
    * Returns the <c>minLength</c> field of this schema.
    *
    * @return The <c>minLength</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#minLength(Long)
    */
   public Long getMinLength() { return minLength; }

   /**
    * Returns the <c>minProperties</c> field of this schema.
    *
    * @return The <c>minProperties</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#minProperties(Long)
    */
   public Long getMinProperties() { return minProperties; }

   /**
    * Returns the <c>multipleOf</c> field of this schema.
    *
    * @return The <c>multipleOf</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#multipleOf(Number)
    */
   public Number getMultipleOf() { return multipleOf; }

   /**
    * Returns the name of the object described by this schema, for example the query or form parameter name.
    *
    * @return The name, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#name(String)
    */
   public String getName() { return name; }

   /**
    * Returns the default parsed type for this schema.
    *
    * @return The default parsed type for this schema.  Never <jk>null</jk>.
    */
   public Class<?> getParsedType() { return parsedType; }

   /**
    * Returns the <c>parser</c> field of this schema.
    *
    * @return The <c>parser</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#parser(Class)
    */
   public Class<?> getParser() { return parser; }

   /**
    * Returns the <c>pattern</c> field of this schema.
    *
    * @return The <c>pattern</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#pattern(String)
    */
   public Pattern getPattern() { return pattern; }

   /**
    * Returns the schema information for the specified property.
    *
    * @param name The property name.  Can be <jk>null</jk> (treated as an unmatched name; falls back to the <c>additionalProperties</c> schema).
    * @return The schema information for the specified property, or the <c>additionalProperties</c> schema if no matching property is defined, or <jk>null</jk> if neither is defined.
    */
   public HttpPartSchema getProperty(String name) {
      if (nn(properties)) {
         HttpPartSchema schema = properties.get(name);
         if (nn(schema))
            return schema;
      }
      return additionalProperties;
   }

   /**
    * Returns the <c>serializer</c> field of this schema.
    *
    * @return The <c>serializer</c> field of this schema, or <jk>null</jk> if not specified.
    * @see HttpPartSchema.Builder#serializer(Class)
    */
   public Class<?> getSerializer() { return serializer; }

   /**
    * Returns the <c>type</c> field of this schema.
    *
    * @return The <c>type</c> field of this schema.  Defaults to {@link HttpPartDataType#NO_TYPE} if not specified.
    * @see HttpPartSchema.Builder#type(String)
    */
   public HttpPartDataType getType() { return type; }

   /**
    * Returns the <c>type</c> field of this schema.
    *
    * @param cm
    *    The class info of the object.
    *    <br>Used to auto-detect the type if the type was not specified.
    *    <br>Must not be <jk>null</jk>.
    * @return The <c>type</c> field of this schema, or the type auto-detected from the class info if not specified.
    * @see HttpPartSchema.Builder#type(String)
    */
   public HttpPartDataType getType(ClassInfo cm) {
      if (type != HttpPartDataType.NO_TYPE)
         return type;
      if (cm.isTemporal() || cm.isDateOrCalendar())
         return HttpPartDataType.STRING;
      if (cm.isNumber()) {
         if (cm.isDecimal())
            return HttpPartDataType.NUMBER;
         return HttpPartDataType.INTEGER;
      }
      if (cm.isBoolean())
         return HttpPartDataType.BOOLEAN;
      if (cm.isMap() || isObjectType(cm))
         return HttpPartDataType.OBJECT;
      if (cm.isCollectionOrArray())
         return HttpPartDataType.ARRAY;
      return HttpPartDataType.STRING;
   }

   private static boolean isObjectType(ClassInfo cm) {
      if (cm instanceof ClassMeta<?> cm2)
         return cm2.isBean();
      return false;
   }

   /**
    * Returns <jk>true</jk> if this schema has properties associated with it.
    *
    * @return <jk>true</jk> if this schema has properties associated with it.
    */
   public boolean hasProperties() {
      return nn(properties) || nn(additionalProperties);
   }

   /**
    * Returns the <c>allowEmptyValue</c> field of this schema.
    *
    * @return The <c>allowEmptyValue</c> field of this schema.
    * @see HttpPartSchema.Builder#allowEmptyValue(Boolean)
    */
   public boolean isAllowEmptyValue() { return allowEmptyValue; }

   /**
    * Returns the <c>exclusiveMaximum</c> field of this schema.
    *
    * @return The <c>exclusiveMaximum</c> field of this schema.
    * @see HttpPartSchema.Builder#exclusiveMaximum(Boolean)
    */
   public boolean isExclusiveMaximum() { return exclusiveMaximum; }

   /**
    * Returns the <c>exclusiveMinimum</c> field of this schema.
    *
    * @return The <c>exclusiveMinimum</c> field of this schema.
    * @see HttpPartSchema.Builder#exclusiveMinimum(Boolean)
    */
   public boolean isExclusiveMinimum() { return exclusiveMinimum; }

   /**
    * Returns the <c>required</c> field of this schema.
    *
    * @return The <c>required</c> field of this schema.
    * @see HttpPartSchema.Builder#required(Boolean)
    */
   public boolean isRequired() { return required; }

   /**
    * Returns the <c>skipIfEmpty</c> field of this schema.
    *
    * @return The <c>skipIfEmpty</c> field of this schema.
    * @see HttpPartSchema.Builder#skipIfEmpty(Boolean)
    */
   public boolean isSkipIfEmpty() { return skipIfEmpty; }

   /**
    * Returns the <c>uniqueItems</c> field of this schema.
    *
    * @return The <c>uniqueItems</c> field of this schema.
    * @see HttpPartSchema.Builder#uniqueItems(Boolean)
    */
   public boolean isUniqueItems() { return uniqueItems; }

   protected FluentMap<String,Object> properties() {
      // @formatter:off
      Predicate<Object> ne = x -> ine(s(x));
      Predicate<Object> nf = x -> x instanceof Boolean x2 && x2;
      Predicate<Object> nm1 = x -> x instanceof Number x2 && x2.intValue() != -1;
      Predicate<Object> nn = Shorts::nn;
      return mapb_so().sorted().buildFluent()
         .ai(ne, "name", name)
         .ai(ne, "type", type)
         .ai(ne, "format", format)
         .ai(ne, "default", default_)
         .ai(ne, "enum", enum_)
         .ai(ne, "properties", properties)
         .ai(nf, "allowEmptyValue", allowEmptyValue)
         .ai(nf, "exclusiveMaximum", exclusiveMaximum)
         .ai(nf, "exclusiveMinimum", exclusiveMinimum)
         .ai(nf, "required", required)
         .ai(nf, "uniqueItems", uniqueItems)
         .ai(nf, "skipIfEmpty", skipIfEmpty)
         .ai(x -> x != HttpPartCollectionFormat.NO_COLLECTION_FORMAT, "collectionFormat", collectionFormat)
         .ai(ne, "pattern", pattern)
         .ai(nn, "items", items)
         .ai(nn, "additionalProperties", additionalProperties)
         .ai(nm1, "maximum", maximum)
         .ai(nm1, "minimum", minimum)
         .ai(nm1, "multipleOf", multipleOf)
         .ai(nm1, "maxLength", maxLength)
         .ai(nm1, "minLength", minLength)
         .ai(nm1, "maxItems", maxItems)
         .ai(nm1, "minItems", minItems)
         .ai(nm1, "maxProperties", maxProperties)
         .ai(nm1, "minProperties", minProperties)
         .a("parsedType", parsedType);
      // @formatter:on
   }

   @Override /* Overridden from Object */
   public String toString() {
      return r(properties());
   }

   /**
    * Throws a {@link SchemaValidationException} if the specified pre-parsed input does not validate against this schema.
    *
    * @param in The input.  Can be <jk>null</jk> (only the <c>required</c> check is performed; format/pattern/length checks are skipped).
    * @return The same object passed in.
    * @throws SchemaValidationException if the specified pre-parsed input does not validate against this schema.
    */
   public String validateInput(String in) throws SchemaValidationException {
      if (! isValidRequired(in))
         throw new SchemaValidationException("No value specified.");
      if (nn(in)) {
         if (! isValidAllowEmpty(in))
            throw new SchemaValidationException("Empty value not allowed.");
         if (! isValidConst(in))
            throw new SchemaValidationException("Value does not match constant.  Must be: %s", const_);
         if (! isValidPattern(in))
            throw new SchemaValidationException("Value does not match expected pattern.  Must match pattern: %s", pattern.pattern());
         if (! isValidEnum(in))
            throw new SchemaValidationException("Value does not match one of the expected values.  Must be one of the following:  %s", toCdl(enum_));
         if (! isValidMaxLength(in))
            throw new SchemaValidationException("Maximum length of value exceeded.");
         if (! isValidMinLength(in))
            throw new SchemaValidationException("Minimum length of value not met.");
         if (! isValidFormat(in))
            throw new SchemaValidationException("Value does not match expected format: %s", format);
      }
      return in;
   }

   /**
    * Validates the specified parsed output against this schema.
    *
    * @param <T> The return type.
    * @param o The parsed output.  Can be <jk>null</jk> (only the <c>required</c> check is performed; type-specific validation is skipped).
    * @return The same object passed in.
    * @throws SchemaValidationException if the specified parsed output does not validate against this schema.
    */
   public <T> T validateOutput(T o) throws SchemaValidationException {
      if (o == null) {
         if (! isValidRequired(o))
            throw new SchemaValidationException("Required value not provided.");
         return o;
      }
      var ci = ClassInfo.of(o);
      switch (getType(ci)) {
         case ARRAY: {
            if (ci.isArray()) {
               if (! isValidMinItems(o))
                  throw new SchemaValidationException("Minimum number of items not met.");
               if (! isValidMaxItems(o))
                  throw new SchemaValidationException("Maximum number of items exceeded.");
               if (! isValidUniqueItems(o))
                  throw new SchemaValidationException("Duplicate items not allowed.");
               HttpPartSchema items2 = getItems();
               if (nn(items2))
                  for (var i = 0; i < Array.getLength(o); i++)
                     items2.validateOutput(Array.get(o, i));
            } else if (ci.isCollection()) {
               Collection<?> c = (Collection<?>)o;
               if (! isValidMinItems(c))
                  throw new SchemaValidationException("Minimum number of items not met.");
               if (! isValidMaxItems(c))
                  throw new SchemaValidationException("Maximum number of items exceeded.");
               if (! isValidUniqueItems(c))
                  throw new SchemaValidationException("Duplicate items not allowed.");
               HttpPartSchema items2 = getItems();
               if (nn(items2))
                  c.forEach(items2::validateOutput);
            }
            break;
         }
         case INTEGER: {
            if (ci.isNumber()) {
               Number n = (Number)o;
               if (! isValidMinimum(n))
                  throw new SchemaValidationException("Minimum value not met.");
               if (! isValidMaximum(n))
                  throw new SchemaValidationException("Maximum value exceeded.");
               if (! isValidMultipleOf(n))
                  throw new SchemaValidationException("Multiple-of not met.");
            }
            break;
         }
         case NUMBER: {
            if (ci.isNumber()) {
               Number n = (Number)o;
               if (! isValidMinimum(n))
                  throw new SchemaValidationException("Minimum value not met.");
               if (! isValidMaximum(n))
                  throw new SchemaValidationException("Maximum value exceeded.");
               if (! isValidMultipleOf(n))
                  throw new SchemaValidationException("Multiple-of not met.");
            }
            break;
         }
         case OBJECT: {
            if (ci.isMap()) {
               Map<?,?> m = (Map<?,?>)o;
               if (! isValidMinProperties(m))
                  throw new SchemaValidationException("Minimum number of properties not met.");
               if (! isValidMaxProperties(m))
                  throw new SchemaValidationException("Maximum number of properties exceeded.");
               m.forEach((k, v) -> {
                  var key = k.toString();
                  HttpPartSchema s2 = getProperty(key);
                  if (nn(s2))
                     s2.validateOutput(v);
               });
            }
            break;
         }
         case STRING: {
            if (ci.isCharSequence()) {
               var s = o.toString();
               if (! isValidMinLength(s))
                  throw new SchemaValidationException("Minimum length of value not met.");
               if (! isValidMaxLength(s))
                  throw new SchemaValidationException("Maximum length of value exceeded.");
               if (! isValidPattern(s))
                  throw new SchemaValidationException("Value does not match expected pattern.  Must match pattern: %s", pattern.pattern());
               if (! isValidFormat(s))
                  throw new SchemaValidationException("Value does not match expected format: %s", format);
            }
            break;
         }
         case BOOLEAN, FILE, NO_TYPE:
            break;
         default:
            break;
      }
      return o;
   }

   private boolean isValidAllowEmpty(String x) {
      return allowEmptyValue || ine(x);
   }

   private boolean isValidConst(String x) {
      return const_ == null || const_.equals(x);
   }

   private static boolean isValidDate(String x) {
      // RFC 3339 full-date: YYYY-MM-DD (relaxed to allow various date formats) (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors prefix match ^\d{4}[-/]\d{1,2}[-/]\d{1,2}.* (\d = ASCII [0-9]; trailing .* is a non-line-terminator prefix check, not a full match).
      if (x.length() < 4)
         return false;
      for (var i = 0; i < 4; i++)
         if (! isAsciiDigit(x.charAt(i)))
            return false;
      var i = scanSepAnd1or2Digits(x, 4);
      if (i < 0)
         return false;
      i = scanSepAnd1or2Digits(x, i);
      if (i < 0)
         return false;
      return hasNoLineTerminator(x, i);
   }

   private static boolean isValidDateTime(String x) {
      // RFC 3339 date-time (relaxed to allow various datetime formats) (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors prefix match ^\d{4}[-/]\d{1,2}[-/]\d{1,2}[T\s]\d{1,2}:\d{1,2}.* (\s = ASCII whitespace; trailing .* is a non-line-terminator prefix check).
      if (x.length() < 4)
         return false;
      for (var i = 0; i < 4; i++)
         if (! isAsciiDigit(x.charAt(i)))
            return false;
      var i = scanSepAnd1or2Digits(x, 4);
      if (i < 0)
         return false;
      i = scanSepAnd1or2Digits(x, i);
      if (i < 0)
         return false;
      if (i >= x.length() || ! (x.charAt(i) == 'T' || isRegexWhitespace(x.charAt(i))))
         return false;
      i = scan1or2Digits(x, i + 1);
      if (i < 0)
         return false;
      if (! charIs(x, i, ':'))
         return false;
      i = scan1or2Digits(x, i + 1);
      if (i < 0)
         return false;
      return hasNoLineTerminator(x, i);
   }

   private static boolean isValidDateTimeZone(String x) {
      // RFC 3339 date-time with time zone (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors full match ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?[+-]\d{2}:\d{2}$ (\d = ASCII [0-9]).
      var len = x.length();
      var i = scanDateTimeCore(x);
      if (i < 0)
         return false;
      i = scanOptionalFractionalSeconds(x, i, len);
      if (i < 0)
         return false;
      return scanTimezoneOffset(x, i, len) == len;
   }

   // Mirrors \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2} - the date/time core consumed by isValidDateTimeZone. Returns
   // the index after the seconds field, or -1 if any component or separator is missing/malformed.
   private static int scanDateTimeCore(String x) {
      var i = scanDigits(x, 0, 4);
      if (i < 0 || ! charIs(x, i, '-'))
         return -1;
      i = scanDigits(x, i + 1, 2);
      if (i < 0 || ! charIs(x, i, '-'))
         return -1;
      i = scanDigits(x, i + 1, 2);
      if (i < 0 || ! charIs(x, i, 'T'))
         return -1;
      i = scanDigits(x, i + 1, 2);
      if (i < 0 || ! charIs(x, i, ':'))
         return -1;
      i = scanDigits(x, i + 1, 2);
      if (i < 0 || ! charIs(x, i, ':'))
         return -1;
      return scanDigits(x, i + 1, 2);
   }

   // Mirrors the optional group (\.\d+)? shared by isValidDateTimeZone and isValidTime: consumes '.' followed
   // by one-or-more ASCII digits.  Returns i unchanged if no '.' is present at i, the index after the digits
   // if one is, or -1 if '.' is present with no following digit.
   private static int scanOptionalFractionalSeconds(String x, int i, int len) {
      if (i < len && x.charAt(i) == '.') {
         var f = i + 1;
         var j = f;
         while (j < len && isAsciiDigit(x.charAt(j)))
            j++;
         if (j == f)
            return -1;
         return j;
      }
      return i;
   }

   // Mirrors [+-]\d{2}:\d{2}, the mandatory zone-offset suffix of isValidDateTimeZone and the offset branch of
   // isValidTime's optional zone group.  Returns the index after the offset, or -1 if the sign, digits, or
   // separator are missing/malformed.
   private static int scanTimezoneOffset(String x, int i, int len) {
      if (i >= len || (x.charAt(i) != '+' && x.charAt(i) != '-'))
         return -1;
      i = scanDigits(x, i + 1, 2);
      if (i < 0 || ! charIs(x, i, ':'))
         return -1;
      return scanDigits(x, i + 1, 2);
   }

   private static boolean isValidDuration(String x) {
      // RFC 3339 Appendix A duration (ISO 8601) (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors full match ^P(?:\d+Y)?(?:\d+M)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$ (\d = ASCII [0-9]).
      var len = x.length();
      if (len == 0 || x.charAt(0) != 'P')
         return false;
      var i = scanDurationUnit(x, 1, 'Y');
      i = scanDurationUnit(x, i, 'M');
      i = scanDurationUnit(x, i, 'D');
      if (i < len && x.charAt(i) == 'T') {
         i = scanDurationUnit(x, i + 1, 'H');
         i = scanDurationUnit(x, i, 'M');
         i = scanDurationSeconds(x, i);
      }
      return i == len;
   }

   private static boolean isValidEmail(String x) {
      // RFC 5321 simplified email validation (programmatic to avoid regex super-linear backtracking on large inputs).
      // Mirrors ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
      var at = x.indexOf('@');
      if (at < 1 || at != x.lastIndexOf('@'))
         return false;
      for (var i = 0; i < at; i++)
         if (! isEmailLocalChar(x.charAt(i)))
            return false;
      var dot = x.lastIndexOf('.');
      if (dot < at + 2)  // Need at least one domain-body char between '@' and the final '.'.
         return false;
      for (var i = at + 1; i < dot; i++)
         if (! isEmailDomainChar(x.charAt(i)))
            return false;
      if (x.length() - dot - 1 < 2)  // TLD must be 2+ characters.
         return false;
      for (var i = dot + 1; i < x.length(); i++)
         if (! isAsciiLetter(x.charAt(i)))
            return false;
      return true;
   }

   private static boolean isEmailLocalChar(char c) {
      return isAsciiAlphanumeric(c) || c == '.' || c == '_' || c == '%' || c == '+' || c == '-';
   }

   private static boolean isEmailDomainChar(char c) {
      return isAsciiAlphanumeric(c) || c == '.' || c == '-';
   }

   private static boolean isAsciiLetter(char c) {
      return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
   }

   private boolean isValidEnum(String x) {
      return enum_.isEmpty() || enum_.contains(x);
   }

   private boolean isValidFormat(String x) {
      if (format == null || format == HttpPartFormat.NO_FORMAT)
         return true;

      // Skip validation for literal "null" string
      if (eq(x, "null"))
         return true;

      try {
         return switch (format) {
            case EMAIL -> isValidEmail(x);
            case IDN_EMAIL -> isValidIdnEmail(x);
            case HOSTNAME -> isValidHostname(x);
            case IDN_HOSTNAME -> isValidIdnHostname(x);
            case IPV4 -> isValidIpv4(x);
            case IPV6 -> isValidIpv6(x);
            case URI -> isValidUri(x);
            case URI_REFERENCE -> isValidUriReference(x);
            case IRI -> isValidIri(x);
            case IRI_REFERENCE -> isValidIriReference(x);
            case UUID -> isValidUuid(x);
            case URI_TEMPLATE -> isValidUriTemplate(x);
            case JSON_POINTER -> isValidJsonPointer(x);
            case RELATIVE_JSON_POINTER -> isValidRelativeJsonPointer(x);
            case REGEX -> isValidRegex(x);
            case DATE -> isValidDate(x);
            case DATE_TIME -> isValidDateTime(x);
            case DATE_TIME_ZONE -> isValidDateTimeZone(x);
            case TIME -> isValidTime(x);
            case DURATION -> isValidDuration(x);
            case BYTE, BINARY, BINARY_SPACED -> true; // These are transformation formats, not validation formats
            case PASSWORD -> true; // Password format is just a UI hint
            case INT32, INT64, FLOAT, DOUBLE -> true; // Numeric formats are validated during parsing
            case UON -> true; // UON format is validated during parsing
            default -> true;
         };
      } catch (@SuppressWarnings("unused") Exception e) {
         return false;
      }
   }

   private static boolean isValidHostname(String x) {
      // RFC 1123 hostname validation (programmatic to avoid regex stack overflow on large inputs)
      if (x.isEmpty())
         return false;
      int labelStart = 0;
      for (int i = 0; i <= x.length(); i++) {
         if (i == x.length() || x.charAt(i) == '.') {
            if (! isValidHostnameLabel(x, labelStart, i))
               return false;
            labelStart = i + 1;
         }
      }
      return true;
   }

   private static boolean isValidHostnameLabel(String x, int start, int end) {
      int len = end - start;
      if (len == 0 || len > 63)
         return false;
      if (! isAsciiAlphanumeric(x.charAt(start)) || ! isAsciiAlphanumeric(x.charAt(end - 1)))
         return false;
      for (int i = start + 1; i < end - 1; i++) {
         char c = x.charAt(i);
         if (! isAsciiAlphanumeric(c) && c != '-')
            return false;
      }
      return true;
   }

   private static boolean isAsciiAlphanumeric(char c) {
      return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9');
   }

   private static boolean isAsciiDigit(char c) {
      // Java regex \d (ASCII [0-9] only).
      return c >= '0' && c <= '9';
   }

   private static boolean isAsciiHexDigit(char c) {
      return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
   }

   private static boolean isUriSchemeChar(char c) {
      // Matches the regex class [a-zA-Z0-9+.-].
      return isAsciiAlphanumeric(c) || c == '+' || c == '.' || c == '-';
   }

   private static boolean isRegexLineTerminator(char c) {
      // Chars NOT matched by regex '.' in default (non-DOTALL) mode.
      return c == '\n' || c == '\r' || c == '\u0085' || c == '\u2028' || c == '\u2029';
   }

   private static boolean charIs(String x, int i, char c) {
      return i < x.length() && x.charAt(i) == c;
   }

   // Returns the index after consuming exactly n ASCII digits starting at i, or -1 if fewer than n digits are present.
   private static int scanDigits(String x, int i, int n) {
      if (i < 0 || i + n > x.length())
         return -1;
      for (var k = 0; k < n; k++)
         if (! isAsciiDigit(x.charAt(i + k)))
            return -1;
      return i + n;
   }

   // Mirrors \d{1,2} - consumes 1 mandatory then 1 optional ASCII digit (greedy). Returns new index or -1.
   private static int scan1or2Digits(String x, int i) {
      var len = x.length();
      if (i < 0 || i >= len || ! isAsciiDigit(x.charAt(i)))
         return -1;
      i++;
      if (i < len && isAsciiDigit(x.charAt(i)))
         i++;
      return i;
   }

   // Mirrors [-/]\d{1,2}. Returns new index or -1.
   private static int scanSepAnd1or2Digits(String x, int i) {
      if (i < 0 || i >= x.length() || (x.charAt(i) != '-' && x.charAt(i) != '/'))
         return -1;
      return scan1or2Digits(x, i + 1);
   }

   // Mirrors '.*' / '.+' tail consumption: returns true iff every char from i onward is a non-line-terminator (i.e. matchable by regex '.').
   private static boolean hasNoLineTerminator(String x, int i) {
      for (var j = i; j < x.length(); j++)
         if (isRegexLineTerminator(x.charAt(j)))
            return false;
      return true;
   }

   // Mirrors the optional group (?:\d+<unit>)?: consumes a run of >=1 ASCII digits followed by the unit char if present; otherwise leaves i unchanged.
   private static int scanDurationUnit(String x, int i, char unit) {
      var len = x.length();
      var j = i;
      while (j < len && isAsciiDigit(x.charAt(j)))
         j++;
      if (j > i && j < len && x.charAt(j) == unit)
         return j + 1;
      return i;
   }

   // Mirrors the optional group (?:\d+(?:\.\d+)?S)?: consumes seconds (with optional fraction) followed by 'S' if present; otherwise leaves i unchanged.
   private static int scanDurationSeconds(String x, int i) {
      var len = x.length();
      var j = i;
      while (j < len && isAsciiDigit(x.charAt(j)))
         j++;
      if (j == i)
         return i;  // \d+ requires at least one digit
      if (j < len && x.charAt(j) == '.') {
         var f = j + 1;
         var k = f;
         while (k < len && isAsciiDigit(x.charAt(k)))
            k++;
         if (k == f)
            return i;  // '.' with no following digit -> group cannot match -> consume nothing
         j = k;
      }
      if (j < len && x.charAt(j) == 'S')
         return j + 1;
      return i;  // no 'S' -> group matches empty
   }

   // Mirrors ^[a-zA-Z][a-zA-Z0-9+.-]*:<rest> where <rest> is .+ (nonEmptyRest=true) or .* (nonEmptyRest=false), all non-line-terminators.
   private static boolean isValidScheme(String x, boolean nonEmptyRest) {
      var len = x.length();
      if (len == 0 || ! isAsciiLetter(x.charAt(0)))
         return false;
      var i = 1;
      while (i < len && isUriSchemeChar(x.charAt(i)))
         i++;
      if (i >= len || x.charAt(i) != ':')
         return false;
      i++;
      if (nonEmptyRest && i >= len)
         return false;
      return hasNoLineTerminator(x, i);
   }

   // Consumes up to 4 ASCII hex digits starting at i (bounded by end). Mirrors [0-9a-fA-F]{0,4}.
   private static int scanHex4(String x, int i, int end) {
      var n = 0;
      while (i < end && n < 4 && isAsciiHexDigit(x.charAt(i))) {
         i++;
         n++;
      }
      return i;
   }

   // Mirrors ^([0-9a-fA-F]{0,4}+:){7}[0-9a-fA-F]{0,4}$ - exactly 8 hextet groups separated by 7 colons.
   private static boolean isIpv6Full(String x) {
      var len = x.length();
      var i = 0;
      for (var g = 0; g < 7; g++) {
         i = scanHex4(x, i, len);
         if (i >= len || x.charAt(i) != ':')
            return false;
         i++;
      }
      i = scanHex4(x, i, len);
      return i == len;
   }

   // Mirrors ^::([0-9a-fA-F]{0,4}+:){0,6}[0-9a-fA-F]{0,4}$.
   private static boolean isIpv6LeadingDoubleColon(String x) {
      var len = x.length();
      if (len < 2 || x.charAt(0) != ':' || x.charAt(1) != ':')
         return false;
      var i = 2;
      var groups = 0;
      while (groups < 6) {
         var j = scanHex4(x, i, len);
         if (j < len && x.charAt(j) == ':') {
            i = j + 1;
            groups++;
         } else {
            break;
         }
      }
      i = scanHex4(x, i, len);
      return i == len;
   }

   // Mirrors ^([0-9a-fA-F]{0,4}+:){1,7}:$ - every such match ends in ':', and the body (minus the final ':') is 1..7 hextet+colon groups.
   private static boolean isIpv6TrailingColon(String x) {
      var len = x.length();
      if (len == 0 || x.charAt(len - 1) != ':')
         return false;
      var body = len - 1;
      var i = 0;
      var groups = 0;
      while (i < body) {
         var j = scanHex4(x, i, body);
         if (j < body && x.charAt(j) == ':') {
            i = j + 1;
            groups++;
         } else {
            return false;
         }
      }
      return groups >= 1 && groups <= 7 && i == body;
   }

   private static boolean isValidIdnEmail(String x) {
      // RFC 6531 - allows international characters (programmatic to avoid regex super-linear backtracking on large inputs).
      // Mirrors ^[^@\s]+@[^@\s]+\.[^@\s]+$
      var at = x.indexOf('@');
      if (at < 1 || at != x.lastIndexOf('@'))
         return false;
      for (var i = 0; i < at; i++)
         if (isRegexWhitespace(x.charAt(i)))
            return false;
      var len = x.length();
      var interiorDot = false;
      for (var i = at + 1; i < len; i++) {
         var c = x.charAt(i);
         if (isRegexWhitespace(c))
            return false;
         if (c == '.' && i > at + 1 && i < len - 1)
            interiorDot = true;
      }
      return interiorDot;
   }

   private static boolean isRegexWhitespace(char c) {
      // Matches Java regex \s (ASCII whitespace only).
      return c == ' ' || c == '\t' || c == '\n' || c == '\u000B' || c == '\f' || c == '\r';
   }

   private static boolean isValidIdnHostname(String x) {
      // RFC 5890 - allows international characters (programmatic to avoid regex stack overflow on large inputs)
      if (x.isEmpty())
         return false;
      for (int i = 0; i < x.length(); i++)
         if (Character.isWhitespace(x.charAt(i)))
            return false;
      return true;
   }

   private static boolean isValidIpv4(String x) {
      // RFC 2673 IPv4 validation
      var parts = x.split("\\.");
      if (parts.length != 4)
         return false;
      for (var part : parts) {
         try {
            int val = Integer.parseInt(part);
            if (val < 0 || val > 255)
               return false;
         } catch (@SuppressWarnings("unused") NumberFormatException e) {
            return false;
         }
      }
      return true;
   }

   private static boolean isValidIpv6(String x) {
      // RFC 4291 IPv6 validation (simplified) (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors the three full-match alternatives:
      //   ^([0-9a-fA-F]{0,4}+:){7}[0-9a-fA-F]{0,4}$ | ^::([0-9a-fA-F]{0,4}+:){0,6}[0-9a-fA-F]{0,4}$ | ^([0-9a-fA-F]{0,4}+:){1,7}:$
      return isIpv6Full(x) || isIpv6LeadingDoubleColon(x) || isIpv6TrailingColon(x);
   }

   private static boolean isValidIri(String x) {
      // RFC 3987 IRI validation (allows international characters) (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors prefix match ^[a-zA-Z][a-zA-Z0-9+.-]*:.+ (.+ requires at least one trailing non-line-terminator char).
      return isValidScheme(x, true);
   }

   private static boolean isValidIriReference(String x) {
      // RFC 3987 IRI reference (allows international characters)
      return !x.isEmpty();
   }

   private static boolean isValidJsonPointer(String x) {
      // RFC 6901 JSON Pointer validation
      return x.isEmpty() || x.charAt(0) == '/';
   }

   private boolean isValidMaximum(Number x) {
      // Check Draft 2020-12 exclusiveMaximumValue first (takes precedence)
      if (nn(exclusiveMaximumValue)) {
         if (x instanceof Integer || x instanceof AtomicInteger)
            return x.intValue() < exclusiveMaximumValue.intValue();
         if (x instanceof Short || x instanceof Byte)
            return x.shortValue() < exclusiveMaximumValue.shortValue();
         if (x instanceof Long || x instanceof AtomicLong || x instanceof BigInteger)
            return x.longValue() < exclusiveMaximumValue.longValue();
         if (x instanceof Float)
            return x.floatValue() < exclusiveMaximumValue.floatValue();
         if (x instanceof Double || x instanceof BigDecimal)
            return x.doubleValue() < exclusiveMaximumValue.doubleValue();
      }
      // Fall back to Draft 04 boolean exclusiveMaximum with maximum
      if (x instanceof Integer || x instanceof AtomicInteger)
         return maximum == null || x.intValue() < maximum.intValue() || (x.intValue() == maximum.intValue() && (! exclusiveMaximum));
      if (x instanceof Short || x instanceof Byte)
         return maximum == null || x.shortValue() < maximum.shortValue() || (x.intValue() == maximum.shortValue() && (! exclusiveMaximum));
      if (x instanceof Long || x instanceof AtomicLong || x instanceof BigInteger)
         return maximum == null || x.longValue() < maximum.longValue() || (x.intValue() == maximum.longValue() && (! exclusiveMaximum));
      if (x instanceof Float)
         return maximum == null || x.floatValue() < maximum.floatValue() || (x.floatValue() == maximum.floatValue() && (! exclusiveMaximum));
      if (x instanceof Double || x instanceof BigDecimal)
         return maximum == null || x.doubleValue() < maximum.doubleValue() || (x.doubleValue() == maximum.doubleValue() && (! exclusiveMaximum));
      return true;
   }

   private boolean isValidMaxItems(Collection<?> x) {
      return maxItems == null || x.size() <= maxItems;
   }

   private boolean isValidMaxItems(Object x) {
      return maxItems == null || Array.getLength(x) <= maxItems;
   }

   private boolean isValidMaxLength(String x) {
      return maxLength == null || x.length() <= maxLength;
   }

   private boolean isValidMaxProperties(Map<?,?> x) {
      return maxProperties == null || x.size() <= maxProperties;
   }

   private boolean isValidMinimum(Number x) {
      // Check Draft 2020-12 exclusiveMinimumValue first (takes precedence)
      if (nn(exclusiveMinimumValue)) {
         if (x instanceof Integer || x instanceof AtomicInteger)
            return x.intValue() > exclusiveMinimumValue.intValue();
         if (x instanceof Short || x instanceof Byte)
            return x.shortValue() > exclusiveMinimumValue.shortValue();
         if (x instanceof Long || x instanceof AtomicLong || x instanceof BigInteger)
            return x.longValue() > exclusiveMinimumValue.longValue();
         if (x instanceof Float)
            return x.floatValue() > exclusiveMinimumValue.floatValue();
         if (x instanceof Double || x instanceof BigDecimal)
            return x.doubleValue() > exclusiveMinimumValue.doubleValue();
      }
      // Fall back to Draft 04 boolean exclusiveMinimum with minimum
      if (x instanceof Integer || x instanceof AtomicInteger)
         return minimum == null || x.intValue() > minimum.intValue() || (x.intValue() == minimum.intValue() && (! exclusiveMinimum));
      if (x instanceof Short || x instanceof Byte)
         return minimum == null || x.shortValue() > minimum.shortValue() || (x.intValue() == minimum.shortValue() && (! exclusiveMinimum));
      if (x instanceof Long || x instanceof AtomicLong || x instanceof BigInteger)
         return minimum == null || x.longValue() > minimum.longValue() || (x.intValue() == minimum.longValue() && (! exclusiveMinimum));
      if (x instanceof Float)
         return minimum == null || x.floatValue() > minimum.floatValue() || (x.floatValue() == minimum.floatValue() && (! exclusiveMinimum));
      if (x instanceof Double || x instanceof BigDecimal)
         return minimum == null || x.doubleValue() > minimum.doubleValue() || (x.doubleValue() == minimum.doubleValue() && (! exclusiveMinimum));
      return true;
   }

   private boolean isValidMinItems(Collection<?> x) {
      return minItems == null || x.size() >= minItems;
   }

   private boolean isValidMinItems(Object x) {
      return minItems == null || Array.getLength(x) >= minItems;
   }

   private boolean isValidMinLength(String x) {
      return minLength == null || x.length() >= minLength;
   }

   private boolean isValidMinProperties(Map<?,?> x) {
      return minProperties == null || x.size() >= minProperties;
   }

   private boolean isValidMultipleOf(Number x) {
      if (x instanceof Integer || x instanceof AtomicInteger)
         return multipleOf == null || x.intValue() % multipleOf.intValue() == 0;
      if (x instanceof Short || x instanceof Byte)
         return multipleOf == null || x.shortValue() % multipleOf.shortValue() == 0;
      if (x instanceof Long || x instanceof AtomicLong || x instanceof BigInteger)
         return multipleOf == null || x.longValue() % multipleOf.longValue() == 0;
      if (x instanceof Float)
         return multipleOf == null || x.floatValue() % multipleOf.floatValue() == 0;
      if (x instanceof Double || x instanceof BigDecimal)
         return multipleOf == null || x.doubleValue() % multipleOf.doubleValue() == 0;
      return true;
   }

   private boolean isValidPattern(String x) {
      return pattern == null || pattern.matcher(x).matches();
   }

   // Upper bound on the length of a value validated as a regular expression.  The value here is intentionally
   // a caller-authored regex (JSON-Schema "format":"regex"), so it must be compiled rather than quoted; the
   // compiled pattern is immediately discarded and never matched against anything.  This cap bounds the cost
   // of that throwaway compilation so an over-long or deeply-nested pattern can't be used as a DoS vector.
   private static final int MAX_REGEX_VALIDATION_LENGTH = 1000;

   private static boolean isValidRegex(String x) {
      // ECMA-262 regex validation.  Reject over-long values before compiling (the compiled Pattern is
      // discarded and never used for matching, so bounding length is sufficient to cap the work done here).
      if (x.length() > MAX_REGEX_VALIDATION_LENGTH)
         return false;
      try {
         Pattern.compile(x);
         return true;
      } catch (@SuppressWarnings("unused") Exception e) {
         return false;
      }
   }

   private static boolean isValidRelativeJsonPointer(String x) {
      // Relative JSON Pointer validation (programmatic to avoid regex stack overflow on large inputs)
      int i = 0;
      int len = x.length();
      if (i >= len)
         return false;
      if (x.charAt(i) == '0') {
         i++;
      } else if (x.charAt(i) >= '1' && x.charAt(i) <= '9') {
         i++;
         while (i < len && x.charAt(i) >= '0' && x.charAt(i) <= '9')
            i++;
      } else {
         return false;
      }
      if (i >= len)
         return true;
      if (x.charAt(i) == '#')
         return i + 1 == len;
      return x.charAt(i) == '/';
   }

   private boolean isValidRequired(Object x) {
      return nn(x) || ! required;
   }

   private static boolean isValidTime(String x) {
      // RFC 3339 time (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors full match ^\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$ (\d = ASCII [0-9]).
      var len = x.length();
      var i = scanTimeCore(x);
      if (i < 0)
         return false;
      i = scanOptionalFractionalSeconds(x, i, len);
      if (i < 0)
         return false;
      if (i == len)
         return true;  // (Z|[+-]\d{2}:\d{2})? matched empty
      if (x.charAt(i) == 'Z')
         return i + 1 == len;
      return scanTimezoneOffset(x, i, len) == len;
   }

   // Mirrors \d{2}:\d{2}:\d{2} - the time core consumed by isValidTime. Returns the index after the seconds
   // field, or -1 if any component or separator is missing/malformed.
   private static int scanTimeCore(String x) {
      var i = scanDigits(x, 0, 2);
      if (i < 0 || ! charIs(x, i, ':'))
         return -1;
      i = scanDigits(x, i + 1, 2);
      if (i < 0 || ! charIs(x, i, ':'))
         return -1;
      return scanDigits(x, i + 1, 2);
   }

   private boolean isValidUniqueItems(Collection<?> x) {
      if (uniqueItems && ! (x instanceof Set)) {
         var s = new HashSet<>();
         for (var o : x)
            if (! s.add(o))
               return false;
      }
      return true;
   }

   private boolean isValidUniqueItems(Object x) {
      if (uniqueItems) {
         var s = new HashSet<>();
         for (var i = 0; i < Array.getLength(x); i++) {
            var o = Array.get(x, i);
            if (! s.add(o))
               return false;
         }
      }
      return true;
   }

   private static boolean isValidUri(String x) {
      // RFC 3986 URI validation
      try {
         new java.net.URI(x);
         // Mirrors prefix match ^[a-zA-Z][a-zA-Z0-9+.-]*:.* (.* permits an empty trailing, non-line-terminator part).
         return isValidScheme(x, false);
      } catch (Exception e) {
         return false;
      }
   }

   private static boolean isValidUriReference(String x) {
      // RFC 3986 URI reference (can be relative)
      try {
         new java.net.URI(x);
         return true;
      } catch (Exception e) {
         return false;
      }
   }

   private static boolean isValidUriTemplate(String x) {
      // RFC 6570 URI Template validation (simplified) (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors full match ^[^\s]*$ - every char must be a non-whitespace char (\s = ASCII whitespace).
      for (var i = 0; i < x.length(); i++)
         if (isRegexWhitespace(x.charAt(i)))
            return false;
      return true;
   }

   private static boolean isValidUuid(String x) {
      // RFC 4122 UUID validation (programmatic to avoid regex recompilation per HTTP-part value).
      // Mirrors full match ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$.
      if (x.length() != 36)
         return false;
      for (var i = 0; i < 36; i++) {
         var c = x.charAt(i);
         if (i == 8 || i == 13 || i == 18 || i == 23) {
            if (c != '-')
               return false;
         } else if (! isAsciiHexDigit(c)) {
            return false;
         }
      }
      return true;
   }

   private static boolean resolve(Boolean b) {
      return b != null && b;
   }
}