From 653edd9832606b4774123f1b0f692c41b2be49e5 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Mon, 6 Jul 2026 14:40:00 +0100 Subject: [PATCH 1/4] docs: Extract Model reference and reshape Models concept pages --- docs/06-concepts/02-models/01-models.md | 43 +---- .../02-inheritance-and-polymorphism.md | 8 +- .../03-vector-and-geography-fields.md | 151 ++++++++++++++++++ .../06-concepts/02-models/03-vector-fields.md | 74 --------- .../02-models/04-geography-fields.md | 72 --------- docs/06-concepts/03-serialization.md | 44 ++--- docs/06-concepts/17-backward-compatibility.md | 2 + docs/06-concepts/20-shared-packages.md | 6 +- docs/06-concepts/lookups/model-reference.md | 46 ++++++ docs/11-upgrading/04-upgrade-to-postgis.md | 2 +- 10 files changed, 240 insertions(+), 208 deletions(-) create mode 100644 docs/06-concepts/02-models/03-vector-and-geography-fields.md delete mode 100644 docs/06-concepts/02-models/03-vector-fields.md delete mode 100644 docs/06-concepts/02-models/04-geography-fields.md create mode 100644 docs/06-concepts/lookups/model-reference.md diff --git a/docs/06-concepts/02-models/01-models.md b/docs/06-concepts/02-models/01-models.md index 08826105..f4669c9f 100644 --- a/docs/06-concepts/02-models/01-models.md +++ b/docs/06-concepts/02-models/01-models.md @@ -1,6 +1,7 @@ --- slug: /concepts/models sidebar_label: Working with models +description: Define serializable classes, exceptions, and enums in Serverpod model files, with fields, defaults, visibility, and generated Dart code. --- # Working with models @@ -23,7 +24,7 @@ fields: employees: List ``` -Supported types are [bool](https://api.dart.dev/dart-core/bool-class.html), [int](https://api.dart.dev/dart-core/int-class.html), [double](https://api.dart.dev/dart-core/double-class.html), [String](https://api.dart.dev/dart-core/String-class.html), [Duration](https://api.dart.dev/dart-core/Duration-class.html), [DateTime](https://api.dart.dev/dart-core/DateTime-class.html), [ByteData](https://api.dart.dev/dart-typed_data/ByteData-class.html), [UuidValue](https://pub.dev/documentation/uuid/latest/uuid_value/UuidValue-class.html), [Uri](https://api.dart.dev/dart-core/Uri-class.html), [BigInt](https://api.dart.dev/dart-core/BigInt-class.html), [Vector](./models/vector-fields#vector), [HalfVector](./models/vector-fields#halfvector), [SparseVector](./models/vector-fields#sparsevector), [Bit](./models/vector-fields#bit), [GeographyPoint](./models/geography-fields#geographypoint), [GeographyLineString](./models/geography-fields#geographylinestring), [GeographyPolygon](./models/geography-fields#geographypolygon), [GeographyGeometryCollection](./models/geography-fields#geographygeometrycollection) and other serializable [classes](#class), [exceptions](#exception) and [enums](#enum). You can also use [List](https://api.dart.dev/dart-core/List-class.html)s, [Map](https://api.dart.dev/dart-core/Map-class.html)s and [Set](https://api.dart.dev/dart-core/Set-class.html)s of the supported types, just make sure to specify the types. All supported types can also be used inside [Record](https://api.dart.dev/dart-core/Record-class.html)s. Null safety is supported. Once your classes are generated, you can use them as parameters or return types to endpoint methods. +Supported types are [bool](https://api.dart.dev/dart-core/bool-class.html), [int](https://api.dart.dev/dart-core/int-class.html), [double](https://api.dart.dev/dart-core/double-class.html), [String](https://api.dart.dev/dart-core/String-class.html), [Duration](https://api.dart.dev/dart-core/Duration-class.html), [DateTime](https://api.dart.dev/dart-core/DateTime-class.html), [ByteData](https://api.dart.dev/dart-typed_data/ByteData-class.html), [UuidValue](https://pub.dev/documentation/uuid/latest/uuid_value/UuidValue-class.html), [Uri](https://api.dart.dev/dart-core/Uri-class.html), [BigInt](https://api.dart.dev/dart-core/BigInt-class.html), [Vector](./models/vector-and-geography-fields#vector), [HalfVector](./models/vector-and-geography-fields#halfvector), [SparseVector](./models/vector-and-geography-fields#sparsevector), [Bit](./models/vector-and-geography-fields#bit), [GeographyPoint](./models/vector-and-geography-fields#geographypoint), [GeographyLineString](./models/vector-and-geography-fields#geographylinestring), [GeographyPolygon](./models/vector-and-geography-fields#geographypolygon), [GeographyGeometryCollection](./models/vector-and-geography-fields#geographygeometrycollection) and other serializable [classes](#class), [exceptions](#exception) and [enums](#enum). You can also use [List](https://api.dart.dev/dart-core/List-class.html)s, [Map](https://api.dart.dev/dart-core/Map-class.html)s and [Set](https://api.dart.dev/dart-core/Set-class.html)s of the supported types, just make sure to specify the types. All supported types can also be used inside [Record](https://api.dart.dev/dart-core/Record-class.html)s. Null safety is supported. Once your classes are generated, you can use them as parameters or return types to endpoint methods. ### Required fields @@ -180,11 +181,11 @@ values: - bird ``` -`serialized` has two valid values: `byName` (the default) and `byIndex`. When using `byName` the string literal of the enum is used; when using `byIndex` the index value (0, 1, 2, etc.) is used. +The `serialized` keyword has two valid values: `byName` (the default) and `byIndex`. When using `byName` the string literal of the enum is used; when using `byIndex` the index value (0, 1, 2, etc.) is used. :::warning -`byIndex` is fragile: adding, removing, or reordering enum values silently changes the serialized form, which can corrupt persisted data. Only use `byIndex` when you need to maintain compatibility with existing data already serialized that way. +Using `byIndex` is fragile: adding, removing, or reordering enum values silently changes the serialized form, which can corrupt persisted data. Only use `byIndex` when you need to maintain compatibility with existing data already serialized that way. ::: @@ -361,7 +362,7 @@ You can use these default values individually or in combination as needed. It is When using `default` or `defaultModel` in combination with `defaultPersist`, it's important to understand how the interaction between these keywords affects the final value in the database. -If you set a `default` or `defaultModel` value, the model's field or variable will have a value when it's passed to the database—it will not be `null`. Because of this, the SQL query will not use the `defaultPersist` value since the field already has a value assigned by the model. In essence, assigning a `default` or `defaultModel` is like directly providing a value to the field, and the database will use this provided value instead of its own default. +If you set a `default` or `defaultModel` value, the model's field or variable will have a value when it's passed to the database, so it will not be `null`. Because of this, the SQL query will not use the `defaultPersist` value since the field already has a value assigned by the model. In essence, assigning a `default` or `defaultModel` is like directly providing a value to the field, and the database will use this provided value instead of its own default. This means that `defaultPersist` only comes into play when the model does not provide a value, allowing the database to apply its own default setting. @@ -520,36 +521,4 @@ fields: ## Keywords -| **Keyword** | Note | [class](#class) | [exception](#exception) | [enum](#enum) | -| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | :-------------: | :---------------------: | :-----------: | -| [**values**](#enum) | A special key for enums with a list of all enum values. | | | ✅ | -| [**serialized**](#enum) | Sets the mode enums are serialized in | | | ✅ | -| [**properties**](#enhanced-enums-with-properties) | Defines custom properties for enhanced enums. | | | ✅ | -| [**immutable**](#immutable-classes) | Boolean flag to generate an immutable class with final fields, equals operator, and hashCode. | ✅ | ✅ | | -| [**serverOnly**](#limiting-visibility-of-a-generated-class) | Boolean flag if code generator only should create the code for the server. | ✅ | ✅ | ✅ | -| [**table**](database/models) | A name for the database table, enables generation of database code. | ✅ | | | -| [**managedMigration**](database/migrations#opt-out-of-migrations) | A boolean flag to opt out of the database migration system. | ✅ | | | -| [**fields**](#class) | All fields in the generated class should be listed here. | ✅ | ✅ | | -| [**type (fields)**](#class) | Denotes the data type for a field. | ✅ | ✅ | | -| [**required**](#required-fields) | Makes the field as required. This keyword can only be used for **nullable** fields. | ✅ | ✅ | | -| [**scope**](#limiting-visibility-of-a-generated-class) | Denotes the scope for a field. | ✅ | | | -| [**jsonKey**](#json-key-aliasing) | Sets a custom key name for JSON serialization and deserialization. | ✅ | | | -| [**persist**](database/models) | A boolean flag if the data should be stored in the database or not can be negated with `!persist` | ✅ | | | -| [**relation**](database/relations/one-to-one) | Sets a relation between model files, requires a table name to be set. | ✅ | | | -| [**name**](database/relations/one-to-one#bidirectional-relations) | Give a name to a relation to pair them. | ✅ | | | -| [**parent**](database/relations/one-to-one#with-an-id-field) | Sets the parent table on a relation. | ✅ | | | -| [**field**](database/relations/one-to-one#custom-foreign-key-field) | A manual specified foreign key field. | ✅ | | | -| [**onUpdate**](database/relations/referential-actions) | Set the referential actions when updating data in the database. | ✅ | | | -| [**onDelete**](database/relations/referential-actions) | Set the referential actions when deleting data in the database. | ✅ | | | -| [**optional**](database/relations/one-to-one#optional-relation) | A boolean flag to make a relation optional. | ✅ | | | -| [**indexes**](database/indexing) | Create indexes on your fields / columns. | ✅ | | | -| [**fields (index)**](database/indexing) | List the fields to create the indexes on. | ✅ | | | -| [**type (index)**](database/indexing) | The type of index to create. | ✅ | | | -| [**parameters (index)**](database/indexing#vector-indexes) | Parameters for specialized index types like HNSW and IVFFLAT vector indexes. | ✅ | | | -| [**distanceFunction (index)**](database/indexing#vector-indexes) | Distance function for vector indexes. Allowed values depend on the field's vector type and index type — see [vector indexes](database/indexing#vector-indexes). | ✅ | | | -| [**unique**](database/indexing) | Creates a unique index. | ✅ | | | -| [**default**](#default-values) | Sets the default value for both the model and the database. This keyword cannot be used with **relation**. | ✅ | | | -| [**defaultModel**](#default-values) | Sets the default value for the model side. This keyword cannot be used with **relation**. | ✅ | | | -| [**defaultPersist**](#default-values) | Sets the default value for the database side. This keyword cannot be used with **relation** and **!persist**. | ✅ | | | -| [**extends**](./models/inheritance-and-polymorphism#extending-a-class) | Specifies a parent class to inherit from. | ✅ | ✅ | | -| [**sealed**](./models/inheritance-and-polymorphism#sealed-classes) | Boolean flag to create a sealed class hierarchy, enabling exhaustive type checking. | ✅ | | | +For every keyword available in a model file, and whether it applies to a `class`, `exception`, or `enum`, see the [Model reference](lookups/model-reference). diff --git a/docs/06-concepts/02-models/02-inheritance-and-polymorphism.md b/docs/06-concepts/02-models/02-inheritance-and-polymorphism.md index 0dddb0c6..199b0773 100644 --- a/docs/06-concepts/02-models/02-inheritance-and-polymorphism.md +++ b/docs/06-concepts/02-models/02-inheritance-and-polymorphism.md @@ -1,3 +1,7 @@ +--- +description: Define class hierarchies in Serverpod models with extends and sealed, use polymorphic types in endpoints, and handle unknown subtypes across client versions. +--- + # Inheritance and polymorphism ## Inheritance @@ -176,7 +180,7 @@ class NotificationEndpoint extends Endpoint { } ``` -Polymorphic types also work seamlessly in Lists, Maps, Sets, Records, and nullable contexts. +Polymorphic types also work in Lists, Maps, Sets, Records, and nullable contexts. ### Handling unknown class names @@ -186,7 +190,7 @@ When deserializing polymorphic types, Serverpod uses the class name encoded in t - An older client is receiving data from a class that was recently added on the server. - A newer client is sending data with a class that hasn't been deployed to the server yet. -If the missing class is a subclass of a known class, Serverpod will try to deserialize the model as the known class. This makes it safe to replace base classes with subclasses on endpoints without breaking backward compatibility. +If the missing class is a subclass of a known class, Serverpod will try to deserialize the model as the known class. This makes it safe to replace base classes with subclasses on endpoints without breaking [backward compatibility](../backward-compatibility). :::info This will only work for non-streaming endpoints. Streaming endpoints will always throw an exception if the class name is not known. diff --git a/docs/06-concepts/02-models/03-vector-and-geography-fields.md b/docs/06-concepts/02-models/03-vector-and-geography-fields.md new file mode 100644 index 00000000..90f0ba44 --- /dev/null +++ b/docs/06-concepts/02-models/03-vector-and-geography-fields.md @@ -0,0 +1,151 @@ +--- +description: Store high-dimensional embeddings with vector fields (pgvector) and geospatial data with geography fields (PostGIS) in Serverpod models. +--- + +# Vector & geography fields + +Serverpod supports two families of specialized field types backed by PostgreSQL extensions: vector fields for high-dimensional embeddings (via pgvector) and geography fields for geospatial data (via PostGIS). + +## Vector fields + +Vector types are used for storing high-dimensional vectors, which are especially useful for similarity search operations. + +When specifying vector types, the dimension is required between parentheses (e.g., `Vector(1536)`). Common dimensions include: + +- 1536 (OpenAI embeddings) +- 768 (many sentence transformers) +- 384 (smaller models) + +All vector types support specialized distance operations for similarity search and filtering. See the [Vector distance operators](../database/filter#vector-distance-operators) section for details. + +To ensure optimal performance with vector similarity searches, consider creating specialized vector indexes on your vector fields. See the [Vector indexes](../database/indexing#vector-indexes) section for more details. + +:::info +The usage of Vector fields requires a Postgres database with the `pgvector` extension installed. The extension comes by default on new Serverpod projects. To upgrade an existing project, see the [Upgrade to pgvector](../../upgrading/archive/upgrade-to-pgvector) guide. +::: + +### Vector + +The `Vector` type stores full-precision floating-point vectors for general-purpose embeddings. + +```yaml +class: Document +table: document +fields: + ### The category of the document (e.g., article, tutorial). + category: String + + ### The contents of the document. + content: String + + ### A vector field for storing document embeddings + embedding: Vector(1536) +``` + +### HalfVector + +The `HalfVector` type uses half-precision (16-bit) floating-point numbers, providing memory savings with acceptable precision loss for several applications. + +```yaml +class: Document +table: document +fields: + content: String + ### Half-precision embedding for memory efficiency + embedding: HalfVector(1536) +``` + +### SparseVector + +The `SparseVector` type efficiently stores sparse vectors where most values are zero, which is ideal for high-dimensional data with few non-zero elements. + +```yaml +class: Document +table: document +fields: + content: String + ### Sparse vector for keyword-based embeddings + keywords: SparseVector(10000) +``` + +### Bit + +The `Bit` type stores binary vectors where each element is 0 or 1, offering maximum memory efficiency for binary embeddings. + +```yaml +class: Document +table: document +fields: + content: String + ### Binary vector for semantic hashing + hash: Bit(256) +``` + +## Geography fields + +Geography types are used for storing geospatial data on the surface of the Earth. They are stored as PostGIS geography columns in PostgreSQL using the WGS 84 coordinate system (SRID 4326), which is the standard used by GPS. The SRID is fixed to `4326`, available in Dart as `Geography.defaultSrid`; configuring a different SRID per column is not yet supported. + +Like other fields, geography fields can be made optional by appending `?` to the type, for example `location: GeographyPoint?`. + +All geography types support spatial filter operations such as proximity search, intersection, containment, and distance-based ordering. See the [Geography operators](../database/filter#geography-operators) section for details. + +To ensure optimal performance with spatial queries, consider creating a spatial index on your geography fields. See the [Geography indexes](../database/indexing#geography-indexes) section for more details. + +:::info +The usage of Geography fields requires the PostGIS PostgreSQL extension to be installed. To set up PostGIS in a new or existing project, see the [Upgrading to PostGIS support](../../upgrading/upgrade-to-postgis) guide. +::: + +:::warning +Spatial operations are only supported on PostgreSQL. On SQLite, geography values are stored as text in EWKT format and round-trip through CRUD operations, but spatial query operations are not supported and throw at query time. +::: + +### GeographyPoint + +The `GeographyPoint` type stores a single geographic location defined by longitude and latitude. + +```yaml +class: Store +table: store +fields: + name: String + location: GeographyPoint + address: String? +``` + +### GeographyLineString + +The `GeographyLineString` type stores an ordered sequence of points forming a path or route. + +```yaml +class: DeliveryRoute +table: delivery_route +fields: + name: String + path: GeographyLineString + description: String? +``` + +### GeographyPolygon + +The `GeographyPolygon` type stores a closed region defined by an exterior ring and optional interior holes. + +```yaml +class: DeliveryZone +table: delivery_zone +fields: + name: String + boundary: GeographyPolygon + description: String? +``` + +### GeographyGeometryCollection + +The `GeographyGeometryCollection` type stores a collection of mixed geography types (points, lines, and polygons) as a single field. + +```yaml +class: Region +table: region +fields: + name: String + features: GeographyGeometryCollection +``` diff --git a/docs/06-concepts/02-models/03-vector-fields.md b/docs/06-concepts/02-models/03-vector-fields.md deleted file mode 100644 index 38390f08..00000000 --- a/docs/06-concepts/02-models/03-vector-fields.md +++ /dev/null @@ -1,74 +0,0 @@ -# Vector fields - -Vector types are used for storing high-dimensional vectors, which are especially useful for similarity search operations. - -When specifying vector types, the dimension is required between parentheses (e.g., `Vector(1536)`). Common dimensions include: - -- 1536 (OpenAI embeddings) -- 768 (many sentence transformers) -- 384 (smaller models) - -All vector types support specialized distance operations for similarity search and filtering. See the [Vector distance operators](../database/filter#vector-distance-operators) section for details. - -To ensure optimal performance with vector similarity searches, consider creating specialized vector indexes on your vector fields. See the [Vector indexes](../database/indexing#vector-indexes) section for more details. - -:::info -The usage of Vector fields requires a Postgres database with the `pgvector` extension installed. The extension comes by default on new Serverpod projects. To upgrade an existing project, see the [Upgrade to pgvector](../../upgrading/archive/upgrade-to-pgvector) guide. -::: - -## Vector - -The `Vector` type stores full-precision floating-point vectors for general-purpose embeddings. - -```yaml -class: Document -table: document -fields: - ### The category of the document (e.g., article, tutorial). - category: String - - ### The contents of the document. - content: String - - ### A vector field for storing document embeddings - embedding: Vector(1536) -``` - -## HalfVector - -The `HalfVector` type uses half-precision (16-bit) floating-point numbers, providing memory savings with acceptable precision loss for several applications. - -```yaml -class: Document -table: document -fields: - content: String - ### Half-precision embedding for memory efficiency - embedding: HalfVector(1536) -``` - -## SparseVector - -The `SparseVector` type efficiently stores sparse vectors where most values are zero, which is ideal for high-dimensional data with few non-zero elements. - -```yaml -class: Document -table: document -fields: - content: String - ### Sparse vector for keyword-based embeddings - keywords: SparseVector(10000) -``` - -## Bit - -The `Bit` type stores binary vectors where each element is 0 or 1, offering maximum memory efficiency for binary embeddings. - -```yaml -class: Document -table: document -fields: - content: String - ### Binary vector for semantic hashing - hash: Bit(256) -``` diff --git a/docs/06-concepts/02-models/04-geography-fields.md b/docs/06-concepts/02-models/04-geography-fields.md deleted file mode 100644 index f451f44e..00000000 --- a/docs/06-concepts/02-models/04-geography-fields.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -description: Store geospatial data in Serverpod models using GeographyPoint, GeographyLineString, GeographyPolygon, and GeographyGeometryCollection backed by PostGIS. ---- - -# Geography fields - -Geography types are used for storing geospatial data on the surface of the Earth. They are stored as PostGIS geography columns in PostgreSQL using the WGS 84 coordinate system (SRID 4326), which is the standard used by GPS. The SRID is fixed to `4326`, available in Dart as `Geography.defaultSrid`; configuring a different SRID per column is not yet supported. - -Like other fields, geography fields can be made optional by appending `?` to the type, for example `location: GeographyPoint?`. - -All geography types support spatial filter operations such as proximity search, intersection, containment, and distance-based ordering. See the [Geography operators](../database/filter#geography-operators) section for details. - -To ensure optimal performance with spatial queries, consider creating a spatial index on your geography fields. See the [Geography indexes](../database/indexing#geography-indexes) section for more details. - -:::info -The usage of Geography fields requires the PostGIS PostgreSQL extension to be installed. To set up PostGIS in a new or existing project, see the [Upgrading to PostGIS support](../../upgrading/upgrade-to-postgis) guide. -::: - -:::warning -Spatial operations are only supported on PostgreSQL. On SQLite, geography values are stored as text in EWKT format and round-trip through CRUD operations, but spatial query operations are not supported and throw at query time. -::: - -## GeographyPoint - -The `GeographyPoint` type stores a single geographic location defined by longitude and latitude. - -```yaml -class: Store -table: store -fields: - name: String - location: GeographyPoint - address: String? -``` - -## GeographyLineString - -The `GeographyLineString` type stores an ordered sequence of points forming a path or route. - -```yaml -class: DeliveryRoute -table: delivery_route -fields: - name: String - path: GeographyLineString - description: String? -``` - -## GeographyPolygon - -The `GeographyPolygon` type stores a closed region defined by an exterior ring and optional interior holes. - -```yaml -class: DeliveryZone -table: delivery_zone -fields: - name: String - boundary: GeographyPolygon - description: String? -``` - -## GeographyGeometryCollection - -The `GeographyGeometryCollection` type stores a collection of mixed geography types (points, lines, and polygons) as a single field. - -```yaml -class: Region -table: region -fields: - name: String - features: GeographyGeometryCollection -``` diff --git a/docs/06-concepts/03-serialization.md b/docs/06-concepts/03-serialization.md index 486babc7..add35967 100644 --- a/docs/06-concepts/03-serialization.md +++ b/docs/06-concepts/03-serialization.md @@ -1,32 +1,38 @@ +--- +sidebar_label: Custom serialization +description: Pass custom classes through Serverpod endpoints and models with toJson/fromJson, Freezed support, and ProtocolSerialization for server-only fields. +--- + # Custom serialization For most purposes, you will want to use Serverpod's native serialization. However, there may be cases where you want to serialize more advanced objects. With Serverpod, you can pass any serializable objects as long as they conform to the following rules: 1. Your objects must have a method called `toJson()` which returns a JSON serialization of the object. - ```dart - Map toJson() { - return { - 'name': 'John Doe', - }; - } - ``` + ```dart + Map toJson() { + return { + 'name': 'John Doe', + }; + } + ``` 2. There must be a constructor or factory called `fromJson()`, which takes a JSON serialization as parameters. - ```dart - factory ClassName.fromJson( - Map json, - ) { - return ClassName( - name: json['name'] as String, - ); - } - ``` + ```dart + factory ClassName.fromJson( + Map json, + ) { + return ClassName( + name: json['name'] as String, + ); + } + ``` 3. You must declare your custom serializable objects in the `config/generator.yaml` file in the server project, the path needs to be accessible from both the server package and the client package. ```yaml + ... extraClasses: - package:my_project_shared/my_project_shared.dart:ClassName @@ -96,12 +102,12 @@ class ClassName { } ``` -After adding a new serializable class, you must run `serverpod generate`. You are now able to use this class in your endpoints and leverage the full serialization/deserialization management that comes with Serverpod. +After adding a new serializable class, you must run `serverpod generate`. You are now able to use this class in your endpoints with the full serialization and deserialization management that comes with Serverpod. In your server project, you can create an endpoint returning your custom object. ```dart -import 'package:relation_test_shared/relation_test_shared.dart'; +import 'package:my_project_shared/my_project_shared.dart'; import 'package:serverpod/serverpod.dart'; class ExampleEndpoint extends Endpoint { @@ -158,7 +164,7 @@ class CustomClass implements ProtocolSerialization { final String? value; final String? serverSideValue; - ....... + CustomClass({this.value, this.serverSideValue}); // Serializes fields specifically for protocol communication Map toJsonForProtocol() { diff --git a/docs/06-concepts/17-backward-compatibility.md b/docs/06-concepts/17-backward-compatibility.md index bb5ac0cc..280ec1ba 100644 --- a/docs/06-concepts/17-backward-compatibility.md +++ b/docs/06-concepts/17-backward-compatibility.md @@ -14,6 +14,8 @@ Following a simple set of rules, your server will stay compatible with older app 4. __Avoid changing parameter names in future call methods.__ Changing the parameter names of the future call methods will break backward compatibility since parameters are passed by name. 5. __Do not delete future call methods or change their signature.__ Instead, add new methods if you must pass another set of parameters. +For polymorphic models, Serverpod can also deserialize an unknown subtype as its known base class, which lets you add subtypes without breaking older clients. See [Handling unknown class names](models/inheritance-and-polymorphism#handling-unknown-class-names). + ## Managing breaking changes with endpoint inheritance An [endpoint sub-class](/concepts/working-with-endpoints) can be useful when you have to make a breaking change to an entire endpoint but need to keep supporting existing clients. Doing so allows you to share most of its implementation with the old endpoint. diff --git a/docs/06-concepts/20-shared-packages.md b/docs/06-concepts/20-shared-packages.md index 55cb0482..d34f15f1 100644 --- a/docs/06-concepts/20-shared-packages.md +++ b/docs/06-concepts/20-shared-packages.md @@ -4,7 +4,7 @@ description: Shared packages in Serverpod let you define models usable in both s # Shared packages -Shared packages let you define models and logic that can be safely imported in both server and client code. They contain the models and the protocol file, depend exclusively on the `serverpod_serialization` package, and have no server-only dependencies. This makes them ideal for data structures that need to be used across your full stack—for example, DTOs, API request/response shapes, or domain models that flow between Flutter and your Serverpod backend with their custom logic. +Shared packages let you define models and logic that can be safely imported in both server and client code. They contain the models and the protocol file, depend exclusively on the `serverpod_serialization` package, and have no server-only dependencies. This makes them ideal for data structures that need to be used across your full stack, for example DTOs, API request/response shapes, or domain models that flow between Flutter and your Serverpod backend with their custom logic. Models and the protocol file are generated in the shared package's own directory when you run `serverpod generate` from your server project. The shared package is tied to the project through the `shared_packages` field in `config/generator.yaml`. @@ -21,14 +21,14 @@ version: 1.0.0 publish_to: none environment: - sdk: ^3.8.0 + sdk: ^3.10.3 dependencies: serverpod_serialization: SERVERPOD_VERSION ``` :::info -Use the same Serverpod version as your project. Replace `SERVERPOD_VERSION` with your Serverpod version (e.g., `3.4.0`). +Use the same Serverpod version as your project. Replace `SERVERPOD_VERSION` with your Serverpod version (e.g., `3.5.0`). ::: ### Add model files diff --git a/docs/06-concepts/lookups/model-reference.md b/docs/06-concepts/lookups/model-reference.md new file mode 100644 index 00000000..59c0b4f0 --- /dev/null +++ b/docs/06-concepts/lookups/model-reference.md @@ -0,0 +1,46 @@ +--- +description: Every keyword available in Serverpod model files, and which of class, exception, and enum each one applies to. +--- + +# Model reference + +Every keyword available in a Serverpod model file, and whether it applies to a `class`, `exception`, or `enum`. For how each one works, see [Working with models](../models). + +| **Keyword** | Note | [class](../models#class) | [exception](../models#exception) | [enum](../models#enum) | +| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------: | :------------------------------: | :--------------------: | +| [**values**](../models#enum) | A special key for enums with a list of all enum values. | | | ✅ | +| [**serialized**](../models#enum) | Sets the mode enums are serialized in | | | ✅ | +| [**properties**](../models#enhanced-enums-with-properties) | Defines custom properties for enhanced enums. | | | ✅ | +| [**immutable**](../models#immutable-classes) | Boolean flag to generate an immutable class with final fields, equals operator, and hashCode. | ✅ | ✅ | | +| [**serverOnly**](../models#limiting-visibility-of-a-generated-class) | Boolean flag if code generator only should create the code for the server. | ✅ | ✅ | ✅ | +| [**table**](../database/models) | A name for the database table, enables generation of database code. | ✅ | | | +| [**managedMigration**](../database/migrations#opt-out-of-migrations) | A boolean flag to opt out of the database migration system. | ✅ | | | +| [**fields**](../models#class) | All fields in the generated class should be listed here. | ✅ | ✅ | | +| [**type (fields)**](../models#class) | Denotes the data type for a field. | ✅ | ✅ | | +| [**required**](../models#required-fields) | Makes the field as required. This keyword can only be used for **nullable** fields. | ✅ | ✅ | | +| [**scope**](../models#limiting-visibility-of-a-generated-class) | Denotes the scope for a field. | ✅ | | | +| [**jsonKey**](../models#json-key-aliasing) | Sets a custom key name for JSON serialization and deserialization. | ✅ | | | +| [**persist**](../database/models) | A boolean flag if the data should be stored in the database or not can be negated with `!persist` | ✅ | | | +| [**relation**](../database/relations/one-to-one) | Sets a relation between model files, requires a table name to be set. | ✅ | | | +| [**name**](../database/relations/one-to-one#bidirectional-relations) | Give a name to a relation to pair them. | ✅ | | | +| [**parent**](../database/relations/one-to-one#with-an-id-field) | Sets the parent table on a relation. | ✅ | | | +| [**field**](../database/relations/one-to-one#custom-foreign-key-field) | A manual specified foreign key field. | ✅ | | | +| [**onUpdate**](../database/relations/referential-actions) | Set the referential actions when updating data in the database. | ✅ | | | +| [**onDelete**](../database/relations/referential-actions) | Set the referential actions when deleting data in the database. | ✅ | | | +| [**optional**](../database/relations/one-to-one#optional-relation) | A boolean flag to make a relation optional. | ✅ | | | +| [**indexes**](../database/indexing) | Create indexes on your fields / columns. | ✅ | | | +| [**fields (index)**](../database/indexing) | List the fields to create the indexes on. | ✅ | | | +| [**type (index)**](../database/indexing) | The type of index to create. | ✅ | | | +| [**parameters (index)**](../database/indexing#vector-indexes) | Parameters for specialized index types like HNSW and IVFFLAT vector indexes. | ✅ | | | +| [**distanceFunction (index)**](../database/indexing#vector-indexes) | Distance function for vector indexes. Allowed values depend on the field's vector type and index type, see [vector indexes](../database/indexing#vector-indexes). | ✅ | | | +| [**unique**](../database/indexing) | Creates a unique index. | ✅ | | | +| [**default**](../models#default-values) | Sets the default value for both the model and the database. This keyword cannot be used with **relation**. | ✅ | | | +| [**defaultModel**](../models#default-values) | Sets the default value for the model side. This keyword cannot be used with **relation**. | ✅ | | | +| [**defaultPersist**](../models#default-values) | Sets the default value for the database side. This keyword cannot be used with **relation** and **!persist**. | ✅ | | | +| [**extends**](../models/inheritance-and-polymorphism#extending-a-class) | Specifies a parent class to inherit from. | ✅ | ✅ | | +| [**sealed**](../models/inheritance-and-polymorphism#sealed-classes) | Boolean flag to create a sealed class hierarchy, enabling exhaustive type checking. | ✅ | | | + +## Related + +- [Working with models](../models): how each keyword works, with examples. +- [Database tables](../database/models): the database-specific keywords (`table`, `relation`, `persist`, and indexing). diff --git a/docs/11-upgrading/04-upgrade-to-postgis.md b/docs/11-upgrading/04-upgrade-to-postgis.md index 38893d55..308e19fb 100644 --- a/docs/11-upgrading/04-upgrade-to-postgis.md +++ b/docs/11-upgrading/04-upgrade-to-postgis.md @@ -45,7 +45,7 @@ services: - _test_data:/var/lib/postgresql/data ``` -If your project also uses [vector fields](../concepts/models/vector-fields), you need both pgvector and PostGIS. Create a custom `Dockerfile` instead: +If your project also uses [vector fields](../concepts/models/vector-and-geography-fields), you need both pgvector and PostGIS. Create a custom `Dockerfile` instead: ```dockerfile FROM pgvector/pgvector:pg16 From 98f4fb96f56fb2c375747d511e66b8e1b72b6cde Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Mon, 6 Jul 2026 16:34:06 +0100 Subject: [PATCH 2/4] docs: Use 4.0-beta as the Serverpod version example in shared packages --- docs/06-concepts/20-shared-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/06-concepts/20-shared-packages.md b/docs/06-concepts/20-shared-packages.md index d34f15f1..d8504ed6 100644 --- a/docs/06-concepts/20-shared-packages.md +++ b/docs/06-concepts/20-shared-packages.md @@ -28,7 +28,7 @@ dependencies: ``` :::info -Use the same Serverpod version as your project. Replace `SERVERPOD_VERSION` with your Serverpod version (e.g., `3.5.0`). +Use the same Serverpod version as your project. Replace `SERVERPOD_VERSION` with your Serverpod version (e.g., `4.0.0-beta.0`). ::: ### Add model files From 142ed8ee5f943f06e48567a09e92116ce46fdeda Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Mon, 6 Jul 2026 16:50:39 +0100 Subject: [PATCH 3/4] docs: Make Models page descriptions noun-first --- docs/06-concepts/02-models/01-models.md | 2 +- docs/06-concepts/02-models/02-inheritance-and-polymorphism.md | 2 +- docs/06-concepts/02-models/03-vector-and-geography-fields.md | 2 +- docs/06-concepts/03-serialization.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/06-concepts/02-models/01-models.md b/docs/06-concepts/02-models/01-models.md index f4669c9f..4ec32911 100644 --- a/docs/06-concepts/02-models/01-models.md +++ b/docs/06-concepts/02-models/01-models.md @@ -1,7 +1,7 @@ --- slug: /concepts/models sidebar_label: Working with models -description: Define serializable classes, exceptions, and enums in Serverpod model files, with fields, defaults, visibility, and generated Dart code. +description: Serverpod model files define serializable classes, exceptions, and enums, with fields, defaults, visibility, and generated Dart code. --- # Working with models diff --git a/docs/06-concepts/02-models/02-inheritance-and-polymorphism.md b/docs/06-concepts/02-models/02-inheritance-and-polymorphism.md index 199b0773..e9d8ee76 100644 --- a/docs/06-concepts/02-models/02-inheritance-and-polymorphism.md +++ b/docs/06-concepts/02-models/02-inheritance-and-polymorphism.md @@ -1,5 +1,5 @@ --- -description: Define class hierarchies in Serverpod models with extends and sealed, use polymorphic types in endpoints, and handle unknown subtypes across client versions. +description: Model inheritance defines class hierarchies with extends and sealed, uses polymorphic types in endpoints, and handles unknown subtypes across client versions. --- # Inheritance and polymorphism diff --git a/docs/06-concepts/02-models/03-vector-and-geography-fields.md b/docs/06-concepts/02-models/03-vector-and-geography-fields.md index 90f0ba44..5e55ad63 100644 --- a/docs/06-concepts/02-models/03-vector-and-geography-fields.md +++ b/docs/06-concepts/02-models/03-vector-and-geography-fields.md @@ -1,5 +1,5 @@ --- -description: Store high-dimensional embeddings with vector fields (pgvector) and geospatial data with geography fields (PostGIS) in Serverpod models. +description: Vector and geography fields store high-dimensional embeddings with pgvector and geospatial data with PostGIS in Serverpod models. --- # Vector & geography fields diff --git a/docs/06-concepts/03-serialization.md b/docs/06-concepts/03-serialization.md index add35967..671aef7b 100644 --- a/docs/06-concepts/03-serialization.md +++ b/docs/06-concepts/03-serialization.md @@ -1,6 +1,6 @@ --- sidebar_label: Custom serialization -description: Pass custom classes through Serverpod endpoints and models with toJson/fromJson, Freezed support, and ProtocolSerialization for server-only fields. +description: Custom serialization passes your own classes through Serverpod endpoints and models with toJson/fromJson, Freezed, and ProtocolSerialization for server-only fields. --- # Custom serialization From 632a3e1b16ddc86b2a2766cfe30dc035e9fb1b09 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Mon, 6 Jul 2026 17:29:17 +0100 Subject: [PATCH 4/4] docs: Make backward compatibility description noun-first --- docs/06-concepts/17-backward-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/06-concepts/17-backward-compatibility.md b/docs/06-concepts/17-backward-compatibility.md index 280ec1ba..79b097b0 100644 --- a/docs/06-concepts/17-backward-compatibility.md +++ b/docs/06-concepts/17-backward-compatibility.md @@ -1,5 +1,5 @@ --- -description: Keep your Serverpod server compatible with older client versions by following rules around endpoint signatures, serialized model fields, and future call methods. +description: Backward compatibility keeps your Serverpod server working with older client versions through rules for endpoint signatures, serialized model fields, and future call methods. --- # Backward compatibility