> For the complete documentation index, see [llms.txt](https://docs.internetobject.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.internetobject.org/appendices/grammar.md).

# Formal Grammar (EBNF)

This appendix gives the grammar of Internet Object in EBNF. It is the normative reference for document structure; the prose chapters explain semantics. Lexical rules (whitespace, comments, literals) are listed at the end.

> Notation: `=` defines a rule, `|` alternation, `[ ]` optional, `{ }` zero-or-more, `( )` grouping, `"…"` a literal. Whitespace and comments may appear between tokens unless a rule states otherwise.

## Document

```ebnf
document        = [ header "---" ] section { sectionBreak section }
                | value ;                         (* a bare, header-less value/object *)

header          = { definition } ;
section         = [ sectionTag ] ( collection | object ) ;
sectionBreak    = "---" [ sectionTag ] ;
sectionTag      = name [ ":" schemaRef ]          (* e.g.  employee : $employee *)
                | schemaRef ;                      (* e.g.  $employee *)
```

## Header definitions

```ebnf
definition      = "~" key ":" defValue ;
key             = metaKey | variableKey | refKey ;
metaKey         = name ;                            (* metadata *)
variableKey     = "@" name ;                        (* value variable *)
refKey          = "$" name ;                        (* schema/type reference *)
defValue        = value | schema ;
schemaRef       = "$" name ;
```

## Collections and records

```ebnf
collection      = record { record } ;
record          = "~" [ recordBody ] ;             (* "~" alone = empty object {} *)
recordBody      = object | openObject | value ;    (* a bare value is promoted to an object *)
```

## Objects and arrays

```ebnf
object          = "{" [ memberList ] "}" ;
openObject      = memberList ;                      (* unbraced, top-level only *)
memberList      = member { "," member } [ "," ] ;
member          = [ key ":" ] value ;              (* keyed or positional *)

array           = "[" [ valueList ] "]" ;
valueList       = value { "," value } ;
```

## Values

```ebnf
value           = object | array | scalar | variableRef ;
variableRef     = "@" name | "$" name ;
scalar          = string | number | bigint | decimal
                | datetime | binary | boolean | null ;
```

## Schema (MemberDef and SchemaDef)

```ebnf
schema          = schemaDef | memberDef | refKey ;
schemaDef       = "{" memberDefList "}" | memberDefList ;   (* object shape *)
memberDefList   = schemaMember { "," schemaMember } [ "," "*" [ ":" memberDef ] ] ;
schemaMember    = name [ "?" ] [ "*" ] [ ":" ( type | memberDef | array | schemaRef ) ] ;
memberDef       = "{" type { "," option } "}" ;            (* type + constraints *)
option          = positionalValue | ( name ":" value ) ;   (* e.g. min: 0 *)
type            = "string" | "int" | "uint8" | "bool" | "datetime" | "decimal" | … ;
```

## Lexical

```ebnf
string          = openString | regularString | rawString ;
regularString   = '"' { char | escape } '"' | "'" { char | escape } "'" ;
rawString       = "r" ( '"' { rawChar } '"' | "'" { rawChar } "'" ) ;
openString      = unquotedChar { unquotedChar } ;          (* ends at a structural char *)

number          = [ sign ] ( decInt [ frac ] [ exp ]    (* frac/exp: base-10 only *)
                           | frac [ exp ]               (* leading-dot form, e.g. .5 *)
                           | hex | octal | binaryNum ) ;
hex             = ( "0x" | "0X" ) hexDigit { hexDigit } ;
octal           = ( "0o" | "0O" ) octDigit { octDigit } ;
binaryNum       = ( "0b" | "0B" ) ( "0" | "1" ) { "0" | "1" } ;
bigint          = [ sign ] ( decInt | hex | octal | binaryNum ) "n" ;
decimal         = [ sign ] ( decInt [ frac ] | frac ) "m" ;

datetime        = "dt" quoted | "d" quoted | "t" quoted ;  (* ISO-8601 inside quotes *)
binary          = "b" quoted ;                              (* base64 inside quotes *)

boolean         = "T" | "F" | "true" | "false" ;
null            = "N" | "null" ;
specialNumber   = "NaN" | "Inf" | "+Inf" | "-Inf" ;

comment         = "#" { anyCharExceptNewline } ;
ws              = ? Unicode whitespace ? ;
name            = nameStart { nameChar } ;
```

> This grammar is a working draft for the 1.0 specification. Edge cases (precise open-string termination, escape sequences, and datetime sub-formats) are described in their respective chapters and will be folded in as the grammar is finalized.

## See Also

* [Structural Elements](/structure-and-syntax/structural-elements.md)
* [Value Representations](/structure-and-syntax/values.md)
* [Internet Object Schema](/schema-definition-language/internet-object-schema.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.internetobject.org/appendices/grammar.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.