Discriminator context (OpenAPI) | Fern Documentation

The x-fern-discriminator-context extension tells Fern where a discriminated union’s discriminator field lives: inside the data payload (data, the default) or at the protocol framing level (protocol). This distinction matters for SSE endpoints where the event field is part of the SSE protocol, not a property inside the data payload.

Value	Meaning
`data`	Discriminator is a property inside the JSON body (default)
`protocol`	Discriminator is at the protocol level (e.g., the SSE `event` field)

Place x-fern-discriminator-context on the discriminator object of a oneOf schema.

Protocol-level discrimination (SSE)

In the SSE protocol, the event field is part of the wire framing and isn’t included in the parsed data payload. Setting x-fern-discriminator-context: protocol tells Fern and the generated SDKs that the discriminant lives outside the data, so they deserialize each variant’s data without expecting the discriminant property to be present.

openapi.yml

1 components:
2   schemas:
3     StreamEvent:
4       discriminator:
5         propertyName: event
6         x-fern-discriminator-context: protocol
7         mapping:
8           completion: "#/components/schemas/CompletionEvent"
9           error: "#/components/schemas/ErrorEvent"
10       oneOf:
11         - $ref: "#/components/schemas/CompletionEvent"
12         - $ref: "#/components/schemas/ErrorEvent"
13 
14     CompletionEvent:
15       type: object
16       properties:
17         content:
18           type: string
19 
20     ErrorEvent:
21       type: object
22       properties:
23         message:
24           type: string
25         code:
26           type: integer

The corresponding SSE stream would look like:

event: completion
data: {"content": "Hello"}
event: error
data: {"message": "Rate limited", "code": 429}

Without x-fern-discriminator-context: protocol, Fern would treat event as a field inside each variant’s JSON body and expect it in the data payload.

Data-level discrimination (default)

When x-fern-discriminator-context is omitted or set to data, the discriminator is a property inside the JSON body. This is standard OpenAPI discriminated-union behavior and requires no extension.

openapi.yml

1 components:
2   schemas:
3     Plant:
4       discriminator:
5         propertyName: type
6         mapping:
7           tree: "#/components/schemas/Tree"
8           flower: "#/components/schemas/Flower"
9       oneOf:
10         - $ref: "#/components/schemas/Tree"
11         - $ref: "#/components/schemas/Flower"
12 
13     Tree:
14       type: object
15       required:
16         - type
17       properties:
18         type:
19           type: string
20           enum: ["tree"]
21         height:
22           type: number
23 
24     Flower:
25       type: object
26       required:
27         - type
28       properties:
29         type:
30           type: string
31           enum: ["flower"]
32         color:
33           type: string

Auto-inference

Fern auto-infers protocol context when every variant in a discriminated union uses only SSE spec fields (event, data, id, retry) with their expected types. In that case you don’t need to add the extension. Use x-fern-discriminator-context explicitly when you want to override the inferred value or when your variant schemas don’t match the SSE shape exactly.