GiantJSON Viewer+ is built to handle files that crash other apps. It uses memory mapping, native code, and a structural index to navigate multi-gigabyte JSON files on mobile devices with constant memory usage.
But every system has boundaries. This article explains what those boundaries are, when you might encounter them, and what to do if a limitation affects your workflow.
For the vast majority of real-world JSON files, you'll never hit these limits.
Architectural Limits
The app's index format (v3) defines several hard limits that ensure stability on mobile devices:
| Limit | Value | What it means |
|---|---|---|
| Maximum file size | 1 TB | Files larger than 1 terabyte cannot be indexed. The internal offset format uses 40 bits, which caps at 1 TB. |
| Maximum nesting depth | 255 levels | JSON structures nested more than 255 levels deep will trigger an early exit. This prevents stack overflow during parsing. |
| Maximum node count | ~4.3 billion | The index uses 32-bit node addressing. Files with more than 4.3 billion objects and arrays cannot be fully indexed. |
| Maximum children per container | ~4.3 billion | Any single object or array can contain up to 4.3 billion items. |
Will you hit these limits?
Almost certainly not. A 1 TB JSON file would be exceptional even in enterprise data processing. Nesting depth of 255 is far beyond any practical data structure (most APIs nest 3-10 levels deep). And 4.3 billion nodes would require an extraordinarily large file.
These limits exist as guardrails for system stability, not as practical constraints.
Structure Mode: Configurable Analysis
When you view a file in Structure Mode (the tree view), the app analyzes the JSON to show you a collapsible schema. All analysis parameters are configurable from the Settings screen.
How it works
- Arrays: The engine samples elements from each array to determine the type pattern. Default: 1,000 elements, configurable from 10 to 1 million.
- Objects: All keys are displayed, but type inference is based on the sampled values. If a key sometimes contains a string and sometimes a number, the type shown is the majority type from the sample.
- Display limits (all configurable in Settings):
- Max depth: 50 levels (options: 10 / 25 / 50 / 100 / 255)
- Max children per level: 50 (options: 20 / 50 / 100 / 200)
- Max total nodes rendered: 1,000 (options: 500 / 1,000 / 2,000 / 5,000)
What this means for you
If your array contains 1 million items where the first 1,000 are objects but items 1,001+ are strings, the Structure Mode will show the array as containing objects (since that was 100% of the sample).
This is an intentional tradeoff: sampling makes structure analysis instant even on files with millions of records, while exhaustive analysis could take minutes and consume significant memory.
Unique JSONPath Limit
During indexing, the app collects every unique JSONPath in your file (e.g.,
$.users[*].name, $.users[*].address.city). These paths power Structure
Mode rendering, Browser Mode filter key selection, and export features.
Why there is a limit
Files with extremely complex or deeply nested structures can generate hundreds of thousands of unique paths. Each path is held in memory during index building, and collecting all of them on a mobile device can cause out-of-memory crashes.
Default and options
The default limit is 200,000 unique paths, configurable in Settings:
- 100K: Handles virtually all real-world files. Even complex APIs and large datasets rarely exceed a few thousand unique paths — 100K is already far beyond what typical JSON structures produce.
- 200K (default): Extra headroom for edge cases
- 500K: For moderately complex files on devices with 6 GB+ RAM
- 1M: For very complex files on high-end devices with 8 GB+ RAM
- Unlimited: No cap. Use only on powerful devices with very complex files
What happens when the limit is reached
If the number of unique paths exceeds the configured limit during indexing, the schema collection phase stops and returns an error. The file still opens and is fully navigable in Text Mode and Browser Mode — only Structure Mode and filter key suggestions are affected.
This is rare. Most JSON files, even multi-gigabyte ones, contain a few hundred unique paths at most. You'll typically only hit this limit with auto-generated schemas, deeply nested configuration files, or files where every object has unique key names.
Long Lines and Large Values
Android's text rendering system can struggle with extremely long lines. To prevent freezes, both viewing modes apply truncation:
- Text Mode detects lines longer than 4 KB and offers truncation options (partial preview or hide completely)
- Browser Mode always shows truncated value previews by design — it displays the first portion of each value inline, which keeps navigation instant regardless of value size
During indexing, a large value index is built that flags all values exceeding 4,096 bytes. This allows both modes to make instant truncation decisions without scanning the file at read time.
Viewing the full content
Truncation does not mean the data is inaccessible. Both Text Mode and Browser Mode include a Large Content Viewer — a dedicated screen for viewing the full value separately. If the value contains a stringified JSON, it is displayed unescaped and formatted for readability.
Additionally, Encoded Data Detection recognizes base64-encoded content matching 50+ known file formats (images, documents, archives, etc.) and lets you extract and download the original file directly.
Binary Format Support (CBOR & MessagePack)
Since version 1.8.1, GiantJSON Viewer+ can open CBOR and MessagePack binary JSON files.
How it works
On first open, the binary file is converted to standard JSON using a streaming Rust converter. The conversion runs token-by-token with constant memory usage — no intermediate allocation, regardless of file size. The resulting JSON file is stored locally, so subsequent opens skip the conversion entirely.
Limitations
- Output size: The converted JSON file will be larger than the original binary, since binary formats are more compact by design.
- Type mapping: Binary-specific types without a JSON equivalent are handled best-effort. Byte arrays are encoded as hex strings, CBOR tags are unwrapped, and MsgPack extension types are represented as strings.
- Storage: The converted JSON file is stored in the app's cache and counts toward your storage usage. You can clear all converted files from the Recent Files storage breakdown.
Index Storage
The structural index is stored in your device's app cache directory, and keeping large files in your Recent Files list means keeping their indexes.
How much storage does indexing use?
Each indexed node (object or array) costs exactly 32 bytes of on-disk storage. Primitive values (strings, numbers, booleans) are not indexed. During indexing, temporary files require additional disk space that is automatically cleaned up when indexing completes.
| File description | Indexed nodes | Final index size | Peak temp storage |
|---|---|---|---|
| Simple API response (50 objects) | 50 | ~1.6 KB | ~5 KB |
| Medium dataset (10,000 arrays/objects) | 10,000 | ~320 KB | ~1 MB |
| Large export (1 million containers) | 1,000,000 | ~32 MB | ~100 MB |
| Massive log file (100 million nodes) | 100,000,000 | ~3.2 GB | ~10 GB |
Additional auxiliary files (sparse line index, line length cache, keys index) add modest overhead, typically 1-5% of the final index size.
Memory usage during indexing
Indexing is designed to use a constant amount of memory regardless of file size. A 100 MB file and a 50 GB file use roughly the same peak memory — approximately 150 MB. This means you won't run into out-of-memory issues even when indexing very large files on devices with limited RAM.
Storage implications
- Re-indexing is required after clearing the app cache
- Index files are stored separately from your original JSON files
- Remote files (fetched via URL) are stored in app data and lost if the app is uninstalled
- Removing a file from Recent Files deletes its associated indexes
You can view your total storage usage and per-file breakdown from the Recent Files screen.
What GiantJSON Viewer+ Doesn't Do
To set expectations clearly:
- No editing: This is a viewer and analysis tool only. You cannot modify source files.
- No XML, YAML, or TOML: Supported formats are JSON, NDJSON/JSONL, HAR, CBOR, MessagePack, and Markdown.
- No pre-request/test scripts: The API client does not include a JavaScript engine. Postman scripts are skipped on import.
- No cloud sync: Files, indexes, and API collections stay on your device.
Hitting a Limitation?
If any of these boundaries blocks your actual use case, we want to hear about it. Understanding real-world edge cases helps us prioritize improvements.
Open an issue on GitHub: github.com/kotysoft/GiantJSON/issues
When reporting, please include:
- A description of your file (approximate size, structure type)
- Which limitation you encountered
- What you were trying to accomplish
All feedback helps shape future development.
Summary
| Area | Limit |
|---|---|
| File size | 1 TB |
| Nesting depth | 255 levels |
| Indexed nodes | 4.3 billion |
| Schema sampling (arrays) | Configurable (default: 1,000) |
| Structure tree depth | Configurable (default: 50) |
| Structure tree children per level | Configurable (default: 50) |
| Structure tree total nodes | Configurable (default: 1,000) |
| Long line threshold | 4 KB |
| Unique JSONPath limit | Configurable (default: 200,000) |
For typical JSON files, including multi-gigabyte ones, these limits are invisible. The app is designed so you only think about limits when you genuinely need to.
Handle Large JSON Files With Ease
Try GiantJSON Viewer+ free and experience smooth navigation through files that crash other apps.
Get GiantJSON Viewer+