René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"SEP-1330: Elicitation Enum Schema Improvements and Standards Compliance","articleBody":"## Preamble\n\n**Title**: Elicitation Enum Schema Improvements and Standards Compliance\n**Author(s)**: Cliff Hall (@cliffhall), Tapan Chugh (@chughtapan)\n**Track**: Standards Track\n**Status**: Proposal\n**Created**: 2025-08-11\n\n## Abstract\n\nThis 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.\n\n**Schema Changes:** https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1148\nTypescript SDK Changes: https://github.com/modelcontextprotocol/typescript-sdk/pull/1077\nPython SDK Changes: https://github.com/modelcontextprotocol/python-sdk/pull/1246\n**Client Implementation:** https://github.com/evalstate/fast-agent/pull/324/files\n**Working Demo:** https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta\n\n## Motivation\n\nThe 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. \n\nFor these reasons, we propose the following non-breaking minor improvements to the `EnumSchema` for improving user and developer experience. \n\n- Keep the existing `EnumSchema` as \"Legacy\"\n     - It uses a non-standard approach for adding titles to enumerated values\n     - Mark it as Legacy but still support it for now. \n     - As per @dsp-ant When we have a proper deprecation strategy, we'll mark it deprecated \n- Introduce the distinction between Untitled and Titled enums.\n     - If the enumerated values are sufficient, no separate title need be specified for each value.\n     - If the enumerated values are not optimal for display, a title may be specified for each value. \n- Introduce the distinction between Single and Multi-select enums. \n     - If only one value can be selected, a Single select schema can be used\n     - If more than one value can be selected, a Multi-select schema can be used\n- In `ElicitResponse`, add array as an `additionalProperty` type \n     - Allows multiple selection of enumerated values to be returned to the server\n\n## Specification\n\n### 1. Mark Current `EnumSchema` with Non-Standard `enumNames` Property as \"Legacy\"\n\nThe 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. \n\n```typescript\n// Continue to support the current EnumSchema as Legacy\n\n/**\n  * Legacy: Use TitledSingleSelectEnumSchema instead. \n  * This interface will be removed in a future version.\n  */\nexport interface LegacyEnumSchema {\n  type: \"string\";\n  title?: string;\n  description?: string;\n  enum: string[];\n  enumNames?: string[]; // Titles for enum values (non-standard, legacy)\n}\n```\n\n### 2. Define Single Selection Enums (with Titled and Untitled varieties)\n\nEnums 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`. \n\n```typescript\n// Single select enum without titles \nexport type UntitledSingleSelectEnumSchema = {\n      type: \"string\";\n      title?: string;\n      description?: string;\n      enum: string[]; // Plain enum without titles\n    };\n\n// Single select enum with titles\nexport type TitledSingleSelectEnumSchema = {\n      type: \"string\";\n      title?: string;\n      description?: string;\n      oneOf: Array\u003c{\n        const: string; // Enum value\n        title: string; // Display name for enum value\n      }\u003e;\n    };\n\n// Combined single selection enumeration\nexport type SingleSelectEnumSchema = \n  | UntitledSingleSelectEnumSchema\n  | TitledSingleSelectEnumSchema;\n```\n\n### 3. Introduce Multiple Selection Enums (with Titled and Untitled varieties)\n\nWhile 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.\n\n```typescript\n// Multiple select enums without titles\nexport type UntitledMultiSelectEnumSchema = {\n      type: \"array\";\n      title?: string;\n      description?: string;\n      minItems?: number; // Minimum number of items to choose\n      maxItems?: number; // Maximum number of items to choose\n      items: {\n        type: \"string\";\n        enum: string[]; // Plain enum without titles\n      };\n    };\t\n\n// Multiple select enums with titles\nexport type TitledMultiSelectEnumSchema = {\n      type: \"array\";\n      title?: string;\n      description?: string;\n      minItems?: number; // Minimum number of items to choose\n      maxItems?: number; // Maximum number of items to choose\n      items: {\n        oneOf: Array\u003c{\n          const: string; // Enum value\n          title: string; // Display name for enum value\n        }\u003e;\n      };\n    };\t\n\n// Combined Multiple select enumeration\nexport type MultiSelectEnumSchema = \n  | UntitledMultiSelectEnumSchema\n  | TitledMultiSelectEnumSchema;\n```\n\n### 4. Combine All Varieties as `EnumSchema`\n\nThe final `EnumSchema` rolls up the legacy, multi-select, and single-select schemas as one, defined as:\n\n```typescript\n// Combined legacy, multiple, and single select enumeration\nexport type EnumSchema = \n  | SingleSelectEnumSchema \n  | MultiSelectEnumSchema \n  | LegacyEnumSchema;\n```\n\n### 5. Extend ElicitResult \n\nThe current elicitation result schema only allows returning primitive types. We extend this to include string arrays for MultiSelectEnums:\n\n```typescript\nexport interface ElicitResult extends Result {\n  action: \"accept\" | \"decline\" | \"cancel\";\n  content?: { [key: string]: string | number | boolean | string[] }; // string[] is new\n}\n```\n\n## Instance Schema Examples\n\n### Single-Select Without Titles (No change)\n\n```json\n{\n  \"type\": \"string\",\n  \"title\": \"Color Selection\",\n  \"description\": \"Choose your favorite color\",\n  \"enum\": [\"Red\", \"Green\", \"Blue\"],\n  \"default\": \"Green\"\n}\n```\n\n### Legacy Single Select With Titles\n\n```json\n{\n  \"type\": \"string\",\n  \"title\": \"Color Selection\",\n  \"description\": \"Choose your favorite color\",\n  \"enum\": [\"#FF0000\", \"#00FF00\", \"#0000FF\"],\n  “enumNames”: [\"Red\", \"Green\", \"Blue\"],\n  \"default\": \"Green\"\n}\n```\n\n### Single-Select with Titles\n\n```json\n{\n \"type\": \"string\",\n \"title\": \"Color Selection\",\n \"description\": \"Choose your favorite color\",\n \"oneOf\": [\n   { \"const\": \"#FF0000\", \"title\": \"Red\" },\n   { \"const\": \"#00FF00\", \"title\": \"Green\" },\n   { \"const\": \"#0000FF\", \"title\": \"Blue\" }\n ],\n \"default\": \"#00FF00\"\n}\n```\n\n### Multi-Select Without Titles\n\n```json\n{\n  \"type\": \"array\",\n  \"title\": \"Color Selection\",\n  \"description\": \"Choose your favorite colors\",\n  \"minItems\": 1,\n  \"maxItems\": 3,\n  \"items\": {\n    \"type\": \"string\",\n    \"enum\": [\"Red\", \"Green\", \"Blue\"]\n  },\n  \"default\": [\"Green\"]\n}\n```\n\n### Multi-Select with Titles \n\n```json\n{\n  \"type\": \"array\",\n  \"title\": \"Color Selection\",\n  \"description\": \"Choose your favorite colors\",\n  \"minItems\": 1,\n  \"maxItems\": 3,\n  \"items\": {\n    \"anyOf\": [\n      { \"const\": \"#FF0000\", \"title\": \"Red\" },\n      { \"const\": \"#00FF00\", \"title\": \"Green\" },\n      { \"const\": \"#0000FF\", \"title\": \"Blue\" }\n    ]\n  },\n  \"default\": [\"Green\"]\n}\n```\n\n## Rationale\n\n1. **Standards Compliance**: Aligns with official JSON Schema specification. Standard patterns work with existing JSON Schema validators\n2. **Flexibility**: Supports both plain enums and enums with display names for single and multiple choice enums.\n3. **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\n\n## Backwards Compatibility\n\nThe `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.\n\n## Reference Implementation\n**Schema Changes:** https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1148\nTypescript SDK Changes: https://github.com/modelcontextprotocol/typescript-sdk/pull/1077\nPython SDK Changes: https://github.com/modelcontextprotocol/python-sdk/pull/1246\n**Client Implementation:** https://github.com/evalstate/fast-agent/pull/324/files\n**Working Demo:** https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta\n\n## Security Considerations\n\nNo security implications identified. This change is purely about schema structure and standards compliance.\n\n## Appendix\n\n### Validations\n\nUsing stored validations in the JSON Schema Validator at https://www.jsonschemavalidator.net/ we validate: \n- All of the example instance schemas from this document against the proposed JSON meta-schema `EnumSchema` in the next section.\n- Valid and invalid values against the example instance schemas from this document.\n\n#### Legacy Single Selection\n\n- `EnumSchema` validating a [legacy single select instance schema with titles](https://www.jsonschemavalidator.net/s/lsK7Bn0C)\n- The legacy titled single select instance schema validating [a correct single selection](https://www.jsonschemavalidator.net/s/GSk7rnRe)\n- The legacy titled single select instance schema validating [an incorrect single selection](https://www.jsonschemavalidator.net/s/3kYvxsVP)\n\n#### Single Selection\n\n- `EnumSchema` validating a [single select instance schema without titles](https://www.jsonschemavalidator.net/s/MBlHW5IQ)\n- `EnumSchema` validating a [single select instance schema with titles](https://www.jsonschemavalidator.net/s/s38xt4JV)\n- The untitled single select instance schema validating [a correct single selection](https://www.jsonschemavalidator.net/s/M0hkYoeG)\n- The untitled single select instance schema invalidating [an incorrect single selection](https://www.jsonschemavalidator.net/s/3Try4BCt)\n- The titled single select instance schema validating [a correct single selection](https://www.jsonschemavalidator.net/s/4oDbv9yt)\n- The titled single select instance schema invalidating [an incorrect single selection](https://www.jsonschemavalidator.net/s/A2KlNzLH)\n\n#### Multiple Selection\n\n- `EnumSchema` validating the [multi-select instance schema without titles](https://www.jsonschemavalidator.net/s/4uc3Ndsq)\n- `EnumSchema` validating the [multi-select instance schema with titles](https://www.jsonschemavalidator.net/s/TmkIqqXI)\n- The untitled multi-select instance schema validating [a correct multiple selection](https://www.jsonschemavalidator.net/s/IE8Bkvtg)\nThe untitled multi-select instance schema validating invalidating[ an incorrect multiple selection](https://www.jsonschemavalidator.net/s/8tlqjUgW)\nThe titled multi-select instance schema validating [a correct multiple selection](https://www.jsonschemavalidator.net/s/Nb1Rw1qa)\nThe titled multi-select instance schema validating invalidating [an incorrect multiple selection](https://www.jsonschemavalidator.net/s/MRfyqrVC)\n\n### JSON meta-schema\n\nThis is our proposal for the replacement of the current `EnumSchema` in the specification’s `schema.json`.\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft-07/schema\",\n  \"definitions\": {\n    // New Definitions Follow\n    \"UntitledSingleSelectEnumSchema\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"type\": { \"const\": \"string\" },\n        \"title\": { \"type\": \"string\" },\n        \"description\": { \"type\": \"string\" },\n        \"enum\": {\n          \"type\": \"array\",\n          \"items\": { \"type\": \"string\" },\n          \"minItems\": 1\n        }\n      },\n      \"required\": [\"type\", \"enum\"],\n      \"additionalProperties\": false\n    },\n    \n    \"UntitledMultiSelectEnumSchema\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"type\": { \"const\": \"array\" },\n        \"title\": { \"type\": \"string\" },\n        \"description\": { \"type\": \"string\" },\n        \"minItems\": {\n          \"type\": \"number\",\n          \"minimum\": 0\n        },\n        \"maxItems\": {\n          \"type\": \"number\",\n          \"minimum\": 0\n        },\n        \"items\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"type\": { \"const\": \"string\" },\n            \"enum\": {\n              \"type\": \"array\",\n              \"items\": { \"type\": \"string\" },\n              \"minItems\": 1\n            }\n          },\n          \"required\": [\"type\", \"enum\"],\n          \"additionalProperties\": false\n        }\n      },\n      \"required\": [\"type\", \"items\"],\n      \"additionalProperties\": false\n    },\n    \n    \"TitledSingleSelectEnumSchema\": {\n      \"type\": \"object\",\n      \"required\": [\"type\", \"anyOf\"],\n      \"properties\": {\n        \"type\": { \"const\": \"string\" },\n        \"title\": { \"type\": \"string\" },\n        \"description\": { \"type\": \"string\" },\n        \"anyOf\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"object\",\n            \"required\": [\"const\", \"title\"],\n            \"properties\": {\n              \"const\": { \"type\": \"string\" },\n              \"title\": { \"type\": \"string\" }\n            },\n            \"additionalProperties\": false\n          }\n        }\n      },\n      \"additionalProperties\": false\n    },\n\n    \"TitledMultiSelectEnumSchema\": {\n      \"type\": \"object\",\n      \"required\": [\"type\", \"anyOf\"],\n      \"properties\": {\n        \"type\": { \"const\": \"array\" },\n        \"title\": { \"type\": \"string\" },\n        \"description\": { \"type\": \"string\" },\n        \"anyOf\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"object\",\n            \"required\": [\"const\", \"title\"],\n            \"properties\": {\n              \"const\": { \"type\": \"string\" },\n              \"title\": { \"type\": \"string\" }\n            },\n            \"additionalProperties\": false\n          }\n        }\n      },\n      \"additionalProperties\": false\n    },\n  \n    \"LegacyEnumSchema\": {\n      \"properties\": {\n          \"type\": {\n              \"type\": \"string\",\n              \"const\": \"string\",\n          },\n          \"title\": {  \"type\": \"string\" },\n          \"description\": { \"type\": \"string\" },\n          \"enum\": {\n              \"type\": \"array\",\n              \"items\": { \"type\": \"string\" },\n          },\n          \"enumNames\": {\n              \"type\": \"array\",\n              \"items\": { \"type\": \"string\" },\n          },\n      },\n      \"required\": [ \"enum\", \"type\" ],\n      \"type\": \"object\"\n    },\n    \n    \"EnumSchema\": {\n      \"oneOf\": [ \n          {\"$ref\": \"#/definitions/UntitledSingleSelectEnumSchema\"}, \n          {\"$ref\": \"#/definitions/UntitledMultiSelectEnumSchema\"},\n          {\"$ref\": \"#/definitions/TitledSingleSelectEnumSchema\"}, \n          {\"$ref\": \"#/definitions/TitledMultiSelectEnumSchema\"},\n          {\"$ref\": \"#/definitions/LegacyEnumSchema\"},\n      ]\n    }\n\n  }\n}\n\n```","author":{"url":"https://github.com/chughtapan","@type":"Person","name":"chughtapan"},"datePublished":"2025-08-11T23:02:11.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":13},"url":"https://github.com/1330/modelcontextprotocol/issues/1330"}