fix: emit standard JSON Schema for JsonEnum (#89)

* fix: emit standard JSON Schema for JsonEnum

* docs: move JsonEnum changelog note to unreleased

Author: leehack

CHANGELOG.md

@@ -1,3 +1,18 @@
+## Unreleased
+
+### Compatibility Notes (Potentially Breaking)
+
+- **`JsonEnum` wire format is now standard JSON Schema**:
+  - `JsonEnum.toJson()` emits standard JSON Schema enum forms instead of the legacy
+    `type: 'enum'` / `values` shape.
+  - Legacy serialized enum input using `values` is still accepted when parsing.
+
+### Reliability
+
+- Fixed `JsonEnum` tool/input schema serialization to use standard JSON Schema enum output,
+  improving compatibility with downstream consumers that reject the legacy
+  `type: 'enum'` / `values` shape.
+
 ## 2.1.0
 
 ### Compatibility Notes (Potentially Breaking)

lib/src/shared/json_schema/json_schema.dart

@@ -811,9 +811,13 @@ class JsonEnum extends JsonSchema {
   @override
   final dynamic defaultValue;
 
+  /// The canonical values accepted by this enum schema.
+  List<dynamic> get normalizedValues =>
+      values.map((value) => _normalizeEntry(value).value).toList();
+
   factory JsonEnum.fromJson(Map<String, dynamic> json) {
     return JsonEnum(
-      json['values'] as List<dynamic>? ?? json['enum'] as List<dynamic>? ?? [],
+      _parseValues(json),
       title: json['title'] as String?,
       description: json['description'] as String?,
       defaultValue: json['default'],
@@ -822,12 +826,88 @@ class JsonEnum extends JsonSchema {
 
   @override
   Map<String, dynamic> toJson() {
+    final normalizedEntries =
+        values.map((value) => _normalizeEntry(value)).toList(growable: false);
+    final hasTitles = normalizedEntries.any((entry) => entry.title != null);
+    final allStrings =
+        normalizedEntries.every((entry) => entry.value is String);
+
     return {
       if (title != null) 'title': title,
       if (description != null) 'description': description,
       if (defaultValue != null) 'default': defaultValue,
-      'type': 'enum',
-      'values': values,
+      if (allStrings) 'type': 'string',
+      if (allStrings)
+        'enum': normalizedEntries.map((entry) => entry.value as String).toList()
+      else if (!hasTitles)
+        'enum': normalizedEntries.map((entry) => entry.value).toList()
+      else
+        'oneOf': normalizedEntries
+            .map(
+              (entry) => {
+                'const': entry.value,
+                if (entry.title != null) 'title': entry.title,
+              },
+            )
+            .toList(),
+      if (allStrings && hasTitles)
+        'enumNames': normalizedEntries
+            .map((entry) => entry.title ?? entry.value as String)
+            .toList(),
     };
   }
+
+  static List<dynamic> _parseValues(Map<String, dynamic> json) {
+    final legacyValues = json['values'];
+    if (legacyValues is List) {
+      return List<dynamic>.from(legacyValues);
+    }
+
+    final enumValues = json['enum'];
+    if (enumValues is List) {
+      final enumNames = json['enumNames'];
+      if (enumNames is List && enumNames.length == enumValues.length) {
+        return List<dynamic>.generate(enumValues.length, (index) {
+          final value = enumValues[index];
+          final title = enumNames[index];
+          if (title is String && title != '$value') {
+            return {'value': value, 'title': title};
+          }
+          return value;
+        });
+      }
+
+      return List<dynamic>.from(enumValues);
+    }
+
+    final oneOfValues = json['oneOf'];
+    if (oneOfValues is List) {
+      return oneOfValues.map((entry) {
+        if (entry is Map && entry.containsKey('const')) {
+          final value = entry['const'];
+          final title = entry['title'];
+          if (title is String && title != '$value') {
+            return {'value': value, 'title': title};
+          }
+          return value;
+        }
+
+        return entry;
+      }).toList();
+    }
+
+    return const [];
+  }
+
+  static ({dynamic value, String? title}) _normalizeEntry(dynamic entry) {
+    if (entry is Map && entry.containsKey('value')) {
+      final title = entry['title'];
+      return (
+        value: entry['value'],
+        title: title is String ? title : null,
+      );
+    }
+
+    return (value: entry, title: null);
+  }
 }

lib/src/shared/json_schema/json_schema_validator.dart

@@ -318,9 +318,9 @@ extension JsonSchemaValidation on JsonSchema {
   }
 
   void _validateEnum(JsonEnum schema, dynamic data, List<String> path) {
-    if (!schema.values.any((e) => _deepEquals(e, data))) {
+    if (!schema.normalizedValues.any((value) => _deepEquals(value, data))) {
       throw JsonSchemaValidationException(
-        'Value must be one of ${schema.values}',
+        'Value must be one of ${schema.normalizedValues}',
         path,
       );
     }

test/mcp_2025_11_25_test.dart

@@ -184,11 +184,15 @@ void main() {
       expect((schema.values[1] as Map)['title'], 'Complex Option');
 
       final json = schema.toJson();
-      expect(json['values'], hasLength(2));
+      expect(json['type'], 'string');
+      expect(json['enum'], ['simple', 'complex']);
+      expect(json['enumNames'], ['simple', 'Complex Option']);
+      expect(json.containsKey('values'), isFalse);
 
       final deserialized = JsonEnum.fromJson(json);
       expect(deserialized.values[0], 'simple');
       expect((deserialized.values[1] as Map)['value'], 'complex');
+      expect((deserialized.values[1] as Map)['title'], 'Complex Option');
     });
 
     test('ToolAnnotations SEP-???', () {

test/shared/json_schema_from_json_test.dart

@@ -22,6 +22,17 @@ void main() {
       expect(s.enumValues, ['a', 'b']);
     });
 
+    test('parses legacy enum schema', () {
+      final json = {
+        'type': 'enum',
+        'values': ['simple', 'complex'],
+      };
+      final schema = JsonSchema.fromJson(json);
+      expect(schema, isA<JsonEnum>());
+      final s = schema as JsonEnum;
+      expect(s.values, ['simple', 'complex']);
+    });
+
     test('parses number schema', () {
       final json = {
         'type': 'number',

test/shared/json_schema_test.dart

@@ -163,6 +163,27 @@ void main() {
         'not': {'type': 'string'},
       });
     });
+
+    test('JsonEnum serializes titled string values compatibly', () {
+      const schema = JsonEnum([
+        'simple',
+        {'value': 'complex', 'title': 'Complex Option'},
+      ]);
+
+      expect(schema.toJson(), {
+        'type': 'string',
+        'enum': ['simple', 'complex'],
+        'enumNames': ['simple', 'Complex Option'],
+      });
+    });
+
+    test('JsonEnum serializes mixed primitive values as standard enum', () {
+      const schema = JsonEnum([1, 'two', true, null]);
+
+      expect(schema.toJson(), {
+        'enum': [1, 'two', true, null],
+      });
+    });
   });
 
   group('JsonSchema Validation Integration', () {

test/shared/json_schema_validator_test.dart

@@ -416,6 +416,21 @@ void main() {
           throwsA(isA<JsonSchemaValidationException>()),
         );
       });
+
+      test('validates titled enum values against canonical values', () {
+        final schema = const JsonEnum([
+          'simple',
+          {'value': 'complex', 'title': 'Complex Option'},
+        ]);
+
+        schema.validate('simple');
+        schema.validate('complex');
+
+        expect(
+          () => schema.validate('Complex Option'),
+          throwsA(isA<JsonSchemaValidationException>()),
+        );
+      });
     });
 
     group('composition schemas', () {

test/tool_schema_test.dart

@@ -143,6 +143,35 @@ void main() {
       );
     });
 
+    test('Tool serializes JsonEnum properties as standard enum schema', () {
+      const tool = Tool(
+        name: 'configure_mode',
+        inputSchema: JsonObject(
+          properties: {
+            'mode': JsonEnum([
+              'simple',
+              {'value': 'complex', 'title': 'Complex Option'},
+            ]),
+          },
+        ),
+      );
+
+      final json = tool.toJson();
+      final modeSchema =
+          json['inputSchema']['properties']['mode'] as Map<String, dynamic>;
+
+      expect(modeSchema['type'], equals('string'));
+      expect(modeSchema['enum'], equals(['simple', 'complex']));
+      expect(modeSchema['enumNames'], equals(['simple', 'Complex Option']));
+      expect(modeSchema.containsKey('values'), isFalse);
+
+      final restored = Tool.fromJson(json);
+      final restoredMode = (restored.inputSchema as JsonObject)
+          .properties!['mode'] as JsonString;
+      expect(restoredMode.enumValues, equals(['simple', 'complex']));
+      expect(restoredMode.enumNames, equals(['simple', 'Complex Option']));
+    });
+
     test('ListToolsResult preserves tool required fields', () {
       final tools = [
         Tool(