# Model

The classes can be used as a model in your application. Ts.ED uses these models to convert JSON objects to their class equivalents.

The classes models can be used in the following cases:

  • Data serialization and deserialization (Converters),
  • Data validation with AJV,
  • Generating documentation with Swagger.

To create a model, Ts.ED provides decorators which will store and generate a standard JsonSchema model.

WARNING

Validation is only available when you import @tsed/ajv package in your server.

import "@tsed/ajv";

@ServerSettings()
class Server extends ServerLoader {}
1
2
3
4

Without this package, decorators like won't have any effect.

# Example

The example below uses decorators to describe a property of the class and store metadata such as the description of the field.

import {
  Default,
  Enum,
  Format,
  Maximum,
  MaxLength,
  Minimum,
  MinLength,
  Pattern,
  Required
} from "@tsed/common";

enum Categories {
  CAT1 = "cat1",
  CAT2 = "cat2"
}

export class MyModel {
  _id: string;

  @Required()
  unique: string;

  @MinLength(3)
  @MaxLength(50)
  indexed: string;

  @Minimum(0)
  @Maximum(100)
  @Default(0)
  rate: Number = 0;

  @Enum(Categories)
    // or @Enum("type1", "type2")
  category: Categories;

  @Pattern(/[a-z]/)
  pattern: String;

  @Format("date-time")
  @Default(Date.now)
  dateCreation: Date = new Date();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

TIP

The Model will generate a JsonSchema which can be used by modules supporting JsonSchema spec

WARNING

The schema generated by Ts.ED lists only properties decorated by at least one decorator. In the previous example, the _id won't be displayed in the JsonSchema. It's very important to understand that TypeScript only generates metadata on properties with at least of theses decorators:

Our model is now described, we can use it inside a as input type parameter for our methods. Ts.ED will use the model to convert the raw data to an instance of your model.

import {BodyParams, Controller, Post} from "@tsed/common";
import {PersonModel} from "../models/PersonModel";

@Controller("/")
export class PersonsCtrl {

  @Post("/")
  save(@BodyParams() model: PersonModel): PersonModel {
    console.log(model instanceof PersonModel); // true
    return model; // will be serialized according to your annotation on PersonModel class.
  }

  // OR

  @Post("/")
  save(@BodyParams("person") model: PersonModel): PersonModel {
    console.log(model instanceof PersonModel); // true
    return model; // will be serialized according to your annotation on PersonModel class.
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Collections

Declaring a property that uses a collection is a bit different than declaring a simple property. TypeScript stores only the Array/Set/Map type when you declare the type of your property. The type used by the collection is lost.

To tell Ts.ED (and other third party which uses JsonSchema) that a property uses a collection with a specific type, you must use decorator as following:

import {PropertyType} from "@tsed/common";
import {Role} from "./Role";
import {Security} from "./Security";

class User {
  @PropertyType(Role)
  roles: Role[];

  @PropertyType(String)
  securities: Map<string, Security>;

  @PropertyType(String)
  scopes: Set<string>;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Use JsonSchema

In some cases, it may be useful to retrieve the JSON Schema from a Model to use with another library. This is possible by using . Here a small example:

import {getJsonSchema, MinLength, Required} from "@tsed/common";

class PersonModel {
  @MinLength(3)
  @Required()
  firstName: string;

  @MinLength(3)
  @Required()
  lastName: string;
}

const schema = getJsonSchema(PersonModel);

console.log(schema);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Result:

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "minLength": 3
    },
    "lastName": {
      "type": "string",
      "minLength": 3
    }
  },
  "required": [
    "firstName",
    "lastName"
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Decorators

← Converters →