> For the complete documentation index, see [llms.txt](https://docs.internetobject.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.internetobject.org/internet-object/why-internet-object.md).

# Why Internet Object?

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 core idea

The same data, in JSON and in IO:

```json
[
  { "name": "John Doe", "age": 30, "email": "john@example.com", "active": true },
  { "name": "Jane Doe", "age": 25, "email": "jane@example.com", "active": false }
]
```

```ruby
~ $schema: { name: string, age: int, email: email, active: bool }
---
~ John Doe, 30, john@example.com, T
~ Jane Doe, 25, jane@example.com, F
```

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.

## How it compares

| Need                                | JSON | CSV | YAML    | Internet Object |
| ----------------------------------- | ---- | --- | ------- | --------------- |
| Human-readable                      | ✓    | ✓   | ✓       | ✓               |
| No repeated keys                    | ✗    | ✓   | ✗       | ✓               |
| Built-in schema & validation        | ✗    | ✗   | ✗       | ✓               |
| Nested / structured data            | ✓    | ✗   | ✓       | ✓               |
| Comments                            | ✗    | ✗   | ✓       | ✓               |
| Streaming of records                | ✗    | ✓   | ✗       | ✓               |
| Precise numerics (bigint, decimal)  | ✗    | ✗   | ✗       | ✓               |
| Dates/times & binary as first-class | ✗    | ✗   | partial | ✓               |

## What you gain

* **Smaller payloads** — keys live in the schema, not in every record.
* **Validation built in** — types and constraints travel with the data; bad values are reported with precise errors.
* **Comments** — annotate documents inline with `#`.
* **Collections & streaming** — emit and consume records one at a time.
* **Richer types** — `int`/`uint`/`decimal`/`bigint`, `date`/`time`/`datetime`, `binary`, and reusable named types.
* **JSON-compatible where it counts** — quoted-key object syntax is accepted, easing migration. See [JSON Compatibility](/interoperability/json-compatibility.md).

## When JSON is still fine

For one-off, schema-less, small payloads — or where ubiquitous tooling matters most — JSON is perfectly adequate. Internet Object pays off when you have **many similar records**, want **validation**, or care about **size and streaming**.

## See Also

* [Getting Started](/internet-object/getting-started.md) · [Objectives](/internet-object/objectives.md)
* [JSON Compatibility](/interoperability/json-compatibility.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.internetobject.org/internet-object/why-internet-object.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.