Skip to content

SEP-1330: Elicitation Enum Schema Improvements and Standards Compliance #1330

Description

@chughtapan

Preamble

Title: Elicitation Enum Schema Improvements and Standards Compliance
Author(s): Cliff Hall (@cliffhall), Tapan Chugh (@chughtapan)
Track: Standards Track
Status: Proposal
Created: 2025-08-11

Abstract

This SEP proposes improvements to enum schema definitions in MCP, deprecating the non-standard enumNames property in favor of JSON Schema-compliant patterns, and introducing additional support for multi-select enum schemas in addition to single choice schemas. The new schemas have been validated against the JSON specification.

Schema Changes: #1148
Typescript SDK Changes: modelcontextprotocol/typescript-sdk#1077
Python SDK Changes: modelcontextprotocol/python-sdk#1246
Client Implementation: https://github.com/evalstate/fast-agent/pull/324/files
Working Demo: https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta

Motivation

The existing schema for enums uses a non-standard approach to adding titles to enumerated values. It also limits use of enums in Elicitation (and any other schema object that should adopt EnumSchema in the future) to a single selection model. It is a common pattern to ask the user to select multiple entries. In the UI, this amounts to the difference between using checkboxes or radio buttons.

For these reasons, we propose the following non-breaking minor improvements to the EnumSchema for improving user and developer experience.

  • Keep the existing EnumSchema as "Legacy"
    • It uses a non-standard approach for adding titles to enumerated values
    • Mark it as Legacy but still support it for now.
    • As per @dsp-ant When we have a proper deprecation strategy, we'll mark it deprecated
  • Introduce the distinction between Untitled and Titled enums.
    • If the enumerated values are sufficient, no separate title need be specified for each value.
    • If the enumerated values are not optimal for display, a title may be specified for each value.
  • Introduce the distinction between Single and Multi-select enums.
    • If only one value can be selected, a Single select schema can be used
    • If more than one value can be selected, a Multi-select schema can be used
  • In ElicitResponse, add array as an additionalProperty type
    • Allows multiple selection of enumerated values to be returned to the server

Specification

1. Mark Current EnumSchema with Non-Standard enumNames Property as "Legacy"

The current MCP specification uses a non-standard enumNames property for providing display names for enum values. We propose to mark enumNames property as legacy, suggest using TitledSingleSelectEnum, a standards compliant enum type we define below.

// Continue to support the current EnumSchema as Legacy

/**
  * Legacy: Use TitledSingleSelectEnumSchema instead. 
  * This interface will be removed in a future version.
  */
export interface LegacyEnumSchema {
  type: "string";
  title?: string;
  description?: string;
  enum: string[];
  enumNames?: string[]; // Titles for enum values (non-standard, legacy)
}

2. Define Single Selection Enums (with Titled and Untitled varieties)

Enums may or may not need titles. The enumerated values may be human readable and fine for display. In which case an untitled implementation using the JSON Schema keyword enum is simpler. Adding titles requires the enum array to be replaced with an array of objects using const and title.

// Single select enum without titles 
export type UntitledSingleSelectEnumSchema = {
      type: "string";
      title?: string;
      description?: string;
      enum: string[]; // Plain enum without titles
    };

// Single select enum with titles
export type TitledSingleSelectEnumSchema = {
      type: "string";
      title?: string;
      description?: string;
      oneOf: Array<{
        const: string; // Enum value
        title: string; // Display name for enum value
      }>;
    };

// Combined single selection enumeration
export type SingleSelectEnumSchema = 
  | UntitledSingleSelectEnumSchema
  | TitledSingleSelectEnumSchema;

3. Introduce Multiple Selection Enums (with Titled and Untitled varieties)

While elicitation does not support arbitrary JSON types like arrays and objects so clients can display the selection choice easily, multiple selection enumerations can be easily implemented.

// Multiple select enums without titles
export type UntitledMultiSelectEnumSchema = {
      type: "array";
      title?: string;
      description?: string;
      minItems?: number; // Minimum number of items to choose
      maxItems?: number; // Maximum number of items to choose
      items: {
        type: "string";
        enum: string[]; // Plain enum without titles
      };
    };	

// Multiple select enums with titles
export type TitledMultiSelectEnumSchema = {
      type: "array";
      title?: string;
      description?: string;
      minItems?: number; // Minimum number of items to choose
      maxItems?: number; // Maximum number of items to choose
      items: {
        oneOf: Array<{
          const: string; // Enum value
          title: string; // Display name for enum value
        }>;
      };
    };	

