Custom fields

Custom fields and the JSON Schema types they may use.

CustomField

A custom field on a model

Property	Type	Required	Description
`name`	`string`	Yes	Name of the custom field.
`fieldType`	`CustomFieldType`	Yes	The JSON schema type to use when de-serializing the `value` field.
`schema`	`string`	No	Link to the full JSON schema for this custom field.
`value`	`unknown`	Yes	Value of the custom field.
`description`	`string`	No	Description of the custom field's purpose.

{
  "name": "eligibilityType",
  "fieldType": "array",
  "value": [
    "individual",
    "household"
  ],
  "description": "Types of eligible applicants"
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: CustomField.yaml
type: object
properties:
  name:
    type: string
    description: Name of the custom field.
  fieldType:
    $ref: CustomFieldType.yaml
    description: The JSON schema type to use when de-serializing the `value` field.
  schema:
    type: string
    format: uri
    description: Link to the full JSON schema for this custom field.
  value:
    description: Value of the custom field.
  description:
    type: string
    description: Description of the custom field's purpose.
required:
  - name
  - fieldType
  - value
examples:
  - name: eligibilityType
    fieldType: array
    value:
      - individual
      - household
    description: Types of eligible applicants
  - name: programArea
    fieldType: string
    value: Food assistance
    description: Primary focus area of the benefit program
    schema: https://example.com/program-areas.json
description: A custom field on a model

/** Model for defining custom fields that are specific to a given implementation.
 *
 * @example How to define a custom field using this model
 *
 * ```typespec
 * model Agency extends CustomField {
 *   name: "agency";
 *   fieldType: CustomFieldType.string;
 *
 *   @example("Department of Health and Human Services")
 *   value: string;
 *
 *   description?: "The agency administering this benefit";
 * }
 * ```
 */
@example(Examples.CustomField.programArea, #{ title: "String field for program area" })
@example(Examples.CustomField.eligibilityTypes, #{ title: "Array field for eligibility types" })
@doc("A custom field on a model")
@Versioning.added(Versions.v0_1)
model CustomField {
  /** Name of the custom field. */
  name: string;

  /** The JSON schema type to use when de-serializing the `value` field. */
  fieldType: CustomFieldType;

  /** Link to the full JSON schema for this custom field. */
  schema?: url;

  /** Value of the custom field. */
  value: unknown;

  /** Description of the custom field's purpose. */
  description?: string;
}

CustomFieldType

The set of JSON schema types supported by a custom field.

Value	Description
`string`	A sequence of characters.
`number`	A numeric value (integer or decimal).
`integer`	A whole number without decimals.
`boolean`	A `true` or `false` value.
`object`	A nested object with its own properties.
`array`	An ordered list of values.

"string"

$schema: https://json-schema.org/draft/2020-12/schema
$id: CustomFieldType.yaml
type: string
enum:
  - string
  - number
  - integer
  - boolean
  - object
  - array
description: |-
  The set of JSON schema types supported by a custom field.

  - `string`: A sequence of characters.
  - `number`: A numeric value (integer or decimal).
  - `integer`: A whole number without decimals.
  - `boolean`: A `true` or `false` value.
  - `object`: A nested object with its own properties.
  - `array`: An ordered list of values.

/** The set of JSON schema types supported by a custom field.
 *
 * - `string`: A sequence of characters.
 * - `number`: A numeric value (integer or decimal).
 * - `integer`: A whole number without decimals.
 * - `boolean`: A `true` or `false` value.
 * - `object`: A nested object with its own properties.
 * - `array`: An ordered list of values.
 */
@Versioning.added(Versions.v0_1)
enum CustomFieldType {
  /** A sequence of characters. */
  string,

  /** A numeric value (integer or decimal). */
  number,

  /** A whole number without decimals. */
  integer,

  /** A `true` or `false` value. */
  boolean,

  /** A nested object with its own properties. */
  object,

  /** An ordered list of values. */
  array,
}