writing-hashql-jexpr

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:

"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, ...]

// 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

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

Struct

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

List and Tuple

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

Dict

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

Common Patterns

Let Binding

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

Function Definition

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

Conditionals

["if", condition_expr, then_expr, else_expr]

Comparison

["==", "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:

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

Filtering with comparison:

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

Struct with type:

{"#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