Project setup

Contents

JSON is the canonical command form every module is stored in — the interchange the other targets render from, not a language you run. These pages describe that form.

• Introduction — what the JSON form is, and how to read the rest of this section.
• Capabilities — which high-level features are possible — deferred to whichever target this JSON renders to.
• Example — a full program using every keyword, in the canonical JSON form.
• Naming considerations — how Program's dotted names are stored, verbatim and un-munged.
• Object format — every node in the self-describing object form, keyword by keyword.
• Array format — every node in the compact tagged-array form, keyword by keyword.
• Project setup — there is no build; how a module file is stored, read and rendered onward.
• Reserved words — why the canonical form has none, and never escapes a name.

The files

A module is one JSON document. A project is a directory of them — one file per top module, named for the module, with nothing else required: no manifest, no lockfile, no toolchain.

my-app/
  app.json              # module App
  ui.json               # module Ui
  maths.json            # module Maths
  ...                   # one file per top module

Each file is the exact tree of canonical nodes — every node detailed under object format and array format — it is the whole of the “source” for this target.

There is no build

Nothing compiles or runs the JSON directly. The form exists to be read — validated against the schema and then rendered onward into one of the executable targets, which is where a real project setup begins.

# validate a module against the schema
program check app.json

# render this module (and its imports) to a target
program render app.json --target javascript --out ./build
program render app.json --target swift      --out ./build

The renderer is the only tool that consumes the JSON; from its output you follow the chosen target's own project setup to build and run.

Why keep it as a file at all

Storing the module as canonical JSON means every tool — editor, renderer, diff, review — reads the same lossless record, and any target can be regenerated from it at any time without going back to a particular language. The file is the program; the languages are views of it.