gram

name	gram
description	Work with gram notation files (.gram). Use this skill when the user is creating, reading, editing, or validating gram notation — a text format for Pattern<Subject> structures. Gram encodes nodes, annotations, relationships, and general list/tree patterns in two interchangeable syntactic styles: square-bracket pattern notation and parenthesis path notation. Trigger on .gram files, graph data tasks, or any task involving Pattern<Subject> serialization.
license	MIT
compatibility	Requires the gram CLI. Install with: cargo install gram-data Verify with: gram --version
metadata	{"author":"gram-data","homepage":"https://github.com/gram-data/tree-sitter-gram"}

Gram Notation

Gram is a text format for serializing and deserializing Pattern<Subject> structures. Files use the .gram extension.

Core Data Model: Pattern<Subject>

Every gram construct lowers to a Pattern<Subject>:

Pattern<Subject> {
    value:    Option<Subject>,   // identity, labels, properties
    elements: Vec<Pattern>       // zero or more child patterns
}

The number of elements determines the structural role:

Elements	Role
0	Node / atomic pattern
1	Annotation wrapper
2	Relationship
N ≥ 3	General / list pattern

A graph (nodes + relationships) is one special case; gram can also represent annotations, trees, and arbitrary list structures.

Syntactic Styles

Both styles produce identical Pattern<Subject> structures and are fully interchangeable.

Pattern Notation (Square Brackets)

[]                          // empty pattern (node)
[a]                         // identified node
[a:Person]                  // labeled node
[a:Person {name: "Alice"}]  // node with properties
[r:KNOWS | a, b]            // relationship (2 elements)
[list | a, b, c]            // general pattern (3+ elements)
[outer | [inner | a, b]]    // nested / tree

The | separator divides the subject from its elements. Bare identifiers inside [v | ...] are references to previously (or forward-) defined patterns.

Path Notation (Parentheses + Brackets)

Path notation uses (...) for nodes and [...] for relationship labels — familiar to Cypher users.

(n)                             // node
(alice:Person {name: "Alice"})  // labeled node with properties
(a)-[r:KNOWS]->(b)              // directed relationship → [r:KNOWS | a, b]
(a)<-[r:KNOWS]-(b)              // reversed  → [r:KNOWS | b, a]
(a)-[:KNOWS]->(b)               // anonymous relationship
(a)-[:KNOWS]->(b)-[:KNOWS]->(c) // multi-hop path

Arrow families are stylistic variants — all semantically equivalent:

Family	Example
Dash (default)	(a)-->(b)
Fat	(a)==>(b)
Tilde	(a)~~>(b)

Annotations

An annotation wraps a pattern with metadata (1-element pattern):

@timestamp(2024-01-15) (alice:Person)
@source("db") @confidence(0.9) (n:Entity)
@@provenance:Source (alice:Person)   // identified annotation with label

Properties

(a:Person {name: "Alice", age: 30})
(a {scores: [10, 20, 30], address: {city: "Portland"}})

Property values: strings ("text", 'text', `text`), integers, decimals, booleans, arrays (scalars only), maps (scalars only), measurements (5m, 10kg), ranges (1..10), tagged strings (url`https://...`).

Schema / Ontology Style

Double-colon :: labels and == / ~~ arrows conventionally signal schema definitions:

{ kind: "schema" }

(Person::Entity)
(name::Property)
(Person)==[:HAS_PROPERTY::]==>(name)

Validation with gram check

gram check path/to/file.gram          # validate a file
gram check path/to/dir/               # validate all .gram files in a directory
gram check -e '(a)-[:KNOWS]->(b)'     # validate an inline expression
cat file.gram | gram check            # read from stdin
gram check --json file.gram           # machine-readable JSON output
gram check --strict file.gram         # warnings treated as errors

Exit codes: 0 = no errors, 1 = errors found, 2 = tool/IO error.

Quick Examples

Graph (nodes + relationships):

(alice:Person {name: "Alice"})
(bob:Person {name: "Bob"})
(alice)-[:KNOWS {since: 2020}]->(bob)

Annotated data:

@timestamp(2024-01-15) @source("api") (event:Event {type: "login"})

Schema definition:

{ kind: "schema" }
(User::Entity)
(email::Property)
(User)==[:HAS::]==>(email)

General list pattern:

[playlist:Playlist | [s1:Song {title: "A"}], [s2:Song {title: "B"}], [s3:Song {title: "C"}]]

Working with Gram Files

• Always validate with gram check before using files downstream
• .gram files are UTF-8 text; whitespace and line endings are not significant
• Each identifier may be defined only once per file; forward references are allowed
• Pattern notation [...] and path notation (...) can be mixed in the same file
• Use gram check --json when integrating into build pipelines or CI