// ***************************************************************************************************************************
// * 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.httppart;

import static org.apache.juneau.internal.StringUtils.*;
import java.lang.annotation.*;
import java.lang.reflect.*;
import java.util.*;
import java.util.regex.*;

import org.apache.juneau.*;
import org.apache.juneau.http.annotation.*;
import org.apache.juneau.jsonschema.annotation.Schema;
import org.apache.juneau.jsonschema.annotation.Items;
import org.apache.juneau.jsonschema.annotation.SubItems;
import org.apache.juneau.reflect.*;
import org.apache.juneau.httppart.HttpPartSchema.*;
import org.apache.juneau.httppart.HttpPartSchema.Type;
import org.apache.juneau.utils.*;

/**
 * The builder class for creating {@link HttpPartSchema} objects.
 *
 */
public class HttpPartSchemaBuilder {
   String name, _default;
   Set<Integer> codes;
   Set<String> _enum;
   Boolean allowEmptyValue, exclusiveMaximum, exclusiveMinimum, required, uniqueItems, skipIfEmpty;
   CollectionFormat collectionFormat = CollectionFormat.NO_COLLECTION_FORMAT;
   Type type = Type.NO_TYPE;
   Format format = Format.NO_FORMAT;
   Pattern pattern;
   Number maximum, minimum, multipleOf;
   Long maxLength, minLength, maxItems, minItems, maxProperties, minProperties;
   Map<String,HttpPartSchemaBuilder> properties;
   HttpPartSchemaBuilder items, additionalProperties;
   boolean noValidate;
   Class<? extends HttpPartParser> parser;
   Class<? extends HttpPartSerializer> serializer;

