This is a five-minute tour of Internet Object (IO) using the format itself — no programming language required.

1. A single object

The simplest document is one object. Fields are comma-separated; the header line names them:

name: string, age: int, email: email
---
John Doe, 30, [email protected]

Above the --- is the header (here, the schema); below it is the data. Because the schema fixes the field order, the data is just values — no repeated keys.

2. A schema and a collection

Define the schema once in the header with $schema, then stream many records, each beginning with ~:

~ $schema: { name: string, age: int, email: email, active: bool }
---
~ John Doe, 30, [email protected], T
~ Jane Doe, 25, [email protected], F

T/F are booleans. A collection of records shares one schema — compact and validated.

Fields can carry constraints. Invalid data is reported, not silently accepted:

Define a shape once and reference it with $:

Header keys without a prefix carry document metadata, kept separate from the data:

• — how it compares to JSON and others

• — header and data in depth

• — the schema language

• — records and streaming

Requirement keywords

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174, and only when they appear in all capitals.

They apply to every chapter, not only to Conformance Requirements. Where a chapter states a rule in ordinary prose — "a section name must be unique" — the requirement is the same; the capitals mark where the wording has been made precise, and their absence is not permission.

Normative and informative

Every page carries a status in its front matter:

Where the two disagree, the normative page wins. If you find such a disagreement, it is a defect in this specification, not a choice.

