Add type definition for `format` option in `@ApiProperty` decorator

[joaovtacabral]

Is there an existing issue that is already proposing this?

• [x] I have searched the existing issues

Is your feature request related to a problem? Please describe it

Yes. When using @ApiProperty({ format: 'date-time' }), TypeScript allows any string value, which can lead to typos or unsupported formats being used without any warning. A stricter type would help ensure correctness and better IDE support.

Describe the solution you'd like

Define a union type such as:

type OpenAPIFormat =
  | 'date-time'
  | 'time'
  | 'date'
  | 'email'
  | 'uuid'
  | 'uri'
  | 'hostname'
  | 'ipv4'
  | 'ipv6'
  | 'int32'
  | 'int64'
  | 'float'
  | 'double'
  | 'password'
  | 'binary';

Then apply this type to the format field in the ApiPropertyOptions interface:

interface ApiPropertyOptions {
  ...
  format?: OpenAPIFormat;
  ...
}

Teachability, documentation, adoption, migration strategy

No response

What is the motivation / use case for changing the behavior?

The main motivation is to improve type safety and developer experience when using the @ApiProperty() decorator. Currently, the format field accepts any string, which allows for invalid or misspelled values without any feedback from the TypeScript compiler.

[krishna-singha]

Hi @joaovtacabral , I’d like to work on this issue. Could you please assign it to me under Hacktoberfest?

[mag123c]

Modified the proposal slightly to use (string & {}) pattern for backward compatibility - this allows custom format values while still providing IDE autocomplete for standard formats.