> 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/schema-definition-language/data-types/object.md).

# Object (SchemaDef)

The **`object`** type validates structured key/value data. Like an array, it is a **container**: you declare its **shape** — the set of fields and their types. That shape is called a **SchemaDef**.

> For the object *value* syntax (`{ … }`), see [Objects](/structure-and-syntax/values/object.md).

## Declaring the shape (SchemaDef)

```ruby
addr: { street: string, city: string }   # inline SchemaDef
meta: {}                                  # any object (no fixed shape)
meta: object                              # same as {}
home: $address                            # a referenced SchemaDef
```

A field may itself be any type, nested object, array, or [reference](/definitions/schema-references.md).

```ruby
name: string, location: { x: int, y: int }
---
~ John, { 1, 2 }            # ✓ location = { x: 1, y: 2 }
~ John, { 1, two }          # ✗ invalid-type (y is not an int)
```

> In a record with several fields, write nested objects in the open positional form (`~ John, { 1, 2 }`). A record written wholly as `{ … }` maps its values to the *record's* fields, not to one field's object.

## TypeDef

An `object` MemberDef accepts only the options below.

| Option     | Type      | Description                                                   |
| ---------- | --------- | ------------------------------------------------------------- |
| `type`     | string    | The type name `object`.                                       |
| `default`  | object    | Value used when the member is omitted.                        |
| `schema`   | SchemaDef | The object's shape. Usually written inline (`{ … }`) instead. |
| `optional` | bool      | If `true`, the member may be omitted. Shorthand: `?` suffix.  |
| `null`     | bool      | If `true`, the member may be `null`. Shorthand: `*` suffix.   |

## Nesting

Objects nest to any depth:

```ruby
~ $address: { street: string, city: string }
~ $schema: { name: string, home: $address }
---
~ John, { Main St, NYC }     # ✓
```

## Open and dynamic objects

An empty SchemaDef (`{}` or `object`) accepts any object. To allow **extra** fields beyond those declared, add `*` to the shape — see [Open & Dynamic Schemas](/schema-definition-language/advanced-schema-concepts/dynamic-schema.md):

```ruby
~ $schema: { name: string, * }
---
~ John, extra1, extra2       # ✓ extra fields accepted
```

## Optional, nullable & defaults

```ruby
~ $address: { street: string, city: string }
~ $schema: { name: string, home?*: $address }
---
~ John, { Main St, NYC }     # ✓
~ Jane, N                    # ✓ home is null
```

| Input                   | Result                                  |
| ----------------------- | --------------------------------------- |
| valid object            | the object                              |
| field fails its type    | the field's error (e.g. `invalid-type`) |
| `N`, nullable (`*`)     | `null`                                  |
| `N`, not nullable       | `null-not-allowed` error                |
| omitted, optional (`?`) | absent                                  |
| omitted, required       | `value-required` error                  |

## Implementation status (beta)

* Keyed `null:` is not yet honored — use the `*` suffix.

## See Also

* [Objects (value syntax)](/structure-and-syntax/values/object.md)
* [Open & Dynamic Schemas](/schema-definition-language/advanced-schema-concepts/dynamic-schema.md) · [Schema References](/definitions/schema-references.md)
* [TypeDef](/schema-definition-language/advanced-schema-concepts/typedef.md) · [MemberDef](/schema-definition-language/advanced-schema-concepts/memberdef.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/schema-definition-language/data-types/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.