Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(api): title OpenAPI union variants for Scalar (#16701)

Tobias Wochinger99aa9785afbc
diff --git a/package.json b/package.json
index 700c9cabba..63f8022870 100644
--- a/package.json
+++ b/package.json
@@ -38,7 +38,7 @@
"format": "prettier --write \"**/*.{js,jsx,ts,tsx,css}\" --experimental-cli",
"format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,css}\" --experimental-cli",
"playwright:install": "pnpm --filter web exec playwright install chromium",
- "openapi:export": "npx fern-api export --api server web/public/generated/api/openapi.yml && pnpm --filter web exec tsx scripts/openapi/sync-deprecations.ts && npx fern-api export --api client web/public/generated/api-client/openapi.yml && npx fern-api export --api organizations web/public/generated/organizations-api/openapi.yml",
+ "openapi:export": "npx fern-api export --api server web/public/generated/api/openapi.yml && pnpm --filter web exec tsx scripts/openapi/postprocess-openapi.ts && npx fern-api export --api client web/public/generated/api-client/openapi.yml && npx fern-api export --api organizations web/public/generated/organizations-api/openapi.yml",
"storybook": "pnpm --filter web run storybook",
"test": "turbo run test",
"release": "bash ./scripts/release-preflight.sh && dotenv -e ../.env -- release-it",
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index a2008c9afa..46477fb5de 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -10983,6 +10983,7 @@ components:
- $ref: '#/components/schemas/NumericScoreV1'
required:
- dataType
+ title: NumericScoreV1
- type: object
allOf:
- type: object
@@ -10994,6 +10995,7 @@ components:
- $ref: '#/components/schemas/CategoricalScoreV1'
required:
- dataType
+ title: CategoricalScoreV1
- type: object
allOf:
- type: object
@@ -11005,6 +11007,7 @@ components:
- $ref: '#/components/schemas/BooleanScoreV1'
required:
- dataType
+ title: BooleanScoreV1
- type: object
allOf:
- type: object
@@ -11016,6 +11019,7 @@ components:
- $ref: '#/components/schemas/TextScoreV1'
required:
- dataType
+ title: TextScoreV1
BaseScore:
title: BaseScore
type: object
@@ -11185,6 +11189,7 @@ components:
- $ref: '#/components/schemas/NumericScore'
required:
- dataType
+ title: NumericScore
- type: object
allOf:
- type: object
@@ -11196,6 +11201,7 @@ components:
- $ref: '#/components/schemas/CategoricalScore'
required:
- dataType
+ title: CategoricalScore
- type: object
allOf:
- type: object
@@ -11207,6 +11213,7 @@ components:
- $ref: '#/components/schemas/BooleanScore'
required:
- dataType
+ title: BooleanScore
- type: object
allOf:
- type: object
@@ -11218,6 +11225,7 @@ components:
- $ref: '#/components/schemas/CorrectionScore'
required:
- dataType
+ title: CorrectionScore
- type: object
allOf:
- type: object
@@ -11229,6 +11237,7 @@ components:
- $ref: '#/components/schemas/TextScore'
required:
- dataType
+ title: TextScore
properties:
_deprecation:
$ref: '#/components/schemas/Deprecation'
@@ -11238,7 +11247,9 @@ components:
oneOf:
- type: number
format: double
+ title: DoubleNumber
- type: string
+ title: String
description: >-
The value of the score. Must be passed as string for categorical and
text scores, and numeric for boolean and numeric scores
@@ -12015,17 +12026,22 @@ components:
oneOf:
- type: string
nullable: true
+ title: String
- type: integer
nullable: true
+ title: Integer
- type: number
format: float
nullable: true
+ title: FloatNumber
- type: boolean
nullable: true
+ title: Boolean
- type: array
items:
type: string
nullable: true
+ title: Array
CommentObjectType:
title: CommentObjectType
type: string
@@ -12328,6 +12344,7 @@ components:
- $ref: '#/components/schemas/PublicEvaluatorNumericScore'
required:
- dataType
+ title: PublicEvaluatorNumericScore
- type: object
allOf:
- type: object
@@ -12339,6 +12356,7 @@ components:
- $ref: '#/components/schemas/PublicEvaluatorBooleanScore'
required:
- dataType
+ title: PublicEvaluatorBooleanScore
- type: object
allOf:
- type: object
@@ -12350,6 +12368,7 @@ components:
- $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'
required:
- dataType
+ title: PublicEvaluatorCategoricalScore
description: >-
Flat structured output definition used when creating or updating an
evaluator.
@@ -12451,6 +12470,7 @@ components:
- $ref: '#/components/schemas/PublicEvaluatorNumericScore'
required:
- dataType
+ title: PublicEvaluatorNumericScore
- type: object
allOf:
- type: object
@@ -12462,6 +12482,7 @@ components:
- $ref: '#/components/schemas/PublicEvaluatorBooleanScore'
required:
- dataType
+ title: PublicEvaluatorBooleanScore
- type: object
allOf:
- type: object
@@ -12473,6 +12494,7 @@ components:
- $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'
required:
- dataType
+ title: PublicEvaluatorCategoricalScore
description: >-
Flat evaluator output definition returned by the public API.
@@ -12876,6 +12898,7 @@ components:
- $ref: '#/components/schemas/DateTimeEvaluationRuleFilter'
required:
- type
+ title: DateTimeEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12887,6 +12910,7 @@ components:
- $ref: '#/components/schemas/StringEvaluationRuleFilter'
required:
- type
+ title: StringEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12898,6 +12922,7 @@ components:
- $ref: '#/components/schemas/NumberEvaluationRuleFilter'
required:
- type
+ title: NumberEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12909,6 +12934,7 @@ components:
- $ref: '#/components/schemas/StringOptionsEvaluationRuleFilter'
required:
- type
+ title: StringOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12920,6 +12946,7 @@ components:
- $ref: '#/components/schemas/CategoryOptionsEvaluationRuleFilter'
required:
- type
+ title: CategoryOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12931,6 +12958,7 @@ components:
- $ref: '#/components/schemas/ArrayOptionsEvaluationRuleFilter'
required:
- type
+ title: ArrayOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12942,6 +12970,7 @@ components:
- $ref: '#/components/schemas/StringObjectEvaluationRuleFilter'
required:
- type
+ title: StringObjectEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12953,6 +12982,7 @@ components:
- $ref: '#/components/schemas/NumberObjectEvaluationRuleFilter'
required:
- type
+ title: NumberObjectEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12964,6 +12994,7 @@ components:
- $ref: '#/components/schemas/BooleanEvaluationRuleFilter'
required:
- type
+ title: BooleanEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -12975,6 +13006,7 @@ components:
- $ref: '#/components/schemas/NullEvaluationRuleFilter'
required:
- type
+ title: NullEvaluationRuleFilter
description: >-
One filter condition used to decide whether a live-ingested observation
should be evaluated.
@@ -13467,6 +13499,7 @@ components:
title: EvaluatorChatPromptInput
oneOf:
- type: string
+ title: String
- $ref: '#/components/schemas/EvaluatorChatPrompt'
description: >-
A user prompt string, or a list containing exactly one user chat message.
@@ -13582,6 +13615,7 @@ components:
- $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion'
required:
- type
+ title: LlmAsJudgeEvaluatorVersion
- type: object
allOf:
- type: object
@@ -13593,6 +13627,7 @@ components:
- $ref: '#/components/schemas/CodeEvaluatorVersion'
required:
- type
+ title: CodeEvaluatorVersion
EvaluationRuleAssignment:
title: EvaluationRuleAssignment
type: object
@@ -13778,6 +13813,7 @@ components:
- $ref: '#/components/schemas/LlmAsJudgeEvaluator'
required:
- type
+ title: LlmAsJudgeEvaluator
- type: object
allOf:
- type: object
@@ -13789,6 +13825,7 @@ components:
- $ref: '#/components/schemas/CodeEvaluator'
required:
- type
+ title: CodeEvaluator
description: >-
One evaluator that can be used for scoring.
@@ -13897,6 +13934,7 @@ components:
- $ref: '#/components/schemas/CreateLlmAsJudgeEvaluatorRequest'
required:
- type
+ title: CreateLlmAsJudgeEvaluatorRequest
- type: object
allOf:
- type: object
@@ -13908,6 +13946,7 @@ components:
- $ref: '#/components/schemas/CreateCodeEvaluatorRequest'
required:
- type
+ title: CreateCodeEvaluatorRequest
description: >-
Initial evaluator definition with metadata and definition fields at the
same level. The returned evaluator starts at version `1`.
@@ -14301,6 +14340,7 @@ components:
- $ref: '#/components/schemas/TraceEvent'
required:
- type
+ title: TraceEvent
- type: object
allOf:
- type: object
@@ -14312,6 +14352,7 @@ components:
- $ref: '#/components/schemas/ScoreEvent'
required:
- type
+ title: ScoreEvent
- type: object
allOf:
- type: object
@@ -14323,6 +14364,7 @@ components:
- $ref: '#/components/schemas/CreateSpanEvent'
required:
- type
+ title: CreateSpanEvent
- type: object
allOf:
- type: object
@@ -14334,6 +14376,7 @@ components:
- $ref: '#/components/schemas/UpdateSpanEvent'
required:
- type
+ title: UpdateSpanEvent
- type: object
allOf:
- type: object
@@ -14345,6 +14388,7 @@ components:
- $ref: '#/components/schemas/CreateGenerationEvent'
required:
- type
+ title: CreateGenerationEvent
- type: object
allOf:
- type: object
@@ -14356,6 +14400,7 @@ components:
- $ref: '#/components/schemas/UpdateGenerationEvent'
required:
- type
+ title: UpdateGenerationEvent
- type: object
allOf:
- type: object
@@ -14367,6 +14412,7 @@ components:
- $ref: '#/components/schemas/CreateEventEvent'
required:
- type
+ title: CreateEventEvent
- type: object
allOf:
- type: object
@@ -14378,6 +14424,7 @@ components:
- $ref: '#/components/schemas/SDKLogEvent'
required:
- type
+ title: SDKLogEvent
- type: object
allOf:
- type: object
@@ -14389,6 +14436,7 @@ components:
- $ref: '#/components/schemas/CreateObservationEvent'
required:
- type
+ title: CreateObservationEvent
- type: object
allOf:
- type: object
@@ -14400,6 +14448,7 @@ components:
- $ref: '#/components/schemas/UpdateObservationEvent'
required:
- type
+ title: UpdateObservationEvent
ObservationType:
title: ObservationType
type: string
@@ -14976,6 +15025,7 @@ components:
- type: object
additionalProperties:
type: integer
+ title: Object
- $ref: '#/components/schemas/OpenAICompletionUsageSchema'
- $ref: '#/components/schemas/OpenAIResponseUsageSchema'
legacyMetricsResponse:
@@ -16072,6 +16122,7 @@ components:
- $ref: '#/components/schemas/ChatPrompt'
required:
- type
+ title: ChatPrompt
- type: object
allOf:
- type: object
@@ -16083,6 +16134,7 @@ components:
- $ref: '#/components/schemas/TextPrompt'
required:
- type
+ title: TextPrompt
PromptType:
title: PromptType
type: string
@@ -16649,6 +16701,7 @@ components:
- $ref: '#/components/schemas/ScoreSubjectTraceV3'
required:
- kind
+ title: ScoreSubjectTraceV3
- type: object
allOf:
- type: object
@@ -16660,6 +16713,7 @@ components:
- $ref: '#/components/schemas/ScoreSubjectObservationV3'
required:
- kind
+ title: ScoreSubjectObservationV3
- type: object
allOf:
- type: object
@@ -16671,6 +16725,7 @@ components:
- $ref: '#/components/schemas/ScoreSubjectSessionV3'
required:
- kind
+ title: ScoreSubjectSessionV3
- type: object
allOf:
- type: object
@@ -16682,6 +16737,7 @@ components:
- $ref: '#/components/schemas/ScoreSubjectExperimentV3'
required:
- kind
+ title: ScoreSubjectExperimentV3
description: >-
A reference to the entity this score is attached to. Discriminated by
"kind" — one of trace, observation, session, or experiment.
@@ -16826,6 +16882,7 @@ components:
- $ref: '#/components/schemas/NumericScoreV3'
required:
- dataType
+ title: NumericScoreV3
- type: object
allOf:
- type: object
@@ -16837,6 +16894,7 @@ components:
- $ref: '#/components/schemas/BooleanScoreV3'
required:
- dataType
+ title: BooleanScoreV3
- type: object
allOf:
- type: object
@@ -16848,6 +16906,7 @@ components:
- $ref: '#/components/schemas/CategoricalScoreV3'
required:
- dataType
+ title: CategoricalScoreV3
- type: object
allOf:
- type: object
@@ -16859,6 +16918,7 @@ components:
- $ref: '#/components/schemas/TextScoreV3'
required:
- dataType
+ title: TextScoreV3
- type: object
allOf:
- type: object
@@ -16870,6 +16930,7 @@ components:
- $ref: '#/components/schemas/CorrectionScoreV3'
required:
- dataType
+ title: CorrectionScoreV3
GetScoresV3Meta:
title: GetScoresV3Meta
type: object
@@ -17071,6 +17132,7 @@ components:
- $ref: '#/components/schemas/GetScoresResponseDataNumeric'
required:
- dataType
+ title: GetScoresResponseDataNumeric
- type: object
allOf:
- type: object
@@ -17082,6 +17144,7 @@ components:
- $ref: '#/components/schemas/GetScoresResponseDataCategorical'
required:
- dataType
+ title: GetScoresResponseDataCategorical
- type: object
allOf:
- type: object
@@ -17093,6 +17156,7 @@ components:
- $ref: '#/components/schemas/GetScoresResponseDataBoolean'
required:
- dataType
+ title: GetScoresResponseDataBoolean
- type: object
allOf:
- type: object
@@ -17104,6 +17168,7 @@ components:
- $ref: '#/components/schemas/GetScoresResponseDataCorrection'
required:
- dataType
+ title: GetScoresResponseDataCorrection
- type: object
allOf:
- type: object
@@ -17115,6 +17180,7 @@ components:
- $ref: '#/components/schemas/GetScoresResponseDataText'
required:
- dataType
+ title: GetScoresResponseDataText
GetScoresResponse:
title: GetScoresResponse
type: object
@@ -17368,6 +17434,7 @@ components:
#/components/schemas/unstablePublicNumericEvaluatorOutputDefinition
required:
- dataType
+ title: UnstablePublicNumericEvaluatorOutputDefinition
- type: object
allOf:
- type: object
@@ -17380,6 +17447,7 @@ components:
#/components/schemas/unstablePublicBooleanEvaluatorOutputDefinition
required:
- dataType
+ title: UnstablePublicBooleanEvaluatorOutputDefinition
- type: object
allOf:
- type: object
@@ -17392,6 +17460,7 @@ components:
#/components/schemas/unstablePublicCategoricalEvaluatorOutputDefinition
required:
- dataType
+ title: UnstablePublicCategoricalEvaluatorOutputDefinition
description: >-
Structured output definition to send when creating an evaluator.
@@ -17508,6 +17577,7 @@ components:
#/components/schemas/unstablePublicNumericEvaluatorOutputDefinition
required:
- dataType
+ title: UnstablePublicNumericEvaluatorOutputDefinition
- type: object
allOf:
- type: object
@@ -17520,6 +17590,7 @@ components:
#/components/schemas/unstablePublicBooleanEvaluatorOutputDefinition
required:
- dataType
+ title: UnstablePublicBooleanEvaluatorOutputDefinition
- type: object
allOf:
- type: object
@@ -17532,6 +17603,7 @@ components:
#/components/schemas/unstablePublicCategoricalEvaluatorOutputDefinition
required:
- dataType
+ title: UnstablePublicCategoricalEvaluatorOutputDefinition
description: >-
Evaluator output definition returned by the public API.
@@ -17897,6 +17969,7 @@ components:
- $ref: '#/components/schemas/unstableDateTimeEvaluationRuleFilter'
required:
- type
+ title: UnstableDateTimeEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17908,6 +17981,7 @@ components:
- $ref: '#/components/schemas/unstableStringEvaluationRuleFilter'
required:
- type
+ title: UnstableStringEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17919,6 +17993,7 @@ components:
- $ref: '#/components/schemas/unstableNumberEvaluationRuleFilter'
required:
- type
+ title: UnstableNumberEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17930,6 +18005,7 @@ components:
- $ref: '#/components/schemas/unstableStringOptionsEvaluationRuleFilter'
required:
- type
+ title: UnstableStringOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17941,6 +18017,7 @@ components:
- $ref: '#/components/schemas/unstableCategoryOptionsEvaluationRuleFilter'
required:
- type
+ title: UnstableCategoryOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17952,6 +18029,7 @@ components:
- $ref: '#/components/schemas/unstableArrayOptionsEvaluationRuleFilter'
required:
- type
+ title: UnstableArrayOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17963,6 +18041,7 @@ components:
- $ref: '#/components/schemas/unstableStringObjectEvaluationRuleFilter'
required:
- type
+ title: UnstableStringObjectEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17974,6 +18053,7 @@ components:
- $ref: '#/components/schemas/unstableNumberObjectEvaluationRuleFilter'
required:
- type
+ title: UnstableNumberObjectEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17985,6 +18065,7 @@ components:
- $ref: '#/components/schemas/unstableBooleanEvaluationRuleFilter'
required:
- type
+ title: UnstableBooleanEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -17996,6 +18077,7 @@ components:
- $ref: '#/components/schemas/unstableNullEvaluationRuleFilter'
required:
- type
+ title: UnstableNullEvaluationRuleFilter
description: >-
One filter condition used to decide whether a live-ingested target
should be evaluated.
@@ -18409,6 +18491,7 @@ components:
- $ref: '#/components/schemas/unstableWidgetPlacement'
required:
- type
+ title: UnstableWidgetPlacement
- type: object
allOf:
- type: object
@@ -18420,6 +18503,7 @@ components:
- $ref: '#/components/schemas/unstablePresetPlacement'
required:
- type
+ title: UnstablePresetPlacement
description: |-
A tile on the dashboard's 12-column grid. `x`/`y` are the tile's
top-left cell (0-based; `y` grows downward), `width`/`height` its size
@@ -18486,6 +18570,7 @@ components:
- $ref: '#/components/schemas/unstableCreateWidgetPlacement'
required:
- type
+ title: UnstableCreateWidgetPlacement
- type: object
allOf:
- type: object
@@ -18497,6 +18582,7 @@ components:
- $ref: '#/components/schemas/unstableCreatePresetPlacement'
required:
- type
+ title: UnstableCreatePresetPlacement
unstableCreateWidgetPlacement:
title: unstableCreateWidgetPlacement
type: object
@@ -19598,6 +19684,7 @@ components:
- $ref: '#/components/schemas/unstableLlmAsJudgeEvaluator'
required:
- type
+ title: UnstableLlmAsJudgeEvaluator
- type: object
allOf:
- type: object
@@ -19609,6 +19696,7 @@ components:
- $ref: '#/components/schemas/unstableCodeEvaluator'
required:
- type
+ title: UnstableCodeEvaluator
description: >-
One evaluator that can be used for scoring.
@@ -19776,6 +19864,7 @@ components:
- $ref: '#/components/schemas/unstableCreateLlmAsJudgeEvaluatorRequest'
required:
- type
+ title: UnstableCreateLlmAsJudgeEvaluatorRequest
- type: object
allOf:
- type: object
@@ -19787,6 +19876,7 @@ components:
- $ref: '#/components/schemas/unstableCreateCodeEvaluatorRequest'
required:
- type
+ title: UnstableCreateCodeEvaluatorRequest
description: >-
Request body for creating an evaluator.
diff --git a/web/scripts/openapi/sync-deprecations.ts b/web/scripts/openapi/postprocess-openapi.ts
similarity index 69%
rename from web/scripts/openapi/sync-deprecations.ts
rename to web/scripts/openapi/postprocess-openapi.ts
index ecf8b932be..f98a420b91 100644
--- a/web/scripts/openapi/sync-deprecations.ts
+++ b/web/scripts/openapi/postprocess-openapi.ts
@@ -3,6 +3,7 @@ import path from "node:path";
import { getFernDeprecatedOperations } from "./fern-deprecations";
import { stampDeprecations } from "./stamp-deprecations";
+import { stampUnionVariantTitles } from "./stamp-union-variant-titles";
const webDirectory = process.cwd();
const definitionDirectory = path.resolve(
@@ -16,10 +17,13 @@ const openApiPath = path.resolve(
const deprecatedOperations = getFernDeprecatedOperations(definitionDirectory);
const openApiSource = fs.readFileSync(openApiPath, "utf8");
-const syncedSource = stampDeprecations(openApiSource, deprecatedOperations);
+const deprecatedSource = stampDeprecations(openApiSource, deprecatedOperations);
+const { source: syncedSource, stamped } =
+ stampUnionVariantTitles(deprecatedSource);
if (syncedSource !== openApiSource) fs.writeFileSync(openApiPath, syncedSource);
console.log(
`Synced ${deprecatedOperations.length} deprecated OpenAPI operations from Fern definitions.`,
);
+console.log(`Titled ${stamped} anonymous OpenAPI union variants for Scalar.`);
diff --git a/web/scripts/openapi/stamp-union-variant-titles.ts b/web/scripts/openapi/stamp-union-variant-titles.ts
new file mode 100644
index 0000000000..1758ccc9b2
--- /dev/null
+++ b/web/scripts/openapi/stamp-union-variant-titles.ts
@@ -0,0 +1,176 @@
+import assert from "node:assert/strict";
+import {
+ isMap,
+ isScalar,
+ isSeq,
+ parse,
+ parseDocument,
+ type Node,
+ type Pair,
+} from "yaml";
+
+/** Fold width used by `fern export`. */
+const LINE_WIDTH = 80;
+const RESOLVE_OPTIONS = { maxAliasCount: -1 };
+const UNION_KEYS = ["oneOf", "anyOf"] as const;
+
+function scalarString(node: unknown): string | undefined {
+ if (!isScalar(node)) return undefined;
+ const value = node.value;
+ return typeof value === "string" ? value : undefined;
+}
+
+function pairKey(pair: Pair): string | undefined {
+ return scalarString(pair.key);
+}
+
+function refName(node: Node | null | undefined): string | undefined {
+ if (!isMap(node)) return undefined;
+ const ref = scalarString(node.get("$ref", true));
+ return ref?.split("/").at(-1) ?? ref;
+}
+
+/** References that compose the variant itself, excluding refs in properties. */
+function composingRefNames(variant: Node): string[] {
+ if (!isMap(variant)) return [];
+
+ const direct = refName(variant);
+ if (direct) return [direct];
+
+ const allOf = variant.get("allOf", true);
+ if (!isSeq(allOf)) return [];
+
+ return allOf.items
+ .map((item) => refName(item as Node))
+ .filter((name): name is string => Boolean(name));
+}
+
+function pascalCase(value: string): string {
+ return value
+ .split(/[^A-Za-z0-9]+/)
+ .filter(Boolean)
+ .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)
+ .join("");
+}
+
+function inferVariantName(
+ variant: Node,
+ schemas: Node | null | undefined,
+): string | undefined {
+ if (!isMap(variant)) return undefined;
+
+ const title = scalarString(variant.get("title", true));
+ if (title) return pascalCase(title);
+
+ const uniqueRefs = [...new Set(composingRefNames(variant))];
+ if (uniqueRefs.length > 1) return undefined;
+
+ const refName = uniqueRefs[0];
+ if (refName) {
+ const referencedSchema = isMap(schemas)
+ ? schemas.get(refName, true)
+ : undefined;
+ if (isMap(referencedSchema)) {
+ const referencedTitle = scalarString(referencedSchema.get("title", true));
+ if (referencedTitle) return pascalCase(referencedTitle);
+ }
+ return refName;
+ }
+
+ const type = scalarString(variant.get("type", true));
+ if (!type) return undefined;
+
+ const format = scalarString(variant.get("format", true));
+ return pascalCase(format ? `${format}-${type}` : type);
+}
+
+function stampNode(
+ node: Node | null | undefined,
+ path: string,
+ schemas: Node | null | undefined,
+): number {
+ let stamped = 0;
+
+ if (isMap(node)) {
+ for (const unionKey of UNION_KEYS) {
+ const union = node.get(unionKey, true);
+ if (!isSeq(union)) continue;
+
+ const names = union.items.map((variant, index) => {
+ const name = inferVariantName(variant as Node, schemas);
+ if (!name) {
+ throw new Error(
+ `Cannot infer OpenAPI variant title for ${path}.${unionKey}[${index}]`,
+ );
+ }
+ return name;
+ });
+
+ const duplicate = names.find(
+ (name, index) => names.indexOf(name) !== index,
+ );
+ if (duplicate) {
+ throw new Error(
+ `Duplicate OpenAPI variant title ${duplicate} in ${path}.${unionKey}`,
+ );
+ }
+
+ union.items.forEach((variant, index) => {
+ if (!isMap(variant)) {
+ throw new Error(
+ `Cannot stamp non-object union variant ${path}.${unionKey}[${index}]`,
+ );
+ }
+ const hasNaturalName =
+ scalarString(variant.get("title", true)) || refName(variant);
+ if (!hasNaturalName) {
+ variant.set("title", names[index]);
+ stamped += 1;
+ }
+ });
+ }
+
+ for (const pair of node.items) {
+ const key = pairKey(pair) ?? "?";
+ stamped += stampNode(pair.value as Node, `${path}.${key}`, schemas);
+ }
+ } else if (isSeq(node)) {
+ node.items.forEach((item, index) => {
+ stamped += stampNode(item as Node, `${path}[${index}]`, schemas);
+ });
+ }
+
+ return stamped;
+}
+
+/**
+ * Gives every OpenAPI `oneOf` / `anyOf` branch a stable display title.
+ *
+ * Fern emits anonymous wrapper objects for discriminated unions. Scalar then
+ * falls back to the parent schema title, making every option look identical in
+ * the API reference. Name anonymous wrappers from their composing schema and
+ * anonymous primitives from their format/type. Direct refs and existing titles
+ * already have a stable name and stay untouched.
+ */
+export function stampUnionVariantTitles(source: string): {
+ source: string;
+ stamped: number;
+} {
+ const document = parseDocument(source);
+ if (document.errors.length > 0) {
+ throw new Error(document.errors.map((error) => error.message).join("\n"));
+ }
+
+ const schemas = document.getIn(["components", "schemas"], true) as
+ | Node
+ | null
+ | undefined;
+ const stamped = stampNode(document.contents, "$", schemas);
+ const expected = document.toJS(RESOLVE_OPTIONS) as unknown;
+ const text = document.toString({ lineWidth: LINE_WIDTH });
+ const after = parse(text, RESOLVE_OPTIONS) as unknown;
+
+ assert.deepStrictEqual(after, expected);
+
+ return { source: text, stamped };
+}
diff --git a/web/src/__tests__/server/unit/openapi-union-variant-titles.servertest.ts b/web/src/__tests__/server/unit/openapi-union-variant-titles.servertest.ts
new file mode 100644
index 0000000000..0a51c0f8c7
--- /dev/null
+++ b/web/src/__tests__/server/unit/openapi-union-variant-titles.servertest.ts
@@ -0,0 +1,163 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+
+import { stampUnionVariantTitles } from "../../../../scripts/openapi/stamp-union-variant-titles";
+
+type Schema = {
+ oneOf?: Array<Record<string, unknown>>;
+ anyOf?: Array<Record<string, unknown>>;
+};
+type OpenApiDocument = {
+ components: { schemas: Record<string, Schema> };
+};
+
+const SPEC = `openapi: 3.0.1
+components:
+ schemas:
+ LlmRequest:
+ title: LLMJudgeRequest
+ type: object
+ CodeRequest:
+ type: object
+ CreateRequest:
+ oneOf:
+ - type: object
+ allOf:
+ - type: object
+ properties:
+ type:
+ type: string
+ enum: [llm_as_judge]
+ - $ref: '#/components/schemas/LlmRequest'
+ - type: object
+ allOf:
+ - type: object
+ properties:
+ type:
+ type: string
+ enum: [code]
+ - $ref: '#/components/schemas/CodeRequest'
+ DirectRequest:
+ oneOf:
+ - $ref: '#/components/schemas/LlmRequest'
+ - $ref: '#/components/schemas/CodeRequest'
+ Value:
+ oneOf:
+ - type: number
+ format: double
+ - type: string
+`;
+
+function parseSpec(source: string): OpenApiDocument {
+ return parse(source, { maxAliasCount: -1 }) as OpenApiDocument;
+}
+
+function titles(source: string, schema: string): unknown[] {
+ return (
+ parseSpec(source).components.schemas[schema].oneOf?.map(
+ (variant) => variant.title,
+ ) ?? []
+ );
+}
+
+function expectAllUnionVariantsNamed(value: unknown, path = "$"): void {
+ if (Array.isArray(value)) {
+ value.forEach((item, index) =>
+ expectAllUnionVariantsNamed(item, `${path}[${index}]`),
+ );
+ return;
+ }
+ if (!value || typeof value !== "object") return;
+
+ const record = value as Record<string, unknown>;
+ for (const unionKey of ["oneOf", "anyOf"] as const) {
+ const union = record[unionKey];
+ if (!Array.isArray(union)) continue;
+
+ union.forEach((variant, index) => {
+ const branch = variant as Record<string, unknown>;
+ const name = branch.title ?? branch.$ref;
+ expect(name, `${path}.${unionKey}[${index}]`).toEqual(expect.any(String));
+ });
+ }
+
+ for (const [key, child] of Object.entries(record)) {
+ expectAllUnionVariantsNamed(child, `${path}.${key}`);
+ }
+}
+
+describe("OpenAPI union variant titles", () => {
+ it("gives every union variant in the generated public spec a resolvable name", () => {
+ const openApiPath = path.resolve(
+ process.cwd(),
+ "public/generated/api/openapi.yml",
+ );
+ const openApi = parseSpec(fs.readFileSync(openApiPath, "utf8"));
+
+ expectAllUnionVariantsNamed(openApi);
+ });
+
+ it("names Fern wrappers from referenced schema titles and names", () => {
+ const result = stampUnionVariantTitles(SPEC);
+
+ expect(titles(result.source, "CreateRequest")).toEqual([
+ "LLMJudgeRequest",
+ "CodeRequest",
+ ]);
+ expect(titles(result.source, "DirectRequest")).toEqual([
+ undefined,
+ undefined,
+ ]);
+ expect(result.stamped).toBe(4);
+ });
+
+ it("names primitive variants by format and type", () => {
+ const result = stampUnionVariantTitles(SPEC);
+
+ expect(titles(result.source, "Value")).toEqual(["DoubleNumber", "String"]);
+ });
+
+ it("is idempotent", () => {
+ const first = stampUnionVariantTitles(SPEC);
+ const second = stampUnionVariantTitles(first.source);
+
+ expect(second.source).toBe(first.source);
+ expect(second.stamped).toBe(0);
+ });
+
+ it("does not use nested property refs as the variant name", () => {
+ const nestedPropertyRef = `openapi: 3.0.1
+components:
+ schemas:
+ Payload:
+ type: object
+ Value:
+ oneOf:
+ - type: object
+ properties:
+ payload:
+ $ref: '#/components/schemas/Payload'
+ - type: string
+`;
+
+ const result = stampUnionVariantTitles(nestedPropertyRef);
+
+ expect(titles(result.source, "Value")).toEqual(["Object", "String"]);
+ });
+
+ it("fails when inferred names are ambiguous", () => {
+ const ambiguous = `openapi: 3.0.1
+components:
+ schemas:
+ Value:
+ oneOf:
+ - type: string
+ - type: string
+`;
+
+ expect(() => stampUnionVariantTitles(ambiguous)).toThrow(
+ /Duplicate OpenAPI variant title String/,
+ );
+ });
+});