TL;DR

JSON-C isn’t a single spec; it’s a moving target with many incompatible “JSON with comments” dialects. MAML gives one clear name, one spec, and predictable behavior.
JSON5 adds lots of JavaScript-style conveniences. I wanted the opposite: keep JSON’s tight, easy-to-parse core and add only a few carefully chosen affordances (newline separators, raw multiline strings, one comment style).

MAML vs JSON-C (aka “JSON with comments”)

Single, stable target vs. many dialects
“JSON-C” isn’t a standard—different tools disagree on what’s allowed (which comment styles? trailing commas? relaxed numbers?). That makes it hard to rely on. MAML has a single specification, a distinct name, a file extension (.maml), and a MIME type (application/maml). You always know what you’re targeting.
Clear, minimal comment model
MAML uses exactly one comment form: # … (not // and /* … */). Simple, unambiguous, and easy to implement.
Syntax beyond comments is well-defined
MAML isn’t “JSON + maybe comments.” It also deliberately defines:
- Optional commas (newline-separated items/fields work),
- Raw multiline strings with """…""",
- Ordered objects (keys have a defined order),
  all of which are specified—not left to implementation choice.

MAML vs JSON5

JSON5 is nicer to write than JSON, but it expands the language surface (and the parser). I went the other way: keep it small.

Minimal numbers, no JS literals
- MAML numbers are strict: no +1, .5, 5., 0xFF, Infinity, or NaN.
- Floats are classic decimal with optional exponent (1.23e-4).
  This keeps lexing/parsing trivial and consistent.
Strings: quoted or raw triple-quoted
- MAML normal strings are quoted with a small, fixed escape set. Same as JSON.
- For blocks, MAML has raw multiline strings: """…""" (no escaping, first newline after the opener is ignored).
  JSON5 allows single quotes and comment-style line continuations, but not raw triple-quoted blocks. MAML’s block strings make pasting code/config chunks painless—no backslashes, no extra processing.
Structure separators: commas are optional
- In MAML, arrays/objects can be separated by commas or newlines; trailing commas are allowed.
- JSON5 still requires commas between elements; newlines alone aren’t separators.
  This makes MAML feel closer to YAML in writing while keeping JSON’s {} and [].
Comments: one style vs two
- MAML: only # ….
- JSON5: // and /* … */.
  One style is simpler to parse and easier to standardize.
Object keys and ordering
- MAML objects are ordered by definition.
- MAML keys can be identifiers (letters/digits/_/-) or quoted strings. Identifiers may be all digits (they’re still keys, not numbers).
- JSON5 allows many JS-like unquoted keys but does not specify object ordering as part of the data model.
  MAML’s explicit ordering is useful for config diffs, tooling, and reproducible formatting.
Scope and philosophy
- JSON5’s goal is “JSON for humans,” adding lots of JS conveniences.
- My goal with MAML is “minimal config, easy to read, easy to parse.” Keep the JSON feel and constraints, add only what materially improves authoring:
  - newline separation (less punctuation),
  - raw multiline strings,
  - one comment style,
  - ordered objects,
    while keeping everything else strict and boring.

Why I chose this design

Parser friendliness: tight number/string rules + one comment form = simpler, more robust parsers.
Author ergonomics: fewer commas, raw multiline strings, and kept {}/[] so formatters and tools work (a YAML pain point).
Interoperability: a named format with a single spec so different implementations actually agree.
Determinism: ordered objects make diffs and tooling predictable.

That’s the heart of it: JSON-C is vague; JSON5 is expansive; MAML is minimal, precise, and pleasant to write.

Uh oh!

Uh oh!

What's MAML different from JSONC and JSON5? #1

Description

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions