From 56cce7128214c69de7c5ca80c19a45f0c2ba6ff7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 22 Mar 2026 01:17:46 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20documentation=20section=20?=
 =?UTF-8?q?for=20typed=20ServerSentEvent[Data]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous commit added ServerSentEvent[Data] generic support and
tutorial006 but did not add a corresponding section to the SSE docs.
This adds the missing "Typed ServerSentEvent" section explaining the
generic syntax, validation behavior, and OpenAPI contentSchema benefit.

https://claude.ai/code/session_01GRv2sCmACvBQFX7fh7anWm
---
 docs/en/docs/tutorial/server-sent-events.md | 25 +++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/en/docs/tutorial/server-sent-events.md b/docs/en/docs/tutorial/server-sent-events.md
index d264f8536f..bba119a8e9 100644
--- a/docs/en/docs/tutorial/server-sent-events.md
+++ b/docs/en/docs/tutorial/server-sent-events.md
@@ -93,6 +93,31 @@ This is useful for sending pre-formatted text, log lines, or special <dfn title=
 
 ///
 
+## Typed `ServerSentEvent` { #typed-serversentevent }
+
+When you yield plain `ServerSentEvent` objects, the `data` field accepts any value and the OpenAPI schema has no `contentSchema` for the payload.
+
+If you want **typed data validation** and a `contentSchema` in the OpenAPI spec while still having full control over SSE fields like `event`, `id`, `retry`, and `comment`, you can parameterize `ServerSentEvent` with a type:
+
+{* ../../docs_src/server_sent_events/tutorial006_py310.py hl[4,23,25] *}
+
+`ServerSentEvent[Item]` means:
+
+* `data` **must** be an `Item` instance — omitting it or passing the wrong type raises a validation error.
+* The generated OpenAPI schema includes a `contentSchema` referencing `Item` inside the SSE `data` field.
+
+/// tip
+
+If you need events where `data` is optional (for example, comment-only keep-alive pings), use `ServerSentEvent[Item | None]` instead.
+
+///
+
+/// note
+
+Bare `ServerSentEvent` (without a type parameter) still works exactly as before — `data` accepts any value including `None`.
+
+///
+
 ## Resuming with `Last-Event-ID` { #resuming-with-last-event-id }
 
 When a browser reconnects after a connection drop, it sends the last received `id` in the `Last-Event-ID` header.