What is PrimitiveSchemaDefinition?
PrimitiveSchemaDefinition is a discriminated union type that represents the set of permissible property schemas inside an elicitation form: StringSchema, NumberSchema, BooleanSchema, and EnumSchema. It exists as a deliberate constraint boundary — rather than allowing arbitrary JSON Schema (which could nest objects, arrays, or recursive references), MCP pins elicitation inputs to a flat, well-understood set of primitives that any compliant UI renderer can handle without custom logic. The single required field, variant, carries the entire payload; the specific subtype you supply determines which additional fields (minLength, minimum, enum values, etc.) are valid. In the MCP message flow, PrimitiveSchemaDefinition values appear as entries in the properties map of an ElicitRequestParams schema object. When a server sends an elicitation request over the wire, the client deserializes each property value as one of the four concrete subtypes, renders the appropriate form control, collects user input, and returns typed values in the ElicitResult. The union therefore acts as the schema-layer contract between server intent and client rendering capability. The four-variant design was introduced alongside the elicitation capability in the 2025-03-26 spec revision. Restricting to primitives was an explicit ergonomic choice: it sidesteps the combinatorial complexity of full JSON Schema validation in clients that may be thin UIs (e.g., desktop app sidebars or mobile assistants). Future spec revisions could expand the union — adding an ArraySchema or NestedObjectSchema — but any such change would be additive and versioned, so existing clients that only handle four variants remain compliant by treating unknown variants as unsupported properties.
When to use
Inside elicitation requestedSchema properties.
When NOT to use
For tool inputs — use full JSON Schema there.
Notes
Discriminating on the variant field
Each concrete subtype uses the variant field as its discriminator ("string", "number", "boolean", or "enum"). When deserializing, both client and server SDKs key off this field before reading type-specific attributes. If variant is missing or unrecognized, the safest behavior is to skip that property and log a warning rather than aborting the entire elicitation request.
EnumSchema requires non-empty values array
EnumSchema is the only PrimitiveSchemaDefinition variant that carries a list sub-field (the enumerated values). A common production pitfall is sending an empty values array, which is technically invalid — the form control has no options to render. Validate that values has at least one entry on the server side before constructing the elicitation request, since clients may either crash or silently omit the field.
Flat schema prevents injection via nested refs
Restricting elicitation schemas to primitive variants eliminates an entire class of JSON Schema security concerns: no $ref pointers, no allOf/anyOf combinators, and no recursive definitions. This design choice means a malicious server cannot craft a schema that causes a client's validator to enter an infinite resolution loop or fetch external URIs.
Client capability check before sending
Elicitation is an optional capability that clients advertise in ClientCapabilities. Before constructing any PrimitiveSchemaDefinition payload, the server should verify that the connected client declared elicitation support. Sending an elicit request to a client that did not advertise the capability will result in a -32601 MethodNotFound error, not a graceful no-op.
StringSchema vs EnumSchema for bounded input
A common design question is whether to use StringSchema with a pattern constraint or EnumSchema for a small fixed set of choices. Prefer EnumSchema whenever the valid values are known at request time — clients can render it as a native select/radio control, which is more accessible and less error-prone than free-text regex validation handled post-submission.
Fields
| Field | Type | Required | Purpose |
|---|---|---|---|
| variant | StringSchema | NumberSchema | BooleanSchema | EnumSchema | yes | Which primitive shape applies. |
Examples
Form schema
{ "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } } }Common mistakes
❌ Nesting objects in elicitation forms
✅ Elicitation supports only primitive properties.