What's MAML different from JSONC and JSON5?

[suzuki-shunsuke]

Just curious.
What's MAML different from JSONC and JSON5?

https://jsonc.org/
https://json5.org/

[antonmedv]

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”)

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

2. Clear, minimal comment model
   MAML uses exactly one comment form: # … (not // and /* … */). Simple, unambiguous, and easy to implement.

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

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

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

3. 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 [].

4. Comments: one style vs two

   • MAML: only # ….
   • JSON5: // and /* … */.
     One style is simpler to parse and easier to standardize.

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

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

[suzuki-shunsuke]

Thank you for the detailed explanation!
That makes sense.

Parser friendliness

Yeah, I like this point.
It would be great if we could edit MAML through the AST while preserving the style (indentation, spaces, comments, etc.).

[antonmedv]

It would be great if we could edit MAML through the AST while preserving the style (indentation, spaces, comments, etc.).

I'm going to build a library for that as well.

[smaspe]

Floats are classic decimal with optional exponent (1.23e-4).

2 questions:

• Does the spec specifies what data type the host language supposed to use to interpret numbers? (float vs any other representation of numbers is an implementation detail and should be left to the parser to decide)
• Is 0.000123 meant to represent a different parsed value that 1.23e-4? (with 0.000123 being a fixed-precision decimal and 1.23e-4 a floating-point value?)

[antonmedv]

For the spec:

Floats should be implemented as IEEE 754 binary64 values.