Protected$typeProtectedattributesProtecteddataProtectedpassthroughThe attribute name from the data object
Optionaloptions: AutomaticSerializerAttributeOptionsForTypeConfiguration options:
as - Rename the attribute key in the serialized output and OpenAPI shapedefault - Value to use when the attribute is undefined (not available for type columns)openapi - OpenAPI schema definition; required for json/jsonb columns and non-virtual
getters, optional for standard columns (where it can supplement inferred types with a
description), and optional for @deco.Virtual() columns (where the type is inferred
from the decorator)precision - Round decimal values to the specified number of decimal places (0–9)
during rendering; does not affect the OpenAPI shape (not available for type or
virtual columns)required - Set to false to mark the attribute as optional in the OpenAPI schema;
when omitted, attributes are required by default, meaning undefined values will
serialize as null (not available for type columns)The serializer builder for method chaining
// With type inference (database column)
.attribute('email')
// With explicit OpenAPI type (virtual attribute or json column)
.attribute('fullName', { openapi: { type: 'string' } })
// With default value
.attribute('status', { default: 'pending' })
// Rename output key
.attribute('email', { as: 'userEmail' })
// Round decimal to 2 places
.attribute('price', { precision: 2 })
// Mark as optional in OpenAPI (omitted from response when undefined)
.attribute('deletedAt', { required: false })
Includes an attribute from the data object in the serialized output.
For DreamSerializer, OpenAPI types are automatically inferred from database columns.
For json/jsonb columns and virtual attributes (getters), the openapi option is required.
The attribute name from the data object
Optionaloptions: SerializerAttributeOptionsForVirtualColumnConfiguration options:
as - Rename the attribute key in the serialized output and OpenAPI shapedefault - Value to use when the attribute is undefined (not available for type columns)openapi - OpenAPI schema definition; required for json/jsonb columns and non-virtual
getters, optional for standard columns (where it can supplement inferred types with a
description), and optional for @deco.Virtual() columns (where the type is inferred
from the decorator)precision - Round decimal values to the specified number of decimal places (0–9)
during rendering; does not affect the OpenAPI shape (not available for type or
virtual columns)required - Set to false to mark the attribute as optional in the OpenAPI schema;
when omitted, attributes are required by default, meaning undefined values will
serialize as null (not available for type columns)The serializer builder for method chaining
// With type inference (database column)
.attribute('email')
// With explicit OpenAPI type (virtual attribute or json column)
.attribute('fullName', { openapi: { type: 'string' } })
// With default value
.attribute('status', { default: 'pending' })
// Rename output key
.attribute('email', { as: 'userEmail' })
// Round decimal to 2 places
.attribute('price', { precision: 2 })
// Mark as optional in OpenAPI (omitted from response when undefined)
.attribute('deletedAt', { required: false })
Includes an attribute from the data object in the serialized output.
For DreamSerializer, OpenAPI types are automatically inferred from database columns.
For json/jsonb columns and virtual attributes (getters), the openapi option is required.
The attribute name from the data object
Configuration options:
as - Rename the attribute key in the serialized output and OpenAPI shapedefault - Value to use when the attribute is undefined (not available for type columns)openapi - OpenAPI schema definition; required for json/jsonb columns and non-virtual
getters, optional for standard columns (where it can supplement inferred types with a
description), and optional for @deco.Virtual() columns (where the type is inferred
from the decorator)precision - Round decimal values to the specified number of decimal places (0–9)
during rendering; does not affect the OpenAPI shape (not available for type or
virtual columns)required - Set to false to mark the attribute as optional in the OpenAPI schema;
when omitted, attributes are required by default, meaning undefined values will
serialize as null (not available for type columns)The serializer builder for method chaining
// With type inference (database column)
.attribute('email')
// With explicit OpenAPI type (virtual attribute or json column)
.attribute('fullName', { openapi: { type: 'string' } })
// With default value
.attribute('status', { default: 'pending' })
// Rename output key
.attribute('email', { as: 'userEmail' })
// Round decimal to 2 places
.attribute('price', { precision: 2 })
// Mark as optional in OpenAPI (omitted from response when undefined)
.attribute('deletedAt', { required: false })
Includes an attribute from the data object in the serialized output.
For DreamSerializer, OpenAPI types are automatically inferred from database columns.
For json/jsonb columns and virtual attributes (getters), the openapi option is required.
The attribute name from the data object
Optionaloptions: AutomaticSerializerAttributeOptionsConfiguration options:
as - Rename the attribute key in the serialized output and OpenAPI shapedefault - Value to use when the attribute is undefined (not available for type columns)openapi - OpenAPI schema definition; required for json/jsonb columns and non-virtual
getters, optional for standard columns (where it can supplement inferred types with a
description), and optional for @deco.Virtual() columns (where the type is inferred
from the decorator)precision - Round decimal values to the specified number of decimal places (0–9)
during rendering; does not affect the OpenAPI shape (not available for type or
virtual columns)required - Set to false to mark the attribute as optional in the OpenAPI schema;
when omitted, attributes are required by default, meaning undefined values will
serialize as null (not available for type columns)The serializer builder for method chaining
// With type inference (database column)
.attribute('email')
// With explicit OpenAPI type (virtual attribute or json column)
.attribute('fullName', { openapi: { type: 'string' } })
// With default value
.attribute('status', { default: 'pending' })
// Rename output key
.attribute('email', { as: 'userEmail' })
// Round decimal to 2 places
.attribute('price', { precision: 2 })
// Mark as optional in OpenAPI (omitted from response when undefined)
.attribute('deletedAt', { required: false })
Includes a computed value in the serialized output.
Executes a callback function to generate a custom attribute value.
The openapi option is always required since the return type cannot be inferred.
The callback's return value renders as is, so any fallback or rounding belongs in the callback.
The attribute name for the computed value
Callback function that returns the computed value
Configuration options:
openapi - (required) OpenAPI schema definition for the computed valueflatten - When true, spreads the returned object's properties directly into the
parent serialized output instead of nesting them under name. The openapi option
then describes the whole returned object, not each property, because Psychic adds it
to the parent's schema as an allOf branch: either an object schema with full
property bodies (type: 'object', properties, and required listing the keys that
are always present), or { $serializer: SomeSerializer } when the callback returns
what that serializer renders. A serializer ref with many: true does not type-check
here, since a list has no properties to spread. A null return, a serializer built over
null or undefined data, or an undefined return without required: false renders as
null each key the openapi requires: a key an object shape lists in its required
array, a key a $serializer or $serializable ref's serializer declares without
required: false, and each such key of an allOf, anyOf or oneOf member. Its
optional keys stay absent, and an undefined return with required: false adds no keys.
A returned plain object also renders as null each key its shape requires that it
leaves out, and its optional keys it leaves out stay absent. When the openapi is an
anyOf or oneOf, or a $serializable ref to an STI base, a present value also renders
as null each key another variant requires that the rendered one does not declare, so a
client sees the same keys whichever variant is rendered.
Every key it adds follows the render's casing like the parent's own keys: a returned
plain object's top-level keys and the openapi's properties keys are cased (so
casing: 'snake' renders phoneNumber as phone_number, present or null), while
nested values render as returned. Attributes render in declaration order, so a key the returned object shares with
another attribute takes the value of whichever is declared later; under the allOf,
that value must match both schemasrequired - Set to false to mark the attribute as optional in the OpenAPI schema;
when omitted, attributes are required by defaultThe serializer builder for method chaining
// Simple computed value
.customAttribute('initials', () =>
`${user.firstName?.[0]}${user.lastName?.[0]}`.toUpperCase(),
{ openapi: { type: 'string' } }
)
// Flattened object properties: `openapi` describes the whole returned object
.customAttribute('coordinates', () => ({ lat: 40.7, lng: -74.0 }), {
flatten: true,
openapi: {
type: 'object',
required: ['lat', 'lng'],
properties: {
lat: { type: 'number' },
lng: { type: 'number' }
}
}
})
Includes an attribute from a nested object in the serialized output.
Accesses targetName.name on the data object. When the target object or the
delegated attribute is null/undefined, the resolution order is:
default if provided → renders the default valuerequired: false → omits the key entirely from the rendered outputnullWhen the target is a Dream model, a non-json column's OpenAPI shape is inferred
from the column, so its openapi option takes only a description. json/jsonb
columns and non-Dream targets have no shape to infer, so they require a full
openapi shape.
optional and required are not aliases — they encode different things and can
be used together:
optional: true is an OpenAPI-only marker (no runtime effect). It declares
that the rendered value may be null (e.g. when delegating through a HasOne
that may be missing). Use this when you want the key to always be present
but the value to be nullable in the schema.required: false affects both runtime and OpenAPI. At runtime, when the
resolved value is undefined (which includes the case of a missing delegated
association with no default), the key is omitted from the rendered output.
In OpenAPI, the field is marked as not required.The property name containing the target object (e.g., an association name)
The attribute name within the target object
Configuration options:
as - Rename the attribute key in the serialized output and OpenAPI shape
(e.g., delegating 'user', 'email' with as: 'userEmail' outputs the value
under userEmail)default - Value to use when the target object or its attribute is null/undefined
(not available when delegating to a 'type' STI discriminator column: substituting
a discriminator string when the association is actually missing produces a response
indistinguishable from "association present with that type," which is misleading)openapi - OpenAPI schema definition; required for non-Dream targets and json/jsonb
columns. On a non-json Dream column, whose shape is inferred, it takes only a
description (and, on the STI type column, a type: 'string' and enum)optional - Set to true to mark the value as nullable in the OpenAPI schema:
Psychic adds null to the rendered schema (e.g., type: 'string' becomes
type: ['string', 'null'], and a $ref becomes anyOf: [{ $ref }, { type: 'null' }]).
OpenAPI-only — the key is still rendered (as null). For Dream models, this is
auto-inferred from optional BelongsTo associations. Use this when delegating
through a HasOne or other nullable association.precision - Round decimal values to the specified number of decimal places (0–9)
during rendering; does not affect the OpenAPI shape (not available when delegating
to a 'type' STI discriminator column, which is always a string enum)required - Set to false to omit the key from the rendered output when the
resolved value is undefined (including a missing delegated association with
no default), and to mark the field as not required in the OpenAPI schemaThe serializer builder for method chaining
// Delegate to a Dream association's column (type inferred)
.delegatedAttribute('currentLocalizedText', 'title')
// With default value for null target or attribute
.delegatedAttribute('user', 'displayName', { default: 'Unknown User' })
// Rename the output key
.delegatedAttribute('profile', 'avatarUrl', { as: 'avatar' })
// A json/jsonb column has no shape to infer, so it declares one
.delegatedAttribute('user', 'preferences', {
openapi: { type: 'object', properties: { theme: 'string' } }
})
Executes the serializer and returns the serialized output.
Processes all defined attributes, custom attributes, delegated attributes, and associations to produce the final serialized object.
Additional data to pass through to nested serializers (e.g., locale, current user context)
Rendering options for customizing the serialization process
The serialized object, suitable for JSON responses
Includes an array of associated objects in the serialized output.
When rendering a Dream association, the serializer and OpenAPI shape are automatically inferred from that associated Dream model's registered serializers.
The association property name (should resolve to an array)
Optionaloptions: BaseOptions & SerializerOptionsConfiguration options:
as - Rename the association key in the serialized outputserializerKey - Use a specific serializer key from the associated Dream model's
registered serializers (e.g., 'summary')serializer - Provide an explicit serializer function instead of using the
associated model's registered serializersFor ViewModel associations, one of these is required:
viewModelClass + optional serializerKeyserializerFor non-Dream/non-ViewModel associations:
serializer is requiredThe serializer builder for method chaining
// Auto-infer serializer from Dream association
.rendersMany('rooms')
// With specific serializer key
.rendersMany('rooms', { serializerKey: 'summary' })
// Explicit serializer function (for non-Dream objects)
.rendersMany('bedTypes', { serializer: BedTypeSerializer })
// Rename output key
.rendersMany('rooms', { serializerKey: 'forGuests', as: 'guestRooms' })
Includes a single associated object in the serialized output.
When rendering a Dream association, the serializer and OpenAPI shape are automatically inferred from that associated Dream model's registered serializers.
The association property name
Optionaloptions: BaseOptions & SerializerOptionsConfiguration options:
as - Rename the association key in the serialized outputflatten - When true, spreads the rendered association's attributes directly into
the parent serialized output instead of nesting them under name. Attributes render in
declaration order, so when the parent and the association share a key (e.g., id),
whichever is declared later wins: the association's value replaces an attribute declared
before the rendersOne, and an attribute declared after it replaces the association's.
When the association is null, each key its serializer requires renders as null: an
attribute, delegatedAttribute or customAttribute declared without required: false, and
every non-flattened rendersOne and rendersMany (for a polymorphic BelongsTo, each
key the serializer of any of its target classes requires, and for an association to an
STI base, each key the serializer of any of its STI children requires), in the same order
(so an id declared before the rendersOne becomes null), while a key declared with
required: false stays absent. A flattened customAttribute in that serializer adds the
keys its openapi requires: a key an object shape lists in its required array, a key a
$serializer or $serializable ref's serializer declares without required: false, and
each such key of an allOf, anyOf or oneOf member; a ref with many: true adds none,
and a flattened customAttribute declared with required: false adds none. Nothing in
that serializer is rendered, so its custom attribute callbacks do not run. When the
association to an STI base or polymorphic BelongsTo is present, each key another STI
child's or target's serializer requires that the held one's serializer does not declare
also renders as null, so a client sees the same keys whichever is held. Psychic adds
the association's OpenAPI schema to the parent's as an allOf branch, so a shared key's
value must match both schemas, whichever declaration winsoptional - When true, allows the association to be null/missing without causing
an OpenapiResponseValidationFailure during Psychic controller unit specs. By default,
rendersOne expects the association to be present (mirroring the optional option on
@deco.BelongsTo). Set this to true when the association is genuinely nullableserializerKey - Use a specific serializer key from the associated Dream model's
registered serializers (e.g., 'summary')serializer - Provide an explicit serializer function instead of using the
associated model's registered serializersFor ViewModel associations, one of these is required:
viewModelClass + optional serializerKeyserializerFor non-Dream/non-ViewModel associations:
serializer is requiredThe serializer builder for method chaining
// Auto-infer serializer from Dream association
.rendersOne('profile')
// With specific serializer key
.rendersOne('user', { serializerKey: 'summary' })
// Allow null association
.rendersOne('approver', { optional: true })
// Flatten into parent object
.rendersOne('candidate', { serializerKey: 'summary', flatten: true })
// Explicit serializer function
.rendersOne('owner', { serializer: CustomOwnerSerializer })
Includes an attribute from the data object in the serialized output.
For DreamSerializer, OpenAPI types are automatically inferred from database columns. For json/jsonb columns and virtual attributes (getters), the
openapioption is required.