> 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/conventions.md).

# Conventions

How to read this specification — requirement keywords, examples, and error codes.

## 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](https://www.rfc-editor.org/rfc/rfc2119) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174), and only when they appear in all capitals.

They apply to **every chapter**, not only to [Conformance Requirements](/conformance/requirements.md). 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:

| `status`      | Meaning                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------- |
| `candidate`   | **Normative.** An implementation is measured against it. Still open to change before 1.0. |
| `informative` | Explanatory. Rationale, comparisons, history — nothing here constrains an implementation. |

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

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:

| Marker             | Means                                     |
| ------------------ | ----------------------------------------- |
| `# ✗ <error-code>` | this line **is rejected**, with that code |
| `# → <value>`      | this line loads to that value             |

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.

## Error codes

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 [Error Codes](/parsing-and-errors/error-codes.md). The codes themselves are catalogued in [Error Model](/parsing-and-errors/error-model.md).

## Terminology

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

|                                    |                                                                            |
| ---------------------------------- | -------------------------------------------------------------------------- |
| **open** / **closed** object       | written **without** braces / **with** braces. A question of syntax.        |
| **strict** / **extensible** schema | rejects undeclared members / accepts them (`*`). A question of validation. |

All four combinations occur, and a document may hold them at once. See the [Glossary](/appendices/glossary.md).

## See Also

* [Conformance Requirements](/conformance/requirements.md)
* [Error Codes](/parsing-and-errors/error-codes.md)
* [Glossary](/appendices/glossary.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, and the optional `goal` query parameter:

```
GET https://docs.internetobject.org/conventions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.