Formal Grammar (EBNF)

The grammar of Internet Object in 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

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

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

Header definitions

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

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

Objects and arrays

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

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

A member's value may be absent, which is how an empty position is written: {p, , q} holds three members, the middle one carrying no value. A writer is required to emit this form when a positional member is skipped, so a grammar that demanded a value here would reject conformant writer output.
An array has no such production: valueList requires a value between commas, so [a,,c] is not an array with a hole — it is an error (unexpected-token). Objects bind members by position and therefore need to express a gap; arrays do not.
The optional trailing comma in memberList closes the list; it does not add an empty final position. {a, b,} holds two members, not three.

Values

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

Schema (MemberDef and SchemaDef)

schema          = schemaDef | memberDef | refKey ;
schemaDef       = "{" memberDefList "}" | memberDefList ;   (* object shape *)
memberDefList   = schemaMember { "," schemaMember } [ "," "*" [ ":" memberDef ] ] ;
                                                    (* the wildcard `*` is BARE; a quoted "*"
                                                       is an ordinary memberName *)
schemaMember    = memberName [ ":" ( type | memberDef | array | schemaRef ) ] ;
memberName      = name [ "?" ] [ "*" ]              (* suffixes belong to the bare-name token *)
                | regularString | rawString ;       (* quoted: literal, no suffixes -- use
                                                       optional: / "null": in the memberDef *)
memberDef       = "{" type { "," option } "}" ;            (* type + constraints *)
option          = positionalValue | ( name ":" value ) ;   (* e.g. min: 0 *)
type            = "string" | "int" | "uint8" | "bool" | "datetime" | "decimal" | … ;

Lexical

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" ;   (* reachable via `scalar` *)

comment         = "#" { anyCharExceptNewline } ;
ws              = ? Unicode whitespace ? ;
name            = nameStart { nameChar } ;
sectionName     = sectionChar { sectionChar } ;    (* ANCHORED: the whole name must match *)
sectionChar     = letter | mark | digit | "-" | "_" ;

sectionName is narrower than name, and it is the one name in the format with no quoted form — the separator line runs to the end of the line, so nothing bounds the name. The rule is anchored on purpose: a parser must not match a prefix and leave the remainder to fail later, or --- a,b: $x would silently become a section named a. See Data Sections.

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.