State the project's position on relations and references #126

State the project's position on relations and references.

What happens

There is no notion of a link between models — no Link[Author] (Beanie), no Reference (ODMantic), no lazy loading. Grepping docs/ and README.md for any statement of that position returns nothing.

Why it matters

Given TinyDB's model this is almost certainly the right scope decision, and application-level foreign keys work fine. But it is the first thing an ODM-experienced evaluator looks for, and right now they find silence — which reads as "not built yet" rather than "deliberately out of scope". Silence costs a reader several minutes of searching and leaves them unsure whether the library is finished.

Everywhere else this project states its scope decisions well (docs/contributing/static_typing.md on Mapped[T], _config.py on model_config, find.md on why a second .sort() raises). This is the same kind of decision with none of the writing.

What to do

One paragraph in docs/usage/models.md, roughly:

tinydantic does not model relationships. Store the related document's id and resolve it explicitly. TinyDB has no joins, so a relation abstraction would only hide N+1 reads behind attribute access — the cost would be the same and the reader would no longer see it.

Worth a line in the README's scope framing too, since that is where the fifteen-second evaluation happens.

Reproduction

Nothing to run — the finding is an absence. The evidence is the search:

$ grep -rniE "relationship|foreign key|\bLink\[|\bReference\b" docs/ README.md --include='*.md'

15 matches across docs/ and README.md, and not one of them states a position on relations. They are: the word "reference" in TinyDB's storage internals and in the private-API registry (docs/contributing/upstream_limitations.md), "foreign keys" meaning stray extra keys under extra='allow' (docs/usage/schema-evolution.md), "reference-style"/"Reference material" describing the docs sections themselves (docs/usage/crud.md, docs/usage/index.md, docs/reference/index.md), and API-reference hyperlinks (docs/usage/fastapi.md, README.md).

No Link[...], no Reference type, and no sentence anywhere saying relations are out of scope.

Expected: one paragraph in docs/usage/models.md stating the decision, so an ODM-experienced reader finds the answer instead of silence.

Environment: tinydantic 0.4.0 at 4d373d1, macOS. Run 2026-08-13.

Verified at e7d0ed0 on 2026-08-12. Originally finding L7 of the 2026-08-06 internal review.

Assisted-by: Claude:claude-opus-5