Data Sections

The data section — section separators, objects, and collections.

The data section is where the actual data of an Internet Object document resides. A document can have one or more data sections, each introduced by a separator line (---) and optionally labelled with a section name and schema. The data itself is either a single object or a collection of objects, giving a flexible yet structured way to represent information. The diagram below shows the shape of a data section.

Structure overview

Section separator line

Each data section begins with a separator line (---) that divides the document into distinct sections. The separator can carry two optional elements:

Section name — identifies the section and its purpose.
Schema name — names the schema that constrains the section, prefixed with $.

Separator line. The separator line MUST end with a newline (\n) or EOF (end of file).

The separator can take several forms, from least to most detailed, each ending with a newline (\n) or EOF:

Without name and schema — the simplest form, just the separator (---).
With section name — the separator followed by a name (--- employee).
With section name and schema — a name and schema name, separated by a colon (--- employee : $employee).
With only schema — the separator followed by just the schema name (--- $employee).

Rules for section names and schemas

What a section name may contain — a section name is a bare name: letters, marks, digits, - and _. It has no quoted form, so unlike a member name it cannot carry a colon, a comma, a space, or any other structural character. See Section names are bare names below.
Omitting the section name — in a multi-section document, the section name may be omitted only once. When omitted, the name is derived from the associated schema (e.g. --- $employee implies the section name employee).
Default section name and schema — if both the name and schema are omitted, the section name defaults to data and the document's default schema is used.
Unique section names — each section MUST have a unique name; duplicate names are not allowed. A document that repeats one is invalid, but a parser still recovers from it: the duplicate is renamed (data → data_2, users → users_2) and the error is reported, so no section is lost. See Duplicate section names.

Section names are bare names

The separator line is read to the end of the line, so a section name has no delimiters to mark where it stops. It is therefore a bare name and the only one in the format that cannot be quoted:

sectionName = ( letter | mark | digit | "-" | "_" )+

This is narrower than a member name, which may be quoted and can then contain anything at all. The asymmetry is deliberate — a member name sits inside a record, where the quotes bound it, whereas a section name sits on a line of its own.

Two obligations follow, one for each side.

A reader MUST reject a name outside that set and report invalid-section-name. It must not accept a prefix and discard the rest: the production is anchored, so --- a,b: $x is an error rather than a section named a, and leading or trailing spaces are not part of the name and are not silently absorbed. Accepting a truncated name would change the data with no diagnostic — the one outcome the format does not tolerate.

Known implementation gap. The reference implementation currently truncates rather than reporting: --- a,b: $x reads the name as a and surfaces only a downstream unexpected-token, and --- lead: $x silently drops the leading space. Tracked as ISSUE-20.

A writer MUST NOT emit a section name it cannot read back. When converting foreign data whose keys fall outside the set — code:en, a,b, a key with a leading space — the multi-section layout is simply unavailable, and the writer MUST fall back to a single section, where those keys become ordinary member names and may be quoted:

# data: { "code:en": […], "a,b": […] }
# WRONG - neither name survives the round trip
--- code:en: $a
--- a,b: $b

# RIGHT - one section; the keys are member names, which may be quoted
--- $schema
{ "code:en": […], "a,b": […] }

See Record & Document Output.

Examples of section separators

Separator line without name and schema

The simplest form. It uses the default section name (data) and the document's default schema.

---
~ John Doe, 25, Male, {Bond Street, New York, NY}, [agile, swift]
~ Jane Doe, 20, Male, {Duke Street, New York, NY}

Separator line with a section name

Here the section name is employee. The schema is the document's default schema.

--- employee
~ John Doe, 25, Male, {Bond Street, New York, NY}, [agile, swift]
~ Jane Doe, 20, Male, {Duke Street, New York, NY}

Separator line with a section name and schema

Here both the name and schema are stated explicitly, as employee and $employee.

--- employee : $employee
~ John Doe, 25, Male, {Bond Street, New York, NY}, [agile, swift]
~ Jane Doe, 20, Male, {Duke Street, New York, NY}

Separator line with only a schema

Here only the schema is named. The section name is derived from the schema name (employee). If that name is already used elsewhere in the document, it is an error.

--- $employee
~ John Doe, 25, Male, {Bond Street, New York, NY}, [agile, swift]
~ Jane Doe, 20, Male, {Duke Street, New York, NY}

Data

After the separator line comes the data. It is either a single object or a collection of objects — the flexibility that lets the format carry many kinds of information efficiently.

Objects

Objects are structured entities composed of key-value pairs. Each object is written within curly braces {} and may contain nested objects or other values, forming a hierarchy.

Collections

Collections are lists of objects, allowing multiple records within one data section. Each object in a collection is written the same way as a standalone object but belongs to the broader collection. See Collection for record syntax, type promotion, and validation rules.

Root values that are not objects

Unlike JSON, a data section may hold a value that is not an object — an array, or a bare scalar. Because a record binds values to names, such a value is promoted into a record under its positional key:

---
[1, 2, 3]                # the record { "0": [1, 2, 3] }

---
42                       # the record { "0": 42 }

The same promotion applies per row in a collection, so ~ [1, 2] is the record { "0": [1, 2] }. A writer converting foreign data MUST use this binding rather than invent a member name, or its output would decode differently from the identical document written by hand — see Record & Document Output.

Examples of data

Single object

A single object can follow the separator directly.

---
John Doe, 25, Male, {Bond Street, New York, NY}, [agile, swift]

A single-section document with no header or schema does not need a separator, so the example above can also be written as:

John Doe, 25, Male, {Bond Street, New York, NY}, [agile, swift]

Collection of objects

A collection lists objects, each prefixed with ~ on its own line:

---
~ John Doe, 25, Male, {Bond Street, New York, NY}, [agile, swift]
~ Jane Doe, 20, Male, {Duke Street, New York, NY}

Empty data section

A data section may be empty — just the separator line with no data.

---

An entirely empty document needs no separator at all.

Multi-section document example

A document can include multiple sections, each with its own data:

--- $library
# Bookville Library
City Central Library, "123 Library St, Bookville"

--- $books
~ The Great Gatsby, "F. Scott Fitzgerald", 1234567890, T, [Fiction, Classic], 1925
~ "1984", George Orwell, 2345678901, F, [Fiction, Dystopian], 1949, { user123, d"2024-02-20"}

--- subscribers: $users
~ user123, John Doe, Standard, [{2345678901, d"2024-01-20"}]
~ user456, Jane Smith, Premium, []

Organized by separators and built from objects and collections, the data section offers a robust, flexible way to carry data — keeping documents clear, consistent, and effective across a wide range of applications.