// Combined Multiple select enumeration
export type MultiSelectEnumSchema = 
  | UntitledMultiSelectEnumSchema
  | TitledMultiSelectEnumSchema;

4. Combine All Varieties as EnumSchema

The final EnumSchema rolls up the legacy, multi-select, and single-select schemas as one, defined as:

// Combined legacy, multiple, and single select enumeration
export type EnumSchema = 
  | SingleSelectEnumSchema 
  | MultiSelectEnumSchema 
  | LegacyEnumSchema;

5. Extend ElicitResult

The current elicitation result schema only allows returning primitive types. We extend this to include string arrays for MultiSelectEnums:

export interface ElicitResult extends Result {
  action: "accept" | "decline" | "cancel";
  content?: { [key: string]: string | number | boolean | string[] }; // string[] is new
}

Instance Schema Examples

Single-Select Without Titles (No change)

{
  "type": "string",
  "title": "Color Selection",
  "description": "Choose your favorite color",
  "enum": ["Red", "Green", "Blue"],
  "default": "Green"
}

Legacy Single Select With Titles

{
  "type": "string",
  "title": "Color Selection",
  "description": "Choose your favorite color",
  "enum": ["#FF0000", "#00FF00", "#0000FF"],
  “enumNames”: ["Red", "Green", "Blue"],
  "default": "Green"
}

Single-Select with Titles

{
 "type": "string",
 "title": "Color Selection",
 "description": "Choose your favorite color",
 "oneOf": [
   { "const": "#FF0000", "title": "Red" },
   { "const": "#00FF00", "title": "Green" },
   { "const": "#0000FF", "title": "Blue" }
 ],
 "default": "#00FF00"
}

Multi-Select Without Titles

{
  "type": "array",
  "title": "Color Selection",
  "description": "Choose your favorite colors",
  "minItems": 1,
  "maxItems": 3,
  "items": {
    "type": "string",
    "enum": ["Red", "Green", "Blue"]
  },
  "default": ["Green"]
}

Multi-Select with Titles

{
  "type": "array",
  "title": "Color Selection",
  "description": "Choose your favorite colors",
  "minItems": 1,
  "maxItems": 3,
  "items": {
    "anyOf": [
      { "const": "#FF0000", "title": "Red" },
      { "const": "#00FF00", "title": "Green" },
      { "const": "#0000FF", "title": "Blue" }
    ]
  },
  "default": ["Green"]
}

Rationale

  1. Standards Compliance: Aligns with official JSON Schema specification. Standard patterns work with existing JSON Schema validators
  2. Flexibility: Supports both plain enums and enums with display names for single and multiple choice enums.
  3. Client Implementation: shows that the additional overhead of implementing a group of checkboxes v/s a single checkbox is minimal: https://github.com/evalstate/fast-agent/pull/324/files

Backwards Compatibility

The LegacyEnumSchema type maintains backwards compatible during the migration period. Existing implementations using enumNames will continue to work until a protocol-wide deprecation strategy is implemented, and this schema is removed.

Reference Implementation

Schema Changes: #1148
Typescript SDK Changes: modelcontextprotocol/typescript-sdk#1077
Python SDK Changes: modelcontextprotocol/python-sdk#1246
Client Implementation: https://github.com/evalstate/fast-agent/pull/324/files
Working Demo: https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta

Security Considerations

No security implications identified. This change is purely about schema structure and standards compliance.

Appendix

Validations

Using stored validations in the JSON Schema Validator at https://www.jsonschemavalidator.net/ we validate:

  • All of the example instance schemas from this document against the proposed JSON meta-schema EnumSchema in the next section.
  • Valid and invalid values against the example instance schemas from this document.

Legacy Single Selection

Single Selection

Multiple Selection

JSON meta-schema

