Skip to Content
DocsNestJS CRUD AutomatorAPI ReferenceDecoratorsProperty Decorators@ApiPropertyDescribe

@ApiPropertyDescribe

Central metadata decorator for entity properties. The metadata drives auto-generated DTOs, validation rules, Swagger schemas, filters, and guards.

Signature

@ApiPropertyDescribe(properties: TApiPropertyDescribeProperties)

Key configuration

OptionDescription
typeRequired EApiPropertyDescribeType (STRING, NUMBER, BOOLEAN, DATE, ENUM, OBJECT, UUID, RELATION). Governs downstream validators and Swagger schema.
descriptionHuman-readable field description appended to DTOs and Swagger docs.
exampleValueExample displayed in Swagger and used when validating pattern alignment.
dtoFine-grained control over exposure in create/update/query/response DTOs, plus guard configuration for response properties.
relationMetadataRelation-specific settings: relationType, related entity, isEager, cascade flags, etc.
Type-specific fieldsEach type exposes additional options (e.g., minLength, format, enum, identifier, minimum, maximum).

The decorator stores values in MetadataStorage, allowing factory pipelines to retrieve them even when DTOs are generated lazily.

Example

@Column()
@ApiPropertyDescribe({
	type: EApiPropertyDescribeType.STRING,
	description: "Display name",
	format: EApiPropertyStringType.STRING,
	minLength: 3,
	maxLength: 64,
	pattern: "/^[a-zA-Z0-9 _-]+$/",
	dto: {
		body: { isExposedInCreateDto: true, isRequiredInCreateDto: true },
		response: { isExposed: true },
		query: { getList: { isExposedAsFilter: true } },
	},
})
name!: string;

Best practices

  • Apply @ApiPropertyDescribe to every persistent column so DTOs remain in sync with the entity model.
  • Pair it with the property-level decorators (@ApiPropertyString, @ApiPropertyNumber, etc.) for manual DTOs or overrides.
  • Keep exampleValue in sync with pattern/range rules to avoid validation errors during bootstrapping.
Last updated on
@ApiPropertyDate@ApiPropertyEnum