Skip to content

docs: Split models page into three use cases#465

Open
Swiftaxe wants to merge 1 commit intomainfrom
feat/improve-models
Open

docs: Split models page into three use cases#465
Swiftaxe wants to merge 1 commit intomainfrom
feat/improve-models

Conversation

@Swiftaxe
Copy link
Copy Markdown
Contributor

Problem

The models page has become the largest file in the docs, by far. It includes advanced use cases that make it harder for newcomers to understand.

Solution

Divide the file into three use cases:

  1. Working with models (core)
  2. Inheritance & polymorphism
  3. Vector fields

The core page is still quite large (500+ lines), but no single topic is large enough to warrant a new page.

Change in menu structure

The files are placed in a new folder, and the core page ("Working with models") loads when the "Working with models" menu category is clicked.

Reference

Fixes serverpod/serverpod#4250.

Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Splits the previously large “models” documentation into three focused pages (core models, inheritance/polymorphism, and vector fields) and updates navigation + cross-links accordingly.

Changes:

  • Added a new Models docs category with “Working with models” as the category landing page.
  • Moved inheritance/polymorphism and vector fields content into dedicated docs pages.
  • Updated inbound links across docs to point to the new locations/anchors.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
docs/06-concepts/22-experimental.md Updates an inheritance cross-link to the new inheritance/polymorphism doc path.
docs/06-concepts/09-logging.md Updates the duration-format reference link to the new models section anchor.
docs/06-concepts/02-models/category.json Introduces a new “Models” sidebar category and links it to the core models doc.
docs/06-concepts/02-models/03-vector-fields.md New standalone page documenting vector field types and references.
docs/06-concepts/02-models/02-inheritance-and-polymorphism.md New standalone page for inheritance + polymorphism guidance and examples.
docs/06-concepts/02-models/01-models.md Becomes the core “Working with models” page; adds slug and updates internal references to split-out pages.
docs/01-get-started/03-working-with-the-database.md Updates link to the relocated models keywords reference.
docs/01-get-started/02-models-and-data.md Updates link to the relocated “Working with models” doc.
docs/01-get-started/01-creating-endpoints.md Updates link to the relocated serializable model reference.
Comments suppressed due to low confidence (2)

docs/06-concepts/02-models/01-models.md:25

  • The links to the Vector type sections look like they include an extra models/ path segment (e.g. ./models/vector-fields#vector). Since vector-fields is a sibling doc within the same 02-models folder, this likely resolves to a non-existent doc path and will trip the broken-link checks. Update these links to point directly to the sibling doc (e.g. vector-fields#vector, vector-fields#halfvector, etc.).
    docs/06-concepts/02-models/01-models.md:554
  • These keyword table links use ./models/inheritance-and-polymorphism..., which appears to add an extra models/ segment relative to this doc’s location. The target doc is a sibling (inheritance-and-polymorphism), so this link is likely broken and will fail the docs build’s broken-link validation. Point the links directly at the sibling doc (e.g. inheritance-and-polymorphism#...).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Inheritance can also be used with table models. However, **only one class** in an inheritance hierarchy can have a `table` property defined. The table can be placed at any level in the inheritance chain (top, middle or bottom).

:::info
This is a current limitation due to the parent class implementing the `table` getter and other table-related fields, so classes that `extends` the parent cannot override such properties with different types. This might be lifted with a future implementation of `interface` support for table models.
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar: “classes that extends the parent” should be “classes that extend the parent”.

Suggested change
This is a current limitation due to the parent class implementing the `table` getter and other table-related fields, so classes that `extends` the parent cannot override such properties with different types. This might be lifted with a future implementation of `interface` support for table models.
This is a current limitation due to the parent class implementing the `table` getter and other table-related fields, so classes that `extend` the parent cannot override such properties with different types. This might be lifted with a future implementation of `interface` support for table models.

Copilot uses AI. Check for mistakes.
When deserializing polymorphic types, Serverpod uses the class name encoded in the serialized data to determine which concrete subtype to instantiate. However, there are situations where the class name in the incoming data may not correspond to any known class on the server or client:

- An older client is sending data with a class that no longer exists on the server.
- An older client is receiving data from a class that was added lately on the server.
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wording: “was added lately on the server” is unidiomatic; “was added recently on the server” (or “was recently added”) reads more clearly.

Suggested change
- An older client is receiving data from a class that was added lately on the server.
- An older client is receiving data from a class that was recently added on the server.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Split working-with-models page into multiple pages

2 participants