Spec (Typed AST) Output

Export the full typed AST as JSON.

Synopsis

paradox generate --spec [--out FILEPATH] [--path PATH]

Description

The --spec target outputs the entire type-checked program as a JSON document. This includes all types, functions, validation rules, illumination rules, and interfaces with their full type annotations.

This is useful for:

  • Building tooling on top of Paradox (custom code generators, documentation tools)

  • Inspecting the type-checked representation

  • Integration with external systems that need schema information

Options

--out FILEPATH

Write output to a file instead of stdout.

--path PATH

Directory containing .dox source files.

Examples

# Print AST JSON to stdout
paradox generate --spec --path .

# Write to file
paradox generate --spec --out schema.json --path .

Output Structure

The output is a JSON array of Commented declarations. Each declaration is wrapped with an optional comments array:

[
  {
    "commented": { "tag": "DProduct", "contents": { ... } },
    "comments": []
  },
  ...
]

Declaration Tags

Every declaration has a tag field indicating its kind:

Tag Paradox construct

DProduct

type (product type with named fields)

DUnion

union (sum type with tagged variants)

DWrap

wrap (newtype wrapper)

DConst

Named function/constant definition

DInterface

interface declaration

DInstance

Interface instance

DImport

import statement

Annotated Nodes

Most named nodes in the AST are wrapped in an Annotated structure carrying source location and type information:

{
  "annotation": {
    "srcSpan": {
      "fileName": "example.dox",
      "startLine": 2, "startCol": 3,
      "endLine": 2, "endCol": 7
    },
    "origin": null,
    "typeInst": null
  },
  "unannotated": "name"
}
srcSpan

Source location in the original .dox file.

origin

Where the node was imported from (null if local).

typeInst

Resolved type instance after type checking (null for unresolved).

Type Instances

Types are represented as tagged arrays under the unannotated field of an annotated node:

Value Meaning

["tiPrimitive", "pText"]

Primitive Text type

["tiPrimitive", "pInteger"]

Primitive Integer type

["tiPrimitive", "pBoolean"]

Primitive Boolean type

["tiPrimitive", "pFloat"]

Primitive Float type

["tiVar", "a"]

Type variable a

["tiProduct", …​]

Reference to a product type

["tiUnion", …​]

Reference to a union type

["tiWrap", …​]

Reference to a wrap type

Product Types

Input:

type Person
  name: Text
  age: Integer

Output (annotations abbreviated as "…​"):

{
  "commented": {
    "tag": "DProduct",
    "contents": {
      "pname": { "annotation": "...", "unannotated": "Person" },
      "pparams": [],
      "pfields": [
        {
          "pfName": { "annotation": "...", "unannotated": "name" },
          "pfField": {
            "pfDoc": [],
            "pfType": {
              "annotation": "...",
              "unannotated": ["tiPrimitive", "pText"]
            }
          }
        },
        {
          "pfName": { "annotation": "...", "unannotated": "age" },
          "pfField": {
            "pfDoc": [],
            "pfType": {
              "annotation": "...",
              "unannotated": ["tiPrimitive", "pInteger"]
            }
          }
        }
      ]
    }
  },
  "comments": []
}
pname

The type name.

pparams

Type parameters (empty for monomorphic types).

pfields

Array of fields, each with a name (pfName) and field info (pfField) containing documentation (pfDoc) and type (pfType).

Union Types

Input:

union Either l r
  left: l
  right: r

Output (annotations abbreviated):

{
  "commented": {
    "tag": "DUnion",
    "contents": {
      "uname": { "annotation": "...", "unannotated": "Either" },
      "uparams": [
        { "annotation": "...", "unannotated": "l" },
        { "annotation": "...", "unannotated": "r" }
      ],
      "uvariants": [
        {
          "uvName": { "annotation": "...", "unannotated": "left" },
          "uvVariant": {
            "uvDoc": [],
            "uvType": {
              "annotation": "...",
              "unannotated": ["tiVar", "l"]
            }
          }
        },
        {
          "uvName": { "annotation": "...", "unannotated": "right" },
          "uvVariant": {
            "uvDoc": [],
            "uvType": {
              "annotation": "...",
              "unannotated": ["tiVar", "r"]
            }
          }
        }
      ]
    }
  },
  "comments": []
}
uname

The union name.

uparams

Type parameters.

uvariants

Array of variants, each with a tag name (uvName) and variant info (uvVariant) containing documentation (uvDoc) and payload type (uvType).

See Also