JSONL Processing

Relevant source files

The following files were used as context for generating this wiki page:

• packages/jsonl/jsonl.go
• messagebatch.go
• schemautil.go
• examples/structured-outputs/main.go
• examples/tools-streaming-jsonschema/main.go
• shared/constant/constants.go

Introduction

JSONL (JSON Lines) processing in the Anthropic Go SDK is primarily utilized for handling high-volume asynchronous operations via the Message Batches API. This format allows the SDK to stream and parse individual JSON objects line-by-line, providing an efficient mechanism for processing large datasets of model requests and responses without loading the entire payload into memory.

The SDK integrates JSONL processing into its MessageBatchService, enabling developers to retrieve results from processed batches as a continuous stream of individual response objects. This is critical for maintaining performance and reliability when dealing with the 24-hour processing window and potentially massive result sets associated with batch operations.

Sources: messagebatch.go:167-171, messagebatch.go:183-186

Architecture and Data Flow

The JSONL processing architecture follows a streaming pattern where the SDK requests a specific resource with the application/x-jsonl header. The raw HTTP response body is then wrapped in a specialized jsonl.Stream that handles the iterative decoding of each line into a target Go struct.

Batch Result Streaming Flow

The following diagram illustrates how the SDK requests and processes JSONL results from the Message Batches API.

This flow ensures that even if a batch contains thousands of messages, the client application processes them sequentially as they arrive over the wire.

Sources: messagebatch.go:171-181, packages/jsonl/jsonl.go

Key Components and Data Structures

Message Batch Individual Response

The primary data structure retrieved via JSONL is the MessageBatchIndividualResponse. Each line in the .jsonl result file represents one such object, containing a unique identifier and the result of the specific request.

Field	Type	Description
custom_id	string	Developer-provided ID to match results to requests.
result	MessageBatchResultUnion	The outcome (Success, Error, Canceled, or Expired).

Sources: messagebatch.go:343-356

Message Batch Result Variants

The result field within a JSONL line is a union type that can represent multiple states of a processed message.

Result Type	Constant	Description
Succeeded	constant.Succeeded	Contains the successfully generated Message.
Errored	constant.Errored	Contains a shared.ErrorResponse.
Canceled	constant.Canceled	Indicates the request was canceled before completion.
Expired	constant.Expired	Indicates the 24-hour window for processing was exceeded.

Sources: messagebatch.go:389-430, shared/constant/constants.go:102,118,119,154

Schema Transformation and Validation

While JSONL handles the transport of multiple JSON objects, the SDK also provides utilities in schemautil.go to ensure individual JSON structures (like those used in tool calls or structured outputs) conform to Anthropic's strict requirements.

The transformSchema function recursively processes JSON schemas to:

1. Ensure additionalProperties is set to false.
2. Filter for supportedStringFormats (e.g., date-time, uuid, ipv4).
3. Convert oneOf blocks to anyOf for compatibility.
4. Append unsupported properties to the description field for visibility.

Implementation Example: Results Streaming

The following snippet demonstrates how the SDK initiates a JSONL stream for batch results.

// From messagebatch.go:171-181
func (r *MessageBatchService) ResultsStreaming(ctx context.Context, messageBatchID string, opts ...option.RequestOption) (stream *jsonl.Stream[MessageBatchIndividualResponse]) {
	var (
		raw *http.Response
		err error
	)
	opts = slices.Concat(r.Options, opts)
	opts = append([]option.RequestOption{option.WithHeader("Accept", "application/x-jsonl")}, opts...)
	path := fmt.Sprintf("v1/messages/batches/%s/results", messageBatchID)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &raw, opts...)
	return jsonl.NewStream[MessageBatchIndividualResponse](https://github.com/ajit216/anthropic-sdk-go/blob/HEAD/raw%2C%20err)
}

Sources: messagebatch.go:171-181

Conclusion

JSONL Processing serves as the backbone for high-throughput interactions with the Anthropic API within this SDK. By leveraging application/x-jsonl streaming and robust schema transformation utilities, the SDK allows developers to manage large-scale message batches and complex structured outputs efficiently. This approach minimizes memory overhead and ensures that batch results are processed in a reliable, type-safe manner.