Add docs detailing language + grammar spec by ujaandas · Pull Request #11 · ujaandas/invariants

ujaandas · 2026-04-24T20:47:38Z

Fairly straightforward, just some documentation detailing the "top-level" of how the invariants language works. To be used as a single source-of-truth for implementation, which was completed on the feat/lang/lexer branch, which was merged recently.

Some features remain TBC, such as proper typing for Array-types (ie; Array<Boolean>), the this and value keyword, etc...

Copilot

Pull request overview

Adds documentation intended to be the single source of truth for the invariants DSL’s top-level structure, expressions, and type system.

Changes:

Documented statement forms (spec, field, check, invariant) and their intended semantics.
Documented expression concepts including implicit identifiers and operator precedence.
Added type-system notes plus a sample .inv file and a (currently empty) EBNF grammar file.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/lang/statements.md	Defines the statement-level constructs and evaluation semantics.
docs/lang/expressions.md	Defines expression semantics, implicit identifiers, and operator precedence.
docs/lang/data_types.md	Describes supported primitive/compound types and how to constrain them.
docs/lang/introduction.md	Provides a high-level overview and links to the other docs.
docs/lang/sample.inv	Adds an example invariants program demonstrating the language.
docs/lang/grammar.ebnf	Intended location for formal grammar (currently empty).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-24T20:50:10Z

+
+## Mixed Types
+
+Mixed types (ie; to define a list with many possible types) is not supported.


Grammar: “Mixed types ... is not supported” should be “are not supported” (plural subject).

Suggested change

Mixed types (ie; to define a list with many possible types) is not supported.

Mixed types (ie; to define a list with many possible types) are not supported.

Copilot · 2026-04-24T20:50:11Z

