ExtensibleEnum

A standard pattern for enum fields that accept custom values: the value property is chosen from a predefined set of options (usually including a custom option), with an optional customValue and description to document caller-defined values in a structured way.

Fields like OppStatus, AppStatus, and ApplicantType follow this pattern via the ExtensibleEnumT<T> template.

ExtensibleEnum

The untyped base model, for cases where the value set is open-ended and a typed constraint isn’t appropriate.

Table

Property	Type	Required	Description
value	any	Yes	The selected value. May be from a predefined set of options or a custom value
customValue	string	No	A custom value, used when the selected value does not fit a predefined option
description	string	No	A human-readable description of the value

Formats

Example

A JSON example of this model.

{
  "value": "custom",
  "customValue": "underReview",
  "description": "The application is under review by the program team"
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: ExtensibleEnum.yaml
type: object
properties:
  value:
    description: The selected value. May be from a predefined set of options or a custom value
  customValue:
    type: string
    description: A custom value, used when the selected value does not fit a predefined option
  description:
    type: string
    description: A human-readable description of the value
required:
  - value
unevaluatedProperties:
  not: {}
examples:
  - value: custom
    customValue: underReview
    description: The application is under review by the program team
description: A value from an open-ended set of options

TypeSpec

The TypeSpec code for this model.

/** A value from an open-ended set of options: a `value` of unspecified shape,
 * an optional `customValue` for caller-defined options, and an optional
 * free-form `description`. Use this when the value set is open-ended and a
 * typed constraint isn't appropriate. For typed variants, see `ExtensibleEnumT<T>`.
 */
@example(Examples.ExtensibleEnum.customStatus)
@doc("A value from an open-ended set of options")
@Versioning.added(CommonGrants.Versions.v0_4)
model ExtensibleEnum {
  /** The selected value. May be from a predefined set of options or a custom value */
  value: unknown;

  /** A custom value, used when the selected value does not fit a predefined option */
  customValue?: string;

  /** A human-readable description of the value */
  description?: string;
}

Changelog

Version	Changes	Schema
0.4.0	Added ExtensibleEnum model	ExtensibleEnum.yaml

ExtensibleEnumT

A templated variant that constrains value to a given enum. Use this to define new extensible enum fields so they stay consistent with the rest of the protocol:

enum OppStatusOptions {
  forecasted,
  open,
  closed,
  custom,
}

model OppStatus is Fields.ExtensibleEnumT<OppStatusOptions>;

Formats

TypeSpec

The TypeSpec code for this model.

/** A typed extensible enum: `value` is constrained to a caller-supplied enum (or
 * other type), with a free-form `description` for annotation or custom-value
 * details.
 *
 * @template T The type (typically an enum) accepted for `value`.
 *
 * @example How to instantiate a typed extensible enum
 *
 * ```typespec
 * enum OppStatusOptions {
 *   forecasted,
 *   open,
 *   closed,
 *   custom,
 * }
 *
 * model OppStatus is ExtensibleEnumT<OppStatusOptions>;
 * ```
 */
@Versioning.added(CommonGrants.Versions.v0_4)
model ExtensibleEnumT<T> {
  /** The selected value, from a predefined set of options */
  value: T;

  /** A custom value, used when the selected value is the `custom` option */
  customValue?: string;

  /** A human-readable description of the value */
  description?: string;
}