1 of 73

Internet Object

Internet Object 1.0

Thin, schema-first and robust data-interchange object format for Internet

This document aims to provide the Internet Object 1.0 specification and showcase various aspects of the subject.

Field

Value

Author and Researcher

Mohamed Aamir Maniar at ManiarTech® Lab

Contact

[email protected]

Version

1.0 Draft

Status

Work-in-Progress Draft

Website

Docs

Last Updated

14th July 2025

Internet Object

Abstract

Internet Object is a data interchange format designed for modern network communication. This specification introduces Internet Object as a text-based, schema-first, document-oriented, and streamable format that prioritizes human readability and language independence. Internet Object aims to optimize the serialization of structured data for efficient transmission between servers and clients across the internet.

The Poetic Principles of Internet Object

This poem encapsulates the core guiding principles that shape the design and objectives of the Internet Object format.

The poem serves as a unique and memorable medium to communicate the foundational principles that form the basis of the Internet Object format. By creatively capturing these concepts in verse, the poem enables readers to appreciate and remember the essence of the data interchange system more effectively. The Internet Object format is designed to be efficient, clear, and versatile in facilitating data interchange, and the poem highlights these attributes by artistically expressing the philosophy and goals that drive its development. The poem, therefore, not only adds an engaging element to the specification but also reinforces the core values of the Internet Object format.

Poem

Size holds weight, in bytes confined, Small prevails, large left behind.

Simplicity shines over complexity's shroud, Readability echoes, accurate and loud.

Reusability births productivity's rise, Verbosity's burden efficiency defies.

Data, definitions, separate ways, Together they clutter, apart they amaze.

Headers and data, distinctions drawn, Confusion dissolves, clarity's dawn.

Errors and statuses, data's divide, Their entanglement brings chaos inside.

Two lone records, states unswayed, No interference, connections unmade.

Trust not the sender, vigilance displayed, Expect the unanticipated, foundations laid.

Surprises, enchanting, yet beware, Not all of them good, handle with care.

Objectives

The Internet Object serialization format aims to redefine data interchange on the internet by addressing key challenges and limitations present in existing formats.

The inception of the Internet Object began as a side project aimed at addressing the limitations observed in the JSON format. Over time, it evolved into an independent research endeavor, focusing on effectively tackling data-transfer challenges such as size, schema validation, data streaming, header, and metadata support, among others. The design of the Internet Object format revolves around the following key objectives:

Uninfluenced Development

To optimize the format for internet wire transfer, the Internet Object must be conceived and developed without being excessively influenced by existing mechanisms. However, it may draw inspiration from other formats as needed.

Human Friendly

Internet Object documents must be text-based, human-friendly, and easy to work with. Developers should be able to write these documents using plain text IDEs without needing any frameworks, libraries, or utilities.

Minimal Footprint

To ensure a small footprint, the Internet Object format should separate data and schema, allowing data to be sent alone over the network.

Schema First

To uphold data integrity during wire transfer, the Internet Object format should prioritize a schema-first approach.

Document Oriented

Embracing a comprehensive document-oriented approach, the Internet Object format should facilitate the bundling of all essential components - including records, data, definitions, schemas, and comments - within a single document. This approach ensures that all related information is conveniently stored together, promoting the efficient organization and streamlined management of data and its associated elements. Moreover, it enhances maintainability and simplifies collaboration among team members, as they can easily access and understand the complete context within a single, unified document.

Complex Data Types

The Internet Object must support complex data types so that any kind of data whether large number or complex data structure can be easily serialized and deserialized for the wire.

Streaming Friendly

The Internet Object format should support the streaming of independent records, allowing for efficient and continuous data transfer. With this feature, the failure of a single record will not affect the processing of other records, ensuring more resilient data transmission.

Platform and Language independence

The Internet Object format should be designed to work seamlessly across different platforms, operating systems, and programming languages. This universal compatibility ensures broad adoption and versatility, enabling developers to easily integrate the format into their projects without limitations.

Comments

By providing support for inline comments, the Internet Object format allows users to document schemas and definitions directly within the data itself. This feature enhances readability and maintainability, making it easier for users to understand and manage complex data structures.

Reusability

To increase the format's adaptability, the Internet Object should promote reusability through concepts like references and variables. This dynamic feature allows for the customization of data structures and enables users to manipulate data more effectively, catering to various needs and scenarios.

The Structure

Internet Object Document

The Internet Object format is a document-oriented format that emphasizes the separation of header and data. This structure is similar to that of HTML, and MIME, where the header is kept separate from the data or body.

In an Internet Object document, the header is optional but can be used to define schemas and definitions. The data section always starts with the --- separator. This separator is the first element of the data section and is mandatory to distinguish it from the header.

[ Internet Object Document Structure Diagram ]

Internet Object Document Examples

Full Document

If an Internet Object document includes both a header and a data section you can call it a full document.

# Header
name, age:int, address: {street, city, state}, active # Header

# Data Section
---
John Doe, 25, {Bond Street, New York, NY}, T

Data-only Document

When an Internet Object document contains only a data section, it is okay to omit the --- separator. Such documents are sent to the server without any header because the schema is either not required or already known to the recipient.

With Separator:

---
John Doe, 25, {Bond Street, New York, NY}, T # Data section

Without Separator:

~ John Doe, 25, {Bond Street, New York, NY}, T
~ Jane Done, 48, {Malibu Point 10880, Malibu, CA}

Header-only Document

In many cases, a query-generating document may not yield any results. In such cases, you can use the header with result metadata to send the query and the results. However, it is important to include the --- separator to mark the end of the header and the start of the data section.

# Header Record Metadata
~ reocordCount: 0
~ pageSize: 10
~ currentPage: 1
~ nexPage: N
~ prevPage: N

# Empty Data Section
---

Document with Multiple Data Sections

Internet Object document can contain multiple data sections. This facility allows user to provide multiple types of data collection to be embedded in the single document.

# Schema section
~ $address: {street, city, state, zip} # Adddress Schema
~ $person: {firstName, lastName, age, gender }

# The collection of person
--- $person
~ John, Doe, 25, M
~ Jane, Doe, 22, F

# The address
--- $address
~ Bond Street, New York, NY, 500001
~ Georeg Street, New York, NY, 500002

Internet Object document structure is designed to be simple and flexible. The next section will discuss the Header and Data section in detail.

Header

The header of an Internet Object document is positioned at the beginning of the document and serves a crucial role in defining the schema or associated definitions for the data it contains. This section includes essential metadata, context, variables, and schema references for the document's content. It plays an important role in ensuring that the data is presented in a consistent format and provides the necessary information for accurate interpretation and processing.

[ Header Image Placeholder ]

Default Schema

The schema is a fundamental component of the Internet Object format, defining the structure and semantics of the data within an Internet Object document. When the header contains only a schema, it is referred to as a "default schema." This schema is typically used to outline the structure of the data included in the document, separating the structure definition from the data itself. This separation makes the data more compact, readable, and easier to process. For more detailed information about schemas, refer to .

In this schema example, five keys are defined with additional details:

name: Represents a standard key, expected to contain a value such as a string.
age:int: Specifies that the age key should contain an integer value, indicating the data type explicitly.
address: Another standard key, which could hold a more complex value like a string or an object, depending on the context.
isActive?: The question mark (?) signifies that the isActive key is optional, meaning it may or may not be present in the data.
remark: Represents a standard key, expected to contain a value, likely a string, which could hold additional comments or notes.

This schema not only defines the structure but also includes type annotations and optionality, enhancing the clarity and robustness of the data model. By using this schema, the document can ensure consistent and accurate data representation, making it easier to process and interpret across different systems.

See this page for more information about .

Definitions

Definitions, at their core, are collections of key-value pairs used to declare metadata, variables, complex schemas, and other key-value pairs within the header of an Internet Object document.

In this example, the header contains response metadata and schema details presented as Definitions, rather than using a Default Schema as seen in the previous example. The Definitions provide metadata that specify the page size (pageSize), the current page number (currentPage), and the total record count (recordCount). Additionally, more complex structures are defined, such as an address schema ($address) with nested keys (street, city, state) and a higher-level schema ($schema) that references both simple and complex data types. The $schema is a reserved key used to define the default schema for the document.

For further information about , click the link.

Structural Elements

The Internet Object format includes several structural characters, literals, and other special characters that are used to structure and delimit data within a document. These characters are used in conjunction with objects, strings, arrays, numbers, and whitespace to create complex and flexible data structures.

Literals

Literals are predefined constant values in Internet Object that represent common data states and special values. They provide a concise way to express boolean values, null states, and special numeric values without requiring quotes or additional syntax.

Supported Literals

Internet Object supports the following literal values:

Literal

Type

Represents

Case Sensitive

Examples

Rules

Case Sensitive: All literals must use exact case (True, FALSE, NULL are invalid)
No Quotes: Literals are written without quotes
Short Forms: Single-letter shortcuts available for brevity

Other Special Characters

Special characters are used in conjunction with structural characters and literals to provide additional functionality or context within an Internet Object document. These characters have specific semantic meanings and modify the behavior of schemas, values, or parsing.

Special Character Set

Symbol

Name

Unicode

Context

Application

@

At Sign

U+0040

Variable

When prefixed to a key name, declares a variable reference

$

Dollar Sign

