Package org.apache.juneau.bean.mcp.v20260728

Class ElicitSchema

java.lang.Object
org.apache.juneau.bean.mcp.v20260728.ElicitSchema
public class ElicitSchema extends Object
Fluent builder for a restricted elicitation JSON Schema (MCP 2026-07-28 SEP-2322), producing the JsonMap consumed by ElicitRequest.setRequestedSchema(java.util.Map).

The elicitation restricted schema permits only primitive-typed, non-nested top-level properties. There is deliberately no objectField/arrayField method, so a nested/object/array-typed field is a compile-time impossibility, never a runtime-rejected one. build() additionally rejects a handful of structurally-invalid per-field modifier combinations (for example format(String) on a non-string field) with an IllegalStateException, so a handler author gets an immediate, in-process failure rather than a wire-level schema-validation error discovered by the client much later.

Each xxxField(name) call starts a new field and becomes the target of every subsequent modifier call (title(String), description(String), etc.) until the next xxxField(...) call. Re-declaring a field under a name already used by an earlier xxxField(...) call replaces that field's definition entirely, silently discarding any per-field modifiers already applied to it (last-field-wins). minLength(int)/maxLength(int) are additional string-only per-field modifiers, alongside format(String). required(String...) is a separate, builder-level (not per-field) call that marks one or more field names required, emitting a top-level "required":[...] array; unlike the per-field modifiers, it is not tied to the most-recently-started field, is order-independent with respect to xxxField(...) (a name may be marked required before or after the field it names is (re)declared, and a redeclaration of that field does not discard the marking), and may be called any time, with an unknown name validated only at build() time.

Example:

JsonMap schema = ElicitSchema.create() .booleanField("confirm").title("Confirm") .build();

  • Method Details

    • create

      public static ElicitSchema create()
      Creates a new, empty schema builder.
      Returns:
      A new builder. Never null.

    • stringField

      public ElicitSchema stringField(String name)
      Starts a string-typed field.
      Parameters:
      name - The property name. Must not be null or blank.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If name is null or blank.

    • numberField

      public ElicitSchema numberField(String name)
      Starts a number-typed (floating-point) field.
      Parameters:
      name - The property name. Must not be null or blank.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If name is null or blank.

    • integerField

      public ElicitSchema integerField(String name)
      Starts an integer-typed field.
      Parameters:
      name - The property name. Must not be null or blank.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If name is null or blank.

    • booleanField

      public ElicitSchema booleanField(String name)
      Starts a boolean-typed field.
      Parameters:
      name - The property name. Must not be null or blank.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If name is null or blank.

    • enumField

      public ElicitSchema enumField(String name, String... values)
      Starts a closed-choice string-typed field restricted to values (wire shape: type:"string", enum:[...]). Pair with enumNames(String...) for parallel display labels.
      Parameters:
      name - The property name. Must not be null or blank.
      values - The allowed values. Must not be null or empty, and must not contain a null element.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If name is null or blank, or values is null, empty, or contains a null element.

    • title

      public ElicitSchema title(String value)
      Sets the display title of the most-recently-started field.
      Parameters:
      value - The title. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • description

      public ElicitSchema description(String value)
      Sets the description of the most-recently-started field.
      Parameters:
      value - The description. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • format

      public ElicitSchema format(String value)
      Sets the string-subtype format of the most-recently-started field (for example email, uri, date, date-time). Applying this to a non-string field is rejected at build() time.
      Parameters:
      value - The format token. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • minLength

      public ElicitSchema minLength(int value)
      Sets the minimum UTF-16 code-unit length of the most-recently-started string field. Applying this to a non-string field, to an enumField(String, String...) (a closed-choice field, where a length constraint is meaningless), or a value that is negative or exceeds a previously-/subsequently-set maxLength(int), is rejected at build() time.
      Parameters:
      value - The minimum length.
      Returns:
      This object (for method chaining).

    • maxLength

      public ElicitSchema maxLength(int value)
      Sets the maximum UTF-16 code-unit length of the most-recently-started string field. Applying this to a non-string field, to an enumField(String, String...) (a closed-choice field, where a length constraint is meaningless), or a value that is negative or less than a previously-/subsequently-set minLength(int), is rejected at build() time.
      Parameters:
      value - The maximum length.
      Returns:
      This object (for method chaining).

    • min

      public ElicitSchema min(Number value)
      Sets the minimum value of the most-recently-started number/integer field. Applying this to a field of any other type is rejected at build() time.
      Parameters:
      value - The minimum. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • max

      public ElicitSchema max(Number value)
      Sets the maximum value of the most-recently-started number/integer field. Applying this to a field of any other type is rejected at build() time.
      Parameters:
      value - The maximum. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • defaultValue

      public ElicitSchema defaultValue(Object value)
      Sets the default value of the most-recently-started field.

      Named defaultValue, not default (a reserved Java keyword) — the wire schema property this writes is still literally "default".

      Parameters:
      value - The default value. Can be null.
      Returns:
      This object (for method chaining).

    • enumNames

      public ElicitSchema enumNames(String... values)
      Sets parallel display labels for the most-recently-started enumField(String, String...)'s values. Applying this to a field with no enum values is rejected at build() time.
      Parameters:
      values - The display labels, parallel in order to the field's enum values. Must not be null or empty, must not contain a null element, and (when the current field already carries enum values) must be the same length as those values.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If values is null, empty, or contains a null element, or if its length does not match the current field's existing enum values' length.

    • required

      public ElicitSchema required(String... names)
      Marks one or more already-added field names required, contributing to the built schema's top-level "required":[...] array.

      Unlike the per-field modifiers (title(String), etc.), this is a builder-level, not per-field, call — it is not tied to the most-recently-started field and may name any field(s) already added via an earlier xxxField(...) call, in any order. May be called more than once; each call adds to the previously-marked names (not replaced). Naming a field not (yet) added is rejected at build() time, not here, since a later xxxField(...) call may still add it.

      Parameters:
      names - The field names to mark required. Must not be null or empty, and must not contain a null element.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If names is null, empty, or contains a null element.

    • build

      public JsonMap build()
      Validates every field's modifier combination (and the builder-level required(String...) marking) and builds the final restricted-schema JsonMap ({"type":"object","properties":{...},"required":[...]}, the last member present only if required(String...) was called at least once).
      Returns:
      The built schema, ready for ElicitRequest.setRequestedSchema(java.util.Map).
      Throws:
      IllegalStateException - If no field was ever added, if any field carries a structurally-invalid modifier combination, or if required(String...) named a field that was never added.