Skip to Content
DocsNestJS CRUD AutomatorAPI ReferenceDecoratorsProperty Decorators@ApiPropertyObject

@ApiPropertyObject

Describes nested object fields in DTOs. Works with single DTO types, arrays, polymorphic discriminators, or dynamically generated DTOs. Handles both Swagger documentation and class-validator/class-transformer setup.

Signature

@ApiPropertyObject(properties: TApiPropertyObjectProperties)

Key options

OptionDescription
typeEither a single DTO class, an array of DTOs (for polymorphic oneOf), or a dynamically generated DTO registry.
discriminatorOptional { propertyName, mapping, shouldKeepDiscriminatorProperty } enabling OpenAPI discriminators and runtime validation. Required when supplying multiple types.
shouldValidateNestedAdds ValidateNested and Type decorators so nested objects are validated/serialized. Mandatory for request-side arrays.
isArray, minItems, maxItems, isUniqueItemsEnables arrays with validation.
additionalPropertiesPass-through for arbitrary JSON object schemas.

Behavior

  • Calls RegisterAutoDtoChild so generated DTOs are discoverable inside auto contexts.
  • Emits @ApiProperty with type, oneOf, or discriminator metadata. Allows arrays and additionalProperties.
  • Adds Type, ValidateNested, IsOptional, IsArray, ArrayMinSize, ArrayMaxSize, and ArrayNotEmpty as needed.
  • Supports polymorphic validation via MustMatchOneOfSchemasValidator.
  • Adds ApiResponseProperty, Expose, or Exclude for response DTOs.

Example

class AddressDto {
	/* ... */
}
class BillingAddressDto extends AddressDto {
	/* ... */
}
class ShippingAddressDto extends AddressDto {
	/* ... */
}
 
class OrderDto {
	@ApiPropertyObject({
		entity: () => OrderEntity,
		description: "Address payload",
		type: [BillingAddressDto, ShippingAddressDto],
		discriminator: {
			propertyName: "type",
			mapping: {
				billing: BillingAddressDto,
				shipping: ShippingAddressDto,
			},
			shouldKeepDiscriminatorProperty: true,
		},
		shouldValidateNested: true,
	})
	address!: BillingAddressDto | ShippingAddressDto;
}
Last updated on
@ApiPropertyNumber@ApiPropertyString