ox-json

JSON export back end for Emacs Org mode.

Usage

(require 'ox-json) somewhere and then use the org-export-dispatch interactive command and select the J key for JSON export.

You can also use the ox-json-export-to-buffer and ox-json-export-to-file functions or any of the built-in org-export- functions by passing 'json as the backend argument.

Output

Document

An exported document looks like:

{
  "$$data_type": "org-document",
  "properties": {
    "title": ["Test file"],
    "filetags": ["foo", "bar"],
    "author": ["Jared Lumpe"],
    "creator": "Emacs 30.2 (Org mode 9.7.11)",
    "date": ["2026-01-01"],
    "description": ["Test file"],
    "email": "jared@example.com",
    "language": "en"
  },
  "contents": [
    ...
  ]
}

• "contents": array containing the top-level elements of the document (which will be an optional section element followed by any number of headline elements).
• "properties": File-level properties:
  • "title" (array, secondary string)
  • "filetags" (array of strings)
  • "author" (string)
  • "creator" (string)
  • "date" (array, secondary string)
  • "description" (array, secondary string)
  • "email" (string)
  • "language" (string)

Nodes

All nodes (elements and objects) in the document tree are exported like:

{
  "$$data_type": "org-node",
  "type": "headline",
  "ref": "orgd51ec19",
  "properties": { ... },
  "contents": [ ... ]
}

• "type" (string): node type returned by org-element-type
• "properties" (object): property names and values obtained from org-element-property. Leading colons in the keys are omitted.
• ref (string): unique string assigned to all nodes during the export process, from org-export-get-reference.
• "contents": encoded return value of org-element-contents. Items are either more org nodes or strings.

See the Org element API documentation for a complete list of all node types and properties. Also see the section Node types with specific handling.

Additional notes

The "$$data_type" property is added to JSON objects to indicate the type of structured data they contain. This is meant to make it easier for external tools to interpret. Objects lacking this property represent simple key-value mappings with no additional implied structure.

The resulting JSON should include the correct choice of empty object ({}), empty list ([]), null, or false for the given context, even though these are represented as nil in elisp (don`t get me started).

Node types with specific handling

Some specific node types have additional properties added. These are at the outer level instead of under the "properties" key to distinguish them from Org's builtin properties.

headline

Additional properties:

• "drawer" (object): Properties defined in :PROPERTIES: drawer.
• "tags-all" (array of strings): All tags including those inherited from parents.

link

Additional properties:

• is-inline-image (bool): Whether org mode think this link should be rendered as an inline image.
• is-internal (bool): Whether this link points to a location in the same document. True for the id, fuzzy, and radio link types.
• target-ref (string): The ref property of the headline or other node this link resolves to. Only exists for internal links.

timestamp

Additional properties:

• "start", "end" (string): Year/month/day/hour/minute from the start-* and end-* sets of properties combined together and encoded as a single string in ISO 8601 format.

Options

Property	Data type	Default
:json-data-type-property	string	"$$data_type"
:json-exporters	plist	See variable ox-json-default-type-exporters
:json-property-types	plist	See variable ox-json-default-property-types
:json-strict	bool	nil
:json-include-extra-properties	bool	t
:json-omit-default-property-values	bool	t
:json-postprocess	symbol	pretty
:json-deterministic-refs	bool	nil

• :json-data-type-property: Name of the property added to JSON objects which indicates the type of data they represent. Set to nil to disable.
• :json-omit-default-property-values: When non-nil, node properties whose value equals the configured default are omitted from export. Defaults are defined in ox-json-default-property-values (not customizable currently).
• :json-postprocess: How to format the final output. pretty indents the JSON, minimal strips whitespace, and nil leaves the output unmodified.
• :json-deterministic-refs: When non-nil, node ref values are derived from each node's structural path in the parse tree rather than a random number, producing refs that are stable across repeated exports of identical source (and across Org versions). Defaults to nil (random refs).

Related software

Check out the pyorg Python package, which contains tools for reading and manipulating the exported JSON data and interacting with a running Emacs process.