Skip to content

CONCEPT Cited by 1 source

JSON-serializable DSL

What it is

A JSON-serializable DSL is a domain-specific language whose authoritative representation is a plain JSON (or structurally similar) data structure — not source text requiring a parser, and not language bytecode requiring a runtime. Authoring tooling (often a typed host language) compiles down to the JSON; any consumer speaks the JSON directly.

Properties

  • Zero-parser consumption. Any language with a JSON parser (everyone) can consume DSL artifacts without embedding a bespoke lexer/parser or AST walker.
  • Trivial cross-platform. Same artifact runs unchanged against multiple evaluator implementations; Figma reports writing a new evaluator takes 2–3 days for a senior engineer.
  • Static analysis is plain data traversal. Linters, dependency extractors, and validators are simple recursive functions over the JSON tree — no AST library required (patterns/policy-static-analysis-in-ci).
  • Composable authoring. A typed host-language surface (Figma uses TypeScript) can layer types, enums, helper functions, and transpile to JSON while preserving structural isomorphism.
  • Self-describing & diffable. JSON is human-readable, storable in a config store or database, version-controllable.

Trade-offs vs source-text DSLs

  • Verbosity. JSON is bulkier than dedicated surface syntax. Mitigated by never being the authoring surface.
  • Control-flow primitives (loops, variables, recursion) don't serialize cleanly. JSON-serializable DSLs tend to be declarative — boolean expressions, policy rules, filter trees, query clauses.
  • Runtime-computed values are inherently not representable. The DSL is data; values must come from outside.

Canonical examples

  • AWS IAM policies (systems/aws-iam) — JSON Statement with Effect / Action / Resource / Condition. Possibly the most widely deployed JSON-serializable DSL in production.
  • Figma ExpressionDef — triples ([field, op, value | ref]) composed by and/or/not (patterns/expression-def-triples) — the data layer behind Figma's permissions DSL.
  • Elasticsearch Query DSL — JSON queries (bool / must / should / must_not trees). Same shape as ExpressionDef philosophically.
  • MongoDB aggregation / filter syntax — JSON-structured operators.
  • JSON Schema — the schema-description DSL itself as JSON.
  • LiveGraph ExpressionDef — the predecessor DSL Figma extended for the permissions engine.

Design guidance

  • Pair with a typed authoring surface (TypeScript, Protobuf, typed Python) so authors see type errors at compile time, not runtime.
  • Keep the core set of operators tiny (Figma: 6 binary ops + and/or/not + field references). Simplicity is what makes multi-language evaluators tractable.
  • Use field references ({"type":"field","ref":"team.id"}) to distinguish scalar-literal-strings from field-references rather than overloading bare strings.
  • Add static analysis in CI from day one (patterns/policy-static-analysis-in-ci); the JSON-ness makes it cheap.

Caveats

  • Not every DSL should be JSON-serializable — arithmetic-heavy expressions, rich type systems, and user-facing DSLs for non-engineers usually benefit from proper surface syntax.
  • JSON's lack of comments and trailing-commas makes human editing painful; almost always authored via a host language.
  • Composition across multiple JSON-DSL artifacts (e.g. importing / inheriting) is non-standard and varies per ecosystem.

Seen in

Last updated · 200 distilled / 1,178 read