Implementation:Langfuse Langfuse Eval JSONPath Extraction Utilities

Knowledge Sources	Langfuse
Domains	Evaluations, JSONPath, Data Extraction
Last Updated	2026-02-14 00:00 GMT

Overview

Provides utility functions for the evaluation system, including string conversion of unknown values, recursive multi-encoded JSON parsing, and JSONPath-based value extraction from trace and observation data.

Description

This module contains three core utilities used by the evaluation pipeline:

• parseUnknownToString: Converts any unknown value to its string representation. Handles null/undefined (returns empty string), primitives (uses .toString()), objects (uses JSON.stringify), and symbols. This is the standard conversion applied to any evaluation variable that needs string form.

• parseMultiEncodedJson (internal): Recursively parses JSON strings that may have been JSON.stringify'd multiple times. It attempts JSON.parse and, if the result is still a string, recurses to handle double or triple encoding. Returns the final parsed object or the original value if parsing fails at any level.

• extractValueFromObject: The main extraction function that retrieves a value from a record by column ID, optionally applying a JSONPath selector. It first preprocesses string values through parseMultiEncodedJson, then applies JSONPath extraction using the jsonpath-plus library (or a custom parser function if provided). Returns both the string-converted value and any error encountered during JSONPath evaluation. On JSONPath failure, it falls back to the original unselected column value.

Usage

Use extractValueFromObject when building evaluation variable values from trace or observation data in the evaluation worker. Use parseUnknownToString when any evaluation variable needs to be converted to a string for template insertion or comparison.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/features/evals/utilities.ts
• Lines: 1-102

Signature

export const parseUnknownToString = (value: unknown): string;

export function extractValueFromObject(
  obj: Record<string, unknown>,
  selectedColumnId: string,
  jsonSelector?: string,
  parseJson?: (selectedColumn: unknown, jsonSelector: string) => unknown,
): { value: string; error: Error | null };

Import

import {
  parseUnknownToString,
  extractValueFromObject,
} from "@langfuse/shared/src/features/evals/utilities";

I/O Contract

Inputs

Name	Type	Required	Description
obj	Record<string, unknown>	Yes	The data object (trace or observation record) to extract a value from.
selectedColumnId	string	Yes	The key in obj to select (e.g., "input", "output", "metadata").
jsonSelector	string	No	Optional JSONPath expression to extract a nested value from the selected column.
parseJson	(selectedColumn: unknown, jsonSelector: string) => unknown	No	Optional custom JSON parser function; defaults to an internal function using jsonpath-plus.
value (parseUnknownToString)	unknown	Yes	Any value to convert to string representation.

Outputs

Name	Type	Description
value	string	The extracted and string-converted value from the object.
error	null	Any error encountered during JSONPath evaluation, or null if extraction succeeded.

Usage Examples

import { extractValueFromObject, parseUnknownToString } from "@langfuse/shared/src/features/evals/utilities";

const traceData = {
  input: JSON.stringify({ messages: [{ role: "user", content: "Hello" }] }),
  output: "World",
};

// Extract with JSONPath
const { value, error } = extractValueFromObject(traceData, "input", "$.messages[0].content");
// value => "Hello", error => null

// Simple string conversion
const str = parseUnknownToString({ key: "value" });
// str => '{"key":"value"}'