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.

ExtensibleEnumT

The templated model, which 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.

/** Template for defining extensible enum fields: constrains `value` to a set of
 * options (typically an enum that includes a `custom` option) while keeping the
 * shared `customValue` + `description` properties. Use this to define new
 * extensible enum fields so they stay consistent with the rest of the protocol.
 *
 * @template T The type (typically an enum) accepted for `value`.
 *
 * @example How to define a new extensible enum field
 *
 * ```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;
}

ExtensibleEnum

The base model for this pattern, derived from the template with an unconstrained value. Its JSON schema is the published shape of the pattern.

Table

Property	Type	Required	Description
value	any	Yes	The selected value, from a predefined set of options
customValue	string	No	A custom value, used when the selected value is the custom 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, from a predefined set of options
  customValue:
    type: string
    description: A custom value, used when the selected value is the `custom` 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 a predefined set of options that can be extended with a custom value when needed

TypeSpec

The TypeSpec code for this model.

/** A value chosen from a known set of options that can also be extended with a
 * custom value when none of the predefined options fit: the chosen `value` is
 * paired with an optional `customValue` and a free-form `description`. To define
 * a typed field that follows this pattern, use `ExtensibleEnumT<T>`.
 */
@example(Examples.ExtensibleEnum.customStatus)
@doc("A value from a predefined set of options that can be extended with a custom value when needed")
@Versioning.added(CommonGrants.Versions.v0_4)
model ExtensibleEnum is ExtensibleEnumT<unknown>;

Changelog

Version	Changes	Schema
0.4.0	Added ExtensibleEnum model	ExtensibleEnum.yaml