Untyped Map-Like Fields in the Langfuse OpenAPI Spec. #38

I came across this while doing #36

There are Untyped Map-Like Fields in the Langfuse OpenAPI Spec.

Problem

The Langfuse OpenAPI spec (openapi.yml) has 28 fields across 18 schemas that represent JSON objects (key-value maps) but lack type: object and additionalProperties declarations. These fields have only a description and optionally nullable: true, with no type information.

In the OpenAPI 3.0 specification, a property with no type is treated as "any type" (AnyType). Code generators for strongly-typed languages map this to the language's top-level type — for example, Object in Java, any in TypeScript, or interface{} in Go — instead of a map/dictionary type. This degrades the developer experience because consumers must manually cast these values.

The spec already correctly types the same fields in other schemas (see Correctly Typed Fields below), making this an internal inconsistency rather than a design choice.

How We Identified Which Fields Should Be Typed

We used four criteria to determine which untyped fields should have type: object + additionalProperties: true added:

1. Internal Consistency Within the Spec

The same field name is correctly typed in some schemas but untyped in others. For example:

If the field is typed as type: object with additionalProperties in one schema, it should be typed the same way everywhere it appears.

2. Langfuse Documentation

The Langfuse documentation explicitly describes these fields as object/dictionary types:

• metadata: Documented as Record<string, unknown>. The v2→v3 migration guide states: "Only the Record type is supported within our UI and endpoints to perform queries and filter events." Non-object values sent as metadata are coerced into objects (e.g., "test" becomes { "metadata": "test" }).
• modelParameters: Documented as a string-keyed map ({ "property1": "string", "property2": "string" }). The UI renders it using Object.entries(), confirming it is always an object.
• config (on prompts): Documented as a freeform JSON dictionary. Accessed via dictionary methods in SDKs (cfg.get("model") in Python, cfg.model in JS/TS).

3. Semantic Analysis

Some fields are structurally always JSON objects by nature:

• inputSchema / expectedOutputSchema: These hold JSON Schema definitions, which are always JSON objects per the JSON Schema specification.
• tokenizerConfig: A configuration map for tokenizer settings — inherently key-value.
• lastConfig (in PromptMeta): The last-used prompt configuration, same semantics as config.

4. Exclusion Criteria — Fields That Should Remain Untyped

We explicitly excluded fields that can legitimately be any JSON value:

• input / output / expectedOutput: The Langfuse API documentation states these "Can be any JSON" — strings, numbers, arrays, or objects are all valid. Typing these as object would be incorrect.
• error (in IngestionError): Error payloads can be structured in various ways.
• log (in SDKLogBody): SDK debug payloads can be any JSON value.

Correctly Typed Fields (8)

These fields already have proper type: object + additionalProperties declarations and serve as the pattern that should be applied to the missing fields:

Fields Missing Type Definitions (28)

These fields should have type: object and additionalProperties: true added:

metadata (19 fields)

modelParameters (2 fields)

Note: The write-side schemas (CreateGenerationBody, UpdateGenerationBody, ObservationBody) already correctly type modelParameters as type: object with additionalProperties: { $ref: MapValue }.

config (3 fields)

Note: LlmConnection.config and UpsertLlmConnectionRequest.config already correctly use type: object with additionalProperties: true.

tokenizerConfig (2 fields)

inputSchema / expectedOutputSchema (4 fields)

lastConfig (1 field)

Cascading Impact via Schema Composition (30 schemas)

The 28 untyped fields cascade into 30 additional composed schemas via oneOf, allOf, and anyOf. Fixing the base schemas will automatically fix all of these:

Fields Correctly Left Untyped (18)

These fields are intentionally untyped because they can be any JSON value (string, number, array, object, or null). No changes needed:

Suggested Fix

For each of the 28 fields listed above, add type: object and additionalProperties: true to the property definition. For example, change:

metadata:
  nullable: true
  description: Additional metadata of the observation

to:

metadata:
  type: object
  additionalProperties: true
  nullable: true
  description: Additional metadata of the observation

And for the empty-definition case (BasePrompt.config: {}), change to:

config:
  type: object
  additionalProperties: true

Originally posted by @edeandrea in #36 (comment)