{"record":{"id":"0895ee238435edf6","repo":"OpenAPITools/openapi-generator","slug":"schema-format-event-stream-is-required-when-sse","errorCode":null,"errorMessage":"schema format 'event-stream' is required, when SSE is detected","messagePattern":"schema format 'event-stream' is required, when SSE is detected","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java","lineNumber":1516,"sourceCode":"                            $ref: <typeRef>\n                 */\n            Map<String, List<Schema>> schemaTypes = operation.getResponses().entrySet().stream()\n                    .map(e -> Pair.of(e.getValue(), fromResponse(e.getKey(), e.getValue())))\n                    .filter(p -> p.getRight().is2xx) // consider only success\n                    .map(p -> p.getLeft().getContent().get(MEDIA_EVENT_STREAM))\n                    .map(MediaType::getSchema)\n                    .collect(Collectors.toList()).stream()\n                    .collect(Collectors.groupingBy(Schema::getType));\n            if (schemaTypes.containsKey(\"array\")) {\n                // we have a match with SSE pattern\n                // double check potential conflicting, multiple specs\n                if (schemaTypes.size() > 1) {\n                    throw new RuntimeException(\"only 1 response media type supported, when SSE is detected\");\n                }\n                // double check schema format\n                List<Schema> eventTypes = schemaTypes.get(\"array\");\n                if (eventTypes.stream().anyMatch(schema -> !\"event-stream\".equalsIgnoreCase(schema.getFormat()))) {\n                    throw new RuntimeException(\"schema format 'event-stream' is required, when SSE is detected\");\n                }\n                // double check item types\n                Set<String> itemTypes = eventTypes.stream()\n                        .map(schema -> schema.getItems().getType() != null\n                                ? schema.getItems().getType()\n                                : schema.getItems().get$ref())\n                        .collect(Collectors.toSet());\n                if (itemTypes.size() > 1) {\n                    throw new RuntimeException(\"only single item type is supported, when SSE is detected\");\n                }\n                codegenOperation.vendorExtensions.put(\"x-sse\", true);\n            } // Not an SSE compliant definition\n        }\n\n        // If substituteGenericPagedModel is enabled, replace paged-model return types\n        // with org.springframework.data.web.PagedModel<T>.\n        if (substituteGenericPagedModel && !pagedModelRegistry.isEmpty()\n                && codegenOperation.returnBaseType != null) {","sourceCodeStart":1498,"sourceCodeEnd":1534,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java#L1498-L1534","documentation":"Once the generator matches the SSE pattern (a 2xx text/event-stream response whose schema type is array), it requires that array schema to declare format: event-stream (case-insensitive). The templates use this format to emit Flux<EventType> SSE endpoints; without it, generation aborts.","triggerScenarios":"A 2xx response with text/event-stream content whose schema has type: array but no format: event-stream (or a different format).","commonSituations":"Hand-written SSE specs that stop at type: array; specs generated by tools that drop the format field; teams learning the generator's undocumented SSE convention for the first time.","solutions":["Add format: event-stream to the array schema of the text/event-stream response.","Keep the item type consistent so the subsequent single-item-type check also passes."],"exampleFix":"# before\ncontent:\n  text/event-stream:\n    schema:\n      type: array\n      items: { $ref: '#/components/schemas/Event' }\n\n# after\ncontent:\n  text/event-stream:\n    schema:\n      type: array\n      format: event-stream\n      items: { $ref: '#/components/schemas/Event' }","handlingStrategy":"validation","validationCode":"// node: every 2xx event-stream array schema must declare format: event-stream\nconst checkSseFormat = (op) => {\n  Object.values(op.responses || {}).forEach(r => {\n    const mt = r.content && r.content['text/event-stream'];\n    if (mt && mt.schema?.type === 'array' && mt.schema.format !== 'event-stream')\n      throw new Error('text/event-stream array schema missing format: event-stream');\n  });\n};","typeGuard":null,"tryCatchPattern":"// Java\ntry { new DefaultGenerator().opts(input).generate(); }\ncatch (RuntimeException e) {\n    if (e.getMessage().contains(\"event-stream\")) { /* fix spec schema, regenerate once */ }\n}","preventionTips":["Add a Spectral/custom lint rule that checks format: event-stream on SSE array schemas.","Use a shared schema snippet for SSE responses so the format is never forgotten.","Review generated diffs after any spec change to catch SSE regressions early."],"tags":["spring","sse","openapi","spec-validation"],"backgroundTag":"sse-schema-validation","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}