[ericproulx]

Summary

Adds JSON Lines (jsonlines.org) as a built-in format: a formatter, a parser and an error formatter registered under :jsonl. Like any format outside the defaults, an API declares it with content_type.

class API < Grape::API
  content_type :jsonl, 'application/jsonl'
  format :jsonl

  get :users do
    User.all # {"id":1,"name":"Ada"}\n{"id":2,"name":"Grace"}\n
  end

  get :export do
    User.find_each # an Enumerator: streamed, one line at a time
  end
end

• Response: an Array renders one line per element and any other object one line, each as Grape::Formatter::Json renders it (so a Grape::PrecompiledJson element is served verbatim as its line). A top-level String is served as it is, taken to be JSON Lines already, as :serializable_hash does.
• Streaming: an Enumerator body renders lazily: each element is encoded only when the server reads the body, and each line goes out as its own chunk. To support this, a formatter may now return a Grape::ServeStream::StreamResponse, which the formatter middleware serves the same way it serves stream. stream itself is unchanged and still writes raw chunks.
• Request: a JSON Lines body parses into an Array of its lines' values. Blank lines are skipped, so a trailing newline and CRLF line ends both parse, and a line that is not JSON answers 400 (InvalidMessageBody).
• Errors render as one JSON line (the JSON error formatter's output followed by a newline).

Design choices

• Kept out of ContentTypes::DEFAULTS. DEFAULTS is what every API that declares no content type negotiates. Adding jsonl there would make all of those APIs answer Accept: application/jsonl and /path.jsonl in JSON Lines, accept application/jsonl bodies where they answer 415 today, and add the type to grape-swagger's produces. An API declares it with content_type :jsonl, ... like any other format outside the defaults, so format :jsonl alone raises MissingMimeType. No new mechanism lets format skip that declaration.
• The parser returns an Array, not a Hash. A JSON body that is an Array is treated the same way: it is available in env['api.request.body'] and not merged into params. Wrapping the lines under an invented key would introduce a convention nobody asked for. The README shows a one-line custom parser that wraps them for params validation.
• Media type application/jsonl. No media type is registered for JSON Lines. application/jsonl matches the format name and the .jsonl extension, and the README declares it; an API whose clients expect application/x-ndjson declares that instead.

Upgrading

An app that already declared content_type :jsonl, ... itself, without its own formatter, parser or error formatter for it, now gets Grape's. Its String bodies are still served as they are, but a request body now arrives as an Array instead of the raw String (parser :jsonl, nil keeps the String), and errors render as a JSON line instead of through default_error_formatter. Covered in UPGRADING.

Caveats

• A streamed response has sent its status and headers before its first line is rendered, so an exception raised mid-stream is past rescue_from and the response simply ends early. This is documented in the README, and stream behaves the same way today.
• On Rack 2.2, Rack::ETag (which Rails includes) buffers any body that does not respond to to_path, so it reads a streamed body in full. Rack 3's ETag only digests to_ary bodies. stream is affected the same way.

Test plan

• New specs: spec/grape/formatter/jsonl_spec.rb, spec/grape/parser/jsonl_spec.rb, spec/grape/error_formatter/jsonl_spec.rb. The streaming spec drives the API through Rack and checks that nothing is rendered before the body is read and that each element arrives as its own chunk.
• Mutation-checked: making the stream eager, dropping the Enumerator branch, the String pass-through or the trailing newline, skipping the middleware's stream check, dropping blank-line skipping, and dropping null/false lines each fail at least one spec.
• bundle exec rake (RuboCop + full RSpec suite) passes on Ruby 4.0.7.
• The new and related specs pass with gemfiles/rack_2_2.gemfile (Rack 2.2.24).
• CI green.

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run

[dblock]

The OPT_IN name is strange. All we are trying to do is to introduce a non-default content-type? Should it be some kind of known type instead?

[ericproulx]

The OPT_IN name is strange. All we are trying to do is to introduce a non-default content-type? Should it be some kind of known type instead?

I removed the OPT_IN