   /**
    * 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);
   }

   HttpPartSchemaBuilder apply(Class<? extends Annotation> c, ParamInfo mpi) {
      apply(c, mpi.getParameterType().innerType());
      for (Annotation a : mpi.getDeclaredAnnotations())
         if (c.isInstance(a))
            apply(a);
      return this;
   }

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

   HttpPartSchemaBuilder apply(Class<? extends Annotation> c, java.lang.reflect.Type t) {
      if (t instanceof Class<?>) {
         ClassInfo ci = ClassInfo.of((Class<?>)t);
         for (Annotation a : ci.getAnnotationsParentFirst(c))
            apply(a);
      } else if (Value.isType(t)) {
         apply(c, Value.getParameterType(t));
      }
      return this;
   }

   /**
    * Apply the specified annotation to this schema.
    *
    * @param a The annotation to apply.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder apply(Annotation a) {
      if (a instanceof Body)
         apply((Body)a);
      else if (a instanceof Header)
         apply((Header)a);
      else if (a instanceof FormData)
         apply((FormData)a);
      else if (a instanceof Query)
         apply((Query)a);
      else if (a instanceof Path)
         apply((Path)a);
      else if (a instanceof Response)
         apply((Response)a);
      else if (a instanceof ResponseHeader)
         apply((ResponseHeader)a);
      else if (a instanceof HasQuery)
         apply((HasQuery)a);
      else if (a instanceof HasFormData)
         apply((HasFormData)a);
      else if (a instanceof Schema)
         apply((Schema)a);
      else
         throw new RuntimeException("HttpPartSchemaBuilder.apply(@"+a.getClass().getSimpleName()+") not defined");
      return this;
   }

   HttpPartSchemaBuilder apply(Body a) {
      required(a.required());
      allowEmptyValue(! a.required());
      apply(a.schema());
      return this;
   }

   HttpPartSchemaBuilder apply(Header a) {
      name(a.value());
      name(a.name());
      required(a.required());
      type(a.type());
      format(a.format());
      allowEmptyValue(a.allowEmptyValue());
      items(a.items());
      collectionFormat(a.collectionFormat());
      _default(a._default().length == 0 ? null : joinnl(a._default()));
      maximum(HttpPartSchema.toNumber(a.maximum()));
      exclusiveMaximum(a.exclusiveMaximum());
      minimum(HttpPartSchema.toNumber(a.minimum()));
      exclusiveMinimum(a.exclusiveMinimum());
      maxLength(a.maxLength());
      minLength(a.minLength());
      pattern(a.pattern());
      maxItems(a.maxItems());
      minItems(a.minItems());
      uniqueItems(a.uniqueItems());
      _enum(HttpPartSchema.toSet(a._enum()));
      multipleOf(HttpPartSchema.toNumber(a.multipleOf()));
      skipIfEmpty(a.skipIfEmpty());
      parser(a.parser());
      serializer(a.serializer());
      return this;
   }

   HttpPartSchemaBuilder apply(ResponseHeader a) {
      name(a.value());
      name(a.name());
      codes(a.code());
      type(a.type());
      format(a.format());
      items(a.items());
      collectionFormat(a.collectionFormat());
      _default(a._default().length == 0 ? null : joinnl(a._default()));
      maximum(HttpPartSchema.toNumber(a.maximum()));
      exclusiveMaximum(a.exclusiveMaximum());
      minimum(HttpPartSchema.toNumber(a.minimum()));
      exclusiveMinimum(a.exclusiveMinimum());
      maxLength(a.maxLength());
      minLength(a.minLength());
      pattern(a.pattern());
      maxItems(a.maxItems());
      minItems(a.minItems());
      uniqueItems(a.uniqueItems());
      _enum(HttpPartSchema.toSet(a._enum()));
      multipleOf(HttpPartSchema.toNumber(a.multipleOf()));
      allowEmptyValue(false);
      serializer(a.serializer());
      return this;
   }

   HttpPartSchemaBuilder apply(FormData a) {
      name(a.value());
      name(a.name());
      required(a.required());
      type(a.type());
      format(a.format());
      allowEmptyValue(a.allowEmptyValue());
      items(a.items());
      collectionFormat(a.collectionFormat());
      _default(a._default().length == 0 ? null : joinnl(a._default()));
      maximum(HttpPartSchema.toNumber(a.maximum()));
      exclusiveMaximum(a.exclusiveMaximum());
      minimum(HttpPartSchema.toNumber(a.minimum()));
      exclusiveMinimum(a.exclusiveMinimum());
      maxLength(a.maxLength());
      minLength(a.minLength());
      pattern(a.pattern());
      maxItems(a.maxItems());
      minItems(a.minItems());
      uniqueItems(a.uniqueItems());
      _enum(HttpPartSchema.toSet(a._enum()));
      multipleOf(HttpPartSchema.toNumber(a.multipleOf()));
      skipIfEmpty(a.skipIfEmpty());
      parser(a.parser());
      serializer(a.serializer());
      return this;
   }

   HttpPartSchemaBuilder apply(Query a) {
      name(a.value());
      name(a.name());
      required(a.required());
      type(a.type());
      format(a.format());
      allowEmptyValue(a.allowEmptyValue());
      items(a.items());
      collectionFormat(a.collectionFormat());
      _default(a._default().length == 0 ? null : joinnl(a._default()));
      maximum(HttpPartSchema.toNumber(a.maximum()));
      exclusiveMaximum(a.exclusiveMaximum());
      minimum(HttpPartSchema.toNumber(a.minimum()));
      exclusiveMinimum(a.exclusiveMinimum());
      maxLength(a.maxLength());
      minLength(a.minLength());
      pattern(a.pattern());
      maxItems(a.maxItems());
      minItems(a.minItems());
      uniqueItems(a.uniqueItems());
      _enum(HttpPartSchema.toSet(a._enum()));
      multipleOf(HttpPartSchema.toNumber(a.multipleOf()));
      skipIfEmpty(a.skipIfEmpty());
      parser(a.parser());
      serializer(a.serializer());
      return this;
   }

   HttpPartSchemaBuilder apply(Path a) {
      name(a.value());
      name(a.name());
      type(a.type());
      format(a.format());
      items(a.items());
      allowEmptyValue(a.allowEmptyValue());
      collectionFormat(a.collectionFormat());
      maximum(HttpPartSchema.toNumber(a.maximum()));
      exclusiveMaximum(a.exclusiveMaximum());
      minimum(HttpPartSchema.toNumber(a.minimum()));
      exclusiveMinimum(a.exclusiveMinimum());
      maxLength(a.maxLength());
      minLength(a.minLength());
      pattern(a.pattern());
      maxItems(a.maxItems());
      minItems(a.minItems());
      uniqueItems(a.uniqueItems());
      _enum(HttpPartSchema.toSet(a._enum()));
      multipleOf(HttpPartSchema.toNumber(a.multipleOf()));
      parser(a.parser());
      serializer(a.serializer());

      // Path remainder always allows empty value.
      if (startsWith(name, '/'))
         allowEmptyValue();
      else
         required(true);

      return this;
   }

   HttpPartSchemaBuilder apply(Response a) {
      codes(a.value());
      codes(a.code());
      required(false);
      allowEmptyValue(true);
      serializer(a.partSerializer());
      parser(a.partParser());
      apply(a.schema());
      return this;
   }

   HttpPartSchemaBuilder apply(Items a) {
      type(a.type());
      format(a.format());
      items(a.items());
      collectionFormat(a.collectionFormat());
      _default(a._default().length == 0 ? null : joinnl(a._default()));
      maximum(HttpPartSchema.toNumber(a.maximum()));
      exclusiveMaximum(a.exclusiveMaximum());
      minimum(HttpPartSchema.toNumber(a.minimum()));
      exclusiveMinimum(a.exclusiveMinimum());
      maxLength(a.maxLength());
      minLength(a.minLength());
      pattern(a.pattern());
      maxItems(a.maxItems());
      minItems(a.minItems());
      uniqueItems(a.uniqueItems());
      _enum(HttpPartSchema.toSet(a._enum()));
      multipleOf(HttpPartSchema.toNumber(a.multipleOf()));
      return this;
   }

   HttpPartSchemaBuilder apply(SubItems a) {
      type(a.type());
      format(a.format());
      items(HttpPartSchema.toObjectMap(a.items()));
      collectionFormat(a.collectionFormat());
      _default(a._default().length == 0 ? null : joinnl(a._default()));
      maximum(HttpPartSchema.toNumber(a.maximum()));
      exclusiveMaximum(a.exclusiveMaximum());
      minimum(HttpPartSchema.toNumber(a.minimum()));
      exclusiveMinimum(a.exclusiveMinimum());
      maxLength(a.maxLength());
      minLength(a.minLength());
      pattern(a.pattern());
      maxItems(a.maxItems());
      minItems(a.minItems());
      uniqueItems(a.uniqueItems());
      _enum(HttpPartSchema.toSet(a._enum()));
      multipleOf(HttpPartSchema.toNumber(a.multipleOf()));
      return this;
   }

   HttpPartSchemaBuilder apply(Schema a) {
      type(a.type());
      format(a.format());
      items(a.items());
      collectionFormat(a.collectionFormat());
      _default(a._default().length == 0 ? null : joinnl(a._default()));
      maximum(HttpPartSchema.toNumber(a.maximum()));
      exclusiveMaximum(a.exclusiveMaximum());
      minimum(HttpPartSchema.toNumber(a.minimum()));
      exclusiveMinimum(a.exclusiveMinimum());
      maxLength(a.maxLength());
      minLength(a.minLength());
      pattern(a.pattern());
      maxItems(a.maxItems());
      minItems(a.minItems());
      uniqueItems(a.uniqueItems());
      _enum(HttpPartSchema.toSet(a._enum()));
      multipleOf(HttpPartSchema.toNumber(a.multipleOf()));
      maxProperties(a.maxProperties());
      minProperties(a.minProperties());
      properties(HttpPartSchema.toObjectMap(a.properties()));
      additionalProperties(HttpPartSchema.toObjectMap(a.additionalProperties()));
      return this;
   }

   HttpPartSchemaBuilder apply(HasQuery a) {
      name(a.value());
      name(a.name());
      return this;
   }

   HttpPartSchemaBuilder apply(HasFormData a) {
      name(a.value());
      name(a.name());
      return this;
   }

   HttpPartSchemaBuilder apply(ObjectMap m) {
      if (m != null && ! m.isEmpty()) {
         _default(m.getString("default"));
         _enum(HttpPartSchema.toSet(m.getString("enum")));
         allowEmptyValue(m.getBoolean("allowEmptyValue"));
         exclusiveMaximum(m.getBoolean("exclusiveMaximum"));
         exclusiveMinimum(m.getBoolean("exclusiveMinimum"));
         required(m.getBoolean("required"));
         uniqueItems(m.getBoolean("uniqueItems"));
         collectionFormat(m.getString("collectionFormat"));
         type(m.getString("type"));
         format(m.getString("format"));
         pattern(m.getString("pattern"));
         maximum(m.get("maximum", Number.class));
         minimum(m.get("minimum", Number.class));
         multipleOf(m.get("multipleOf", Number.class));
         maxItems(m.get("maxItems", Long.class));
         maxLength(m.get("maxLength", Long.class));
         maxProperties(m.get("maxProperties", Long.class));
         minItems(m.get("minItems", Long.class));
         minLength(m.get("minLength", Long.class));
         minProperties(m.get("minProperties", Long.class));

         items(m.getObjectMap("items"));
         properties(m.getObjectMap("properties"));
         additionalProperties(m.getObjectMap("additionalProperties"));

         apply(m.getObjectMap("schema", null));
      }
      return this;
   }

   /**
    * <mk>name</mk> field.
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder name(String value) {
      if (isNotEmpty(value))
         name = value;
      return this;
   }

   /**
    * <mk>httpStatusCode</mk> key.
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerResponsesObject Responses}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if <jk>null</jk> or an empty array.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder codes(int[] value) {
      if (value != null && value.length != 0)
         for (int v : value)
            code(v);
      return this;
   }

   /**
    * <mk>httpStatusCode</mk> key.
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerResponsesObject Responses}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <c>0</c>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder code(int value) {
      if (value != 0) {
         if (codes == null)
            codes = new TreeSet<>();
         codes.add(value);
      }
      return this;
   }

   /**
    * <mk>required</mk> field.
    *
    * <p>
    * Determines whether the parameter is mandatory.
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder required(String value) {
      required = resolve(value, required);
      return this;
   }

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

   /**
    * <mk>type</mk> field.
    *
    * <p>
    * The type of the parameter.
    *
    * <p>
    * The possible values are:
    * <ul class='spaced-list'>
    *    <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 ObjectList}.
    *    <li>
    *       <js>"object"</js>
    *       <br>Parameter must be a map or bean.
    *       <br>If parameter is <c>Object</c>, creates an {@link ObjectMap}.
    *       <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>
    *
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerSecuritySchemeObject SecurityScheme}
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='extlink'>{@doc SwaggerDataTypes}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or empty.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder type(String value) {
      try {
         if (isNotEmpty(value))
            type = Type.fromString(value);
      } catch (Exception e) {
         throw new ContextRuntimeException("Invalid value ''{0}'' passed in as type value.  Valid values: {1}", value, Type.values());
      }
      return this;
   }

   /**
    * <mk>format</mk> field.
    *
    * <p>
    * The extending format for the previously mentioned {@doc SwaggerParameterTypes parameter type}.
    *
    * <p>
    * The possible values are:
    * <ul class='spaced-list'>
    *    <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>
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='extlink'>{@doc SwaggerDataTypeFormats}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or empty.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder format(String value) {
      try {
         if (isNotEmpty(value))
            format = Format.fromString(value);
      } catch (Exception e) {
         throw new ContextRuntimeException("Invalid value ''{0}'' passed in as format value.  Valid values: {1}", value, Format.values());
      }
      return this;
   }

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder allowEmptyValue(String value) {
      allowEmptyValue = resolve(value, allowEmptyValue);
      return this;
   }

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

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or empty.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder items(HttpPartSchemaBuilder value) {
      if (value != null)
         this.items = value;
      return this;
   }

   HttpPartSchemaBuilder items(ObjectMap value) {
      if (value != null && ! value.isEmpty())
         items = HttpPartSchema.create().apply(value);
      return this;
   }

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

   HttpPartSchemaBuilder items(SubItems value) {
      if (! AnnotationUtils.empty(value))
         items = HttpPartSchema.create().apply(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>.
    *
    * <br>Possible values are:
    * <ul class='spaced-list'>
    *    <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>
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </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.
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or empty.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder collectionFormat(String value) {
      try {
         if (isNotEmpty(value))
            this.collectionFormat = CollectionFormat.fromString(value);
      } catch (Exception e) {
         throw new ContextRuntimeException("Invalid value ''{0}'' passed in as collectionFormat value.  Valid values: {1}", value, CollectionFormat.values());
      }
      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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder _default(String value) {
      if (value != null)
         this._default = value;
      return this;
   }

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder maximum(Number value) {
      if (value != null)
         this.maximum = value;
      return this;
   }

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder exclusiveMaximum(String value) {
      exclusiveMaximum = resolve(value, exclusiveMaximum);
      return this;
   }

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

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder minimum(Number value) {
      if (value != null)
         this.minimum = value;
      return this;
   }

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder exclusiveMinimum(String value) {
      exclusiveMinimum = resolve(value, exclusiveMinimum);
      return this;
   }

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

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder maxLength(String value) {
      maxLength = resolve(value, maxLength);
      return this;
   }

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder minLength(String value) {
      minLength = resolve(value, minLength);
      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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or empty.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder pattern(String value) {
      try {
         if (isNotEmpty(value))
            this.pattern = Pattern.compile(value);
      } catch (Exception e) {
         throw new ContextRuntimeException(e, "Invalid value {0} passed in as pattern value.  Must be a valid regular expression.", 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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder maxItems(String value) {
      maxItems = resolve(value, maxItems);
      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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder minItems(String value) {
      minItems = resolve(value, minItems);
      return this;
   }

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder uniqueItems(String value) {
      uniqueItems = resolve(value, uniqueItems);
      return this;
   }

   /**
    * <mk>uniqueItems</mk> field.
    *
    * <p>
    * Shortcut for calling <code>uniqueItems(<jk>true</jk>);</code>.
    *
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder uniqueItems() {
      return uniqueItems(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 (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder skipIfEmpty(String value) {
      skipIfEmpty = resolve(value, skipIfEmpty);
      return this;
   }

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

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or an empty set.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder _enum(Set<String> value) {
      if (value != null && ! value.isEmpty())
         this._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 (for method chaining).
    */
   public HttpPartSchemaBuilder _enum(String...values) {
      return _enum(new ASet<String>().appendAll(values));
   }

