What Is It?

Dogma is a human-friendly metalanguage for describing data formats in documentation using the familiar patterns of Backus-Naur Form.

Human Readable

  • For documentation
  • Concise
  • Unambiguous

Text or Binary

  • Bit-level addressible
  • Non-linear parsing
  • Any character set

Expressiveness

  • Macros and functions
  • Conditions and logic
  • Variables, calculations

Quick Examples

A timestamp in a 64-bit unsigned integer. Each time field is a separate bitfield:

timestamp   = year & month & day & hour & minute & second & microsecond;
year        = uint(18, ~);       # 18-bit unsigned, any value
month       = uint(4, 1~12);     # 4-bit unsigned, range 1 to 12
day         = uint(5, 1~31);
hour        = uint(5, 0~23);
minute      = uint(6, 0~59);
second      = uint(6, 0~60);     # Mustn't forget leap seconds!
microsecond = uint(20, 0~999999);

JSON described in Dogma:

document    = element;
element     = WS & value & WS;
value       = object | array | string | number | "true" | "false" | "null";
object      = '{' & member & (',' & member)* & '}';
member      = string & ':' & element;
array       = '[' & element & (',' & element)* & ']';
string      = WS & '"' (character | escape)* '"' & WS;
character   = (unicode(L|M|N|P|S|Z|Cf|Co) | '\[9]') ! ('"' | '\\');
escape      = '\\' & ('"' | '\\' | '/' | 'b' | 'f' | 'n' | 'r' | 't' | 'u' & hex{4});
hex         = '0'~'9' | 'a'~'f' | 'A'~'F';
number      = integer & fraction? & exponent?;
integer     = '0' | ('-'? & first_digit & digit*);
fraction    = '.' & digit+;
exponent    = ('e' | 'E') & ('+' | '-')? & digit+;
first_digit = '1'~'9';
digit       = '0'~'9';
WS          = (' ' | '\[a]' | '\[d]' | '\[9]')*;

Specification

The Dogma Specification

Highlighter

VS Code Syntax Highlighter

More Examples

See the examples directory