Convert JSON to ORG

Why Convert JSON to ORG?

Converting JSON to Emacs Org-mode format bridges the gap between machine-readable structured data and a powerful human-readable outline system. Org-mode, created by Carsten Dominik in 2003, is far more than a simple markup language. It is a comprehensive environment for organizing information, managing tasks, and writing documents. By converting JSON data to ORG, you can import structured datasets into your Org-mode workflow and leverage headings, property drawers, and tables to navigate and manipulate the data within Emacs.

This conversion is particularly valuable when you need to review API responses, configuration files, or exported database records inside your Org-mode knowledge base. Rather than reading raw JSON with nested braces and brackets, the converted ORG file presents the same information as a collapsible outline with clearly labeled sections. Nested objects become sub-headings, arrays become lists, and key-value metadata is stored in property drawers that can be queried with column view.

The generated ORG output integrates seamlessly with the Emacs Org-mode ecosystem. You can add TODO states to headings, schedule follow-up actions on specific data points, or use Org Babel to write code blocks that process the converted data directly. Since ORG is plain text, the files are version-control friendly and can be exported to HTML, PDF, LaTeX, or ODT through the built-in Org export dispatcher.

Key Benefits of Converting JSON to ORG:

• Outline Navigation: Collapse and expand sections to focus on specific parts of the data
• Property Drawers: Metadata stored in queryable :PROPERTIES: blocks for column view
• Task Integration: Add TODO states and deadlines to data items for follow-up
• Table Formatting: Tabular data rendered as native Org tables with alignment
• Export Flexibility: Convert to HTML, PDF, LaTeX, ODT, or Markdown from Org
• Plain Text Archival: ORG files are future-proof plain text, ideal for long-term storage

Practical Examples

Example 1: API Response to Org Outline

Input JSON file (users_api.json):

{
  "endpoint": "/api/v1/users",
  "total": 3,
  "users": [
    {"id": 1, "name": "Alice", "role": "admin", "active": true},
    {"id": 2, "name": "Bob", "role": "editor", "active": true},
    {"id": 3, "name": "Carol", "role": "viewer", "active": false}
  ]
}

Output ORG file (users_api.org):

* Users API
:PROPERTIES:
:endpoint: /api/v1/users
:total: 3
:END:

** Users
| id | name  | role   | active |
|----+-------+--------+--------|
|  1 | Alice | admin  | true   |
|  2 | Bob   | editor | true   |
|  3 | Carol | viewer | false  |

Example 2: Project Configuration to Org Document

Input JSON file (project.json):

{
  "name": "webapp",
  "version": "3.1.0",
  "scripts": {
    "build": "webpack --mode production",
    "test": "jest --coverage",
    "lint": "eslint src/"
  },
  "dependencies": ["react", "redux", "axios"],
  "devDependencies": ["webpack", "jest", "eslint"]
}

Output ORG file (project.org):

* webapp
:PROPERTIES:
:version: 3.1.0
:END:

** Scripts
| Command | Value                    |
|---------+--------------------------|
| build   | webpack --mode production|
| test    | jest --coverage          |
| lint    | eslint src/              |

** Dependencies
- react
- redux
- axios

** Dev Dependencies
- webpack
- jest
- eslint

Example 3: Task Data to Org TODO Items

Input JSON file (tasks.json):

{
  "project": "Website Redesign",
  "deadline": "2026-04-15",
  "tasks": [
    {"title": "Design mockups", "status": "done", "priority": "high"},
    {"title": "Implement frontend", "status": "in-progress", "priority": "high"},
    {"title": "Write API endpoints", "status": "todo", "priority": "medium"},
    {"title": "Deploy to staging", "status": "todo", "priority": "low"}
  ]
}

Output ORG file (tasks.org):

* Website Redesign
DEADLINE: <2026-04-15>

** DONE [#A] Design mockups
:PROPERTIES:
:priority: high
:END:

** TODO [#A] Implement frontend
:PROPERTIES:
:priority: high
:END:

** TODO [#B] Write API endpoints
:PROPERTIES:
:priority: medium
:END:

** TODO [#C] Deploy to staging
:PROPERTIES:
:priority: low
:END:

Frequently Asked Questions (FAQ)

Q: How are nested JSON objects represented in ORG?

A: Nested JSON objects are converted into sub-headings using increasing levels of asterisks (* for top level, ** for the next level, *** for deeper nesting, and so on). Simple key-value pairs within an object are placed in :PROPERTIES: drawers, while complex nested structures get their own heading sections. This preserves the full hierarchy and makes the data navigable through Org-mode's outline folding.

Q: Can I use the ORG output directly in Emacs?

A: Yes! The converted ORG file is fully compatible with Emacs Org-mode. Simply open the .org file in Emacs and you can immediately fold/unfold sections, use column view on property drawers, add TODO states, set deadlines, or export the document to HTML, PDF, and other formats using the Org export dispatcher (C-c C-e).

Q: How are JSON arrays handled in the conversion?

A: JSON arrays of primitive values (strings, numbers) are converted into Org unordered lists using the dash (-) prefix. Arrays of objects are transformed into Org tables with column headers derived from the object keys, making tabular data easy to read and sort within Emacs.

Q: What happens to JSON data types like booleans and null?

A: Boolean values are represented as "true" or "false" text in the ORG output. Null values are rendered as empty strings or "null" depending on the context. Numbers are preserved as-is. All data type information is maintained in a human-readable form within property drawers or table cells.

Q: Can I edit the ORG file in editors other than Emacs?

A: Absolutely. Since ORG is plain text, you can edit it in any text editor. For enhanced support, Vim users can install vim-orgmode or orgmode.nvim, and VS Code users can install the vscode-org-mode extension. Pandoc can also read and convert ORG files to dozens of other formats without requiring Emacs.

Q: What if my JSON file contains syntax errors?

A: If the JSON file has syntax errors, the converter will attempt to process as much valid data as possible. For severely malformed files, the raw content is included as an Org source block (#+BEGIN_SRC json ... #+END_SRC) so that no data is lost and you can manually correct the structure within Emacs.

Q: Can I export the ORG file to other formats afterward?

A: Yes, one of Org-mode's greatest strengths is its export system. From the converted ORG file you can generate HTML pages, PDF documents via LaTeX, ODT files for LibreOffice, Markdown, plain text, iCalendar for scheduling data, and more. Pandoc also supports ORG as an input format, giving you access to even more output options.