LoganSquare: Annotation-Based JSON Parsing for Android, With a Speed Claim You Should Verify

What LoganSquare Solves and Who It Targets

LoganSquare addresses a specific pain point for Android developers: JSON parsing and serialization that is fast enough for UI-bound work. The README claims it is the fastest JSON library available for Android, consistently outperforming GSON and Jackson Databind by 400% or more. That claim is based on ART, the Android runtime, and the README notes that on Dalvik the comparison is much closer. The target audience is Android developers who are willing to trade build-time complexity for runtime speed. It is not a general-purpose JSON library; it is tied to Android and to a compile-time code generation model. If you are building a server-side Java application or a non-Android mobile app, LoganSquare is not for you.

The Mechanism: Annotation Processing Generates Mappers

LoganSquare's core idea is to move JSON mapping work from runtime reflection to compile-time code generation. You annotate your model class with @JsonObject and each field with @JsonField. The annotation processor, delivered as logansquare-compiler, reads those annotations and generates a class for each model, named something like YourModel$$JsonObjectMapper. That generated class contains the actual parsing and serialization logic, built on top of Jackson's streaming API. At runtime, the library, which is a tiny 19kb jar, calls into those generated classes. The README says this avoids the tedious low-level code of writing JsonParser or JsonGenerator by hand. The result is that there is no reflection during parsing, which is where the speed improvement comes from. The trade-off is that you cannot use LoganSquare without the annotation processor; the generated code is a required part of your build.

Getting It Running: Gradle-Only Setup With a Legacy Plugin

The README is explicit: Gradle is the only supported build configuration. The setup requires the android-apt plugin, version 1.8, from the com.neenbedankt.gradle.plugins group. You add that plugin to your buildscript classpath, apply it, and then add two dependencies: apt 'com.bluelinelabs:logansquare-compiler:1.3.6' for the annotation processor and compile 'com.bluelinelabs:logansquare:1.3.6' for the runtime. The android-apt plugin is what enables compile-time annotation processing in the Android Gradle plugin. This is an older approach; modern Android projects use the annotationProcessor configuration or Kapt for Kotlin. The README does not mention any alternative setup. If you are using a recent Android Gradle plugin, you may find that android-apt is no longer compatible. That is a real friction point for adoption today.

Usage and Custom Types: The Documented Path

The README points to four documentation files: creating models, parsing from JSON, serializing to JSON, and supporting custom types. The basic usage is straightforward: annotate a model class with @JsonObject, annotate each field with @JsonField, and then LoganSquare generates the mapper. Parsing and serializing are handled by the generated code, so you do not write any low-level JSON logic. For custom types, the README mentions TypeConverters, which are presumably classes that tell LoganSquare how to convert a non-standard type to and from JSON. The README does not give a full example of a TypeConverter, so you would need to read the docs in the repository. The presence of TypeConverters suggests that LoganSquare is not limited to simple POJOs, but the documentation is the only source for how they work.

A Genuine Limitation: ProGuard Requirements and Build Age

LoganSquare has a clear failure mode: ProGuard, the code shrinker, might remove the generated mapper classes because they are only referenced reflectively. The README provides a specific ProGuard configuration to prevent this: keep the package com.bluelinelabs.logansquare.**, keep any class annotated with @JsonObject, and keep any class ending in $$JsonObjectMapper. Without those rules, your app will crash at runtime when the mapper is missing. That is a real operational cost. Another limitation is the project's age. The README references version 1.3.6, and there are no recent releases listed. The default branch is development, and the last push is unknown. This is not a library that is being actively maintained. If you hit a bug, you may be on your own.

The Alternative: Jackson Databind or GSON, With a Different Trade-Off

The obvious alternatives are the two libraries LoganSquare claims to beat: GSON and Jackson Databind. Both are runtime reflection-based. GSON uses reflection to map JSON to your fields, which is flexible but slower. Jackson Databind also uses reflection, though it has some optimizations. LoganSquare's approach is different: it generates code at compile time, so there is no reflection cost at runtime. That is the core difference. The trade-off is that GSON and Jackson Databind work with any Java environment, not just Android, and they do not require an annotation processor or a specific build plugin. They also have active communities and frequent releases. If you need speed and are willing to accept the build complexity, LoganSquare is the choice. If you need simplicity, portability, or ongoing support, GSON or Jackson Databind are safer.

Maintenance and License Implications

LoganSquare is licensed under Apache-2.0, which is permissive. You can use it in commercial projects, modify it, and distribute it, as long as you include the license notice. The README includes the full Apache license text. There is no mention of a code of conduct, contributing guidelines, or a changelog. The project is not archived, but the absence of recent releases and the unknown last push date suggest that maintenance is minimal. The README's own props section credits Jackson's streaming API and Instagram's ig-json-parser as inspirations, which gives you a hint about the design lineage. For upgrade cost, you are stuck with version 1.3.6 for the foreseeable future. If you adopt LoganSquare, you are committing to a library that may not receive updates. That is a risk you should weigh against the performance benefit.

Editorial conclusion

Adopt LoganSquare if you need the fastest possible JSON parsing on Android and you are comfortable with a Gradle-only, annotation-processing workflow that has not seen a release in years. Do not adopt it if you need Kotlin support, ongoing maintenance, or a library that works with the modern Android Gradle plugin without legacy apt configuration. Before adopting, verify the 400% claim by building and running the included BenchmarkDemo on your target devices; also check whether the last release, 1.3.6, works with your current Android build tools.

Official sources

1. Official README
2. Project repository