Implementation:Langfuse Langfuse Score Application Validation

Knowledge Sources	Langfuse
Domains	Scores, Validation, Application Layer
Last Updated	2026-02-14 00:00 GMT

Overview

Provides application-layer validation functions for scores retrieved from the database, ensuring type safety through Zod schema parsing and supporting filtering by data types with optional metadata enrichment.

Description

This module contains three exported validation functions that serve as the application boundary for score data retrieved from the database:

• validateDbScore: Validates a single score against the ScoreSchema Zod schema. This is a strict validator that throws an error if the score fails validation. It should be used when a single score is expected to be valid (e.g., after a targeted database fetch).

• filterAndValidateDbScoreList: The primary validation function for score lists. It filters scores by specified data types and validates each against the ScoreSchema. It uses a generic type system with two type parameters: IncludeHasMetadata (boolean toggle for including the hasMetadata field) and DataTypes (a tuple of ScoreDataTypeType values to filter by). Scores that fail validation are logged to the console and optionally reported via an onParseError callback (intended for OpenTelemetry reporting). Invalid scores are silently filtered out rather than causing failures.

• filterAndValidateDbTraceScoreList (deprecated): A legacy v1 API function that validates scores against the APIScoreSchemaV1 schema without data type filtering. It is retained only for backward compatibility with the v1 API where scores were only associated with traces.

Both list validation functions use a reduce pattern to accumulate validated scores, supporting the optional hasMetadata field enrichment from the input score's hasMetadata property.

⚠️ Deprecation Note: The filterAndValidateDbTraceScoreList function is @deprecated and should be replaced with filterAndValidateDbScoreList, which supports scores associated with both traces and observations. Consumers should migrate to the recommended alternatives.

Usage

Use validateDbScore for single score retrieval paths. Use filterAndValidateDbScoreList for all new code paths that fetch multiple scores from the database and need them filtered by data type. The deprecated filterAndValidateDbTraceScoreList should only be maintained for the legacy v1 trace score endpoints.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/features/scores/interfaces/application/validation.ts
• Lines: 1-116

Signature

export const validateDbScore = (score: unknown): ScoreDomain;

export const filterAndValidateDbScoreList = <
  IncludeHasMetadata extends boolean,
  DataTypes extends readonly ScoreDataTypeType[],
>({
  scores,
  dataTypes,
  includeHasMetadata,
  onParseError,
}: {
  scores: InputScore[];
  dataTypes: DataTypes;
  includeHasMetadata?: IncludeHasMetadata;
  onParseError?: (error: z.ZodError) => void;
}): ValidatedScore<IncludeHasMetadata, DataTypes>[];

/** @deprecated Use filterAndValidateDbScoreList instead */
export const filterAndValidateDbTraceScoreList = <
  IncludeHasMetadata extends boolean,
>({
  scores,
  includeHasMetadata,
  onParseError,
}: {
  scores: InputScore[];
  includeHasMetadata?: IncludeHasMetadata;
  onParseError?: (error: z.ZodError) => void;
}): ValidatedAPITraceScore<IncludeHasMetadata>[];

Import

import {
  validateDbScore,
  filterAndValidateDbScoreList,
} from "@langfuse/shared/src/features/scores/interfaces/application/validation";

I/O Contract

Inputs

Name	Type	Required	Description
score	unknown	Yes	A single score object from the database (for validateDbScore).
scores	InputScore[]	Yes	Array of score objects from the database, each a ScoreDomain with optional hasMetadata.
dataTypes	readonly ScoreDataTypeType[]	Yes	Array of data types to filter by (e.g., ["NUMERIC", "BOOLEAN"]).
includeHasMetadata	boolean	No	Whether to include the hasMetadata field in the output (defaults to false).
onParseError	(error: z.ZodError) => void	No	Callback invoked when a score fails Zod validation, typically for telemetry reporting.

Outputs

Name	Type	Description
validateDbScore result	ScoreDomain	The validated score object; throws on failure.
filterAndValidateDbScoreList result	ValidatedScore[]	Array of validated scores filtered by data type, with optional hasMetadata.
filterAndValidateDbTraceScoreList result	ValidatedAPITraceScore[]	Array of validated v1 API scores with optional hasMetadata.

Usage Examples

import { filterAndValidateDbScoreList } from "@langfuse/shared/src/features/scores/interfaces/application/validation";

const rawScores = await fetchScoresFromDb(traceId);

const validatedScores = filterAndValidateDbScoreList({
  scores: rawScores,
  dataTypes: ["NUMERIC", "BOOLEAN"] as const,
  includeHasMetadata: true,
  onParseError: (error) => {
    otelSpan.recordException(error);
  },
});
// validatedScores contains only NUMERIC and BOOLEAN scores that passed validation