Product Updates

Native JSONL support in your SDKs

Emre Tezisci

April 7, 2025

Structured Streaming APIs powered by formats like JSON Lines (JSONL) are revolutionizing how applications consume real-time data. Their surging popularity isn’t surprising—they enable everything from token-by-token LLM interactions to large-scale analytics with minimal latency, fundamentally changing how AI systems process information. Today, we’re excited to announce built-in support for JSONL in Speakeasy-generated SDKs—eliminating complex boilerplate code and improving developer experience. This capability also complements our existing support for the Server-Sent Events (SSE) streaming protocol.

What is JSON Lines (JSONL)?

JSON Lines is a simple yet powerful data format designed specifically for streaming and incremental processing scenarios. By structuring data in a consistent line-by-line approach, JSONL offers significant advantages for modern API implementations:

One JSON per line: Each line is a complete, standalone JSON object
Newline separated: Individual objects separated by \n characters
Streaming-friendly: Process data incrementally as it arrives
Memory efficient: Handle large datasets without significant memory overhead
Easily appendable: Perfect for log aggregation and real-time event streams

Here’s a simple JSONL stream example:

{"id": 101, "username": "alice", "status": "active"}
{"id": 102, "username": "bob", "status": "inactive", "groups": ["dev", "test"]}
{"id": 103, "username": "charlie", "status": "active", "last_login": "2025-04-07T10:00:00Z"}

Think of JSONL like receiving a continuous stream of small packages. Each package can be opened and processed immediately, unlike traditional JSON which requires receiving the complete payload first.

Why JSONL matters for AI & real-time APIs

JSONL powers key capabilities your API consumers increasingly demand:

Enhanced AI/LLM experiences: Token-by-token streaming vastly improves perceived performance
Reactive AI agents: Enables real-time analysis and mid-stream interactions
Large dataset processing: Efficiently handle large datasets with minimal memory footprint
Real-time data processing: Essential for live dashboards and monitoring tools

The Challenge: Consuming JSONL streams

When developers interact with JSONL-formatted API responses, they face significant technical hurdles. Consuming these streams requires writing extensive custom code to handle asynchronous connections, buffer incoming data, parse JSON objects line by line, validate against expected schemas, and transform raw data into usable objects. This complexity creates a substantial barrier to entry, especially for developers who simply want to integrate with your API quickly and reliably. Each implementation risks introducing subtle bugs in stream handling, leading to brittle integrations and increased support burden.

Solution: Built-in JSONL support in your SDKs

Speakeasy addresses these challenges by automatically generating SDKs with sophisticated JSONL handling capabilities built directly into the client libraries you provide to your users. As an API provider, you simply define your streaming endpoints in your OpenAPI specification, and Speakeasy generates all the necessary data processing logic for your consumers. The resulting SDKs handle the entire workflow—from connection management to object deserialization—presenting your users with a clean, intuitive interface that feels like working with native language constructs rather than managing complex protocols.

How to define JSONL in your OpenAPI Spec

To use this feature, simply:

Define an operation with a response using application/jsonl content type
Specify the schema for individual objects in the stream

Speakeasy then does the heavy lifting—generating the SDK logic that handles line-by-line parsing, validation, and type-safe data models automatically.

For example:

/stream:
  get:
    responses:
      '200':
        content:
          application/jsonl:
            schema:
              # Your per-line object schema here
              type: object
              properties:
                id: 
                  type: integer
                message:
                  type: string

Broader streaming support

This new JSONL capability complements Speakeasy’s existing robust support for handling Server-Sent Events (SSE) with the text/event-stream content type. While JSONL is a data format for structured information, SSE is an actual streaming transport mechanism built on HTTP. For more information about our SSE support:

Availability & Automated handling

SDK generation with built-in JSONL handling is available today for Python (using Pydantic models) and we are actively developing support for TypeScript, Go, Java, C#, PHP, Ruby and all future languages. For supported languages, generated SDKs automatically:

Read streams incrementally
Parse each JSON line individually
Validate each object against your OpenAPI-defined schema
Yield typed, ready-to-use data models

Example: Effortless Python Experience

# SDK generated by Speakeasy handles all streaming complexity
try:
    for record in client.operations.stream_log_data():
        # 'record' is a typed Pydantic model matching your schema
        # Typed, validated, and ready-to-use!
        process_record(record.id, record.message)
except ApiException as e:
    print(f"Error consuming stream: {e}")

Without Speakeasy’s SDK generation capabilities, developers would need to implement multiple components themselves. Our approach encapsulates this complexity behind a clean, intuitive interface, significantly reducing development time and potential for errors.

Benefits for your API consumers

Rapid integration: Eliminates boilerplate coding
Increased reliability: Reduces potential parsing and validation errors
Superior developer experience: Simplifies complex stream interactions

Get started today

Define your streaming data formats natively in the spec with text/event-stream for SSE and application/jsonl for JSON Lines.
Generate your SDK: speakeasy quickstart
Empower your users with enhanced data handling capabilities.

See the documentation for a detailed guide.