Skip to main content

human readable and writable data interchange format

Project description
Version: 0.3.0
Released: 2020-09-03
Please post all questions, suggestions, and bug reports to NestedText Github.

NestedText is a file format for exchanging data held in strings that are contained within lists, and dictionaries. In this way it is similar to JSON, YaML, or StrictYaML, but with a restricted set of supported data types, the file format is simpler. It is designed to be easy to enter with a text editor and easy to read. The small number of data types supported means few rules need be kept in mind when creating a file. The result is a data file that is easily created, modified, or viewed with a text editor and be understood and used by both programmers and non-programmers.

NestedText is convenient for configuration files, address books, account information and the like. Here is an example of a file that contains a few addresses:

# Contact information for our officers

    name: Katheryn McDaniel
        > 138 Almond Street
        > Topika, Kansas 20697
        cell: 1-210-555-5297
        home: 1-210-555-8470
        - Joanie
        - Terrance

vice president:
    name: Margaret Hodge
        > 2586 Marigold Lane
        > Topika, Kansas 20682
    phone: 1-470-555-0398
        - Arnie
        - Zach
        - Maggie

    name: Fumiko Purvis
        > 3636 Buffalo Ave
        > Topika, Kansas 20692
    phone: 1-268-555-0280
        - Lue

The format holds dictionaries (ordered collections of name/value pairs), lists (ordered collections of values) and strings organized hierarchically to any depth. Indentation is used to indicate the hierarchy of the data, and a simple natural syntax is used to distinguish the types of data in such a manner that it is not easily confused.


There are no shortage of well established alternative to NestedText for storing data in a human-readable text file. Probably the most obvious are json and YAML. Both have serious short comings.

JSON is a subset of JavaScript suitable for holding data. Like NestedText it consists of a hierarchical collection of dictionaries, lists, and strings, but also allows integers, floats, booleans and nulls. The problem with JSON for this application is that it is awkward. All strings have to be quoted; it only supports multi-line strings by using long single-line strings with embedded newline characters; and dictionary and list items must be separated with commas. All of which results in JSON being a frustrating format for humans to enter or read.

YAML was to be the human friendly alternative to JSON, but things went very wrong at some point. The authors were too ambitious and tried to support too many data types and too many formats. To distinguish between all the various types and formats, a complicated and non-intuitive set of rules developed. YAML at first appears very appealing when used with simple examples, but things quickly become very complicated. A reaction to this is the use of YAML subsets, such as StrictYAML. However, the subsets try to maintain compatibility with YAML and so inherits much of its complexity.

NestedText was inspired by YAML, but eschews its complexity. It supports only a limited number of types and has a very simple set of rules that make up the format.

Quick Start

Install with:

pip3 install --user nestedtext


Please ask questions or report problems on Github.


This package contains a Python reference implementation of NestedText. Implementation in many languages is required for NestedText to catch on widely. If you like the format, please consider contributing additional implementations.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nestedtext-0.3.0.tar.gz (8.5 kB view hashes)

Uploaded source

Built Distribution

nestedtext-0.3.0-py3-none-any.whl (8.0 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page