Writing HashQL J-Expr

J-Expr is a JSON-based expression syntax for HashQL. It represents typed expressions using JSON primitives.

Expression Types

J-Expr has three expression types:

JSON Type	J-Expr Meaning
String	Path/identifier/symbol
Array	Function call
Object	Data constructor (with `#` keys)

Paths (Strings)

Strings are parsed as paths or identifiers:

jsonc

"x"                           // Simple variable
"vertex.id.entity_id"         // Dotted path access
"::core::types::String"       // Namespaced/rooted path
"::graph::head::entities"     // Graph function path

Function Calls (Arrays)

Arrays represent function calls: [function, arg1, arg2, ...]

jsonc

// Basic function call
["add", {"#literal": 1}, {"#literal": 2}]

// Namespaced function
["::graph::head::entities", ["::graph::tmp::decision_time_now"]]

// Labeled argument with :prefix in object
["greet", {":name": {"#literal": "Alice"}}]

// Shorthand labeled argument (string with :prefix)
["func", ":name"]

Data Constructors (Objects with # Keys)

Objects with special # keys construct data:

Key	Purpose	Example
`#literal`	Primitive values	`{"#literal": 42}`
`#struct`	Named fields	`{"#struct": {"x": ...}}`
`#list`	Variable-size ordered	`{"#list": [...]}`
`#tuple`	Fixed-size ordered	`{"#tuple": [...]}`
`#dict`	Key-value map	`{"#dict": {"k": ...}}`
`#type`	Type annotation	Used with other keys

Literals

jsonc

{"#literal": 42}
{"#literal": "hello"}
{"#literal": true}
{"#literal": null}
{"#literal": 3.14, "#type": "Float"}

Struct

jsonc

{"#struct": {"name": {"#literal": "Alice"}, "age": {"#literal": 30}}}
{"#struct": {"x": {"#literal": 1}}, "#type": "Point"}

List and Tuple

jsonc

{"#list": [{"#literal": 1}, {"#literal": 2}]}
{"#tuple": [{"#literal": 1}, {"#literal": "text"}]}

Dict

jsonc

{"#dict": {"key": {"#literal": "value"}}}

Common Patterns

Let Binding

jsonc

["let", "varName", {"#literal": 10}, ["add", "varName", {"#literal": 5}]]

Function Definition

jsonc

["fn", {"#tuple": []}, {"#struct": {"vertex": "_"}}, "_", body_expr]

Conditionals

jsonc

["if", condition_expr, then_expr, else_expr]

Comparison

jsonc

["==", "left", "right"]
[">", {"#literal": 5}, {"#literal": 3}]

Do

•Use #literal for all primitive values (numbers, strings, booleans, null)
•Use :: prefix for namespaced paths
•Use : prefix for labeled arguments
•Combine #type with other constructors for type annotations

Don't

•Don't use bare JSON numbers/booleans - wrap in {"#literal": ...}
•Don't confuse #list (variable-size) with #tuple (fixed-size)
•Don't use # prefix for labeled arguments (use :)
•Don't nest # keys incorrectly - each object should have one primary # key

Examples

Entity query:

jsonc

["::graph::head::entities", ["::graph::tmp::decision_time_now"]]

Filtering with comparison:

jsonc

["filter", "entities", 
  ["fn", {"#tuple": []}, {"#struct": {"entity": "_"}}, "_",
    ["==", "entity.draft_id", {"#literal": null}]]]

Struct with type:

jsonc

{"#struct": {"value": {"#literal": 100}}, "#type": "Amount"}

References

•Syntax Reference - Paths, function calls, operators
•Special Forms - Language constructs (if, let, fn, type, use, etc.)
•Data Constructors - Typed data (#literal, #struct, #tuple, #list, #dict, #type)
•Type DSL - Embedded type annotation syntax
•Parser: libs/@local/hashql/syntax-jexpr/src/parser/
•Object forms: libs/@local/hashql/syntax-jexpr/src/parser/object/
•Type DSL: libs/@local/hashql/syntax-jexpr/src/parser/string/type.rs