CustomKey

@tsed/schema

Usage

import { CustomKey } from "@tsed/schema";

See /packages/specs/schema/src/decorators/common/customKey.ts.

Overview

function CustomKey(key: string, value: any): (...args: any[]) => any;

• key (string): - The custom key name (use x- prefix for vendor extensions)

• value (any): - The value to associate with the key

Description

Adds a custom key-value pair to the JSON Schema that is not part of the official spec.

The @CustomKey() decorator allows adding vendor-specific extensions or custom metadata to schemas. These custom keys are only included in the generated schema when explicitly requested with the customKeys: true option in getJsonSchema().

Basic Usage

class UserModel {
  @CustomKey("x-internal-id", "USER_001")
  @Property()
  username: string;
}

Vendor Extensions

Following OpenAPI conventions, use x- prefix for custom extensions:

class ApiModel {
  @CustomKey("x-visibility", "internal")
  @CustomKey("x-deprecated-by", "newField")
  @Property()
  oldField: string;
}

Documentation Metadata

class ProductModel {
  @CustomKey("x-example-source", "marketing-team")
  @CustomKey("x-last-reviewed", "2024-01-15")
  @Property()
  description: string;
}

Integration Hints

class DataModel {
  @CustomKey("x-database-column", "user_full_name")
  @CustomKey("x-searchable", true)
  @Property()
  fullName: string;
}

Retrieving Custom Keys

Custom keys must be explicitly requested:

import { getJsonSchema } from "@tsed/schema";

const schema = getJsonSchema(UserModel, { customKeys: true });
// Schema will include x-internal-id and other custom keys

const standardSchema = getJsonSchema(UserModel);
// Custom keys are omitted by default

Use Cases

• OpenAPI Extensions: Add vendor-specific OpenAPI extensions
• Tool Integration: Metadata for code generators or documentation tools
• Internal Tracking: Development or operational metadata
• Feature Flags: Schema-level feature flag information
• Database Mapping: ORM or database column hints