U+0024

Schema

When prefixed to a key name, declares a schema reference

?

Question Mark

U+003F

Schema

Shortcut for declaring optional member when suffixed to the key name in object schema

*

Asterisk

U+002A

Schema

Shortcut for declaring nullable member when suffixed to the key name in object schema. Also used to make schema accept undeclared variables

-

Hyphen / Minus

U+002D

Numeric

Represents negative value

+

Plus

U+002B

Numeric

Represents positive value

Usage Examples

Variable References and Schema Definitions

# Variable declarations
~ @r: red
~ @g: green
~ @b: blue

# Schema definitions using variables
~ $color: {string, choices: [@r, @g, @b]}
~ $schema: {
    name: string,
    email: email,
    joiningDt: date,
    color: $color
}

---
# Data using variable references
~ John Doe, '[email protected]', d'2020-01-01', @r

Schema Modifiers

# Optional and nullable field declarations
~ $user: {
    name: string,          # Required field
    email?: string,        # Optional field (may be omitted)
    avatar*: string,       # Nullable field (may be null)
    metadata*?: object     # Optional and nullable field
}

# Schema with undeclared variables acceptance
~ $flexible: {
    id: string,
    name: string,
    *                      # Accept additional undeclared fields
}

Numeric Signs

# Positive and negative numbers
temperature: +23.5         # Explicit positive
balance: -150.75          # Negative value
elevation: +8848          # Positive integer
debt: -5000               # Negative integer

Character Rules

Context Sensitive: Characters have different meanings based on position and context
Variable Prefixes: @ prefixes variable declarations and references
Schema Prefixes: $ prefixes schema definitions and references
Schema Suffixes: ? and * must be suffixed to field names in schema definitions
Numeric Prefixes: + and - prefix numeric values to indicate sign
Case Sensitive: All special characters are case-sensitive
Reserved Usage: These characters are reserved for their specific functions

Strings

Strings in Internet Object

Strings in Internet Object represent sequences of Unicode codepoints. They are used for textual data and always preserve whitespace and formatting within their boundaries.

Internet Object supports three distinct string types, each with unique syntax and use cases:

stringValue = openString | regularString | rawString

String Type

Description

Example Syntax

Unquoted, simplest form, ends at structural character or whitespace.

John Doe

Quoted with double quotes, supports escaping and structural characters.

"John Doe"

Prefixed with r, quoted with single or double quotes, minimal escaping.

r'C:\path' or r"C:\path"

All string types preserve whitespace and Unicode content as written.

When to Use Each String Type

Open String: For simple, unstructured text without leading/trailing whitespace or special characters.
Regular String: When you need to include structural characters, whitespace, or require escaping.
Raw String: For text with many backslashes or quotes (e.g., file paths, regex), with minimal escaping and r prefix.

Regular Strings

Regular strings in Internet Object

