Tsed Models

Ts.ED Models, Validation and Serialization

One class describes the JSON Schema, the validation rules, the mapping and the OpenAPI model. The schema is the source of truth: what is not described does not exist.

Package map (never import from @tsed/common):

1. Describe the model

import {CollectionOf, Default, Email, Enum, Groups, MinLength, Nullable, Property, Required} from "@tsed/schema";
import {Role} from "./Role.js";

export class User {
  @Groups("!creation")
  id: string;

  @Required()
  @MinLength(3)
  name: string;

  @Required()
  @Email()
  email: string;

  @Enum("admin", "member")
  @Default("member")
  kind: string = "member";

  @Nullable(String)
  bio: string | null;

  @CollectionOf(Role)
  roles: Role[];

  @Property()
  createdAt: Date;
}

1. Use classes. Interfaces and type aliases carry no runtime metadata.
2. Put at least one schema decorator on every property; @Property() is the minimum. Undecorated properties are dropped from the schema, from deserialized inputs and from serialized outputs.
3. Declare the item type of every Array, Map and Set with @CollectionOf(Item) (aliases @ArrayOf, @MapOf). Use @RecordOf for records.
4. Presence and nullability are separate: @Required() / @Optional() versus @Nullable(Type). @Required() treats undefined, null and "" as missing; whitelist a value with @Allow("") or @Allow(null).
5. Constraints: @MinLength/@MaxLength, @Minimum/@Maximum (aliases @Min/@Max), @Pattern, @Format("date"), @Email, @Uri, @Url, @DateTime, @Enum, @Const, @Integer, @MinItems/@MaxItems/@UniqueItems.
6. Rename on the wire with @Name("first_name"). Mark direction with @ReadOnly() / @WriteOnly(). Document with @Description, @Example, @Title.
7. Allow unknown keys per model with @AdditionalProperties(true) (or a schema). Do not enable jsonMapper.additionalProperties globally to work around a missing decorator.
8. Polymorphism: @OneOf(A, B) / @AnyOf / @AllOf. Add @DiscriminatorKey() on the base property and @DiscriminatorValue("a") on each subclass so deserialize instantiates the right class.
9. Generics: @Generics("T") on the class, @CollectionOf("T") or @Property("T") on the member, then bind at the endpoint with @(Returns(200, Pagination).Of(Product)).
10. Do not use @Ignore() in new code (deprecated); use @Groups.

2. Vary the model with groups

1. @Groups("creation") exposes a property only for that group; @Groups("!creation") hides it for that group; patterns such as group.* match several.
2. Select groups on input with @BodyParams() @Groups("creation") user: User and on output with @(Returns(200, User).Groups("read")).
3. @BodyParams() @Partial() payload: User makes all properties optional for PATCH.
4. Set jsonMapper.strictGroups: true in new applications. Without it, an endpoint that declares no group exposes every grouped property, and the generated documentation does not match the runtime.

3. Enable validation

import "@tsed/ajv";
import {Configuration} from "@tsed/di";

@Configuration({
  ajv: {returnsCoercedValues: true},
  jsonMapper: {strictGroups: true}
})
export class Server {}

1. Install ajv and @tsed/ajv, and import @tsed/ajv in the server. Without a registered validator the built-in ValidationPipe only checks required parameters; every other constraint is silently skipped.
2. The ajv configuration key takes AJV constructor options directly, plus errorFormatter and returnsCoercedValues.
3. Failures throw AjvValidationError (a BadRequest, name AJV_VALIDATION_ERROR, with errors[]), returned as 400. Payload shape and customization: tsed-exceptions.
4. Custom messages: .Error("...") on a constraint decorator, or @ErrorMsg, @TypeError, @DefaultMsg.
5. Custom format: @Formats("slug", {type: "string"}) on a class implementing FormatsMethods<string> (validate(value): boolean); apply with @Format("slug").
6. Custom keyword: @Keyword({keyword: "range", type: "number", schemaType: "array"}) on a class implementing KeywordMethods (compile or validate); apply with @CustomKey("range", [1, 10]).
7. Import format and keyword classes from the server entry point, otherwise they are never registered.
8. Replace the validator only as a last resort: extend ValidationPipe and decorate with @OverrideProvider(ValidationPipe) from @tsed/di, throwing ValidationError. OpenAPI and mapping keep using the JSON Schema.