Semantic graph

The semantic graph is the model as data. Every element becomes a node identified by its qualified name, every reference becomes an edge, and module dependencies are computed from the edges. The IDE draws it, the AI tools query it, code generation extensions read it and releases store it. appling graph prints it as JSON; in code, buildGraph from @appling/model builds it (see API).

Example

This model has two modules, a cross module reference and an invariant:

module crm {
  export Account

  entity Account {
    name: String
  }
}

module sales {
  enum OrderStatus {
    draft
    placed
  }

  entity Order {
    customer: crm.Account
    status: OrderStatus state default draft
    total: Money

    invariant "total never negative" { total >= 0 }
  }
}

flowchart TB
  subgraph m0["crm"]
    n0["Account<br/><small>entity</small>"]:::domain
  end
  subgraph m1["sales"]
    n1["OrderStatus<br/><small>enum</small>"]:::domain
    n2["Order<br/><small>entity</small>"]:::domain
  end
  n2 -->|"type"| n0
  n2 -->|"type, uses"| n1
  classDef domain fill:#3d2510,stroke:#3d2510,color:#f7f2ea
  classDef behavior fill:#6b3f12,stroke:#6b3f12,color:#f7f2ea
  classDef application fill:#a85f17,stroke:#a85f17,color:#f7f2ea
  classDef interface fill:#d98a1c,stroke:#d98a1c,color:#0c0a08
  classDef experience fill:#f2b632,stroke:#f2b632,color:#0c0a08
  classDef cross fill:#1b1712,stroke:#7a6e5e,color:#f7f2ea

appling graph prints 12 nodes, 14 edges and one dependency. An excerpt:

{
  "nodes": [
    {
      "qn": "sales",
      "kind": "Module",
      "layer": "cross",
      "level": "out",
      "module": "",
      "props": {},
      "data": {}
    },
    {
      "qn": "sales.Order",
      "kind": "Entity",
      "layer": "domain",
      "level": "medium",
      "module": "sales",
      "props": {},
      "data": {}
    },
    {
      "qn": "sales.Order.status",
      "kind": "Field",
      "layer": "domain",
      "level": "in",
      "module": "sales",
      "props": {
        "type": "OrderStatus",
        "modifiers": ["state"],
        "default": "draft"
      },
      "data": {
        "type": { "$type": "TypeRef", "decl": "sales.OrderStatus" },
        "modifiers": ["state"],
        "default": {
          "$type": "NameExpr",
          "name": "draft",
          "type": "OrderStatus",
          "target": "sales.OrderStatus.draft"
        }
      }
    },
    {
      "qn": "sales.Order.invariant[\"total never negative\"]",
      "kind": "Invariant",
      "layer": "domain",
      "level": "in",
      "module": "sales",
      "props": {
        "label": "total never negative",
        "condition": "total >= 0"
      },
      "data": {
        "label": "total never negative",
        "condition": {
          "$type": "BinaryExpr",
          "left": { "$type": "NameExpr", "name": "total", "type": "Money", "target": "sales.Order.total" },
          "op": ">=",
          "right": { "$type": "NumberExpr", "value": 0, "type": "Int" },
          "type": "Bool"
        }
      }
    }
  ],
  "edges": [
    { "from": "sales", "to": "sales.Order", "kind": "contains" },
    { "from": "sales.Order", "to": "sales.Order.status", "kind": "contains" },
    { "from": "sales.Order.customer", "to": "crm.Account", "kind": "type" },
    { "from": "sales.Order.status", "to": "sales.OrderStatus", "kind": "type" },
    { "from": "sales.Order.status", "to": "sales.OrderStatus.draft", "kind": "uses" },
    { "from": "sales.Order.invariant[\"total never negative\"]", "to": "sales.Order.total", "kind": "uses" }
  ],
  "dependencies": [
    { "from": "sales", "to": "crm", "count": 1 }
  ]
}

Top level

Nodes

Layer

A module is cross. A top level declaration gets the layer of its keyword:

A nested element takes the layer of the declaration that contains it: a field of an entity is domain, a parameter of an action is behavior.

Level

props and data

Both hold the element’s own properties, without its name and without the elements nested in it (those are nodes of their own, linked by contains). Properties that are empty, false or missing are left out.

So an action’s precondition shows as "requires { lines.size() > 0 } else EmptyOrder" in props and as { "$type": "Precondition", "condition": { ... }, "error": "sales.PlaceOrder.EmptyOrder" } in data.

Node kinds

Only some AST types become nodes. All other AST nodes fold into the props and data of the nearest element that contains them, and their references become edges of that element.

Named elements:

Unnamed elements, which get a key instead of a name:

Lists keep their separators without spaces, and references in keys are written as in the source. When siblings share a key, the second gets #2, the third #3, and so on: policy[read]#2.

Everything else folds into its element, for example types (TypeRef), expressions, preconditions, assignments, sorts, use case steps and handlers, page components (list, detail, form), navigation items, messages and migration steps.

Edges

The reference kinds, with the element the edge starts from:

References made by parts that are not elements (preconditions, sorts, steps, components, navigation items) belong to the element that contains them. An edge appears once per element, target and kind, however often the reference repeats.

Dependencies

dependencies aggregates every edge except contains whose ends lie in different modules:

The IDE draws these at the Modules zoom level, labeled with the count.

ExprData

An expression inside data:

See Expressions for the language itself.

TypeData

A type inside data, such as a field’s type: