You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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.
Reacted by Shunsuke Suzuki, Vasco, Iddan Aaronsohn, Erin and Alex Turpin
Reacted by JJ
Reacted by Shunsuke Suzuki, Erin, Thijs Koerselman and mxcu
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?)
Activity
[-]What's MAYML different from JSONC and JSON5?[/-][+]What's MAML different from JSONC and JSON5?[/+]antonmedv commentedon Sep 24, 2025
TL;DR
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:
"""…""",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
+1,.5,5.,0xFF,Infinity, orNaN.1.23e-4).This keeps lexing/parsing trivial and consistent.
Strings: quoted or raw triple-quoted
"""…"""(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
This makes MAML feel closer to YAML in writing while keeping JSON’s
{}and[].Comments: one style vs two
# ….//and/* … */.One style is simpler to parse and easier to standardize.
Object keys and ordering
_/-) or quoted strings. Identifiers may be all digits (they’re still keys, not numbers).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:
while keeping everything else strict and boring.
Why I chose this design
{}/[]so formatters and tools work (a YAML pain point).That’s the heart of it: JSON-C is vague; JSON5 is expansive; MAML is minimal, precise, and pleasant to write.
suzuki-shunsuke commentedon Sep 24, 2025
Thank you for the detailed explanation!
That makes sense.
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 commentedon Sep 26, 2025
I'm going to build a library for that as well.
smaspe commentedon Oct 13, 2025
2 questions:
0.000123meant to represent a different parsed value that1.23e-4? (with0.000123being a fixed-precision decimal and1.23e-4a floating-point value?)antonmedv commentedon Oct 13, 2025
For the spec: