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

# Best Practices & Guidelines

## Schemas

* **Type your fields in production.** Prefer `name: string, age: int` over bare `name, age`; types catch bad data and document intent.
* **Use keyed schemas beyond trivial records.** Positional (CSV-like) data is great for flat, fully-required records; reach for keyed fields once shapes get richer.
* **Put optional fields last in positional schemas.** A leading optional field can swallow the next value (the first value provided fills the optional slot).
* **Reuse with references.** Define a shape once as `$address` and reference it; change it in one place. See [Composition & Reuse](/schema-definition-language/advanced-schema-concepts/composition.md).

## Values

* **Quote ambiguous values.** Quote strings that look like numbers, booleans, or null (`"123"`, `"true"`, `"N"`), contain commas, or contain `:` / `/` (URLs, times).
* **Pick the right number type.** Use `int`/`uint`/`intN` for whole numbers, `decimal` (`m`) for money, `bigint` (`n`) for very large integers — not `number` for everything.
* **Mark nullability explicitly** with the `*` suffix; mark optionality with `?`.

## Documents

* **Keep the schema in the header**, data below `---`. Use metadata keys for paging/status.
* **Use collections for many similar records**; one schema validates them all.
* **Comment the why.** Use `#` to explain intent, not to restate the obvious.

## Interoperability

* **Stay in Internet Object when exactness matters.** `decimal`, `bigint`, `datetime`, and `binary` can be lossy when converted to JSON — see [JSON Compatibility](/interoperability/json-compatibility.md).

## See Also

* [Schema-First Design](/core-concepts/schema-first.md) · [Getting Started](/internet-object/getting-started.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/best-practices/best-practices.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.