This is our proposal for the replacement of the current EnumSchema in the specification’s schema.json.

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "definitions": {
    // New Definitions Follow
    "UntitledSingleSelectEnumSchema": {
      "type": "object",
      "properties": {
        "type": { "const": "string" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "enum": {
          "type": "array",
          "items": { "type": "string" },
          "minItems": 1
        }
      },
      "required": ["type", "enum"],
      "additionalProperties": false
    },
    
    "UntitledMultiSelectEnumSchema": {
      "type": "object",
      "properties": {
        "type": { "const": "array" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "minItems": {
          "type": "number",
          "minimum": 0
        },
        "maxItems": {
          "type": "number",
          "minimum": 0
        },
        "items": {
          "type": "object",
          "properties": {
            "type": { "const": "string" },
            "enum": {
              "type": "array",
              "items": { "type": "string" },
              "minItems": 1
            }
          },
          "required": ["type", "enum"],
          "additionalProperties": false
        }
      },
      "required": ["type", "items"],
      "additionalProperties": false
    },
    
    "TitledSingleSelectEnumSchema": {
      "type": "object",
      "required": ["type", "anyOf"],
      "properties": {
        "type": { "const": "string" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "anyOf": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["const", "title"],
            "properties": {
              "const": { "type": "string" },
              "title": { "type": "string" }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },

    "TitledMultiSelectEnumSchema": {
      "type": "object",
      "required": ["type", "anyOf"],
      "properties": {
        "type": { "const": "array" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "anyOf": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["const", "title"],
            "properties": {
              "const": { "type": "string" },
              "title": { "type": "string" }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
  
    "LegacyEnumSchema": {
      "properties": {
          "type": {
              "type": "string",
              "const": "string",
          },
          "title": {  "type": "string" },
          "description": { "type": "string" },
          "enum": {
              "type": "array",
              "items": { "type": "string" },
          },
          "enumNames": {
              "type": "array",
              "items": { "type": "string" },
          },
      },
      "required": [ "enum", "type" ],
      "type": "object"
    },
    
    "EnumSchema": {
      "oneOf": [ 
          {"$ref": "#/definitions/UntitledSingleSelectEnumSchema"}, 
          {"$ref": "#/definitions/UntitledMultiSelectEnumSchema"},
          {"$ref": "#/definitions/TitledSingleSelectEnumSchema"}, 
          {"$ref": "#/definitions/TitledMultiSelectEnumSchema"},
          {"$ref": "#/definitions/LegacyEnumSchema"},
      ]
    }

  }
}

Activity

  1. self-assigned this
    on Aug 12, 2025
  2. changed the title [-]SEP: Elicitation Enum Schema Improvements and Standards Compliance[/-] [+]SEP-1330: Elicitation Enum Schema Improvements and Standards Compliance[/+] on Aug 12, 2025
  3. added
    in-reviewSEP proposal ready for review.
    and removed
    draftSEP proposal with a sponsor.
    on Aug 12, 2025
  4. changed the issue type fromtoon Aug 20, 2025
  5. changed the issue type fromtoon Aug 20, 2025
  6. changed the issue type fromtoon Aug 20, 2025
  7. domdomegg commented on Aug 21, 2025

    @domdomegg
    Member

    I'm generally supportive of this! Moving towards standards compliance seems good, and I can see how this unlocks more capabilities with enums.

    However, I'm concerned about the complexity introduced by having 5 different enum schema types (deprecated + 4 new variants). This seems like it could be confusing for both implementers and users.

    Some ideas to reduce this:

    1. Just have TitledSingleSelectEnumSchema: Start with a single base enum schema that supports optional titles:

      {
        "type": "string",
        "oneOf": [
          { "const": "#FF0000", "title": "Red" },
          { "const": "#00FF00" }  // title is optional
        ]
      }

      For multi-select, users can wrap this in a standard array schema:

      {
        "type": "array",
        "minItems": 1,
        "maxItems": 3,
        "items": {
          "type": "string",
          "oneOf": [
            { "const": "#FF0000", "title": "Red" },
            { "const": "#00FF00", "title": "Green" }
          ]
        }
      }
    2. Alternative: Roll everything into TitledMultiSelectEnumSchema: I'm not sure I see why we can't wrap the thing in an array. But if that's not possible for some reason, I think everything could be modeled as one schema with:

      • items with anyOf with {const, title} objects, where title is optional
      • minItems/maxItems to control single vs multi-select (both set to 1 for single-select)
      • Optional title and description at the top level

      This would give us one schema pattern that handles all cases:

      {
        "type": "array",
        "title": "Color Selection",
        "minItems": 1,
        "maxItems": 1,  // Single select when min=max=1
        "items": {
          "anyOf": [
            { "const": "#FF0000", "title": "Red" },
            { "const": "#00FF00", "title": "Green" }
          ]
        }
      }

    Also a minor suggested correction to the proposal:

    Schema vs Value confusion: The TitledSingleSelectEnumSchema appears to have type: "array" in the TypeScript definition but type: "string" in the JSON examples. This seems incorrect - for single selection, the validated value should be a string, not an array.

  8. cliffhall commented on Aug 21, 2025

    @cliffhall
    Member

    I'm generally supportive of this! Moving towards standards compliance seems good, and I can see how this unlocks more capabilities with enums.

    Thanks, so do we!

    However, I'm concerned about the complexity introduced by having 5 different enum schema types (deprecated + 4 new variants). This seems like it could be confusing for both implementers and users.

    Some ideas to reduce this:

    1. Just have TitledSingleSelectEnumSchema: Start with a single base enum schema that supports optional titles:
      {
      "type": "string",
      "oneOf": [
      { "const": "#FF0000", "title": "Red" },
      { "const": "#00FF00" } // title is optional
      ]
      }

    This would make sense, but for single select without titles, we want to support the enum type. It is valid JSON, and it's what people will go to most of the time when they have a simple enum.

    {
      "type": "string",
      "title": "Color Selection",
      "description": "Choose your favorite color",
      "enum": ["Red", "Green", "Blue"]
    }

    ... is simpler than ...

    {
      "type": "string",
      "title": "Color Selection",
      "description": "Choose your favorite color",
      "oneOf": [
        { "const": "Red"},
        { "const": "Green"}, 
        { "const": "Blue"}
      ]
    }

    We only go to the "oneOf" format when we need to add titles, since that's the only in-spec way to do it.

    For multi-select, users can wrap this in a standard array schema:
    {
    "type": "array",
    "minItems": 1,
    "maxItems": 3,
    "items": {
    "type": "string",
    "oneOf": [
    { "const": "#FF0000", "title": "Red" },
    { "const": "#00FF00", "title": "Green" }
    ]
    }
    }

    That's true, but for enums, we want a title and description, this helps the UI know how to label and describe the thing being chosen. Thus the formal TitledMultiSelectEnumSchema.

    ...I'm not sure I see why we can't wrap the thing in an array.
    Answer directly above ^^^. Inclusion of title and description.

    But if that's not possible for some reason, I think everything could be modeled as one schema with:

    • items with anyOf with {const, title} objects, where title is optional
    • minItems/maxItems to control single vs multi-select (both set to 1 for single-select)
    • Optional title and description at the top level

    This would give us one schema pattern that handles all cases:

    {
    "type": "array",
    "title": "Color Selection",
    "minItems": 1,
    "maxItems": 1, // Single select when min=max=1
    "items": {
    "anyOf": [
    { "const": "#FF0000", "title": "Red" },
    { "const": "#00FF00", "title": "Green" }
    ]
    }
    }

    That would require that a single selection be wrapped in an array. In your example "#FF0000" would not be a valid response, it would have to be ["#FF0000"]. That's obvious shoehorning. Code handling the response has to pluck the response from an array, even though it knows there is only ever going to be one value. Extra tokens === sub-optimal.

    Also a minor suggested correction to the proposal:

    Schema vs Value confusion: The TitledSingleSelectEnumSchema appears to have type: "array" in the TypeScript definition but type: "string" in the JSON examples. This seems incorrect - for single selection, the validated value should be a string, not an array.

    Good catch, thanks! That seems to have worked its way accidentally into our document from previous discussions. I've updated the PR and the schemas in all of the validation links. It is correct in the schema change PR.

    Image
  9. 12 remaining items

  10. cliffhall commented on Oct 15, 2025

    @cliffhall
    Member

    @dsp-ant

    Accepted 8-0 in Core Maintainer meeting. Since we don't have a concept of deprecation in the protocol at the moment, we should not introduce "Deprecated" in the names here.

    As a replacement for DeprecatedEnumSchema we're thinking LegacyTitledEnumSchema. I think that word legacy carries the right vibe. "Tell me you're gonna be deprecated without telling me you're gonna be deprecated." And it adds drills down on what that legacy schema was for.

  11. cliffhall commented on Oct 22, 2025

    @cliffhall
    Member

    @dsp-ant @modelcontextprotocol/core-maintainers

    The changes for this accepted SEP, including the changelog update are now ready for review/merge in: #1148

  12. cliffhall commented on Oct 29, 2025

    @cliffhall
    Member

    @modelcontextprotocol/core-maintainers @dsp-ant

    • We have updated the changelog and made the changes to the spec, schema, docs, and changelog.
    • We have updated Typescript and Python SDK.

    It would be nice to get these reviewed and merged as it has been approved and will be part of the next release.

  13. moved this from Review Batch to Accepted in SEP Review Pipelineon Nov 6, 2025
  14. added this to the DRAFT-2025-11-25 milestone on Nov 10, 2025
  15. added
    acceptedSEP accepted by core maintainers, but still requires final wording and reference implementation.
    on Nov 12, 2025
  16. moved this from Accepted to Final in SEP Review Pipelineon Aug 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

SEPacceptedSEP accepted by core maintainers, but still requires final wording and reference implementation.enhancementNew feature or requestfinalSEP finalized.

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions