feat(internal): IR minor update to include SSE parsing information (#12242)

* ir proposal

* ir proposal 2 on internal/external

* data/protocol

* openapi-ir and fern def; x-fern-discriminator-context

* cut mapping

* cut discriminatorField too

* release 3.76.0

* jog

* schema

* snaps

* snaps 2

* snaps 3

* snaps 4 please let this be the last

Author: patrickthornton

fern.schema.json

@@ -847,6 +847,13 @@
       ],
       "additionalProperties": false
     },
+    "types.UnionDiscriminatorContext": {
+      "type": "string",
+      "enum": [
+        "data",
+        "protocol"
+      ]
+    },
     "types.UnionDiscriminantSchema": {
       "type": "object",
       "properties": {
@@ -862,6 +869,16 @@
         },
         "value": {
           "type": "string"
+        },
+        "context": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/types.UnionDiscriminatorContext"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "required": [

fern/apis/fern-definition/definition/types.yml

@@ -219,6 +219,17 @@ types:
       - commons.WithName
     properties:
       value: string
+      context:
+        type: optional<UnionDiscriminatorContext>
+        docs: |
+          Context for where the discriminator exists. Defaults to "data" for backward compatibility.
+          "data" means the discriminator is within the union data itself.
+          "protocol" means the discriminator is at the SSE protocol level.
+
+  UnionDiscriminatorContext:
+    enum:
+      - data
+      - protocol
 
   #### Undiscriminated Union ####
 

package-yml.schema.json

@@ -867,6 +867,13 @@
       ],
       "additionalProperties": false
     },
+    "types.UnionDiscriminatorContext": {
+      "type": "string",
+      "enum": [
+        "data",
+        "protocol"
+      ]
+    },
     "types.UnionDiscriminantSchema": {
       "type": "object",
       "properties": {
@@ -882,6 +889,16 @@
         },
         "value": {
           "type": "string"
+        },
+        "context": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/types.UnionDiscriminatorContext"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "required": [

packages/cli/api-importers/openapi/openapi-ir-parser/src/openapi/v3/extensions/fernExtensions.ts

@@ -500,7 +500,23 @@ export const FernOpenAPIExtension = {
      *    get:
      *      x-fern-explorer-enabled: true  # or false
      */
-    EXPLORER_ENABLED: "x-fern-explorer-enabled"
+    EXPLORER_ENABLED: "x-fern-explorer-enabled",
+
+    /**
+     * Used to specify the context where a discriminator exists for union types.
+     * This is used for SSE discrimination patterns.
+     *
+     * components:
+     *   schemas:
+     *     SseStreamEvent:
+     *       discriminator:
+     *         propertyName: event
+     *         x-fern-discriminator-context: protocol  # or data (default)
+     *       oneOf:
+     *         - $ref: '#/components/schemas/CompletionEvent'
+     *         - $ref: '#/components/schemas/ErrorEvent'
+     */
+    DISCRIMINATOR_CONTEXT: "x-fern-discriminator-context"
 } as const;
 
 export type FernOpenAPIExtension = Values<typeof FernOpenAPIExtension>;

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertDiscriminatedOneOf.ts

@@ -52,6 +52,8 @@ export function convertDiscriminatedOneOf({
 }): SchemaWithExample {
     const discriminant = discriminator.propertyName;
     const discriminantNameOverride = getExtension<string>(discriminator, FernOpenAPIExtension.FERN_PROPERTY_NAME);
+    const discriminatorContext =
+        getExtension<"data" | "protocol">(discriminator, FernOpenAPIExtension.DISCRIMINATOR_CONTEXT) ?? "data";
     const unionSubTypes = Object.fromEntries(
         Object.entries(discriminator.mapping ?? {}).map(([discriminantValue, schema]) => {
             const subtypeReference = convertReferenceObject(
@@ -110,6 +112,7 @@ export function convertDiscriminatedOneOf({
         availability,
         discriminant,
         discriminantNameOverride,
+        discriminatorContext,
         subtypes: unionSubTypes,
         namespace,
         groupName,
@@ -219,6 +222,7 @@ export function convertDiscriminatedOneOfWithVariants({
         availability,
         discriminant,
         discriminantNameOverride: undefined,
+        discriminatorContext: "data", // variants don't have discriminator object, default to data
         subtypes: unionSubTypes,
         namespace,
         groupName,
@@ -237,6 +241,7 @@ export function wrapDiscriminatedOneOf({
     availability,
     discriminant,
     discriminantNameOverride,
+    discriminatorContext,
     subtypes,
     namespace,
     groupName,
@@ -252,6 +257,7 @@ export function wrapDiscriminatedOneOf({
     availability: Availability | undefined;
     discriminant: string;
     discriminantNameOverride: string | undefined;
+    discriminatorContext: "data" | "protocol";
     subtypes: Record<string, SchemaWithExample>;
     namespace: string | undefined;
     groupName: SdkGroupName | undefined;
@@ -263,6 +269,7 @@ export function wrapDiscriminatedOneOf({
             availability,
             discriminantProperty: discriminant,
             discriminantPropertyNameOverride: discriminantNameOverride,
+            discriminatorContext,
             nameOverride,
             generatedName,
             title,

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/utils/convertSchemaToSchemaWithExample.ts

@@ -241,6 +241,7 @@ function convertToOneOf(oneOfSchema: OneOfSchema): OneOfSchemaWithExample {
                 availability: oneOfSchema.availability,
                 discriminantProperty: oneOfSchema.discriminantProperty,
                 discriminantPropertyNameOverride: oneOfSchema.discriminantPropertyNameOverride,
+                discriminatorContext: oneOfSchema.discriminatorContext,
                 generatedName: oneOfSchema.generatedName,
                 nameOverride: oneOfSchema.nameOverride,
                 title: oneOfSchema.title,

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/utils/convertSchemaWithExampleToSchema.ts

@@ -217,6 +217,7 @@ function convertToOneOf(oneOfSchema: OneOfSchemaWithExample): OneOfSchema {
                 availability: oneOfSchema.availability,
                 discriminantProperty: oneOfSchema.discriminantProperty,
                 discriminantPropertyNameOverride: oneOfSchema.discriminantPropertyNameOverride,
+                discriminatorContext: oneOfSchema.discriminatorContext,
                 generatedName: oneOfSchema.generatedName,
                 title: oneOfSchema.title,
                 nameOverride: oneOfSchema.nameOverride,

packages/cli/api-importers/openapi/openapi-ir-to-fern-tests/src/__test__/__snapshots__/openapi-ir/allof-oneof-anyof-edge-cases.json

@@ -613,6 +613,7 @@
         "value": {
           "commonProperties": [],
           "discriminantProperty": "petType",
+          "discriminatorContext": "data",
           "generatedName": "Pet",
           "schemas": {
             "dog": {

packages/cli/api-importers/openapi/openapi-ir-to-fern-tests/src/__test__/__snapshots__/openapi-ir/discriminated-union-value-title.json

@@ -186,6 +186,7 @@
         "value": {
           "commonProperties": [],
           "discriminantProperty": "type",
+          "discriminatorContext": "data",
           "generatedName": "SampleUnion",
           "schemas": {
             "request": {

packages/cli/api-importers/openapi/openapi-ir-to-fern-tests/src/__test__/__snapshots__/openapi-ir/discriminator-base-class.json

@@ -136,6 +136,7 @@
           ],
           "description": "Base form field with discriminator",
           "discriminantProperty": "type",
+          "discriminatorContext": "data",
           "generatedName": "FormFieldBase",
           "schemas": {
             "text": {