# 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 (Json mapping),
- Data validation with AJV or any library compatible with JsonSchema (opens new window),
- Generating documentation with Swagger.
To create a model, Ts.ED provides decorators which will store and generate a standard JsonSchema (opens new window) model.
Validation is only available when you import `@tsed/ajv` package in your server.
import {Configuration} from "@tsed/common";
import "@tsed/ajv";
@Configuration()
class Server {}
2
3
4
5
Without this package, decorators like Email 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/schema";
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();
}
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
The Model will generate a JsonSchema which can be used by modules supporting JsonSchema spec
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 one of these decorators:
Our model is now described, we can use it inside a Controller 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} from "@tsed/platform-params";
import {Post} from "@tsed/schema";
import {Controller} from "@tsed/di";
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.
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Primitives
Just use at least
Property
decorator any other schema
decorator (like
Email
), to create a new property on a
model. Ts.ED will get the type from Typescript metadata and transform this type to a valid Json type.
# Integer
The Integer decorator is used to set integer type for integral numbers.
# Any types
The Any , decorator is used to set one or more types on property. Use this method when you want to set explicitly the json type or when you use a mixed TypeScript types.
# Nullable 6.25.0+
The Nullable decorator is used allow a null value on a field while preserving the original Typescript type.
# Any
The Any decorator is used to allow any types:
# Regular expressions
The Pattern decorator is used to restrict a string to a particular regular expression. The regular expression syntax is the one defined in JavaScript (ECMA 262 (opens new window) specifically). See Regular Expressions (opens new window) for more information.
# Format
The Format decorator allows basic semantic validation on certain kinds of string values that are commonly used. This allows values to be constrained beyond what the other tools in JSON Schema, including Regular Expressions (opens new window) can do.
The following formats are supported for string validation with format
keyword by AJV (opens new window):
- date: full-date according to RFC3339 (opens new window).
- time: time with optional time-zone.
- date-time: date-time from the same source (time-zone is mandatory).
- uri: full uri with optional protocol.
- email: email address.
- hostname: host name according to RFC1034 (opens new window).
- ipv4: IP address v4.
- ipv6: IP address v6.
- regex: tests whether a string is a valid regular expression by passing it to RegExp constructor.
See built-in formats types on Jsonp-schema.org (opens new window) for more details:
# MultipleOf
Numbers can be restricted to a multiple of a given number, using the MultipleOf decorator. It may be set to any positive number. See json-schema documentation (opens new window) for more details.
# Ranges
Ranges of numbers are specified using a combination of the Minimum and Maximum decorators, (or ExclusiveMinimum and ExclusiveMaximum for expressing exclusive range). See json-schema documentation (opens new window) for more details.
# Enumerated values
The Enum decorator is used to restrict a value to a fixed set of values. It must be an array with at least one element, where each element is unique or a TypeScript enum.
Enum decorator can be also in combination with BodyParams or @QueryParams@@:
import {Enum} from "@tsed/schema";
import {QueryParams, Controller} from "@tsed/common";
@Controller("/")
class MyController {
@Post("/")
async method(@QueryParams("type") @Enum(MyEnum) type: MyEnum): Promise<any> {
return null;
}
}
2
3
4
5
6
7
8
9
10
# Constant values
The Const decorator is used to restrict a value to a single value. For example, if you only support shipping to the United States for export reasons:
# 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 CollectionOf (before v5.62.0, use PropertyType ) decorator as following:
Ts.ED provides others related collection decorators:
# Required properties
By default, the properties defined with a decorator are not required
. However, one can use
Required
decorator to
add a required property to the json schema.
# Additional properties
Sometimes, it can be useful to create model with additional properties. By default, Json schema is strict over extra properties not declared in a model ( see Properties json schema documentation (opens new window)) .
Use AdditionalProperties on your model to allow this behavior:
It is also possible to add contraint on additional properties, by giving a raw Json schema:
Or by using getJsonSchema in combination with AdditionalProperty as following:
# Circular ref
Circular reference can be resolved by using arrow with a Property and CollectionOf decorators:
import {CollectionOf, Groups, Property} from "@tsed/schema";
export class Photo {
@Property(() => User)
owner: User;
}
export class User {
@CollectionOf(Photo)
@Groups("group.roles")
photos: Photo[];
}
2
3
4
5
6
7
8
9
10
11
12
# Custom Keys 6.17.0+
Ts.ED introduces the Keyword decorator to declare a new custom validator for Ajv. Combined with the CustomKey decorator to add keywords to a property of your class, you can use more complex scenarios than what basic JsonSchema allows.
For example, we can create a custom validator to support the range
validation over a number. To do that, we have to
define the custom validator by using
Keyword
decorator:
import {Keyword, KeywordMethods} from "@tsed/ajv";
import {array, number} from "@tsed/schema";
@Keyword({
keyword: "range",
type: "number",
schemaType: "array",
implements: ["exclusiveRange"],
metaSchema: array().items([number(), number()]).minItems(2).additionalItems(false)
})
class RangeKeyword implements KeywordMethods {
compile([min, max]: number[], parentSchema: any) {
return parentSchema.exclusiveRange === true ? (data: any) => data > min && data < max : (data: any) => data >= min && data <= max;
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Then we can declare a model using the standard decorators from @tsed/schema
:
Finally, we can create a unit test to verify if our example works properly:
import "@tsed/ajv";
import {PlatformTest} from "@tsed/common";
import {getJsonSchema} from "@tsed/schema";
import {Product} from "./Product";
import "../keywords/RangeKeyword";
describe("Product", () => {
beforeEach(PlatformTest.create);
afterEach(PlatformTest.reset);
it("should call custom keyword validation (compile)", () => {
const ajv = PlatformTest.get<Ajv>(Ajv);
const schema = getJsonSchema(Product, {customKeys: true});
const validate = ajv.compile(schema);
expect(schema).to.deep.equal({
properties: {
price: {
exclusiveRange: true,
range: [10, 100],
type: "number"
}
},
type: "object"
});
expect(validate({price: 10.01})).toEqual(true);
expect(validate({price: 99.99})).toEqual(true);
expect(validate({price: 10})).toEqual(false);
expect(validate({price: 100})).toEqual(false);
});
});
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
# Groups 6.14.0+
Groups
decorator allows you to manage your serialized/deserialized fields by using group label. For example, with a
CRUD controller, you can have many methods like POST
, PUT
, GET
or PATCH
to manage creation
, update
and read
usecases for the exposed resource.
For the creation, you don't need to have the id
field but for the update, you need to have it. With the previous
version for Ts.ED, you had to create the model twice, one for the creation
(without id
) and another one for update
and read
(with id
). Managing many models can be a pain point for the developer, this is why the
Groups
decorator
exists.
For example, we have a User model with the following properties:
import {CollectionOf, Groups, Required} from "@tsed/schema";
export class User {
@Groups("!creation")
id: string;
@Required()
firstName: string;
@Required()
lastName: string;
@Required()
@Groups("group.email", "creation")
email: string;
@Groups("creation")
password: string;
@CollectionOf(String)
@Groups("group.roles")
roles: string[];
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Explanation:
!creation
: This annotation indicates that the field will never be exposed when using thecreation
group.group.email
: This annotation indicates that the field will be exposed only if the group match withgroup.email
or with a glob pattern likegroup.*
.
So by using the deserialize function with the extra groups options, we can map data to the expected user instance:
Note The same principle works with the @@serialize@@ and @@getJsonSchema@@ functions!
Now let's see how groups work with controllers.
We can see that the
Groups
decorator can be used on parameter level as well as on the method through the
Returns
decorator. The generated OpenSpec will create automatically the appropriate JsonSchema according to the groups
configuration!
You can combine different group labels or use a glob pattern to match multiple group labels. It's also possible
to use negation by prefixing the group label with !
.
# Groups class definition 6.48.0+
It's also possible to define all groups on class instead of declaring it on each property.
# ForwardGroups 6.42.0+
Groups configuration isn't forwarded to the nested models to avoid side effect on model generation. With ForwardGroups decorator, your are able to tell if a property should use or not the Groups configuration to generate correctly a nested model.
class ChildModel {
@Groups("!creation")
id: string;
@Required()
prop1: string;
}
class MyModel {
@Groups("!creation")
id: string;
@Groups("group.summary")
@Required()
prop1: string;
@Groups("group.extended")
@Required()
prop2: string;
@Property()
@Required()
prop3: string;
@CollectionOf(ChildModel)
@ForwardGroups()
prop4: ChildModel[];
}
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
Now prop4
will have a ChildModel
generated along to groups configuration.
# RequiredGroups 6.34.0+
As
Groups
decorator,
RequiredGroups
allow you to define when a field is required
depending on the given groups strategy.
The usage is the same as Groups:
import {RequiredGroups, Groups, Required} from "@tsed/schema";
class MyModel {
@Groups("!creation")
id: string;
@Required()
prop1: string;
@RequiredGroups("!patch")
@Required()
prop2: string;
@RequiredGroups("patch")
@Required()
prop3: string;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# AllowedGroups v6.126.0+
This feature let your API consumer to define which field he wants to consume. The server will filter automatically fields based on the Groups strategy.
class MyModel {
@Property()
id: string;
@Property()
description: string;
@Groups("summary")
prop1: string; // not display by default
@Groups("details")
prop2: string; // not display by default
@Groups("admin")
sensitiveProp: string; // not displayed because it's a sensitive props
}
@Controller("/controllers")
class MyController {
@Get("/:id")
@Returns(200, MyModel).Groups("!admin").AllowedGroups("summary", "details")
get() {
return {
id: "id",
description: "description",
prop1: "prop1",
prop2: "prop2",
sensitiveProp: "sensitiveProp"
};
}
}
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
The AllowedGroups is enabled while includes
query params is given in the request. Here the different scenario with this parameter:
# Partial 6.58.0+
Partial allow you to create a Partial model on an endpoint:
import {Returns, Patch, Partial} from "@tsed/schema";
import {Controller} from "@tsed/common";
import {BodyParams} from "./bodyParams";
@Controller("/")
class MyController {
@Patch("/")
@Returns(200, MyModel).Groups("group.*")
async patch(@BodyParams() @Partial() payload: MyModel) {
// ...
}
}
2
3
4
5
6
7
8
9
10
11
12
# Advanced validation
# BeforeDeserialize 6.39.0+
If you want to validate or manipulate data before the model has been deserialized you can use the BeforeDeserialize decorator.
Note
Don't forget to return the data in your callback function otherwise an error will occur.
import {Enum, Property} from "@tsed/schema";
import {BeforeDeserialize} from "@tsed/json-mapper";
import {BadRequest} from "@tsed/exceptions";
enum AnimalType {
DOG = "DOG",
CAT = "CAT"
}
@BeforeDeserialize((data: Record<string, unknown>) => {
if (data.type !== AnimalType.DOG) {
throw new BadRequest("Sorry, we're only responsible for dogs");
} else {
data.name = `Our dog ${data.name}`;
return data;
}
})
export class Animal {
@Property()
name: string;
@Enum(AnimalType)
type: AnimalType;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# AfterDeserialize 6.39.0+
If you want to validate or manipulate data after the model has been deserialized you can use the AfterDeserialize decorator.
Note
Don't forget to return the data in your callback function otherwise an error will occur.
import {Enum, Property} from "@tsed/schema";
import {AfterDeserialize} from "@tsed/json-mapper";
import {BadRequest} from "@tsed/exceptions";
enum AnimalType {
DOG = "DOG",
CAT = "CAT"
}
@AfterDeserialize((data: Animal) => {
if (data.type !== AnimalType.CAT) {
throw new BadRequest("Sorry, we're only responsible for cats");
} else {
data.name = `Our cat ${data.name}`;
return data;
}
})
export class Animal {
@Property()
name: string;
@Enum(AnimalType)
type: AnimalType;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Custom validation decorator
Validation can quickly become complex and therefore confusing. In this case you can use your own validation decorator.
import {BeforeDeserialize} from "@tsed/json-mapper";
import {Property, JsonEntityFn} from "@tsed/schema";
import {BadRequest} from "@tsed/exceptions";
class Company {
@Property()
name: string;
@Property()
@RequiredIf((value: any, data: any) => data.name === "tsed" && value !== undefined)
location: string;
}
function RequiredIf(cb: any): PropertyDecorator {
return JsonEntityFn((store, [target, propertyKey]) => {
BeforeDeserialize((data) => {
if (!cb(data[propertyKey], data)) {
throw new BadRequest(`${String(propertyKey)} is required`);
}
return data;
})(target);
});
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# Generics
# Declaring a generic model
Sometimes, it might be useful to use generic models. TypeScript doesn't store the generic type in the metadata. This is why we need to declare explicitly the generic models with the decorators.
One of the generic's usage can be a paginated list. With Returns decorator, it's now possible to declare generic type and generate the appropriate OpenSpec documentation.
Starting with the pagination model, by using Generics and CollectionOf :
import {CollectionOf, Generics, Property} from "@tsed/schema";
@Generics("T")
class Pagination<T> {
@CollectionOf("T")
data: T[];
@Property()
totalCount: number;
}
2
3
4
5
6
7
8
9
10
Now, we need a model to be used with the generic Pagination model:
import {Property} from "@tsed/schema";
class Product {
@Property()
id: string;
@Property()
title: string;
}
2
3
4
5
6
7
8
9
Finally, we can use our models on a method as following:
# Declaring nested generic models
It's also possible to declare nested generic models in order to have this type Pagination<Submission<Product>>
:
# Generics with Types
# Generics with Functional API
# Pagination
The following advanced example will show you how you can combine the different Ts.ED features to describe Pagination. The used features are the following:
- Generics
- Function programming to declare models
- For decorator to declare a custom model for JsonSchema, OS2 or OS3.
- Response Filter to manage paginated response.
# Deep object on query 6.64.2+
With OpenAPI 3, it's possible to describe and use a deepObject (opens new window) style
as Query params.
It means, a consumer can call your endpoint with the following url:
/users?id[role]=admin&id[firstName]=Alex
Ts.ED will determine automatically the appropriate style
parameter based on the given User
model.
Here is an example with a DeepQueryObject model:
class DeepQueryObject {
@Property()
path: string;
@Property()
condition: string;
@Property()
value: string;
}
@Path("/test")
class TestDeepObjectCtrl {
@OperationPath("GET", "/")
async get(@QueryParams("s") q: DeepQueryObject) {}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
The url to be called will be:
/test?s[path]=title&s[condition]=eq&s[value]=tsed
And the generated swagger will be:
{
"components": {
"schemas": {
"DeepQueryObject": {
"properties": {
"condition": {
"type": "string"
},
"path": {
"type": "string"
},
"value": {
"type": "string"
}
},
"type": "object"
}
}
},
"paths": {
"/test": {
"get": {
"operationId": "testDeepObjectCtrlGet",
"parameters": [
{
"in": "query",
"name": "s",
"required": false,
"style": "deepObject",
"schema": {
"$ref": "#/components/schemas/DeepQueryObject"
}
}
]
}
}
}
}
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
TIP
Ts.ED support also Generics Deep object style!
class FindQuery {
@Property()
tableColumnNameA?: number;
@Property()
tableColumnNameB?: number;
}
@Generics("T")
class PaginationQuery<T> {
@Minimum(0)
@Default(0)
offset?: number;
@Minimum(1)
@Maximum(1000)
@Default(50)
limit?: number;
@Property("T")
where?: T;
}
@Path("/test")
class TestDeepObjectCtrl {
@OperationPath("GET", "/")
async get(@QueryParams() @GenericOf(FindQuery) q: PaginationQuery<FindQuery>) {}
}
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
WARNING
This feature is only available for OpenAPI 3.
# Annotations
JSON Schema includes a few keywords and Ts.ED provide also theses corresponding decorators like Title , Description , Default , Example that aren’t strictly used for validation, but are used to describe parts of a schema.
None of these annotation
keywords are required, but they are encouraged for good practice, and can make your
schema self-documenting
.
# Alias
Name decorator lets you to rename the exposed property in your json schema.
For example mongo db uses the _id
property. In order not to give any indication to our consumer about the nature of
the database, it's better to rename the property to id
.
import {Description, Example, Name} from "@tsed/schema";
import {ObjectID} from "@tsed/mongoose";
export class Model {
@Name("id")
@Description("Object ID")
@Example("5ce7ad3028890bd71749d477")
_id: string;
}
// same example with mongoose
export class Model2 {
@ObjectID("id")
_id: string;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Set Schema
If Ts.ED doesn't provide the expected decorator to describe your json schema, you can use the
Schema
decorator
from @tsed/common
to set a custom schema.
# Using JsonSchemaObject
You can declare schema by using the JsonSchemaObject interface:
import {BodyParams} from "@tsed/platform-params";
import {JsonSchemaObject, Post, Returns, Schema} from "@tsed/schema";
import {Controller} from "@tsed/di";
const ProductSchema: JsonSchemaObject = {
type: "object",
properties: {}
};
export class MyModel {
@Schema({
contains: {
type: "string"
}
})
prop: string;
}
@Controller("/")
class MyController {
@Post("/")
@Returns(200).Description("description").Schema(ProductSchema)
async method(@BodyParams() @Schema(ProductSchema) product: any): Promise<null> {
return null;
}
}
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
# Using functions 6.14.0+
It's also possible to write a valid JsonSchema by using the functional approach (Joi like):
import {BodyParams} from "@tsed/platform-params";
import {Post} from "@tsed/schema";
import {Controller} from "@tsed/di";
import {array, number, object, Returns, Schema, string} from "@tsed/schema";
const ProductSchema = object({
id: string().required().description("Product ID"),
title: string().required().minLength(3).example("CANON D300").description("Product title"),
price: number().minimum(0).example(100).description("Product price"),
description: string().description("Product description"),
tags: array().minItems(1).items(string().minLength(2).maxLength(10).description("Product tag")).description("Product tags")
}).label("ProductModel");
@Controller("/")
class MyController {
@Post("/")
@Returns(200).Description("description").Schema(ProductSchema)
async method(@BodyParams() @Schema(ProductSchema) product: any): Promise<null> {
return null;
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Here is the list of available functions:
# RecordOf
The RecordOf decorator constructs a json schema object type which property keys are set by a given set of keys and which property values are of a given type.
# Get Json schema
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 getJsonSchema . Here is a small example:
# Expose a JsonSchema
You can create a controller, or an endpoint to expose a specific schema with the custom keys. This can allow your consumers to retrieve a validation template so that they can use it to validate a form.
import {Controller, Get} from "@tsed/common";
import {getJsonSchema} from "@tsed/schema";
import {Product} from "../models/Product";
@Controller("/products")
export class ProductsCtrl {
@Get("/.schema")
get(@QueryParams("customKeys") customKeys: boolean, @QueryParams("groups") groups: string[]) {
return getJsonSchema(Product, {customKeys, groups});
}
}
2
3
4
5
6
7
8
9
10
11
# Get OpenSpec
In some cases, it may be useful to retrieve the OpenSpec from a Controller to generate the Swagger OpenSpec. This is possible by using getSpec . Here is a small example:
# Decorators
Last Updated: 9/1/2022, 3:43:26 PM
Other topics
- Session & cookies
- Passport.js
- Keycloak
- Prisma
- TypeORM
- MikroORM
- Mongoose
- GraphQL
- Socket.io
- Swagger
- AJV
- Multer
- Serve static files
- Templating
- Serverless HTTP
- Seq
- OIDC
- Stripe
- Agenda
- Terminus
- Serverless
- IORedis
- Controllers
- Providers
- Model
- JsonMapper
- Middlewares
- Pipes
- Interceptors
- Authentication
- Hooks
- Exceptions
- Throw HTTP Exceptions
- Cache
- Command
- Response Filter
- Injection scopes
- Custom providers
- Lazy-loading provider
- Custom endpoint decorator
- Testing
- Customize 404