Examples are written in Internet Object and marked ```ruby, whose highlighting happens to suit the format. They are executable: a checker runs every complete example against the reference implementation on each change, so an example that contradicts the text fails the build rather than sitting quietly on the page.

Two annotations carry meaning inside an example:

The cross means an error, never "not the form we are discussing". Where a line is legal but not the construct under discussion, the example says so in words instead — a distinction worth keeping, because most such lines are perfectly good values of some other kind.

A fenced block without a --- separator is a fragment: it illustrates shape and is not executed.

Every reported error carries a stable code. Codes are normative; the messages that accompany them are not, and may be reworded or translated freely. Tooling MUST branch on the code and MUST NOT parse the message.

How codes are named — and the closed vocabulary they draw from — is . The codes themselves are catalogued in .

Two pairs of words are easy to confuse, because each names a different axis:

All four combinations occur, and a document may hold them at once. See the .

The decimal type validates an exact, fixed-precision decimal — for money and other values where binary floating point would lose accuracy. In data it is written with an m suffix: 123.45m.

For the literal syntax, see Decimal values.

TypeDef

A decimal MemberDef accepts only the options below. Any other key is invalid.

Unlike the other numeric types, decimal has no format option — and this is deliberate, not an omission. A format selects among the literals that can express a value, and a decimal has only one: <digits>.<digits>m. Radix notations cannot express a fractional value, and (1.23e2m is invalid). With a single possible spelling there is nothing to select.

The m suffix is always written; without it the output would read back as a plain number.

precision and scale together give SQL-style DECIMAL(precision, scale) validation:

• scale — the number of fractional digits MUST equal scale.

• precision — the total significant digits MUST NOT exceed precision.

With neither precision nor scale, a decimal is compared by its exact value.

Resolution follows the :

• ·

• ·

url is a string shortcut (see String Types) whose value MUST be a valid URL. It shares the string MemberDef and adds URL-format validation.

Quote URL values. A URL contains : and /, which end an unquoted (open) string, so URLs must be written as quoted strings.

website: url
---
~ 'https://example.com'         # ✓
~ "https://example.com/p?q=1"   # ✓
~ 'not a url'                    # ✗ invalid-url

Restrict to a fixed set with choices:

homepage: { url, choices: ['https://a.com', 'https://b.com'] }
---
~ 'https://a.com'    # ✓

See Also

• ·

A conformant processor SHOULD recover from errors and continue, so that a single bad record does not discard the rest of a document.

Syntax-error recovery is bounded by structure

On a syntax error, the parser skips tokens until the next boundary and resumes there. The boundaries are:

• the record separator ~ (start of the next collection item), and

• the section separator --- (start of the next section),

• or end of input.

The malformed middle record is reported as an error; the records before and after it are still parsed.

Each record is validated independently. A validation error in one record does not stop validation of the others (see ).

A processor typically offers options that control recovery and output. Common ones:

• continue-on-error — collect errors and keep going (recommended), versus failing on the first error.

• skip-errors — omit error entries from the loaded result, returning only the records that succeeded.

Option names and exact semantics are implementation-defined; this section describes the behaviors a conformant processor is expected to provide.

When continuing past an error, a processor marks the failed record with an error placeholder in the result so consumers can tell which records succeeded and which did not. See .

• ·

Strings represent sequences of Unicode code points. They carry textual data and preserve whitespace and formatting within their boundaries.

Internet Object supports three string forms, each with its own syntax and use cases:

stringValue = openString | regularString | rawString

All three forms preserve whitespace and Unicode content as written.

• Open string — simple, unstructured text with no leading or trailing whitespace and no structural characters.

• Regular string — text that needs structural characters, leading/trailing whitespace, or escape sequences.

• Raw string — text with many backslashes or quotes (file paths, regular expressions), where escaping would be cumbersome.

• — schemas for strings

• — the numeric forms

• — all value types

A reference (ref) is a $-prefixed definition in the header that names a reusable schema or type. You define it once and refer to it elsewhere as $name. Refs come in two forms:

• Schema reference — names an object shape (a ).

• Type reference — names a single constrained type (a MemberDef), e.g. a percentage.

A null represents the absence of a value — data that is missing, unknown, or intentionally empty. Null is a scalar value with a compact and a verbose form.

A collection is a sequence of records in the data section, each introduced by a tilde ~. You can create one with or without a schema — though a schema is recommended.

Without a schema, each record is parsed on its own and its values are mapped to positional indices. Records may differ in shape:

Define a schema in the header; every record is validated against it. Use a keyed reference (address: $address) to reuse a shape:

Reference a shape with a keyed member (address: $address). A bare $address in the schema is read as a field literally named $address, not as the referenced shape.

Processing an Internet Object document is defined as a pipeline of four stages. Each stage has a clear input and output, so implementations behave consistently.

text ──parse──▶ document tree ──validate──▶ checked tree ──load──▶ values
                                                              ◀─stringify── values

Parse

Input: UTF-8 text. Output: a document tree (header, sections, records, values).

Parsing checks only syntax — that the text is well-formed. It does not consult any schema. Syntax errors are produced here (see Error Model).

Validate

Input: the document tree + a schema. Output: the same tree, with each value checked.

Validation applies the schema: types, constraints (min, maxLen, pattern, choices, …), optionality, and nullability. Validation errors are produced here. With no schema, data is accepted structurally and mapped to positional keys.

An implementation will usually offer two ways in: validating a document read from text, and validating values the host language already holds — an object from an API response, a row from a database.

These are two routes to one stage, not two stages. Validation is defined on the logical value. For the same schema and the same logical value, both routes MUST reach the same outcome: the same accept-or-reject decision, the same error codes, in the same order.

Two values are the same logical value when they hold the same members with the same names and the same typed contents — regardless of spelling. Text ~ Alice, 15 under {name: string, age: int} is the same logical value as the native {name: "Alice", age: 15}, because positional binding is part of reading the text, not part of validating it.

This is worth stating because the two routes are commonly written as separate code, each walking its own kind of input. Nothing forces them to stay in step, and a divergence is close to undetectable from inside a single implementation: each route has its own tests, and both pass. It surfaces only when the same data is sent both ways, or when a second implementation reads the specification and builds one validator — at which point the specification can only describe one of the two behaviors, and every user of the other one is affected.

Testing this. Run the conformance corpus's validation cases through every entry point the implementation offers, asserting both produce the same codes. Sampling a handful of cases is not enough: the routes agree on the common shapes by construction, so the disagreements live in exactly the cases nobody thinks to pick.

Input: the validated tree. Output: in-memory values.

Loading converts checked values into their final representations (numbers, booleans, dates, byte data, nested objects/arrays), applying defaults for omitted fields.

The inverse of the pipeline: in-memory values are serialized back to Internet Object text, honoring schema hints such as a number's format or a string's quote style. A value that is loaded and then stringified SHOULD round-trip to an equivalent document.

Large schemas are built by composing smaller, named pieces. Define a shape once in the header as a $ reference and reuse it wherever it's needed — across fields, arrays, and other schemas.

Reuse a shape across fields

~ $address: { street, city }
~ $schema: { name: string, home: $address, office?: $address }
---
~ John, { Main St, NYC }, { 5th Ave, NYC }
~ Jane, { Oak Ave, LA }

Compose schemas from other schemas

A reference can be used inside another reference, building larger shapes from smaller ones:

~ $address: { street, city }
~ $person: { name: string, address: $address }
~ $schema: { lead: $person, members: [$person] }
---
~ { Ann, { Main St, NYC } }, [{ Bob, { Oak Ave, LA } }, { Cy, { 5th Ave, NYC } }]

Here members is an array whose element type is the $person schema.

Set the default schema by reference

$schema may itself be a reference:

~ $address: { street, city }
~ $person: { name: string, home: $address }
~ $schema: $person
---
~ John, { Main St, NYC }

Guidance

• For readability, define a shape before you reference it. Order within the header is not significant — references resolve after the whole header is read (see ).

• Reuse keeps documents consistent and small; change a shape once, everywhere updates.

• ·

Streaming is Internet Object consumed incrementally. A producer frames records onto a byte or text stream, and a consumer reads them back one logical record at a time as the bytes arrive — without waiting for the whole document. It is not a separate format or a second parser: it is the same data model, the same grammar, and the same validation, delivered over time.

Streaming is part of the format, not an add-on. It adds only three things — framing, transport coordination, and an emission envelope around each record. It defines no new type, no new validation rule, and no new serialization behavior. Those all come from the core specification, unchanged.

This chapter is the language-neutral, normative contract for Internet Object streaming. It governs every implementation in every language and on every platform. It uses the requirement keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY as defined in RFC 2119 and RFC 8174. A conformant implementation satisfies every MUST and MUST NOT.

Streaming is an incremental, record-oriented transport. A producer frames Internet Object records onto a stream; a consumer reads them back one logical record at a time as bytes arrive.

The bool type validates a boolean value. In data it is written compactly as T/F or verbosely as true/false.

For the boolean value syntax, see .

A bool MemberDef accepts only the options below. Any other key is invalid.

Internet Object is a text-based, schema-first data format for interchange over the internet. It keeps JSON's readability while removing its biggest costs: repeated keys, no schema, no comments, and no native streaming.

The same data, in JSON and in IO:

The keys are stated once in the schema, so each record carries only its values. For collections of similar objects this is dramatically smaller — closer to CSV's density, but with types, nesting, and validation.

Internet Object is case-sensitive throughout. Keys, keywords, and type names MUST be written with exact casing.

Member keys are distinct by case — Name and name are two different fields:

The literal keywords MUST be written exactly as defined. Their accepted forms are:

This section states the duties of a conformant implementation. Internet Object is language-independent; these requirements describe behavior, not any particular API.

Requirement keywords are defined once, for the whole specification, in Conventions — they are not local to this page, and a rule stated in ordinary prose elsewhere is no weaker for it.

All implementations

• MUST accept input encoded as UTF-8.

• MUST treat the format as case-sensitive (keys, keywords, type names).

• MUST recognize the structural characters and keywords exactly as defined.

• MUST report every error with a code from the registry in , named by the rule in , together with the position in the source. An implementation MUST NOT invent a code, assemble one at runtime, or report an error without one.

• MUST NOT accept a prefix of a malformed construct and discard the remainder — a truncated value that parses is worse than a rejected one, because nothing reports it.

• MUST build a document tree according to the .

• SHOULD recover from a syntax error by skipping to the next boundary (~ or ---) and continuing, rather than aborting the whole document.

• MUST validate data against the schema: types, constraints, optionality, nullability.

• MUST recognize the closed set of built-in types and their allowed options (each type's ).

• MUST reject a value that violates its type or constraints, distinguishing a type failure from a constraint failure as defines.

• MUST validate each record independently; one invalid record MUST NOT invalidate others.

• MUST produce output that re-parses to equivalent data, and MUST produce output that parses without error — see .

• MUST preserve each value's type, not merely its printed form, and MUST quote any string or key that would otherwise read back differently — see .

• MUST write a member's name whenever no schema in scope can recover it, and MUST NOT repeat a name a schema already carries — see .

The section is normative for all of the above.

• The specification carries its own version (currently 1.0 Draft).

• Implementations carry their own versions independently and SHOULD declare which specification version they conform to (e.g. "implements Internet Object 1.0").

The official TypeScript/JavaScript implementation, , serves as a reference implementation. Where this specification and an implementation disagree during the draft period, the discrepancy is tracked and resolved case by case; the specification is the intended source of truth as it stabilizes.

• — requirement keywords, and how examples are marked

• ·

• ·

Definitions are resolved after the entire header has been read, and references are checked again as data is validated. Two errors are specific to definitions:

Error codes are stable; messages and positions may vary between implementations. Branch on the code, not the message.

A $ reference must name a schema or type defined in the header. An undefined name fails with undefined-schema:

A @ reference must name a variable defined in the header. An undefined name fails with undefined-variable:

Because definitions resolve only after the whole header is read, order within the header is not significant — a reference MAY appear before the definition it targets. The following resolves even though $address is defined after the schema that uses it:

For readability you SHOULD still define a reference before you use it; doing so reads top to bottom and makes the dependency obvious.

• · ·

• — the full error catalogue

A schema is written in the same object syntax as data. This page covers how to write one and how a document's data is mapped to it. For the building blocks of a schema, see the ; for types and constraints, see and .

"Open" and "closed" here describe braces, not behaviour: an open object is written without them, a closed one with them. Whether a schema accepts undeclared fields is a separate question, and this specification calls that strict or extensible — see .

A top-level schema may be written in open form, without surrounding braces:

A nested object member must be enclosed in braces, because the braces are what mark the value as an object:

A member with no type defaults to any, so name, age, address is shorthand for three

When a field must accept values of more than one type, use the anyOf constraint on the any type (see ). A value is valid if it matches any one of the listed alternatives.

A value matching none of the alternatives is rejected:

Each alternative may be a full MemberDef (with constraints) or an object shape, not just a bare type name:

• Order alternatives from most specific to least specific.

A Decimal is a fixed-precision decimal value for cases that demand exact numbers — especially financial calculations, where floating-point approximation can introduce errors. A Decimal stores an exact value with a defined precision and scale.

Unlike a standard floating-point Number, a Decimal does not approximate: 0.1m is exactly one-tenth, not the nearest binary fraction.

Syntax

A Decimal is written as a number with the m suffix. It requires a leading digit and, if a decimal point is present, at least one digit after it. Scientific notation is not supported.

decimal = ["-" | "+"] digit+ [ "." digit+ ] "m"

digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

Structural characters

• 123.45m — fractional decimal

• 123m — integer decimal

• 0.001m — leading zeros preserved

Each Decimal carries a precision (the total number of significant digits) and a scale (the number of digits after the decimal point):

A schema can constrain these; see .

A Decimal requires a leading digit and, with a decimal point, a trailing digit. Scientific notation is rejected:

A doubled suffix is not an error. 123.45mm is an , by the same rule that makes 12mm one: nothing in it announced a decimal, because the m that would have done so is followed by more text. See .

A plain 123.45 (no m) is a valid Number, not a Decimal — the m suffix is what selects fixed precision.

Internet Object preserves:

• Exact decimal precision and scale

• Syntactic fidelity as written, except that an explicit + sign is not preserved

It does not interpret:

• Rounding behavior for operations

• Currency or unit semantics

Those semantics belong to the schema, the validator, or the application.

• — all numeric forms

• — standard floating-point numbers

• — arbitrary-precision integers

A reader emits a sequence of stream items, in wire order. Each item corresponds to exactly one logical data record and is exactly one of two kinds: a record (success) or a record-error (recoverable failure). This page defines that abstract model. The concrete representation — object shape, field names, a sum type, an iterator of results — is chosen by each platform, but every implementation MUST preserve the model described here.

Two kinds, never more. Implementations MUST NOT introduce additional item kinds in v1. The discriminant names the protocol event — record versus record-error — not the type of the payload. New metadata MAY be added only as optional, additive fields that do not change the meaning of the fields below.

A record item represents one successfully parsed and validated record. It carries:

Rather than stopping at the first problem, a conformant processor accumulates errors and returns them together, alongside whatever data parsed successfully. This gives authors a full picture in one pass.

Each record is validated independently and may contribute zero, one, or many errors. A failing record is marked as an error; the others are unaffected:

The result contains two valid records and one error entry — not a single fatal failure.

Syntax errors are accumulated per recovered region (between boundaries). One unparsable record yields one error, and parsing resumes at the next ~ or ---.

Because errors are accumulated rather than thrown, the loaded result includes the records that succeeded. Consumers can render valid data and surface the error list side by side (for example, editor markers at each error's position).

When two sections share a name, the duplicate is automatically renamed

A syntax error is a problem in the shape of the text — an unbalanced brace, a missing comma, an unterminated string — detected while tokenizing or parsing, before any schema validation. (Errors about values — wrong type, out of range — are validation errors; see .)

The unclosed { raises expected-closing-bracket. (The predicate unterminated- is reserved for constructs the tokenizer closes, such as a quoted string; a bracket is closed by the parser.)

Values are comma-separated. Where a comma is omitted between two values, the text between them is a single , and an open string may contain spaces — so the result is one well-formed value, and there is nothing for a parser to reject:

A conformant parser MUST NOT report an error here, and MUST NOT

Because a collection is a sequence of independent records, it is naturally streamable: a producer can emit records over time and a consumer can process each as it arrives, without waiting for the whole document.

Further records for the same collection can be sent later in additional batches; a processor merges them into the same collection. Each record is validated on its own, so a malformed record does not interrupt the stream.

The full protocol lives in its own chapter. Framing, the stream-item model, schema and state, the error model, and reader and writer obligations are specified normatively in the chapter. This page only shows why a collection is streamable; the contract is there.

• — the normative, platform-agnostic streaming protocol

email is a string shortcut (see ) whose value MUST be a valid email address. It shares the string (choices, pattern, minLen, …) and adds email-format validation.

Restrict to a fixed set with choices:

Internet Object is a data interchange format designed for modern web communication over the internet. This specification introduces Internet Object as a text-based, schema-first, document-oriented, and streamable format that prioritizes human readability and language independence. By separating the schema from the data, it serializes structured data compactly for efficient transmission between servers and clients across the web, while preserving the clarity and approachability of a plain-text format.

• — a guided walkthrough

• ·

Data is the substance of the Internet, and we still move it wastefully.

JSON proved that humans must be able to read their data — and then it stayed wasteful, lossy, and schemaless by default. The binary formats proved that the wire must be small — and then they made data unreadable and forked their schemas into a separate toolchain. Both were half-right. We accepted the choice between them for twenty years. We don't have to anymore.

Internet Object begins from a refusal: we will not choose between readable and efficient, between expressive and exact, between human and machine. A format for the Internet must serve all of them, at the scale the Internet actually runs.

These are the convictions it is built on.

1. The wire is not free. A format used everywhere, constantly, has no right to be wasteful. Every key repeated on every record is bytes paid for again and again — in storage, in bandwidth, in energy, in latency. We declare structure once and never repeat it.

2. Structure is not data. Keys, types, and constraints belong to the schema. A record carries only its values. Conflating the two was the inherited mistake; separating them is what makes data compact, validated, and self-describing all at once.

Records without a schema

If no schema is defined, each record may have a different shape, and values are mapped to positional indices (0, 1, 2, …):

---
~ John Doe, 20, female
~ true, false
~ marketing, 123, { Z Street, Los Angeles, CA }

The first record loads as { "0": "John Doe", "1": 20, "2": "female" }, and so on.

It is good practice to define a schema even though collections allow schema-less records.

Empty records

A record consisting of just ~ is an empty object ({}). It is valid only if every field in the schema is optional and/or nullable:

If any field is required, an empty record fails:

Each record is validated independently. A failing record is marked as an error; the rest are unaffected:

A conformant processor SHOULD collect per-record errors and continue, rather than stopping at the first failure.

• ·

Turning Internet Object text into validated data happens in stages:

1. Tokenize — split the text into tokens (values, separators, structural characters).

2. Parse — assemble tokens into a document tree (header, sections, records, values).

3. Validate — check the data against the schema.

4. Load — produce the final in-memory values.

Errors fall into two classes, matching the stages that produce them:

The distinction matters because the two classes recover differently:

• Syntax errors are bounded by structure — the parser skips to the next boundary (~ or ---) and continues.

• Validation errors are bounded by the object — each record is validated on its own and may report zero, one, or many errors, without affecting other records.

Whichever class it belongs to, every error reports the same three things: a stable code, a human-readable message, and the position in the source. Only the code is part of this specification — messages may be reworded or translated — so tooling branches on the code.

• — how every code is named, and the closed vocabulary it draws from

• — the catalogue of codes, by class

• — how recovery works; processing options

• — collecting many errors and partial output

The Internet Object format uses a small set of structural characters, literals, and other special characters to structure and delimit data. Working together with objects, strings, arrays, numbers, and whitespace, these elements compose the format's grammar and let documents express complex, flexible data structures.

Categories

• Structural Characters & Separators — core syntax characters that organize data

• Literals — predefined constant values (booleans, null, special numbers)

• — functional modifiers for variables, schemas, and values

• — recognized Unicode whitespace and its handling

• — data types and how values are written

• — comment syntax and usage

• — character encoding and Unicode support

Besides the schema, an Internet Object document's header can hold definitions. A definition is a key–value pair on its own line, introduced by a tilde ~:

There are three kinds of definition, distinguished by the key's prefix:

Temporal values are written as annotated strings in ISO 8601-compatible formats, with a prefix that selects the kind: d for a date, t for a time, and dt for a combined date-time. A parser converts them to native date/time objects on deserialization.

The content between the quotes must be valid for its kind.

Syntax

temporalValue = dateValue | timeValue | dateTimeValue
dateValue     = "d"  ("'" dateContent "'"     | '"' dateContent '"')
timeValue     = "t"  ("'" timeContent "'"     | '"' timeContent '"')
dateTimeValue = "dt" ("'" dateTimeContent "'" | '"' dateTimeContent '"')

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

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

Structural characters

Hours use the 24-hour clock (00–23). A date-only value is treated as UTC midnight; a time-only value uses a reference date and is treated as UTC.

Out-of-range or malformed temporals produce the stable error code invalid-datetime:

• Explicit UTC — dt'2024-03-20T14:30:45Z' is UTC.

• Explicit offset — dt'2024-03-20T14:30:45+05:30' carries that offset; its UTC equivalent is 2024-03-20T09:00:45Z.

• No timezone — a date-time with no zone is treated as UTC.

The reference implementation has known gaps in temporal parsing; a conformant parser SHOULD behave as specified above, not as the current implementation does:

• Overflow dates are normalized rather than rejected: d'2024-02-30' becomes 2024-03-01 instead of raising invalid-datetime.

• Over-long fractions are truncated: a millisecond field with more than three digits is truncated to three rather than rejected.

• — all value types

• — the numeric forms

• — date/time schemas

A TypeDef is the fixed option contract for a built-in type. It defines exactly which options a MemberDef of that type may use, the order of its positional values, and the type of each option. A TypeDef is itself written in Internet Object object syntax, so the same rules that apply to objects apply to it.

TypeDef vs. MemberDef. A TypeDef is the spec-defined contract for a type; a MemberDef is what a schema author writes for one member. Every MemberDef is validated against the TypeDef of its declared type.

Positional and keyed options

A TypeDef fixes the meaning of each positional value. For every type the order is:

1. type — the type name (number, int16, string, …)

2. default — the value used when the member is omitted

3. choices — the allowed set of values

Any further options are written as keyed entries (min: 0, pattern: …) in any order after the positional ones. So all of these are valid number MemberDefs:

A TypeDef written out looks like an ordinary object whose members are the options (most of them optional). Illustratively, the number TypeDef is shaped like this:

Each type page lists its own TypeDef in full; that table is the authoritative source of the options a type accepts. optional and null are the two every type defines — usually written with the ? / * shorthand on the member name, and as keyed options when the name is quoted (see ). The null key is written quoted, since a bare null is the null keyword.

A MemberDef may use only the options its type's TypeDef defines. An unknown option is rejected with unknown-member:

This is what makes options portable: because the contract is fixed, the same MemberDef validates identically in every conformant implementation.

An option is either a constraint (it can reject a value) or a presentation option (it only selects how a value is written, and never rejects anything). Which is which is fixed per option, not per implementation — see .

A schema author cannot change or extend a built-in type's TypeDef — the option set is defined by this specification. To build a reusable, document-local type (a base type plus preset constraints), define a type reference in the header instead; see .

• — how authors write a member's type and constraints

• — every type's TypeDef table

• · — example TypeDefs

The binary type validates a sequence of bytes. In data, binary is written as a base64 literal with a b prefix: b'SGVsbG8='. (Base64 is the encoding; binary is the type.)

For the literal value syntax, see Binary values.

TypeDef

A binary MemberDef accepts the options below.

Binary is under development. The binary schema type is being added to the reference implementation (it is not yet registered), and the b'…' value literal is not yet accepted by the parser. The design above is the agreed target; examples are not yet executable and are excluded from the example verifier.

• ·

Internet Object is a text-based, schema-first, document-oriented data interchange format — JSON's readability without its repeated keys, missing schema, absent comments, or lack of streaming. This site is the official specification and serves as the format's reference documentation.

Status. This is the 1.0 Draft of the specification, published alongside the public beta of the reference implementation. The specification and the implementation are still converging, so some pages note behavior that is ahead of the current implementation. Implementations version independently and declare the specification version they conform to.

Start here

• Manifesto — the convictions behind the format, and why it exists

• — how it compares to JSON, CSV, and YAML

• — a five-minute tour in pure Internet Object

• — the structure of a document

• — types, constraints, and validation

• — what a conformant implementation must do

The header sits at the beginning of an Internet Object document and defines the schema and definitions for the data that follows. It carries the metadata, context, variables, and schema references needed to interpret the data consistently. By stating this information once, up front, the header keeps the data section compact and unambiguous.

A schema defines the structure and meaning of the data in a document. When the header contains only a schema — with no other definitions — that schema is the document's default schema. It describes the shape of the data while keeping the structure separate from the data itself, which makes the data more compact and easier to process.

This header declares five members:

1. name — an untyped member, typically a string.

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 Internet Object began as a side project aimed at addressing limitations observed in the JSON format. Over time, it evolved into an independent research endeavor focused on tackling data-transfer challenges such as size, schema validation, data streaming, header and metadata support, and more. The design of the Internet Object format revolves around the following key objectives:

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

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

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

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

Embracing a comprehensive document-oriented approach, the Internet Object format SHOULD facilitate the bundling of essential components—including records, data, definitions, schemas, and comments—within a single document. This approach helps keep related information together, improving organization and maintainability.

This poem distils the foundational principles of Internet Object into a few memorable verses. It is an informative companion to the specification: the lines below restate, in artistic form, the design values explained throughout these pages — small size, readability, the separation of data and definitions, the independence of records, and a healthy distrust of unvalidated input.

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.

A raw string is a sequence of Unicode code points prefixed with a lower-case r and enclosed in single quotes (', U+0027) or double quotes (", U+0022). Raw strings suit text with many backslashes, quotes, or structural characters — file paths or regular expressions, for example. They process no escape sequences except the enclosing quote, which is written by doubling it 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 a lower-case r and enclosed in single or double quotes. The prefix is case-sensitive, like everything else in Internet Object: R'...' is not a raw string, and reports unknown-annotation. The same holds for every annotation prefix — b, d, t, dt. The only special rule is that the enclosing quote, when it appears inside the string, must be written as two consecutive enclosing quotes.

Backslash is literal. The reverse solidus (\, U+005C) is always a literal character in a raw string — there is no backslash escaping.

Examples of valid raw strings:

• Whitespace — leading, trailing, and internal whitespace are preserved.

• No escaping — no escape sequences are processed except doubling the enclosing quote.

• Multiline — newline and carriage-return characters are preserved.

Comments are not allowed inside raw strings, but may appear outside or between values, per the format's comment rules.

To hold a quote of the same kind, double it: r'Jonas D''costa' and r"He said, ""Hello!""".

Without quotes there is no annotation, so nothing marks the text as raw. That is not an error; it is simply read by the ordinary rules — here as a keyed member, because of the colon:

Internet Object preserves:

• All Unicode code points and whitespace as written

• The doubled-quote convention for an embedded enclosing quote

It does not interpret or enforce:

• Application-specific constraints

• Any escaping beyond doubled enclosing quotes

• — the three string forms

• — the unquoted form

• — quoted strings with escaping

A binary value is a sequence of raw bytes carried as text. It is written as a Base64 byte string: the prefix b followed by Base64 content in single or double quotes. Binary values suit images, encrypted content, cryptographic keys, or any arbitrary byte sequence in an otherwise text-based document.

The content between the quotes is Base64 per RFC 4648. Base64 is the encoding; binary is the value type.

Implementation status (beta). Binary literals are not yet available in the reference implementation: b'…' and b"…" currently raise a syntax error (unexpected-token), and no binary schema type is registered. This page documents the intended design; the examples below are illustrative and are not yet executable. Track progress in the .

A binary value is prefixed with b and enclosed in single or double quotes; the content must be valid Base64.

Without quotes there is no annotation at all, so nothing announces a binary literal and the text is an ordinary :

• Whitespace — leading and trailing whitespace around the quotes is ignored; whitespace inside the Base64 content is not allowed.

• Prefix case — the prefix MUST be lower-case b; the Base64 content is case-sensitive.

• Padding — standard = padding is required for correct decoding.

Internet Object does not interpret the structure of the decoded bytes — any format, compression, or application meaning is the application's concern.

• — all value types

• — the binary schema type

• — text values (open, regular, raw)

The Internet Object format uses UTF-8 as its default and mandatory encoding for all text. This ensures reliable interchange across platforms, systems, and programming languages.

UTF-8 requirement

Every conformant implementation MUST support UTF-8. UTF-8 is chosen because it is:

• Universal — supported by virtually all modern systems and languages.

• ASCII-compatible — the ASCII range (0–127) is encoded identically.

• Complete — it can represent every Unicode character.

• Byte-order independent — no endianness concerns, unlike UTF-16 or UTF-32.

• Self-synchronizing — corruption of one character does not derail later parsing.

UTF-8 is mandatory; an implementation MAY additionally support other encodings for specific needs.

UTF-8 is the baseline. If another encoding fits your situation, convert to or from UTF-8 at the boundary. Because UTF-8 is the only mandatory encoding, every parser and serializer must handle it.

Internet Object supports the full Unicode character set through UTF-8:

• Basic Multilingual Plane — U+0000 to U+FFFF.

• Supplementary planes — U+10000 to U+10FFFF.

• Control characters — handled per the Unicode standard; in strings they should be escaped.

For normalization, NFC (Normalization Form Canonical Composed) is the recommended form. An implementation should normalize consistently when comparing strings; the internal storage form is unconstrained.

• A UTF-8 BOM is the byte sequence EF BB BF (U+FEFF) at the start of a document.

• A parser treats a leading BOM as whitespace and ignores it, so a BOM never causes a parse error.

• A BOM is optional and not recommended for UTF-8; if you use one, do so consistently.

All common line-ending conventions are accepted and treated equivalently:

• Unix/Linux — LF (\n)

• Windows — CRLF (\r\n)

• Classic Mac — CR (\r)

Mixed line endings within one document are handled gracefully.

A conformant parser SHOULD:

1. Accept UTF-8 input and skip a leading BOM if present.

2. Report a clear error for invalid UTF-8 byte sequences and reject overlong encodings.

3. Handle UTF-16 surrogate pairs correctly when decoding \u escape sequences.

A conformant serializer SHOULD:

1. Always emit valid UTF-8.

2. Be consistent about including or omitting a BOM for the target system.

3. Emit escape sequences for control characters where needed.

• — recognized whitespace characters

• — string representation and escaping

• — comment syntax and Unicode support

A boolean is a logical value, either true or false. Booleans are scalar values used for flags, binary states, and conditions.

Each value has a compact and a verbose form, letting you trade brevity for explicitness.

Syntax

boolean        = compactBoolean | verboseBoolean
compactBoolean = "T" | "F"
verboseBoolean = "true" | "false"

Structural elements

The compact and verbose forms are equivalent; the compact form is recommended for terse data.

Boolean keywords are case-sensitive and spelled exactly. Any other token is not an error — it is parsed as a different value type, so it is not a boolean:

Under a bool schema, a non-boolean value fails validation with expected-boolean. Without a schema, the values above are simply kept as their parsed type (string or number).

• — all value types

• — the absence of a value

• — the boolean schema type

A value variable is a reusable value defined in the header with an @-prefixed key and used anywhere a value is expected by writing @name. Variables reduce repetition, shrink payloads, and let you keep sensitive values in one place.

@ is for values. For reusable schemas and types, use $ references — see Schema References.

Defining and using

~ @active: T
~ $schema: { name: string, isActive: bool }
---
~ John, @active
~ Jane, @active

In schema constraints

A variable can supply a constraint value, such as a choices list:

~ @r: red
~ @g: green
~ @b: blue
~ $schema: { name: string, color: { string, choices: [@r, @g, @b] } }
---
~ John, red

Use cases

Reduce size and repetition

Define a value once and reference it many times:

Variables let you isolate secrets/keys in the header instead of scattering them through the data:

• ·

This page records notable changes to the specification, newest first, once versioned releases begin. Implementations (such as io-js2) version independently under their own SemVer and declare which specification version they conform to.

1.0 Draft — in progress

The specification is in its 1.0 Draft: it is still being authored, most features are at Candidate maturity, and it may change without a version bump until 1.0 is finalized.

There are no released versions yet — the first entry here will be 1.0, recorded when the draft is finalized. Until then:

• for the current maturity of each feature, see Feature Status;

• for how versions and stability work, see the ;

• for planned direction, see the .

• · ·

Internet Object is a document-oriented format built on a clear separation between a header and data. This mirrors how HTTP and MIME keep headers apart from the message body: the header describes the payload, and the data carries it.

The header is optional and, when present, holds schemas and definitions. The data section begins with the --- separator. That separator is the boundary between the two parts: when a header is present, --- is required to mark where it ends and the data begins.

Document shapes

A document can take one of a few shapes depending on whether it carries a header, data, or both.

Full document

A document with both a header and a data section is a full document. The header declares the schema; the data conforms to it.

name, age: int, address: {street, city, state}, active
---
John Doe, 25, {Bond Street, New York, NY}, T

Data-only document

When the schema is not needed — or is already known to the recipient — a document can carry data alone. With a single object, the leading --- is optional:

A collection of records can be written without a separator at all; each record begins with ~:

Sometimes a request yields no rows — for example, a query that returns result metadata but an empty result set. The header carries the metadata, and the --- separator marks an empty data section:

A single document can hold multiple data sections, letting related datasets travel together. Each section starts with its own --- separator and names the schema it uses:

• — schemas, definitions, and metadata

• — separators, objects, and collections

• — why the split exists

The streaming wire format is the existing Internet Object document grammar, consumed incrementally. The markers ~, ---, and the header-definition grammar are core constructs; streaming reuses them as its framing layer and does not define them. This page specifies the framing obligations of a streamed document — what a producer must put on the wire and what a consumer may rely on — not the grammar itself. For what the markers mean, see and .

Chunk boundaries are not semantic. Transport may split or coalesce the byte stream however it likes. Splitting or coalescing chunks MUST NOT change the records a reader emits. Framing is determined by the markers below, never by where a packet happens to end.

~ is the only normative data-record marker. A writer MUST frame every logical data record with ~

An array is an ordered collection of values enclosed in square brackets. Arrays are containers used to express lists, sequences, and multi-dimensional tabular structures.

Each value in an array may be:

• A scalar (string, number, boolean, null), or

• A structured value (an object or another array).

Arrays are syntactically compact, support nesting, and avoid ambiguity by requiring every value to be present — trailing and elided elements are not allowed.

An array begins with

Internet Object (IO) is a document-oriented data serialization format designed to optimize data transmission over networks. This specification introduces IO as an alternative to existing formats such as JSON, offering a structured approach to data representation and exchange.

The fundamental structure of IO is an ordered collection of values, analogous to CSV (Comma-Separated Values) but with extended capabilities. These capabilities include support for nested objects, arrays, and inline keys, providing enhanced expressiveness and flexibility.

• Document-oriented design: In contrast to value-oriented formats, IO adopts a document-centric approach, facilitating the separation of data from definitions to enhance clarity and maintainability.

• Ordered collection with extended functionality: IO's core structure maintains an ordered collection of values while supporting complex data structures such as nested objects and arrays.

Internet Object supports single-line comments for documenting and annotating data. A comment starts with a hash sign (#) and runs to the end of the line.

• Start character — the hash sign (#, U+0023).

• Scope — a single line only.