+
+```
+invariant bulk_discount {
+    this.quantity > 500 -> this.total_price < (this.unit_price \* this.quantity);


The multiplication operator in this sample is written as \* inside a fenced code block. In a code fence this backslash is preserved, so a copy/paste would produce an invalid operator. Use * here instead.

Suggested change

this.quantity > 500 -> this.total_price < (this.unit_price \* this.quantity);

this.quantity > 500 -> this.total_price < (this.unit_price * this.quantity);

Copilot · 2026-04-24T20:50:11Z

+        check: value <= 1000;
+    }
+
+    field currency: number {


currency is declared as number, but the check uses string literals ("USD", "EUR", "GBP"). This example should declare currency as string (or change the check literals to numbers) to keep the sample consistent with the type system described in data_types.md.

Suggested change

field currency: number {

field currency: string {

Copilot · 2026-04-24T20:50:11Z

+    field quantity: integer { }
+


field quantity is declared twice in the same spec (once with checks, once empty). If duplicate field keys are not allowed (as implied by “maps directly to a key”), this makes the sample invalid/ambiguous. Remove the duplicate or rename it to demonstrate a different field.

Suggested change

field quantity: integer { }

Copilot · 2026-04-24T20:50:11Z

+
+## 3. Data Types
+
+`invariant` aims to maintain parity with the OpenAPI 3.0 spec. As the lexer reads atomic literals (like `500` or `"USD"`), the syntax oracle maps these directly to foundational C++ types to ensure high performance during the decoding loop. This also covers how complex, recursive structures like arrays and objects are handled.


This section refers to the project/DSL as invariant (singular), but elsewhere in this doc and the repo name it’s invariants. For consistency and to avoid confusion in the docs, pick one and use it consistently (likely invariants).

Suggested change

`invariant` aims to maintain parity with the OpenAPI 3.0 spec. As the lexer reads atomic literals (like `500` or `"USD"`), the syntax oracle maps these directly to foundational C++ types to ensure high performance during the decoding loop. This also covers how complex, recursive structures like arrays and objects are handled.

`invariants` aims to maintain parity with the OpenAPI 3.0 spec. As the lexer reads atomic literals (like `500` or `"USD"`), the syntax oracle maps these directly to foundational C++ types to ensure high performance during the decoding loop. This also covers how complex, recursive structures like arrays and objects are handled.

Copilot · 2026-04-24T20:50:12Z

+`invariant` aims to maintain parity with the OpenAPI 3.0 spec. As such, the
+supported types are also largely the same. The typical complexity of managing
+the custom "object" type defined by the OAS 3 is largely mitigated by the entire DSL
+being focused around `spec`s, which are basically just objects. This therefore
+enables first-class support thereof.


The doc alternates between invariant and invariants when referring to the DSL (e.g., here and later in the Strings/Booleans sections). Standardize the name to avoid ambiguity in the “single source of truth” docs.

ujaandas · 2026-04-24T20:52:39Z

@copilot apply changes based on the comments in this thread

…sistency in docs Agent-Logs-Url: https://github.com/ujaandas/invariants/sessions/2d9cbd8d-d83f-4167-9ce2-bb7ce6d2533b Co-authored-by: ujaandas <79176268+ujaandas@users.noreply.github.com>

Copilot · 2026-04-24T20:53:50Z

@copilot apply changes based on the comments in this thread

Applied all changes from the review thread in commit 7008ce6:

data_types.md: invariant → invariants (line 3), "is not supported" → "are not supported" (line 19)
statements.md: \* → * in the invariant code example
introduction.md: invariant → invariants (line 19)
sample.inv: field currency type changed from number to string, and the duplicate field quantity declaration removed

ujaandas added 8 commits April 3, 2026 17:45

add sample and initial grammar defn

677541d

update sample with better typing

2c4716c

add more types to grammar intro

b262155

add data types doc

a42079c

add expressions doc

9f96ae5

add statements doc

dd2211f

rename grammar doc to intro, rephrase/structure

92ab3ad

clarify null, arrays, recursive access

148e741

Copilot AI review requested due to automatic review settings April 24, 2026 20:47

Copilot started reviewing on behalf of ujaandas April 24, 2026 20:48 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Copilot started work on behalf of ujaandas April 24, 2026 20:52 View session

Apply review feedback: fix grammar, types, duplicates, and naming con…

7008ce6

…sistency in docs Agent-Logs-Url: https://github.com/ujaandas/invariants/sessions/2d9cbd8d-d83f-4167-9ce2-bb7ce6d2533b Co-authored-by: ujaandas <79176268+ujaandas@users.noreply.github.com>

Copilot finished work on behalf of ujaandas April 24, 2026 20:54

ujaandas merged commit c504a38 into main Apr 24, 2026
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs detailing language + grammar spec#11

Add docs detailing language + grammar spec#11
ujaandas merged 9 commits intomainfrom
docs/lang/grammar

ujaandas commented Apr 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

ujaandas commented Apr 24, 2026

Uh oh!

Copilot AI commented Apr 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Mixed Types

		Mixed types (ie; to define a list with many possible types) is not supported.

	this.quantity > 500 -> this.total_price < (this.unit_price \* this.quantity);
	this.quantity > 500 -> this.total_price < (this.unit_price * this.quantity);


		## 3. Data Types

		`invariant` aims to maintain parity with the OpenAPI 3.0 spec. As the lexer reads atomic literals (like `500` or `"USD"`), the syntax oracle maps these directly to foundational C++ types to ensure high performance during the decoding loop. This also covers how complex, recursive structures like arrays and objects are handled.

	`invariant` aims to maintain parity with the OpenAPI 3.0 spec. As the lexer reads atomic literals (like `500` or `"USD"`), the syntax oracle maps these directly to foundational C++ types to ensure high performance during the decoding loop. This also covers how complex, recursive structures like arrays and objects are handled.
	`invariants` aims to maintain parity with the OpenAPI 3.0 spec. As the lexer reads atomic literals (like `500` or `"USD"`), the syntax oracle maps these directly to foundational C++ types to ensure high performance during the decoding loop. This also covers how complex, recursive structures like arrays and objects are handled.

Conversation

ujaandas commented Apr 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

ujaandas commented Apr 24, 2026

Uh oh!

Copilot AI commented Apr 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants