# piml

**Spec version**: v1.1.0

[Available Libraries](https://github.com/fezcode/piml/blob/main/LIBRARIES.md)

[JSON<->PIML Converter](/apps/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.

```piml

(my_key) my_value

(another key with spaces) another_value

```

### 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.

```piml

# This explains the data

(data) value # This entire line is the value, not a comment

```

### 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.

```piml

(name) John Doe

```

* **Integers:** Whole numbers.

```piml

(age) 30

```

* **Floats:** Decimal numbers.

```piml

(price) 19.99

```

* **Booleans:** Logical values, represented as `true` or `false`.

```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.

```piml

(optional_setting) nil

(empty_items) nil

(empty_config) nil

```

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.

```piml

(description)

This is a multi-line string example.

It can hold extensive textual content.

```

### Arrays (Lists)

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

```piml

(fruits)

> apple

> banana

> orange

```

### Sets (Unique, Unordered Collections)

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

```piml

(unique_ids)

>| id_a

>| id_b

>| id_a # This duplicate will be ignored

```

### Objects (Maps)

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

```piml

(user)

(name) Alice

(email) alice@example.com

```

#### 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.

```piml

(contributors)

> (contributor)

(id) 1

(name) Bob

> (contributor)

(id) 2

(name) Carol

```

### 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

(document_metadata)

(title) PIML Specification Document

(version) 1.0.0

(author) Fezcodex

(creation_date) 2025-11-12T10:00:00Z

(is_draft) true

(tags)

> data-format

> serialization

> piml

(abstract)

This document outlines the PIML format,

its syntax, and its design philosophy.

It aims for human-centric data representation.

(contact)

(email) contact@example.com

(website) [https://fezcode.github.io](https://fezcode.github.io)

(empty_settings) nil

(configuration)

(database)

(type) SQLite

(path) /data/app.db

(max_connections) 50

(api_keys)

>| key_abc

>| key_xyz

(feature_toggles)

(new_ui) true

(beta_analytics) false

```

## 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.