> 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/advanced-schema-concepts/memberdef.md).

# MemberDef

A **MemberDef** (member definition) defines a single member of a schema: its type and the constraints on its value. It is an Internet Object object whose first value is the type, optionally followed by a default and choices, then keyed options. Every MemberDef is validated against its type's [TypeDef](/schema-definition-language/advanced-schema-concepts/typedef.md), so only the options that type defines are allowed.

## Writing a MemberDef

The first value is the type; a default and `choices` may follow positionally; all other options are keyed:

```ruby
~ $schema: {
    age:    { number, min: 0, max: 120 },        # type + keyed options
    level:  { int16, 1, [1, 2, 3] },             # type + default + choices
    name:   { string, pattern: "^[A-Za-z]+$" },  # type + keyed option
    tags:   { array, of: string, minLen: 1 }     # container type + options
}
---
~ 30, 2, John, [a, b]
```

A member can also be just a type (`age: int`) or just a name (`age`, which defaults to `any`). The positions and options each type accepts are listed in its [Schema Data Types](/schema-definition-language/data-types.md) page.

## Validation against the TypeDef

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

```ruby
age: { number, minimum: 10 }
---
42                       # ✗ unknown-member — number has no option "minimum" (use min)
```

## Optional, nullable, and default

* **Optional** (`?` on the key) — the member may be omitted: `age?: { number, min: 0 }`.
* **Nullable** (`*` on the key) — the value may be `null`: `age*: number`.
* **Both** (`?*`) — `score?*: { number, min: 0 }`.
* **Default** — the second positional value (or keyed `default:`) supplies a value when the member is omitted: `role?: { string, guest }`.

```ruby
~ $schema: { name: string, role?: { string, guest }, nickname?*: string }
---
~ John                       # role → "guest"; nickname omitted
~ Mary, admin, N             # role "admin"; nickname null
```

> **Use the `*` suffix for nullability.** The keyed `null:` option is part of each TypeDef but is not yet honored by the reference implementation — see *Implementation status*.

## MemberDef vs. SchemaDef

Both use `{ … }`, which makes them easy to confuse, but they serve different purposes:

* A **MemberDef** validates one value — it has a *type* and constraints.
* A **SchemaDef** describes an object's *shape* — a map of field names to types or MemberDefs.

The parser tells them apart by the first entry:

1. **Is the first value a known type?** → it is a **MemberDef**.
2. **Otherwise** (the first entry is a `key: …` pair, or a bare field name) → it is a **SchemaDef**.

```ruby
~ $schema: {
    address: { street: string, city: string },   # SchemaDef — a nested object shape
    age:     { int, min: 0, max: 120 }            # MemberDef — a type with constraints
}
---
~ { Main St, NYC }, 30
```

Here `address` declares fields (`street`, `city`), while `age` declares a type with a range.

## Nested shapes

For a nested object, write the shape inline (`{ … }`). The explicit `{ object, schema: { … } }` form is equivalent and documented on [Object (SchemaDef)](/schema-definition-language/data-types/object.md):

```ruby
~ $schema: { name: string, meta: { author: string, version: { int, min: 1 } } }
---
~ John, { Jane, 2 }
```

## Implementation status (beta)

* Keyed `optional:` works; keyed `null:` is not yet honored — use the `*` suffix for nullability.

## See Also

* [TypeDef](/schema-definition-language/advanced-schema-concepts/typedef.md) — the allowed options for each type
* [Overview](/schema-definition-language/internet-object-schema.md) — how schemas are built
* [Object (SchemaDef)](/schema-definition-language/data-types/object.md) — declaring object shapes
* [Schema References](/definitions/schema-references.md) — reusing shapes with `$`


---

# 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/advanced-schema-concepts/memberdef.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.