   /**
    * <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>{@doc SwaggerParameterObject Parameter}
    *    <li>{@doc SwaggerSchemaObject Schema}
    *    <li>{@doc SwaggerItemsObject Items}
    *    <li>{@doc SwaggerHeaderObject Header}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder multipleOf(Number value) {
      if (value != null)
         this.multipleOf = value;
      return this;
   }

   /**
    * <mk>mapProperties</mk> field.
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerSchemaObject Schema}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or <c>-1</c>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder maxProperties(String value) {
      maxProperties = resolve(value, maxProperties);
      return this;
   }

   /**
    * <mk>minProperties</mk> field.
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerSchemaObject Schema}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk>.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder 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 (for method chaining).
    */
   public HttpPartSchemaBuilder minProperties(String value) {
      minProperties = resolve(value, minProperties);
      return this;
   }

   /**
    * <mk>properties</mk> field.
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerSchemaObject Schema}
    * </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 (for method chaining).
    */
   public HttpPartSchemaBuilder property(String key, HttpPartSchemaBuilder value) {
      if ( key != null && value != null) {
         if (properties == null)
            properties = new LinkedHashMap<>();
         properties.put(key, value);
      }
      return this;
   }

   private HttpPartSchemaBuilder properties(ObjectMap value) {
      if (value != null && ! value.isEmpty())
      for (Map.Entry<String,Object> e : value.entrySet())
         property(e.getKey(), HttpPartSchema.create().apply((ObjectMap)e.getValue()));
      return this;
   }

   /**
    * <mk>additionalProperties</mk> field.
    *
    * <p>
    * Applicable to the following Swagger schema objects:
    * <ul>
    *    <li>{@doc SwaggerSchemaObject Schema}
    * </ul>
    *
    * @param value
    *    The new value for this property.
    *    <br>Ignored if value is <jk>null</jk> or empty.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder additionalProperties(HttpPartSchemaBuilder value) {
      if (value != null)
         additionalProperties = value;
      return this;
   }

   private HttpPartSchemaBuilder additionalProperties(ObjectMap value) {
      if (value != null && ! value.isEmpty())
         additionalProperties = HttpPartSchema.create().apply(value);
      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 {@link HttpPartSerializer.Null}.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder serializer(Class<? extends HttpPartSerializer> value) {
      if (value != null && value != HttpPartSerializer.Null.class)
         serializer = value;
      return this;
   }

   /**
    * 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 {@link HttpPartParser.Null}.
    * @return This object (for method chaining).
    */
   public HttpPartSchemaBuilder parser(Class<? extends HttpPartParser> value) {
      if (value != null && value != HttpPartParser.Null.class)
         parser = value;
      return this;
   }

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

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

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

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

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

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