A Regular String in Internet Object is a sequence of Unicode codepoints enclosed in single quotes (' U+0027) or double quotes (" U+0022). Regular strings allow any character, including whitespace and structural characters, and support escaping for special codepoints. This makes them suitable for text that requires leading/trailing whitespace, structural characters, or complex escaping.

Regular strings are scalar values. They preserve all content as written, including whitespace and Unicode characters.

Syntax

A regular string is enclosed in single or double quotes and may contain any Unicode codepoint, with support for escape sequences.

Structural Characters

Symbol

Name

Unicode

Description

Valid Forms

Examples of valid regular strings:

Optional Behaviors

Whitespace: Leading, trailing, and internal whitespace are preserved.
Escaping: Only designated escape sequences are interpreted: \n, \", \\, \', \b, \f, \r, \t, \u (with exactly 4 hex digits and must be a valid Unicode codepoint), and \x (with exactly 2 hex digits). All others (e.g., \o) are left as a literal backslash and character. For example, "hell\\o" emits hello.
Multiline: Newline and carriage return characters are preserved.
String Comparison: Escaped and unescaped forms are equivalent if they represent the same Unicode codepoints.

Comments

Comments are not allowed within regular strings, but may appear outside or between values as per Internet Object comment rules.

Invalid Forms

Examples of invalid regular strings:

Preservation of Structure

Internet Object preserves:

All Unicode codepoints and whitespace as written
Escaped and unescaped forms (syntactic fidelity)

It does not interpret or enforce:

Application-specific constraints
Normalization of escape sequences (beyond equivalence)

Raw Strings

Raw strings in Internet Object

A Raw String in Internet Object is a sequence of Unicode codepoints prefixed with r or R and enclosed in either single quotes (' U+0027) or double quotes (" U+0022). Raw strings are ideal for text containing many backslashes, quotes, or structural characters, such as file paths or regular expressions. They do not support escape sequences except for the enclosing quote, which can be represented by doubling the enclosing quote character inside the string.

Raw strings are scalar values. They preserve all content as written, including whitespace, newlines, and Unicode characters.

Syntax

A raw string is prefixed with r or R and enclosed in either single or double quotes. The only special rule is that the enclosing quote character inside the string must be represented as two consecutive enclosing quotes.

rawString = "r" (singleQuotedRaw | doubleQuotedRaw)
singleQuotedRaw = "'" { character | doubleSingleQuote } "'"
doubleQuotedRaw = '"' { character | doubleDoubleQuote } '"'
character = any Unicode codepoint except the enclosing quote
doubleSingleQuote = "''" (represents a single quote inside a single-quoted raw string)
doubleDoubleQuote = '""' (represents a double quote inside a double-quoted raw string)

Structural Characters

The following characters are used to structure raw strings:

Symbol

Name

Unicode

Description

r

Raw Prefix

U+0072

Indicates raw string type

'

Single Quote

U+0027

Encloses string, doubled inside for escape

"

Double Quote

U+0022

Encloses string, doubled inside for escape

(space, tab, etc.)

Whitespace

Multiple

Preserved as written

Any

Any Unicode codepoint

Multiple

Allowed, except unescaped enclosing quote

Note: The reverse solidus (\\ U+005C) is always treated as a literal character in raw strings—there is no escaping with backslash.

Valid Forms

Examples of valid raw strings:

r'C:\program files\example\app.exe'
r"C:\program files\example\app.exe"
r'^(19|20)\d\d([- /.])(0[1-9]|1[012])\2(0[1-9]|[12][0-9]|3[01])$'
r"^(19|20)\d\d([- /.])(0[1-9]|1[012])\2(0[1-9]|[12][0-9]|3[01])$"
r'जॉन डो'
r"Can contain Ucharacters 😃"
r'A Unicode string (😃) which does not force you to escape\ncharacters like \, \n or anything except a single quote char ''''.'
r"A Unicode string (😃) which does not force you to escape\ncharacters like \, \n or anything except a double quote char \"\"."
r'Jonas D''costa'  # Contains a single quote inside
r"He said, ""Hello!"""  # Contains a double quote inside

Optional Behaviors

Whitespace: Leading, trailing, and internal whitespace are preserved.
No Escaping: No escape sequences are supported except for doubling the enclosing quote to represent it inside the string.
Multiline: Newline and carriage return characters are preserved.

Comments

Comments are not allowed within raw strings, but may appear outside or between values as per Internet Object comment rules.

Invalid Forms

Examples of invalid raw strings:

rC:\program files\example\app.exe     # ✗ Missing quotes (should be r'...') or r"..."
r'Jonas D'costa'                      # ✗ Unescaped single quote inside (should be r'Jonas D''costa')
r"He said, "Hello!""                  # ✗ Unescaped double quote inside (should be r"He said, ""Hello!"")
r'Unclosed string                     # ✗ Missing closing quote
r'Contains \\ escapes'                # ✗ Backslash is not an escape, just literal

Preservation of Structure

Internet Object preserves:

All Unicode codepoints and whitespace as written
The use of doubled enclosing quotes for embedded quotes

It does not interpret or enforce:

Application-specific constraints
Escaping beyond doubled enclosing quotes

Numeric Values

Numbers in Internet Object

Numbers in Internet Object provide accurate numerical representation for various applications, from simple counting to complex financial calculations. Internet Object supports three distinct numeric data types—Number, BigInt, and Decimal—each designed to meet different numerical requirements in modern applications.

Number Types

(64-bit floating-point): Standard IEEE 754 double-precision numbers, ideal for general-purpose calculations and fractional values.
: Arbitrary-precision integers for extremely large whole numbers that exceed 64-bit limitations.
: Fixed-precision decimal values with exact arithmetic, essential for financial calculations and applications requiring precise decimal representation.

Number Formats

Internet Object supports various number formats. The table below distinguishes between decimal integers and regular (floating-point) numbers, and provides recommendations:

Note: Bases other than decimal (base 10)—that is, binary (base 2), octal (base 8), and hexadecimal (base 16)—can only represent integers, not fractional or decimal values. For non-integer values, use decimal (base 10) or scientific notation.

Format

Supported Types

Recommendation/Use Case

Type Identification

Each number type uses a distinct suffix for identification:

Special Numeric Values

See for details on undefined and infinite results (supported only by Number).

Note: Alternative base formats (binary, octal, hexadecimal) are documented within each number type specification.

Type Selection Guide

Use Case

Recommended Type

Reason

Note: The term "decimal" is used in two contexts:
Decimal (base-10): The common numeral system used by all number types
Decimal (data type): A specific fixed-precision type for exact arithmetic

Number

Standard 64-bit floating-point numbers in Internet Object

A Number in Internet Object represents a 64-bit double-precision floating-point value conforming to the IEEE 754 standard. Numbers are scalar primitives used to express integers, fractional values, and special numeric constants.

Numbers in Internet Object support various representations including different bases (binary, octal, hexadecimal), scientific notation, and special values like NaN and Infinity.

Syntax

A number can be expressed in multiple forms:

number = ["-" | "+"] (
    decimalNumber
  | binaryNumber
  | octalNumber
  | hexNumber
  | scientificNumber
) | specialValue

decimalNumber = digit+ ["." digit+]
binaryNumber = "0b" binaryDigit+
octalNumber = "0o" octalDigit+
hexNumber = "0x" hexDigit+
scientificNumber = (digit+ ["." digit+] | "." digit+) ("e" | "E") ["-" | "+"] digit+
specialValue = "NaN" | "Inf" | "-Inf" | "+Inf"

digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
binaryDigit = "0" | "1"
octalDigit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
hexDigit = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f"

Structural Characters

Symbol

Name

Unicode

Description

0-9

Digits

Multiple

Standard decimal digits

.

Decimal Point

U+002E

Separates integer and fraction

-

Minus Sign

U+002D

Indicates negative numbers

+

Plus Sign

U+002B

Optional positive indicator

e/E

Exponent

Multiple

Scientific notation exponent

0b

Binary Prefix

Multiple

Binary number indicator

0o

Octal Prefix

Multiple

Octal number indicator

0x

Hex Prefix

Multiple

Hexadecimal number indicator

Valid Forms

Decimal Base Number

Numbers in decimal format can include integers and fractional values, with optional sign prefixes:

# Simple integers
42                   # Integer
-17                  # Negative integer
+17                  # Positive integer (explicit)

# Fractional numbers
3.14159              # Fractional number
-0.5                 # Negative fractional
+0.5                 # Positive fractional (explicit)

# Zero
0                    # Zero
+0                   # Positive zero (explicit)
-0                   # Negative zero (explicit)

A decimal number consists of one or more digits, optionally preceded by a sign (+ or -), and optionally including a decimal point followed by one or more digits.

Alternative Bases

Numbers can be expressed in binary, octal, or hexadecimal notation:

Binary Numbers (Base-2)

Binary representation uses 0b or 0B prefix followed by binary digits (0-1):

0b1010               # Binary 1010 (10 in decimal)
0B1111               # Binary 1111 (15 in decimal)
0b0                  # Binary 0
-0b1010              # Negative binary (-10 in decimal)
+0B1100              # Positive binary (12 in decimal)

Octal Numbers (Base-8)

Octal representation uses 0o or 0O prefix followed by octal digits (0-7):

0o755                # Octal 755 (493 in decimal)
0O644                # Octal 644 (420 in decimal)
0o0                  # Octal 0
-0o755               # Negative octal (-493 in decimal)
+0O377               # Positive octal (255 in decimal)

Hexadecimal Numbers (Base-16)

Hexadecimal representation uses 0x or 0X prefix followed by hex digits (0-9, A-F):

0xFF                 # Hexadecimal FF (255 in decimal)
0x10                 # Hexadecimal 10 (16 in decimal)
0XDeadBeef           # Mixed case hex (3735928559 in decimal)
-0xFF                # Negative hex (-255 in decimal)
+0x10                # Positive hex (16 in decimal)

Case Sensitivity

Prefixes: Both lowercase (0b, 0o, 0x) and uppercase (0B, 0O, 0X) are supported
Hex digits: Both uppercase (A-F) and lowercase (a-f) are valid

0xFF                 # ✅ Lowercase prefix, uppercase digits
0XFF                 # ✅ Uppercase prefix, uppercase digits
0xff                 # ✅ Lowercase prefix, lowercase digits
0Xff                 # ✅ Mixed case (all equivalent)

Scientific Notation

Scientific notation expresses numbers using exponential form with e or E:

1.23e4               # 1.23 × 10⁴ = 12300
1.23E4               # Same as above (case insensitive)
1.23e-4              # 1.23 × 10⁻⁴ = 0.000123
-2.5e+3              # -2.5 × 10³ = -2500
5e3                  # 5 × 10³ = 5000
.5e2                 # 0.5 × 10² = 50
6.022e23             # Avogadro's number
1e-10                # Very small number
-3.14159e0           # -3.14159 × 10⁰ = -3.14159

Scientific Notation Components

Mantissa: The significant digits (before e/E)
Exponent marker: e or E (case insensitive)
Exponent: The power of 10 (can be positive, negative, or zero)

# Format: [sign]mantissa[e|E][sign]exponent
1.5e+10              # Explicit positive exponent
1.5e-10              # Negative exponent
1.5e10               # Implicit positive exponent

Optional Behaviors

Literal and Alternate Forms

Numbers support multiple equivalent representations:

42                  # ✅ Standard decimal
0x2A                # ✅ Hexadecimal (equivalent to 42)
0b101010            # ✅ Binary (equivalent to 42)
0o52                # ✅ Octal (equivalent to 42)
4.2e1               # ✅ Scientific notation (equivalent to 42)

Invalid Forms

.5                  # ❌ Must have leading digit
5.                  # ❌ Must have trailing digit if decimal point used
0b                  # ❌ Missing binary digits
0b12                # ❌ Invalid binary digit '2'
0o89                # ❌ Invalid octal digits '8' and '9'
0x                  # ❌ Missing hex digits
0xGH                # ❌ Invalid hex digits 'G' and 'H'
1.2.3               # ❌ Multiple decimal points
0b 1010             # ❌ Space between prefix and digits
0o 755              # ❌ Space between prefix and digits
0x FF               # ❌ Space between prefix and digits
1e                  # ❌ Missing exponent in scientific notation
1e+                 # ❌ Missing exponent digits
1.23ee4             # ❌ Multiple exponent markers
1.2.3e4             # ❌ Multiple decimal points in mantissa

Preservation of Structure

Internet Object preserves:

The chosen representation form (decimal, binary, octal, hex, scientific)
Whitespace (non-significant in interpretation)
Syntactic fidelity (as written, except that an explicit plus sign is not preserved)

However, it does not interpret:

Mathematical relationships between values
Precision requirements beyond IEEE 754
Domain-specific numeric constraints

Such semantics are the responsibility of the schema layer, validators, or application logic.

BigInt

Unbounded integer values for handling extremely large numbers

A BigInt in Internet Object represents arbitrary-precision integers that can handle numeric values exceeding the limitations of standard 64-bit number representations. BigInt is a scalar primitive used for extremely large whole numbers with perfect precision, such as in cryptographic operations, large-scale counting, or mathematical computations requiring unbounded integer arithmetic.

Unlike the regular Number type, which is limited to safe integers within approximately ±9 quadrillion (±2^53-1), BigInt can represent integers of arbitrary length, ensuring that large numerical operations remain exact regardless of magnitude.

Syntax

A BigInt value is expressed as an integer with the n suffix:

bigint = ["-" | "+"] (decimalBigInt | binaryBigInt | octalBigInt | hexBigInt)

decimalBigInt = digit+ "n"
binaryBigInt = "0b" binaryDigit+ "n"
octalBigInt = "0o" octalDigit+ "n"
hexBigInt = "0x" hexDigit+ "n"

digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
binaryDigit = "0" | "1"
octalDigit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
hexDigit = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f"

Structural Characters

Symbol

Name

Unicode

Description

n

BigInt Suffix

U+006E

Identifies value as BigInt

0-9

Digits

Multiple

Standard decimal digits

-

Minus Sign

U+002D

Indicates negative numbers

0b

Binary Prefix

Multiple

Binary number indicator

0o

Octal Prefix

Multiple

Octal number indicator

0x

Hex Prefix

Multiple

Hexadecimal number indicator

Valid Forms

Decimal BigInt

123n                 # Positive BigInt
-42n                 # Negative BigInt
0n                   # Zero as BigInt
9007199254740992n    # Beyond Number.MAX_SAFE_INTEGER

Alternative Bases

0b1010n              # Binary (10 in decimal)
0o7777n              # Octal (4095 in decimal)
0xFFn                # Hexadecimal (255 in decimal)
0xFFFFFFFFFFFFFn     # Large hex BigInt

Optional Behaviors

Literal and Alternate Forms

BigInt values support multiple equivalent representations:

42n                  # ✅ Standard decimal BigInt
0x2An                # ✅ Hexadecimal BigInt (equivalent to 42n)
0b101010n            # ✅ Binary BigInt (equivalent to 42n)
0o52n                # ✅ Octal BigInt (equivalent to 42n)

Integer-Only Operations

BigInt values represent whole numbers only and do not support fractional components:

5n + 3n              # 8n (addition)
5n * 3n              # 15n (multiplication)
5n / 3n              # 1n (integer division, truncates toward zero)
5n % 3n              # 2n (remainder)

Arbitrary Precision

BigInt values maintain exact precision regardless of magnitude:

9007199254740991n + 1n    # 9007199254740992n (exact)
9007199254740991n + 2n    # 9007199254740993n (exact)

Invalid Forms

123                  # ❌ Missing 'n' suffix (should be 123n)
123.45n              # ❌ BigInt cannot have decimal point (use Decimal for fractions)
123nn                # ❌ Multiple suffixes not allowed (should be 123n)
n123                 # ❌ Suffix must be at the end (should be 123n)
0b                   # ❌ Missing binary digits (should be 0b1n)
0xn                  # ❌ Missing hex digits (should be 0x1n)

Preservation of Structure

Internet Object preserves:

The chosen representation form (decimal, binary, octal, hex)
Exact integer precision regardless of magnitude
Syntactic fidelity (as written, except that an explicit plus sign is not preserved)

However, it does not interpret:

Mathematical relationships between values
Domain-specific constraints on large integers
Performance implications of arbitrary-precision arithmetic

Such semantics are the responsibility of the schema layer, validators, or application logic.

Booleans

Booleans in Internet Object

A Boolean in Internet Object represents a logical value that can be either true or false. Boolean values are scalar primitives used to express binary states, flags, or conditional logic.

Boolean values in Internet Object support both compact and verbose representations to balance readability and space efficiency.

Syntax

A boolean value can be expressed in two forms:

Structural Characters

Symbol

Name

Unicode

Description

Valid Forms

Optional Behaviors

Literal and Alternate Forms

Internet Object supports two equivalent representations for each boolean value:

Compact form: T for true, F for false (recommended)
Verbose form: true for true, false for false

Invalid Forms

Nulls

Nulls in Internet Object

A Null in Internet Object represents the absence of a value or an explicitly undefined state. Null is a scalar primitive used to indicate missing, unknown, or intentionally empty data.

Null values in Internet Object support both compact and verbose representations to balance readability and space efficiency.

Syntax

A null value can be expressed in two forms:

null = compactNull | verboseNull
compactNull = "N"
verboseNull = "null"

Structural Characters

Symbol

Name

Unicode

Description

N

Uppercase N

U+004E

Compact representation of null

null

Keyword null

Multiple

Verbose representation of null

Valid Forms

N                    # Compact null
null                 # Verbose null

Optional Behaviors

Literal and Alternate Forms

Internet Object supports two equivalent representations for null values:

Compact form: N (recommended)
Verbose form: null

N        # ✅ Recommended compact form
null     # ✅ Verbose form (equivalent to N)

Empty Representation

Null explicitly represents the absence of a value, distinct from empty strings or empty arrays.

N        # Null value
""       # Empty string (different from null)
[]       # Empty array (different from null)

Invalid Forms

n         # ❌ Lowercase not allowed
NULL      # ❌ All caps not allowed
Null      # ❌ Mixed case not allowed
nil       # ❌ Alternative keywords not allowed
undefined # ❌ Alternative keywords not allowed

Comments

Internet Object supports single-line comments for documenting and annotating data. Comments start with a hash sign (#) and continue to the end of the line.

Syntax

Start Character: Hash sign (# U+0023)
Scope: Single line only
Placement: Can appear anywhere in the document
Content: Everything after # on the same line is ignored by the parser

Examples

Comment Placement

Rules

Comments can appear on any line
Can be standalone or inline after data
Support full Unicode text
Cannot span multiple lines
No special escaping needed

Best Practices

Be Clear and Concise: Use simple, direct language
Explain Why, Not What: Focus on reasoning rather than obvious facts
Keep Comments Updated: Update comments when data structures change
Use Consistently: Maintain uniform style throughout documents

The Collections

Collection Rules

Collection Without schema

If the schema is not defined, the records in the collection can have a different structure from each other across the document. Here is the code snippet,

In the above example, the schema is not defined for the collection records so it will be parsed as,

Even though it is not necessary, it is good practice to define a schema for the collection records.

Empty Record in Collection

Sending an empty record is valid only if all the variables defined in the schema are either set to null or optional or both.

Here in the above code snippet A and B is null and C is optional thus sending an empty record is valid. Because just sending a "~" means an empty object { }.

In the above example, A is null, B is null and optional and C is optional. So all the keys are either optional or null or both thus sending an empty record is valid. Because just sending a "~" means an empty object { }.

In the above example, the invalid record fails while parsing as the name variable is not optional or null. On the other hand, the age variable is optional as well as null so it is valid to not pass any value for the age variable.

Handling Errors

The Collection enables the parser to parse the rest of the document even if the previous record fails to execute.

If the record fails while parsing, that record state becomes invalid and it does not stop parsing the rest of the document.

Data Streaming

For frequently passing object data between the system over the internet there is a need to stream objects over a single connection.

As the collection enables embedding more than one independent record in the document because of its nature it allows streaming real-time data changes. So that the application can react immediately to the changing events in real-time.

Multiple records can be sent in batches after validating with the schema as,

After you have received the first batch of records, the collection allows you to receive more records for the same collection separately. The Internet Object processor should take care of merging the stream of data into the same collection.

Internet Object does not prevent the number of records streamed over with a collection

The Definitions

Complex Schema

The header section of the internet object document can have single or multiple schema definitions

~ $address: {
    street: string, 
    zip:{string, maxLength:5},
    city: string
  }
~ $person: {
    name:string,
    age:int,
    homeAddress?:$address,
    officeAddress?:$address
  }
~ $schema: $person
---
Spiderman, 25, {Queens, 50010, New York}, {Bond Street, 50001, New York}

In the above example, the schema definitions are created for reuse to improve the readability of a schema. The schema definition created for address is reused in the person schema definition.

Schema Definition Language

Data Types

The internet object schema defines six data types that include string, number, int, int32, int16, byte, email, url, datetime, date, time, bool, object, array or any.

The types string and number have subtypes. The email, url, datetime, date and time are subtypes of string. The int, int32, int16, byte are subtypes of number.

TypeDefs

Typedefs are a memberdef schema for the specified type. They define the constraints for the particular data type. The following example

type: { string, choices: [
    string, email, url, datetime, date, time,
    number, int, int32, int16, byte,
    object, array, bool
  ]
}

type      : {string, choices: [string, email, url, datetime, date, time]},
default?  : string,
choices?  : [string],
pattern?  : string,
maxLen?   : {int, min:0},
len?      : {int, min:0},
optional? : {bool, F},
null?     : {bool, F}

Some of the valid String MemberDef values are...

# The name is string and default value is ""
name: {string, ""}

# The website is of url type!
website: {url, optional:T} 

# The rgb's default is red, and choices are red, green, blue
rgb: {string, red, [red, green, blue]}

# The description is string that can have maximum length of 500 characters 
description: {string, maxLen:500} #

As shown in the example above, Objects, Numbers, Arrays, Boolean, and Any have their respective TypeDef.

String Derived Types

Internet object specifies email, url, datetime, date and time as derived types of string and also provides built-in support for them.

The following snippet represents a string and its derived types.

# Strings and its derived types
{ 
  name: string, 
  emailId: email, 
  profileUrl: url,
  journyDate: date,
  departureTime: time,
  bookingDatetime: datetime
   
 }
---
{ 
 Christopher Andrews,                                # string
 [email protected],                      # email
 https://www.abc.com/in/christopher-andrew-06528b155 #url
 2021-02-09                                          # date
 06:30:00                                            # time
 2020-12-30T12:39:48.545                             #datetime
}

Here the, name is of string type and will only accept strings. Similarly, emailId, profileUrl, journyDate departureTime and bookingDatetimedate are of different types such as email, url, date, time, datetime. Therefore they will only accept values with the defined types for the respective variable.

URL

Similar to Email, an URL can also be passed as a string. The URL format is derived from the recommended by W3C.

URL format follows the syntax specified in the

The code snippet shows how to define an url In the Internet Object Document.

In the case of the url format, the data must be valid URL.

MemberDef

The Email is derived from the String type, hence it shares the same as the String. However, URL enforces additional constraints with the respective url format.

Choices

The choices can be added to member variables in the url so that it is restricted to the fixed set of available choices. Choices must be an array of valid url. The code snippet here shows how to add choices for the url.

pattern

User may specify pattern for the url by defining pattern as,

Time

Time can be represented as, HH:mm:ss.SSS or HHmmss.SSS i.e it can be passed with or without separators (: U+003A).

It uses a 24-hour clock system. Midnight is a special case and it may be referred to as "00:00" or "24:00". However, ISO 8601-1: 2019 no longer permits "24:00".

The code snippet demonstrates how to define and use time In the Internet Object Document.

MemberDef

The Time is derived from the String type, hence it shares the same as the String. However, Time enforces additional constraints with the respective time format and the same is applicable to the Time MemberDef.

Derived Types

Internet object specifies the following number derived types and also provides built-in support for them.

The following snippet represents a number and its derived types.

# Number and its derived types
{ applicationNo: int, 
  rollNo: int32, 
  totalScore: int16,
  percentage: number,
   paperCode: byte
 }
---
{ 
8754489612, 
  125447,   
  566,      
  94.33,    
  48        
}

Here the applicationNo is of integer type and will only accept integers. Similarly, rollNo, totalScore, percentage and paperCode are of different types such as int32, int16, number, and byte. Therefore they will only accept values with the defined types for the respective variable.

byte

When a variable is classified as a byte then the data will be accepted only if it is an integer with the size of a byte or 8 bits. A byte may have, decimal, hexadecimal, octal or binary values. The range of values is from -127 to +128.

The byte is derived from the number type that shares the sameas the Number i.e type, default, choices, max, min, multipleOf, divisibleBy, optional and null while enforcing the additional constraint that the number must be of byte type.

By default the max value of byte type variable is 128 and and min is -127.

int16

When a variable is classified as an int16 in the schema then it will be classified as an integer with a size of 16 bits or 2 bytes. The range of values is from -32768 to +32767.

Member Def

The int16 is derived from the number type that shares the sameas the Number i.e type, default, choices, max, min, multipleOf, divisibleBy, optional and null while enforcing the additional constraint that the number must be of int16 type.

By default the max value of byte type variable is +32767 and and min is -32767.

int32

When a variable is classified as an int32 type in the schema then it will be classified as an integer with a size of 32 bits or 4 bytes. The range of values is from -2,147,483,648 to 2,147,483,647.

Member Def

The int32 is derived from the number type that shares the sameas the Number i.e type, default, choices, max, min, multipleOf, divisibleBy, optional and null while enforcing the additional constraint that the number must be of int32 type.

By default the max value of byte type variable is 2,147,483,647 and and min is -2,147,483,648.

Object

An object is the fundamental unit of Internet Object document, it can be defined with the members such as schema, type, default, optional and null.

TypeDefs Schema

The TypeDef schema ensures the validity of object MemberDefs.

schema

In the internet object document, the object may or may not be defined with the member called schema. But it is always recommended to define the schema for an object.

If the schema is not defined then the user can pass an object with values of any type i.e anyOf: [string, object].

The above code snippet represents how the object can be defined with the typedef member schema .

type

The second member of the typedef is type. By default, the object can be of string or an object type. Here the next snippet shows how the object type can be defined.

default

The next member in the object typedef is default . Here is how the default values can be defined for an object.

null

The Object when set to null will accept null values. Here the code snippet demonstrates the way how an object can accept a null value.

optional

A member of an object type can be set to optional. Here are some of the ways through which a member of an object type can be made optional.

Designing Object Schema

Empty Object

An empty object is useful for accepting any object value irrespective of its structure. The empty object definitions can be created using empty curly braces syntax or ignoring schema. Here are some ways in which empty object definitions can be created.

Simple Object

A simple object is an ordered collection of key-value pair that avoids nesting of the object and may or may not contain a child object as shown in the code snippet.

With Memberdef

An object can be defined with the MemberDef as shown in the snippet below.

Nested Object

An Object can be nested inside another object. Accessing a nested object is similar to accessing a nested array. Here is the code snippet that shows how objects can be nested.

Dynamic Schema

Defining dynamic schema allows users to add a dynamic object as shown in the snippet below.

Schema or MemberDef

The object can be represented as as shown here.

Array

An Internet Object array can be defined with the members such as type, default, len, minLen, maxLen, optional and null. Schema of the array TypeDef should be written as,

TypeDef Schema

The TypeDef schema ensures the validity of array MemberDefs.

schema

The first member of the internet object array is a schema. When the schema is defined all array items must be validated against the schema. The code snippet demonstrates how the array can be defined with the schema.

default

The next member in the array typedef is default . Here is how the default values can be defined for an array.

minLen

The value of minLen must be a non-negative integer. The array instance is valid only if, number of items in the array will be greater than or equal to the value of minLen. The code snippet shows how to define minLen for an array.

maxLen

The value of maxlen must be a non-negative integer. The array instance is valid only if, number of items in the array will be less than or equal to the value of the maxlen. Here the code snippet shows how to define maxLen for an array.

len

The next member in the array typedef is length represented as len , it must be a non-negative integer. The Array instance is valid only if, the number of items in the array will be exactly equal to the value of len. Here is how the len can be defined for an array.

The len has higher precedence over minLen and maxLen constraints. That is when the len is set, the implementations must ignore minLen and maxLen constraints.

null

An array when set to null will accept null values. Here the code snippet demonstrates the way how an array can accept a null value.

optional

A member of an array type can be set to optional. Here a code snippet demonstrates different ways how an array can be set to optional

type

An array type can be specified as shown in the snippet below.

Examples

Some of the valid examples of members with array type are...

The above example can be simplified as,

An array can have mixed values as shown in the snippet below.

Nested Arrays

An array containing another array represents a nested array as shown in the code snippet.

Multidimensional Array

A multidimensional array is an array with more than one dimension. Two and three-dimensional arrays are called multidimensional arrays. Here is the code snippet that demonstrates how a multidimensional array is represented.

Bool

A boolean data type is used to assign boolean values to the variable i.e True and False. A boolean can be defined with the members such as type, default, optional and null. Schema of the array TypeDef should be written as,

TypeDef Schema

type?     : {string, choices: [bool]} 
default?  : bool,
optional? : {bool, F},
null?     : {bool, F}

The TypeDef schema ensures the validity of bool MemberDefs.

type

The first member of the bool typedef is type. The next snippet shows how to define a boolean type. We can pass only two values i.e true or false. It can be represented as T, true, F, false.

# Set type to bool 
a: bool, b: {type: bool}
---

default

The next member of the bool typedef is default. The code snippet shows how to define a default for the bool type. The default values are used during the processing of data/instructions if a value is not provided for a key.

# Boolean a and b with default value set to false
a?: {bool, false}, b?: {bool, default: false}
---

optional

A member can be marked as optional. If optional is set to true. The value of an optional must be boolean type i.e true or false. Here, are some ways the the member of bool type can be marked as optional.

# Boolean a and b set to optional
a?: bool, b?: {bool, optional: true}
---

null

When null is set to true, a member can accept null values. The following snippet shows how to set a member of the bool type to null.

# Set a, b so that it will accept null values  
a*: bool, b*: {bool, null: true }
---

Examples

Here are some valid examples of members with bool type...

# The members accOpen and verified are assign to bool type
accOpen: bool, Verified: {type: bool}

# The exServicemen is of bool type and default value is false
exServicemen: {bool, false}

# The regClose is set to optional and null.
regClose?*: {bool, optional: true, null: true}

Base64

Date and Time

Other

Best Practices

FAQs

Frequently Asked Questions about Internet Object (In no particular order). These are the questions that have been frequently asked after the concept was previewed to the community.

Why do we need another data-interchange format?

As the Greek philosopher, Heraclitus, said: “change is the only constant.”. Internet Object was created to address some of the issues found in JSON which happens to be the most prominent data serialization format today. For more information, please read the story.

Does Internet Object support binary data?

One of the primary objectives of the Internet Object is to be solely a text-based human-readable serialization format. Hence, the current version of Intenet Object natively does not support direct binary data. Binary data may be escaped using the algorithms like Base64 so that it can be passed as a string value.

Can the Internet Object parser parse the JSON object?

JSON support was not one of the objectives of creating the Internet Object. However, the final format turned out to be JSON compatible. So yes, Internet Object understands the JSON format.

Can the Internet Object Schema validate JSON objects?

Yes, Internet Object schema can validate an Internet Object document as well as a JSON object.

When compared with JSON, is Internet Object smaller?

The uncompressed (non-gzipped) IO document is generally 40% smaller. When compared with gzipped versions of JSON and IO documents, we saw unpredicatable results. Sometimes IO document was smaller than JSON, sometimes it was around the same size. On a few occasions, the JSON document was a bit smaller than the IO version.

When compared with JSON, is Internet Object document building and parsing is faster?

Internet Object is a very simple format. It is very easy to build the document just by concatenating the strings! In such cases, it is very fast to build the document. However, in reality, the performance of the parsing depends upon the parser and other factors. A well-written parser will be faster than poorly written parsers.

I would like to contribute. How do I do that?

Great, that you would like to support Internet Object. You can contribute in many ways.

Some of them are...

Join the team that is developing an Internet Object library in your favorite language.
Write a blog or article about the Internet Object
Help friends and colleagues get started with the concept
Help us develop various technical documentations
Be a proofreader and help us correct the specification and document language
Translate the documentation in various languages
Spread the word about Internet Object

Contributors

License

ISC (Internet Systems Consortium) License

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Date and Time

Date and time values in Internet Object

Date and Time values in Internet Object are represented using annotated strings that follow ISO 8601-compatible formats. These provide built-in support for temporal data with automatic parsing to native Date objects during deserialization. Internet Object supports three distinct temporal types: dates, times, and combined date-time values.

Date and time values are scalar values that represent temporal data. The content between the quotes must be valid according to their respective format specifications.

Syntax

dateTimeValue = dateValue | timeValue | dateTimeValue
dateValue     = "d" (singleQuotedDate | doubleQuotedDate)
timeValue     = "t" (singleQuotedTime | doubleQuotedTime)
dateTimeValue = "dt" (singleQuotedDateTime | doubleQuotedDateTime)

singleQuotedDate = "'" dateContent "'"
doubleQuotedDate = '"' dateContent '"'
Date and time values use specific annotation prefixes followed by quoted content:

```ebnf
dateTimeValue = dateValue | timeValue | dateTimeValue
dateValue = "d" (singleQuotedDate | doubleQuotedDate)
timeValue = "t" (singleQuotedTime | doubleQuotedTime)
dateTimeValue = "dt" (singleQuotedDateTime | doubleQuotedDateTime)

singleQuotedDate = "'" dateContent "'"
doubleQuotedDate = '"' dateContent '"'
singleQuotedTime = "'" timeContent "'"
doubleQuotedTime = '"' timeContent '"'
singleQuotedDateTime = "'" dateTimeContent "'"
doubleQuotedDateTime = '"' dateTimeContent '"'

dateContent = yearPart [monthPart [dayPart]]
timeContent = hourPart [minutePart [secondPart [millisecondPart]]]
dateTimeContent = yearPart [monthPart [dayPart]] ["T" hourPart [minutePart [secondPart [millisecondPart]]]] [timeZone]

yearPart = digit4
monthPart = ["-"] (("0" digit1-9) | ("1" ("0" | "1" | "2")))
dayPart = ["-"] (("0" digit1-9) | (("1" | "2") digit0-9) | ("3" ("0" | "1")))
hourPart = [":"] (("0" | "1") digit0-9) | ("2" ("0" | "1" | "2" | "3"))
minutePart = [":"] (("0" | "1" | "2" | "3" | "4" | "5") digit0-9)
secondPart = [":"] (("0" | "1" | "2" | "3" | "4" | "5") digit0-9)
millisecondPart = "." digit3+
timeZone = "Z" | (("+" | "-") hourPart [minutePart])

Structural Characters

The following characters are used to structure date and time values:

Symbol

Name

Unicode

Description

d

Date Prefix

U+0064

Indicates date-only value

t

Time Prefix

U+0074

Indicates time-only value

dt

DateTime Prefix

Indicates combined date-time value

'

Single Quote

U+0027

Encloses temporal content

"

Double Quote

U+0022

Encloses temporal content

-

Hyphen

U+002D

Date separator (optional)

:

Colon

U+003A

Time separator (optional)

.

Period

U+002E

Millisecond separator

T

Letter T

U+0054

Date-time separator

Z

Letter Z

U+005A

UTC timezone designator

+

Plus Sign

U+002B

Positive timezone offset

-

Minus Sign

U+002D

Negative timezone offset

0-9

Digits

U+0030-U+0039

Numeric components

Valid Forms

Date Values (`d'...'`)

Examples of valid date values:

d'2024-03-20'                          # Full date with separators
d'2024-03'                             # Year and month (day defaults to 01)
d'2024'                                # Year only (month and day default to 01)
d'20240320'                            # Full date without separators
d'202403'                              # Year and month without separators
d"2024-12-31"                          # Double quotes supported

Time Values (`t'...'`)

Examples of valid time values:

t'14:30:45.123'                        # Full time with milliseconds
t'14:30:45'                            # Hour, minute, second
t'14:30'                               # Hour and minute (second defaults to 00)
t'14'                                  # Hour only (minute and second default to 00)
t'143045123'                           # Without separators
t'143045'                              # Without separators, no milliseconds
t'1430'                                # Without separators, hour and minute
t"09:00:00"                            # Double quotes supported

DateTime Values (`dt'...'`)

Examples of valid datetime values:

dt'2024-03-20T14:30:45.123Z'           # Full datetime with timezone
dt'2024-03-20T14:30:45.123'            # Full datetime, no timezone
dt'2024-03-20T14:30:45'                # Without milliseconds
dt'2024-03-20T14:30'                   # Without seconds
dt'2024-03-20T14'                      # Without minutes
dt'2024-03-20'                         # Date only (time defaults to 00:00:00.000)
dt'20240320T143045123Z'                # Without separators
dt'2024-03-20T14:30:45+05:30'          # With timezone offset
dt'2024-03-20T14:30:45-08:00'          # Negative timezone offset
dt"2024-12-31T23:59:59.999Z"           # Double quotes supported

Format Specifications

Date Format

With separators: YYYY-MM-DD
Without separators: YYYYMMDD
Partial formats: YYYY-MM, YYYY, YYYYMM
Defaults: Missing month defaults to 01, missing day defaults to 01

Time Format

With separators: HH:mm:ss.SSS
Without separators: HHmmss.SSS
Partial formats: HH:mm:ss, HH:mm, HH
Defaults: Missing components default to 00
24-hour format: Hours range from 00 to 23

DateTime Format

Combined: Date + T + Time + optional timezone
Timezone: Z (UTC) or ±HH:mm or ±HHMM
Partial: Any valid date format + optional time components
Defaults: Missing time defaults to 00:00:00.000, missing timezone defaults to Z

Optional Behaviors

Whitespace: Leading and trailing whitespace around quotes are ignored
Separators: Both separated (2024-03-20) and non-separated (20240320) formats are supported
Partial Values: Missing components are filled with appropriate defaults
Timezone: If no timezone is specified, UTC (Z) is assumed for datetime values
Validation: Parser validates format compliance and logical date/time values
Quote Style: Both single and double quotes are supported

Invalid Forms

Examples of invalid date and time values:

d2024-03-20                            # ✗ Missing quotes
d'2024-13-20'                          # ✗ Invalid month (13)
d'2024-02-30'                          # ✗ Invalid date for February
t'25:00:00'                            # ✗ Invalid hour (25)
t'12:60:00'                            # ✗ Invalid minute (60)
dt'2024-03-20 14:30:00'                # ✗ Missing T separator
dt'2024-03-20T14:30:00+25:00'          # ✗ Invalid timezone offset
d'2024-03-20T14:30:00'                 # ✗ Date prefix with time component
t'2024-03-20T14:30:00'                 # ✗ Time prefix with date component
dt'2024-03-20T14:30:00.123456'         # ✗ More than 3 millisecond digits

Parsing Behavior

When processed by an Internet Object parser:

Date values (d'...') are parsed to Date objects with time set to 00:00:00.000Z
Time values (t'...') are parsed to Date objects with date set to 1900-01-01
DateTime values (dt'...') are parsed to complete Date objects
Missing components are filled with appropriate defaults
Invalid formats result in parsing errors
The parsed Date object maintains the exact temporal representation

Preservation of Structure

Internet Object preserves:

The exact format as written (with or without separators)
The choice of single or double quotes
The specific annotation prefix (d, t, or dt)
The timezone information for datetime values

It does not interpret or enforce:

Calendar-specific constraints beyond basic validity
Leap year calculations during parsing (handled by Date constructor)
Business logic constraints (e.g., working hours, holidays)

Type Conversion

During parsing:

All temporal values are converted to native date/time objects in the target platform
Date-only values have time components set to midnight UTC
Time-only values have date components set to a reference date (typically 1900-01-01)
Timezone information is preserved in the resulting date object
Missing timezone defaults to UTC for datetime values

Timezone Handling

Deserialization (Parsing)

When parsing date-time values from Internet Object format:

DateTime Values (dt'...'):

Explicit UTC (Z): dt'2024-03-20T14:30:45.123Z' → Represents UTC time
Explicit Offset: dt'2024-03-20T14:30:45.123+05:30' → Represents time with specific timezone offset, Indian Standard Time (IST) in this case
No Timezone: dt'2024-03-20T14:30:45.123' → Treated as UTC (default behavior)

Date Values (d'...'):

Always treated as UTC at midnight: d'2024-03-20' → 2024-03-20T00:00:00.000Z
No timezone information is preserved or needed for date-only values

Time Values (t'...'):

No timezone information is applicable for time-only values, will always be treated as UTC.

Serialization (Stringification)

When converting native date/time objects back to Internet Object format:

Date Objects to DateTime (dt'...'):

UTC dates: Serialized with Z suffix → dt'2024-03-20T14:30:45.123Z'
Dates with timezone info: Serialized with appropriate offset → dt'2024-03-20T14:30:45.123+05:30'
Local dates: Should be converted to UTC and serialized with Z suffix

Date Objects to Date (d'...'):

Time components are omitted, timezone is not included → d'2024-03-20'
Always represents the date portion regardless of original timezone

Date Objects to Time (t'...'):

Date components are omitted, timezone is not included → t'14:30:45.123'
Represents the time portion regardless of original timezone

Timezone Behavior Rules

Default Timezone: When no timezone is specified in datetime values, UTC is assumed
Timezone Preservation: Explicit timezone information in datetime values is preserved during round-trip operations
Offset Interpretation: Timezone offsets are interpreted according to ISO 8601 standards
Range Validation: Timezone offsets must be within valid ranges (-12:00 to +14:00)
Format Support: Both ±HH:mm and ±HHMM offset formats are supported during parsing
Serialization Consistency: Serialization should use the ±HH:mm format for timezone offsets

Examples

Parsing Examples:

dt'2024-03-20T14:30:45Z'           # → UTC time: 2024-03-20T14:30:45.000Z
dt'2024-03-20T14:30:45+05:30'      # → UTC equivalent: 2024-03-20T09:00:45.000Z
dt'2024-03-20T14:30:45-08:00'      # → UTC equivalent: 2024-03-20T22:30:45.000Z
dt'2024-03-20T14:30:45'            # → UTC time: 2024-03-20T14:30:45.000Z (default)
d'2024-03-20'                      # → Date: 2024-03-20 (time irrelevant)
t'14:30:45'                        # → Time: 14:30:45.000 (date irrelevant)

Serialization Examples:

# UTC time: 2024-03-20T14:30:45.000Z
→ dt'2024-03-20T14:30:45.000Z'     # DateTime format
→ d'2024-03-20'                    # Date format
→ t'14:30:45'                      # Time format

# Time with offset: 2024-03-20T14:30:45.000+05:30
→ dt'2024-03-20T14:30:45.000+05:30' # DateTime format with offset
→ d'2024-03-20'                     # Date format (timezone ignored)
→ t'14:30:45'                       # Time format (timezone ignored)

Internet Object Schema

Internet Object Schema Specification

Internet Object schemas define the structure (“shape”) of objects in IO documents. Unlike verbose, map-based standards, IO schemas use the same concise object syntax as actual data, making them both human-friendly and machine-tractable.

Philosophy and Motivation

Internet Object schemas are designed for clarity, expressiveness, and minimalism. They avoid the verbosity of traditional schema languages (like JSON Schema or XML Schema) by using the same syntax for both data and schema. This makes it easy for humans to author, read, and maintain schemas, while keeping them fully machine-tractable for validation, tooling, and interoperation with other formats.

Schemas describe:

Field names (and order, if needed)
Types and constraints
Nesting and composition
Optional and dynamic fields (by convention)

Schema Structure and Syntax

Schema as Object Shape

A schema is written using the Internet Object object syntax:

Fields are comma-separated: name, age, address
Each field can be:
- Just a name (defaults to “any” type)
- Typed (name: string)
- Nested (address: { street: string, city: string })
- Constrained (score: {int, min: 0, max: 100})
Fields may be marked as optional or dynamic using conventions (see “Semantic Field Modifiers”).

Examples:

# Minimal schema (all fields are "any" type)
name, age, address

# Typed schema
name: string, age: int, isActive: bool

# Nested schema
address: { street: string, city: string }

# Typed with constraints (MemberDef)
name: {string, maxLen: 100}, age: {int, min: 0, max: 120}

Open and Closed Schema Objects

Top-level schemas may use the open object form (no braces): name, age, address
Nested objects (schemas for nested fields) must use { ... }: address: { street: string, city: string }

Keyed and Positional Fields

Keyed fields: Schema and data map fields by name (name: value).
Unkeyed (positional) fields: Supported for compact, CSV-like data. Recommendation: Use positional mapping only when all fields are required and unambiguous.

Mixed Mode

Unkeyed fields can appear before any keyed fields.
Once a keyed field appears, all remaining fields must be keyed.

Nesting and Reuse

Nested objects: Use { ... } for fields whose value is itself an object.
Reusable schemas: Named with $ in the schema header; referenced as $name.

Example:

~ $address: {street: string, city: string}
~ $user: {name: string, age: int, address: $address}

Syntax Summary Table

Feature

Example Syntax

Description

Field

name

Unkeyed field, type is any

Typed Field

name: string

Keyed field, explicit type

Constraint

age: {int, min: 0, max: 120}

With constraints

Optional

remark?

Field may be omitted

Nullable

address*

Field may be null

Dynamic

*, *: string

Allow extra fields

Nested

address: { street: string, city: string }

Nested object

Reusable

$address

Reference to a named schema

Schema Grammar (EBNF)

schema             = objectEntries
objectEntries      = memberDef *( "," memberDef )
memberDef          = [key] [fieldModifier] [":" typeOrDef]
key                = string
fieldModifier      = "?" | "*" | "?*"
typeOrDef          = type | memberDef | ref
type               = "string" | "int" | "bool" | "object" | "array" | ...
ref                = "$" name

Note: Modifiers and complex memberDefs are conventions, not core grammar.

Field Types and Constraints

Built-in Types

Internet Object supports the following built-in types:

string, int, bool, float, number, object, array, and domain-specific types (date, datetime, etc.)
Types may be extended or customized in a future version by user-defined type systems.

Constraints Reference

min / max / minLen / maxLen: For numbers, strings, arrays.
choices: For enums. Example: {string, choices: [A, B, C]}
pattern: For regex constraints on strings. Example: {string, pattern: "^[a-z]+$"}
default: Assigns a default value if missing.

Semantic Field Modifiers (Conventions)

Internet Object schemas use the following conventions (not syntax) for special field semantics:

Optional: Suffix ? on field name (e.g., age?). Means the field may be omitted in data.
Nullable: Suffix * (e.g., remark*). Means the field can be null.
Dynamic/extra fields: Use * at end (e.g., name, age, * or *: string).
These are interpreted by schema tooling, not by the object parser itself.

Optional and Nullable Field Semantics

Optional (?): Field can be omitted from the data object. If omitted, its value is undefined unless a default is provided.
Nullable (*): Field can explicitly be set to null.
Both (?*): Field can be omitted or set to null.

Examples:

email?: string           # May be omitted
nickname*: string        # May be null
bio?*: string            # May be omitted or null

Dynamic/Extra Fields

* at the end of a schema allows extra fields not specified in the schema.
*: type constrains the type of all extra fields.

Example:

name: string, *,         # Allow any extra fields
*: int                   # All extra fields must be int

Recommendations on Modifiers

For strict validation and best interoperability, avoid * unless required.
For positional schemas, avoid optionals except at the end.

Mapping to Industry Standards (for Interoperability)

Keyed schemas map directly to “properties” in JSON Schema, Avro, etc.
Optionals (?) are omitted from "required" arrays.
Dynamic fields (*) map to additionalProperties.
Constraints map to field-level attributes in target schema (e.g., minLength, enum).

Canonicalization for Tooling

Recommendation: For robust tooling and validation, always canonicalize Internet Object schemas to a fully-keyed, explicit, and type-complete form internally. This enables safe mapping to and from JSON Schema, Avro, or other industry formats.

Mapping Table: IO Schema → JSON Schema

IO Schema

JSON Schema Equivalent

foo: string

{ "foo": { "type": "string" } }

age?: int

{ "age": { "type": "integer" } }, "required": []

*, *: string

additionalProperties: true or { "type": "string" }

{ foo: {string, minLen:2} }

{ "foo": { "type": "string", "minLength": 2 } }

JSON Compatibility

A subset of Internet Object schemas and data are directly compatible with JSON and JSON Schema.
For full compatibility, use quoted keys and JSON-legal values.

Best Practices

Prefer explicit types for all fields in production schemas.
Use fully-keyed schemas for anything beyond trivial/CSV-like records.
Use optionals only at the end if using positional mapping.
Document and canonicalize mixed or dynamic schemas for robust tooling.

Common Schema Patterns

Flat (CSV-like): name, age, score
Typed object: name: string, age: int, score: float
Nested: user: {name: string, address: {city: string}}
Optional/nullable: comment?: string, timestamp*: datetime
Dynamic: *, *: string

Open Object and Array Forms

Internet Object allows you to define fields that can accept any object or any array using open forms:

Any Object: `{}`

Use {} as a schema for a field that may contain any object, regardless of fields or structure.
This matches objects of any shape, including empty objects.

meta: {}         # 'meta' can be any object, equivalent to `meta: object`
payload?: {}     # 'payload' is optional, any object allowed
data: object     # 'data' can also be written as `data: {}` for any object

Any Array: `[]`

extras: []       # 'extras' can be any array. Same as `extras: array`
tags?: []        # 'tags' is optional, any array allowed
choices: array  # 'Can also be written as `choices: []` for any array'

Use [] as a schema for a field that may contain any array, regardless of element type or length.
This matches all arrays, including empty arrays.

extras: []       # 'extras' can be any array
tags?: []        # 'tags' is optional, any array allowed

Why Use Open Forms?

Useful for fields where you expect unstructured, arbitrary data (e.g., “metadata,” “extension,” “blob,” or raw API fields).
No validation is performed on object keys or array elements—only the container type is enforced.

Contrast with Typed Forms

To restrict the allowed content, use typed or constrained schemas:
- [int] for an array of integers
- { name: string } for an object with required fields
- [ { name: string } ] for an array of objects with shape

Syntax

Meaning

{}

Any object (no structure required)

[]

Any array (no type/length required)

[type]

Array of the specified type

[MemberDef]

Array validated by MemberDef

[{...}]

Array of objects with defined shape

Note: These open forms can also be used in MemberDefs for fields that may contain arbitrary objects or arrays.


**Summary:**
- Put this new section right after “Common Schema Patterns” and before your “Full Example.”
- This order introduces specific patterns, then the open (most general) forms, then illustrates usage in a complete example.

## **Full Example**

### **Complete Schema Example with Comments**

```ruby
# User schema
name: string,                # Required
age?: int,                   # Optional
email: {string, pattern:"^[^@]+@[^@]+$"},  # Required, pattern constraint
isActive: bool,              # Required
address?: {                  # Optional nested object
  street: string,
  city: string,
  zip?: int                  # Optional zip code
},
*: string                    # Allow extra string fields

Valid Data:

{
  name: John Doe,
  isActive: T,
  address: {
    street: Bond Street,
    city: New York
  },
  nickname: Johnny
}

Appendix: Object Syntax Reference

(Refer to your object.md for formal object syntax and EBNF.)

Object Syntax EBNF (from Object Spec)

See [object.md] for formal definition; include diagrams or syntax trees as appendix if desired.

FAQ & Clarifications

* and ? are schema conventions—they do not change object syntax.
All schema fields are mapped to data fields using either position (unkeyed) or name (keyed).
For compatibility, always provide a canonical, fully-keyed, fully-typed version of the schema for external tooling.
Can I mix positional and keyed fields? Yes, but only unkeyed fields before any keys. Once a key is present, all subsequent fields must be keyed.
What happens if a required field is missing? Validation fails unless the field is optional (?) or has a default.
Are keys case-sensitive? Yes. "Name" and "name" are distinct.
How are unknown fields handled? If * is present in the schema, unknown fields are accepted (and optionally typed); otherwise, they are rejected by validators.

Versioning and Evolution (Future Section)

Schema evolution, migration, backward compatibility best practices can be addressed in future versions.

String

A string type can be defined with the members such as type, default, choices, pattern, minLen, maxLen, len, optional, and null . Schema of the string TypeDef should be written as,

TypeDef Schema

type?    : {
  string, choices: [string, email, url, datetime, date, time]
  },
default? : string,
choices? : [string]
pattern? : string,
minLen?  : {int, min: 0},
maxLen?  : {int, min: 0},
len?     : {int, min: 0}
optional?: {bool, F}
null?    : {bool, F}

The TypeDef schema ensures the validity of string MemberDefs.

type

The first member of the typedef is type. The string can define with a type string or its derived types i.e email, url, datetime, date, time. Here the next snippet shows, how the string type and its derived types can be defined.

# Defining string type 
a: string, b: {type: string}
---

# Defining string derived types

# Set type to email
a: email, b: {type: email}

# Set type to url
a: url, b: {type: url}

# Set type to datetime
a: datetime, b: {type: datetime}

# Set type to date
a: date, b: {type: date}

# Set type to time
a: time, b: {type: time}
---

default

The second member in the string typedef is default . Here is how the default values can be defined for a string.

# A string with default: Monday
a: {string, default: Monday, optional: T}, 


# A string with a null default
b: {string, default: N, optional: T, null: T}
---

Rules for default:

The default value is applicable only if no other value is provided for the key.
If for a key, null is set to true then it must be replaced by its default value.
The default value when set must match with the data type of a key.

Choices

The next member in the string typedef is choices . If set, the choices must be an array of strings. Here the snippet shows how the choices can be added to member variables in a string so that it is restricted to the fixed set of available choices.

# Add choices for the member 
a: {string,  choices: [abc, "123", "MH4458"]}
---

Pattern

The value of the pattern must be a String. The string value passed should be a valid Regular Expression. The data will be then validated according to the Regular Expression and passed accordingly. Regular Expression can be defined in the schema by using pattern in the schema of a string.

Different versions of schema can be created and executed for patterns in the programming environment. But to remain compatible with the host environment, it is better to stick to the constraints described below.

A single Unicode character, other than the special characters specified below matches itself.
(. U+002E): Matches any character except newline character (U+000A).
(^ U+005E): Matches only at the start of the string.
($ U+0024): Matches only at the end of the string.
(...): Assembles the sequence of regular expressions into a single regular expression.
(| U+007C): Matches the regular expression either preceding or following with the "|" symbol.
[abc]: Matches any of the characters enclosed by the square brackets.
[a-z]: Matches the range of characters enclosed by the square bracket.
[^abc]: Matches any character not in the list.
[^a-z]: Matches any character out of the given range.
(+ U+002B): repeats the preceding regular expression one or more times and is greedy as they match as many items as possible.
(* U+002A): repeats the preceding regular expression zero or more times and greedy as they match as many items as possible.
(? U+003F): makes the preceding regular expression optional. Greedy, matches zero or one preceding regular expression.
+?, *?, ??: The *, +, and ? qualifiers are used to match as much text as possible which is not always desired.
(?!x), (?=x): Negative and positive lookahead.
{x}: Match exactly x occurrences of the preceding regular expression.
{x,y}: Match at least x and at most y occurrences of the preceding regular expression.
{x,}: Match x or more occurrences of the preceding regular expression.
{x}?, {x,y}?, {x,}?: Lazy versions of the above expressions.

# Set pattern for the input string
a: {string, pattern:'^(\+[0-9]{3})?[0-9]{10}$'}
---

maxLen

The value of maxLen must be a non-negative integer. The string instance is valid only if the number of characters in the string will be less than or equal to the value of maxLen. Here is the snippet showing how to assign maxLen.

# Assign maxLen:30 for input string 
a: {string, maxLen: 30}
---

minLen

The value of minLen must be a non-negative integer. The string instance is valid only if the number of characters in the string will be greater than or equal to the value of minLen. Here is the snippet showing how to assign minLen.

# Assign minLen:3 for input string 
a: {string, minLen: 3}
---

len

The value of length represented as len must be a non-negative integer. The string instance is valid only if the number of characters in the string will be equal to the value of len. The code snippet shows how to assign len.

# Assign len: 9 for the input string
a: {string, len: 9}
---

Thelen have the highest precedence over minLen and maxLen constraints. When the len is set, the implementation must ignore minLen and maxLen constraints.

optional

The member of a string type can be set to optional. Here is the code snippet that demonstrates how a string can be set to optional.

# Set a to optional
a?: string 

# Assign optional: true for a 
a?: {string, optional: true}

null

A string when set to null: true will accept null values. The snippet below shows how to set a nullable string.

# Set default value of string to null 
a*: {string, null: true}

Examples

Here are some of the examples that demonstrate how to define string member definition.

# String and its derived types
contactDetails : {string, address: {street: string, 
city: string, state: string, default: New York}, 
emailId: email, websiteUrl: url}
---

#  A name with default value set to anonymous
 name?*: {string, anonymous, ,'[ a-z A-Z]', 5, 50}
---
~       # valid
~ N     # valid
~ John  # valid

In the above snippet, name can be kept optional and null. When no value is passed for the name then, its default value is set to anonymous. The name should be a string containing characters from a to z (upper or lower case) with a minimum length of 5 and a maximum length of 50.

# Add choices for the department
department: {
             type: string, 
             choices: [computer_science, Mechanical,
             Civil, Electrical, Information_Technology]
             }

Here the code snippet shows that the users can only select the department provided in choices i.e input is restricted to the set of available departments.

# Add choices for the location
location: {
           type: string, 
           choices: ["19.020216, 72.853729" ,
           "19.242547, 73.130399" , 
           "28.649840, 77.233848"]
           }

In the above code snippet, users can select the location provided in choices i.e the input is restricted to the set of available locations ( locations are enclosed in double-quotes to pass numeric data as string ).

# Add pattern that will only accept valid mobile number
mobileNumber: {string, pattern:'^(\+[0-9]{3})?[0-9]{10}$'}
---
~ "+915789654123" #valid
~ "5789654123"    #valid
~ "578965412"     #invalid as does not follows specified pattern
~ "915789654123"  #invalid as does not follows specified pattern

# Add pattern that will only accept valid social security no. 
socialSecurityno: {
                   string, 
                 pattern: '^(\[0-9]{3})-\[0-9]{2}-\[0-9]{4}$'
               }
---
~ "123-45-6789" #valid
~ "235-26-0012" #valid
~ "1235-12"     #invalid as does not follows specified pattern
~ "123-12365"   #invalid as does not follows specified pattern
~ "12345678"    #invalid as does not follows specified pattern

# Set maxLen of an input string to 30
name: {string, maxLen: 30}
---
John

# Set minLen of an input string to 3
name: {string, minLen: 3}
---
Lee

# A name with minLen: 5 and maxLen: 20 
name: {string, minLen: 5, maxLen: 20}
---
~ Ethan
~ Albert
~ Alexandra Daddario
~ Leonardo DiCaprio
# following input will not be accepted as minLen is 5
~ Leo 
~ Alex
# following input will not be accepted as maxLen is 20 
~ Venkata Narasimha Raju Vari Peta

# A name with len:9  
name: {string, len: 9}
---
Elisabeth

# Set string to optional
address?: {string, optional: T}
---

# Set string to null
address*: {string, null: T}
---

# Set string to optional and null
address?*: {string, optional: T, null: T}
---
~ Mumbai India
~ New York US
~ N
~ California

Internet Object

Internet Object 1.0

Internet Object

Abstract

The Poetic Principles of Internet Object

Poem

Objectives

Uninfluenced Development

Minimal Footprint

Document Oriented

Reusability

The Structure

Internet Object Document

Internet Object Document Examples

Full Document

Data-only Document

Header-only Document

Document with Multiple Data Sections

Header

Default Schema

Definitions

Structural Elements

Categories

See Also

Literals

Supported Literals

Examples

Rules

See Also

Other Special Characters

Special Character Set

Usage Examples

Variable References and Schema Definitions

Schema Modifiers

Numeric Signs

Character Rules

See Also

Strings

When to Use Each String Type

See also

Regular Strings

Syntax

Structural Characters

Valid Forms

Optional Behaviors

Comments

Invalid Forms

Preservation of Structure

See Also

Raw Strings

Syntax

Structural Characters

Valid Forms

Optional Behaviors

Comments

Invalid Forms

Preservation of Structure

See Also

Numeric Values

Number Types

Number Formats

Type Identification

Special Numeric Values

Type Selection Guide

See Also

Number

Syntax

Structural Characters

Valid Forms

Decimal Base Number

Alternative Bases

Binary Numbers (Base-2)

Octal Numbers (Base-8)

Hexadecimal Numbers (Base-16)

Case Sensitivity

Scientific Notation

Scientific Notation Components

Optional Behaviors

Literal and Alternate Forms

Invalid Forms