piml

Spec version: v1.1.0

Available Libraries

JSON<->PIML Converter

Parenthesis Intended Markup Language

In the ever-evolving landscape of data serialization formats, PIML (Parenthesis Intended Markup Language) emerges as a compelling alternative, prioritizing human readability and writability without compromising machine parseability. This post delves into the core tenets of PIML, exploring its syntax, data types, and how it stacks up against established formats like JSON, YAML, and TOML.

What is PIML?

PIML is a data serialization format designed for clarity and ease of use by both humans and machines. It leverages a unique (key) syntax and indentation-based nesting to create a visually intuitive representation of structured data. Conceived as a middle ground between the verbosity of JSON and the potential ambiguity of YAML, PIML aims to offer a clean, unambiguous, and highly readable format for various data exchange and configuration needs.

Syntax Rules: The Building Blocks of PIML

PIML's syntax is intentionally minimal, focusing on consistency and clarity.

Keys

Keys are the identifiers for data elements and are always enclosed in parentheses. This explicit demarcation makes keys instantly recognizable.

Indentation

Indentation is fundamental to PIML's structure, defining hierarchical relationships between data elements.

• Recommendation: Use 2 spaces for each level of indentation to maintain visual consistency.
• Strict Rule: Mixing tabs and spaces for indentation is prohibited to prevent parsing ambiguities.

Comments

PIML supports single-line comments using the # symbol. Anything from # to the end of the line is ignored by parsers, allowing for clear inline documentation.

• Rule: Only lines that start with # are treated as comments. Inline comments (e.g., (key) value # comment) are not supported and will be considered part of the value.

Escaping

The backslash (\) character is used to escape special characters within string values, ensuring that characters like ( or # can be part of the data itself.

• Common escapes include \n (newline), \t (tab), and \\ (literal backslash).
• Example: (title) My \(Awesome\) Title
• To include a # character at the beginning of a line within a multi-line string, escape it with a backslash (\), e.g., \# This is not a comment.

Data Types: Representing Information in PIML

PIML supports a range of data types, from simple primitives to complex nested structures.

Primitive Types

• Single-line Strings: Unquoted text values that reside on a single line.
  EXPAND COPY

  DATA_NODE: piml

  (name) John Doe
• Integers: Whole numbers.
  EXPAND COPY

  DATA_NODE: piml

  (age) 30
• Floats: Decimal numbers.
  EXPAND COPY

  DATA_NODE: piml

  (price) 19.99
• Booleans: Logical values, represented as true or false.
  EXPAND COPY

  DATA_NODE: piml

  (is_active) true

Null and Empty Representations: The nil Unifier

One of PIML's distinctive features is the use of nil as a unified representation for three distinct states:

1. Null: The absence of a value.
2. Empty Array: An empty list.
3. Empty Object: An empty map.

This design choice prioritizes syntactic simplicity, though it means the specific type of an empty collection (array vs. object) is not preserved when nil is used.

Multi-line Strings

For text spanning multiple lines, PIML allows the content to start on the next indented line, preserving newlines.

Arrays (Lists)

Ordered collections of items are denoted by a > prefix on each indented item.

Sets (Unique, Unordered Collections)

PIML introduces >| for sets, which are collections of unique, unordered items. Duplicate values are ignored by parsers.

Objects (Maps)

Unordered key-value pairs are defined through indentation, creating nested structures.

List of Objects

PIML provides a clear way to represent lists of objects, combining the array > marker with nested object syntax. The key within the object (e.g., (contributor)) serves as metadata for readability and is ignored by parsers.

Specialized Types (by Convention)

PIML encourages conventions for specialized data:

• Dates/Times: Typically represented as strings in ISO 8601 format (e.g., 2023-10-27T10:30:00Z).
• Binary Data: Usually encoded as base64 strings.

PIML in Action: A Comprehensive Example

Let's look at a more complete example demonstrating various PIML features:

PIML vs. The World: A Comparison

PIML carves its niche by offering a distinct balance of features compared to other popular data formats.

PIML vs. JSON

• PIML Advantages:
  • Readability: Significantly less visual noise due to the absence of quotes for keys and single-line strings, and no mandatory commas.
  • Comments: Native support for # comments, a feature lacking in JSON.
  • Multi-line Strings: More natural and cleaner syntax for multi-line text.
• PIML Trade-off:
  • nil Ambiguity: The unified nil for null, empty arrays, and empty objects simplifies syntax but means PIML cannot perfectly distinguish between these empty collection types, potentially affecting round-trip conversions from JSON.

PIML vs. YAML

• PIML Advantages:
  • Simplicity & Predictability: PIML's syntax is much smaller and more constrained, avoiding the "many ways to do one thing" complexity and the subtle whitespace pitfalls often associated with YAML. The explicit (key) syntax reduces ambiguity.
• PIML Trade-off:
  • Feature Set: PIML deliberately omits advanced YAML features like anchors, aliases, and complex document structures, focusing on a simpler, more direct representation.

PIML vs. TOML

• PIML Advantages:
  • Nesting Flexibility: PIML's indentation-based nesting is more adaptable for arbitrarily deep and complex data structures, contrasting with TOML's more rigid [table] and [[array of tables]] approach.
• PIML Trade-off:
  • Configuration Focus: TOML excels as a configuration file format due to its flat, key-value pair nature. PIML is more general-purpose, though it can certainly be used for configuration.

Conclusion

PIML offers a refreshing perspective on data serialization, emphasizing human-centric design while maintaining machine parseability. Its explicit key syntax, indentation-driven structure, and thoughtful approach to data types make it a strong contender for scenarios where clarity, readability, and ease of writing are paramount. As data continues to grow in complexity, formats like PIML provide valuable alternatives for developers seeking more intuitive ways to manage and exchange information.