Skip to main content
Version: Next

Working with models

Models are Yaml files used to define serializable classes in Serverpod. They are used to generate Dart code for the server and client, and, if a database table is defined, to generate database code for the server. Using regular .yaml files within lib/src/models is supported, but it is recommended to use .spy.yaml (.spy stands for "Server Pod Yaml") to leverage syntax highlighting provided by the Serverpod Extension for VS Code.

The files are analyzed by the Serverpod CLI when generating the project and creating migrations.

Run serverpod generate to generate dart classes from the model files.


class: Company
name: String
foundedDate: DateTime?
employees: List<Employee>

Supported types are bool, int, double, String, Duration, DateTime, ByteData, UuidValue, and other serializable classes, exceptions and enums. You can also use Lists and Maps of the supported types, just make sure to specify the types. Null safety is supported. Once your classes are generated, you can use them as parameters or return types to endpoint methods.

Limiting visibility of a generated class

By default, generated code for your serializable objects is available both on the server and the client. You may want to have the code on the server side only. E.g., if the serializable object is connected to a database table containing private information.

To make a serializable class generated only on the server side, set the serverOnly property to true.

class: MyPrivateClass
serverOnly: true
hiddenSecretKey: String

It is also possible to set a scope on a per-field basis. By default all fields are visible to both the server and the client. The available scopes are all, serverOnly, none.

class: SelectivelyHiddenClass
hiddenSecretKey: String, scope=serverOnly
publicKey: String

Serverpod's models can easily be saved to or read from the database. You can read more about this in the Database section.


The Serverpod models supports creating exceptions that can be thrown in endpoints by using the exception keyword. For more in-depth description on how to work with exceptions see Error handling and exceptions.

exception: MyException
message: String
errorType: MyEnum


It is easy to add custom enums with serialization support by using the enum keyword.

enum: Animal
- dog
- cat
- bird

By default the serialization will convert the enum to an int representing the index of the value. Changing the order may therefore have unforeseen consequences when reusing old data (such as from a database). Changing the serialization to be based on the name instead of index is easy.

enum: Animal
serialized: byName
- dog
- cat
- bird

serialized has two valid values byName 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.


It's recommended to always set serialized to byName in any new Enum models, as this is less fragile and will be changed to the default setting in version 2 of Serverpod.

Adding documentation

Serverpod allows you to add documentation to your serializable objects in a similar way that you would add documentation to your Dart code. Use three hashes (###) to indicate that a comment should be considered documentation.

### Information about a company.
class: Company
### The name of the company.
name: String

### The date the company was founded, if known.
foundedDate: DateTime?

### A list of people currently employed at the company.
employees: List<Employee>

Generated code

Serverpod generates some convenience methods on the Dart classes.


The copyWith method allows for efficient object copying with selective field updates and is available on all generated classes. Here's how it operates:

var john = User(name: 'John Doe', age: 25);
var jane = john.copyWith(name: 'Jane Doe');

The copyWith method generates a deep copy of an object, preserving all original fields unless explicitly modified. It can distinguish between a field set to null and a field left unspecified (undefined). When using copyWith, any field you don't update remains unchanged in the new object.

toJson / fromJson

The toJson and fromJson methods are generated on all models to help with serialization. Serverpod manages all serialization for you out of the box and you will rarely have to use these methods by your self. See the Serialization section for more info.

Custom methods

Sometimes you will want to add custom methods to the generated classes. The easiest way to do this is with Dart's extension feature.

extension MyExtension on MyClass {
bool isCustomMethod() {
return true;


valuesA special key for enums with a list of all enum values.
serializedSets the mode enums are serialized in
serverOnlyBoolean flag if code generator only should create the code for the server.
tableA name for the database table, enables generation of database code.
managedMigrationA boolean flag to opt out of the database migration system.
fieldsAll fields in the generated class should be listed here.
type (fields)Denotes the data type for a field.
scopeDenotes the scope for a field.
persistA boolean flag if the data should be stored in the database or not can be negated with !persist
relationSets a relation between model files, requires a table name to be set.
nameGive a name to a relation to pair them.
parentSets the parent table on a relation.
fieldA manual specified foreign key field.
onUpdateSet the referential actions when updating data in the database.
onDeleteSet the referential actions when deleting data in the database.
optionalA boolean flag to make a relation optional.
indexesCreate indexes on your fields / columns.
fields (index)List the fields to create the indexes on.
type (index)The type of index to create.
uniqueBoolean flag to make the entries unique in the database.