Competition

CompetitionBase

Base model for a competition.

A competition is an application process for a funding opportunity. It often has a distinct application period and set of application forms.

From v0.5, a competition links to its opportunity with opportunity, an OppRef carrying the opportunity’s id and title, in place of the bare opportunityId used through v0.4. A payload for any one version never carries both; only TypeSpec source examples do (see Authoring in TypeSpec).

The table and the example below show the v0.5 payload. To validate a payload, use the OpenAPI document for its version, such as /openapi/openapi.0.5.0.yaml, also browsable on the API docs page.

Table

Property	Type	Required	Description
id	uuid	Yes	Globally unique id for the competition
opportunity	OppRef	Yes	The opportunity this competition is for
title	string	Yes	The title of the competition
description	string	No	The description of the competition
instructions	string or array<File>	No	The instructions for the competition
status	CompetitionStatus	Yes	The status of the competition
keyDates	CompetitionTimeline	No	The key dates in the competition timeline
forms	CompetitionForms	Yes	The forms for the competition
acceptedApplicantTypes	array<ApplicantType>	No	Accepted applicant types for the competition
customFields	record<CustomField>	No	The custom fields for the competition
createdAt	utcDateTime	Yes	The timestamp (in UTC) at which the record was created.
lastModifiedAt	utcDateTime	Yes	The timestamp (in UTC) at which the record was last modified.

Formats

The JSON Schema tab shows the unversioned authoring schema, not a v0.5 payload schema. It combines every version’s fields, so it requires both opportunityId and opportunity.

A JSON example of this model.

{
  "id": "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a",
  "opportunity": {
    "id": "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6b",
    "title": "Small business grant program"
  },
  "title": "Competition 1",
  "description": "Competition 1 description",
  "instructions": "Competition 1 instructions",
  "status": {
    "value": "open",
    "description": "Competition is open for applications"
  },
  "keyDates": {
    "openDate": {
      "name": "Open Date",
      "eventType": "singleDate",
      "date": "2025-01-01"
    },
    "closeDate": {
      "name": "Close Date",
      "eventType": "singleDate",
      "date": "2025-01-30"
    },
    "otherDates": {
      "reviewPeriod": {
        "name": "Application Review Period",
        "eventType": "dateRange",
        "startDate": "2025-02-01",
        "endDate": "2025-02-28"
      }
    }
  },
  "forms": {
    "forms": {
      "formA": {
        "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "title": "Form A",
        "createdAt": "2025-01-01T00:00:00Z",
        "lastModifiedAt": "2025-01-01T00:00:00Z"
      },
      "formB": {
        "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e60",
        "title": "Form B",
        "createdAt": "2025-01-01T00:00:00Z",
        "lastModifiedAt": "2025-01-01T00:00:00Z"
      }
    },
    "validation": {
      "required": ["formA"]
    }
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "lastModifiedAt": "2025-01-01T00:00:00Z"
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: CompetitionBase.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: Globally unique id for the competition
  opportunityId:
    $ref: uuid.yaml
    description: The opportunity id for the competition
  opportunity:
    $ref: OppRef.yaml
    description: The opportunity this competition is for
  title:
    type: string
    description: The title of the competition
  description:
    type: string
    description: The description of the competition
  instructions:
    anyOf:
      - type: string
      - type: array
        items:
          $ref: File.yaml
    description: The instructions for the competition
  status:
    $ref: CompetitionStatus.yaml
    description: The status of the competition
  keyDates:
    $ref: CompetitionTimeline.yaml
    description: The key dates in the competition timeline
  forms:
    $ref: CompetitionForms.yaml
    description: The forms for the competition
  acceptedApplicantTypes:
    type: array
    items:
      $ref: ApplicantType.yaml
    description: Accepted applicant types for the competition
  customFields:
    $ref: "#/$defs/RecordCustomField"
    description: The custom fields for the competition
  createdAt:
    type: string
    format: date-time
    description: The timestamp (in UTC) at which the record was created.
  lastModifiedAt:
    type: string
    format: date-time
    description: The timestamp (in UTC) at which the record was last modified.
required:
  - id
  - opportunityId
  - opportunity
  - title
  - status
  - forms
  - createdAt
  - lastModifiedAt
unevaluatedProperties:
  not: {}
examples:
  - id: b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a
    opportunityId: b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6b
    opportunity:
      id: b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6b
      title: Small business grant program
    title: Competition 1
    description: Competition 1 description
    instructions: Competition 1 instructions
    status:
      value: open
      description: Competition is open for applications
    keyDates:
      openDate:
        name: Open Date
        eventType: singleDate
        date: 2025-01-01
      closeDate:
        name: Close Date
        eventType: singleDate
        date: 2025-01-30
      otherDates:
        reviewPeriod:
          name: Application Review Period
          eventType: dateRange
          startDate: 2025-02-01
          endDate: 2025-02-28
    forms:
      forms:
        formA:
          id: b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a
          name: Form A
          title: Form A
          description: Form A description
          instructions: Form A instructions
          jsonSchema:
            $id: formA.json
            type: object
            properties:
              name:
                first:
                  type: string
                last:
                  type: string
              email:
                type: string
              phone:
                type: string
          uiSchema:
            type: VerticalLayout
            elements:
              - type: Group
                label: Name
                elements:
                  - type: Control
                    scope: "#/properties/name/first"
                  - type: Control
                    scope: "#/properties/name/last"
              - type: Control
                scope: "#/properties/email"
              - type: Control
                scope: "#/properties/phone"
          mappingToCommonGrants:
            name:
              firstName:
                field: name.first
              lastName:
                field: name.last
            emails:
              primary:
                field: email
            phones:
              primary:
                field: phone
          mappingFromCommonGrants:
            name:
              first:
                field: name.firstName
              last:
                field: name.lastName
            email:
              field: emails.primary
            phone:
              field: phones.primary
          createdAt: 2025-01-01T17:01:01
          lastModifiedAt: 2025-01-02T17:30:00
        formB:
          id: b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a
          name: Form A
          title: Form A
          description: Form A description
          instructions: Form A instructions
          jsonSchema:
            $id: formA.json
            type: object
            properties:
              name:
                first:
                  type: string
                last:
                  type: string
              email:
                type: string
              phone:
                type: string
          uiSchema:
            type: VerticalLayout
            elements:
              - type: Group
                label: Name
                elements:
                  - type: Control
                    scope: "#/properties/name/first"
                  - type: Control
                    scope: "#/properties/name/last"
              - type: Control
                scope: "#/properties/email"
              - type: Control
                scope: "#/properties/phone"
          mappingToCommonGrants:
            name:
              firstName:
                field: name.first
              lastName:
                field: name.last
            emails:
              primary:
                field: email
            phones:
              primary:
                field: phone
          mappingFromCommonGrants:
            name:
              first:
                field: name.firstName
              last:
                field: name.lastName
            email:
              field: emails.primary
            phone:
              field: phones.primary
          createdAt: 2025-01-01T17:01:01
          lastModifiedAt: 2025-01-02T17:30:00
      validation:
        required:
          - formA
          - formB
    createdAt: 2025-01-01T00:00:00Z
    lastModifiedAt: 2025-01-01T00:00:00Z
description: |-
  The base model for a competition.

  A competition is an application process for a funding opportunity. It often has a
  distinct application period and set of application forms.
$defs:
  RecordCustomField:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: CustomField.yaml

The TypeSpec code for this model.

/**
 * The base model for a competition.
 *
 * A competition is an application process for a funding opportunity. It often has a
 * distinct application period and set of application forms.
 */
@example(Examples.Competition.competition)
@Versioning.added(CommonGrants.Versions.v0_2)
model CompetitionBase {
  /** Globally unique id for the competition */
  id: Types.uuid;

  /** The opportunity id for the competition */
  @Versioning.removed(CommonGrants.Versions.v0_5)
  opportunityId: Types.uuid;

  /** The opportunity this competition is for */
  @Versioning.added(CommonGrants.Versions.v0_5)
  opportunity: OppRef;

  /** The title of the competition */
  title: string;

  /** The description of the competition */
  description?: string;

  /** The instructions for the competition */
  instructions?: string | Fields.File[];

  /** The status of the competition */
  status: CompetitionStatus;

  /** The key dates in the competition timeline */
  keyDates?: CompetitionTimeline;

  /** The forms for the competition */
  forms: CompetitionForms;

  /** Accepted applicant types for the competition */
  acceptedApplicantTypes?: ApplicantType[];

  /** The custom fields for the competition */
  customFields?: Record<Fields.CustomField>;

  /** The system metadata for the competition */
  ...Fields.SystemMetadata;
}

Changelog

Version	Changes	Schema
0.5.0	Removed `opportunityId` field Added `opportunity` field	CompetitionBase.yaml
0.2.0	Added `CompetitionBase` model	CompetitionBase.yaml

Migrating from v0.4

Version	Field	Type
v0.4 and earlier	`opportunityId`	`uuid`, required
v0.5	`opportunity`	`OppRef`, required

Producers: replace opportunityId with an opportunity object. Its id is the value you sent as opportunityId, and its title is the linked opportunity’s title, so you need that title at hand when you serialize a competition. identifiers is optional.
Consumers: read the opportunity’s id from opportunity.id. Its title arrives with it, so displaying the opportunity no longer needs a second request.
Applications are unaffected: ApplicationBase keeps its competitionId and opportunityId fields.
Nested forms change too: v0.5 replaces each nested form’s name with title. See migrating forms.

v0.4 and earlier:

{
  "id": "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a",
  "opportunityId": "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6b",
  "title": "Competition 1"
}

v0.5:

{
  "id": "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a",
  "opportunity": {
    "id": "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6b",
    "title": "Small business grant program"
  },
  "title": "Competition 1"
}

Both excerpts omit the other required fields.

Authoring in TypeSpec

The TypeSpec model declares every version’s fields at once: opportunityId is removed in v0.5 and opportunity added in v0.5, so the changelog records a removal and an addition, and the unversioned model requires both.

Examples: an @example for CompetitionBase, or for a model that embeds a competition, must set both opportunityId and opportunity, even in a project pinned to an earlier version, and should give opportunity.id the same value as opportunityId. Its nested forms also need both name and title (see authoring forms in TypeSpec). The compiler checks examples against the unversioned model; each version’s OpenAPI output keeps only the field that version declares.
The unversioned JSON Schema, /schemas/yaml/CompetitionBase.yaml (the JSON Schema tab above), is that combined model, so it requires both fields. No single version’s payload satisfies it; validate a payload with the OpenAPI document for its version.

CompetitionStatus

The status of the competition.

Table

Property	Type	Required	Description
value	CompetitionStatusOptions	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

A JSON example of this model.

{
  "value": "custom",
  "customValue": "canceled",
  "description": "Competition has been canceled"
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: CompetitionStatus.yaml
type: object
properties:
  value:
    $ref: CompetitionStatusOptions.yaml
    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: open
    description: Competition is open for applications
description: The status of the competition

The TypeSpec code for this model.

/** The status of the competition */
@example(Examples.Competition.status)
@Versioning.added(CommonGrants.Versions.v0_2)
model CompetitionStatus is Fields.ExtensibleEnumT<CompetitionStatusOptions>;

Changelog

Version	Changes	Schema
0.2.0	Added `CompetitionStatus` model	CompetitionStatus.yaml

CompetitionStatusOptions

Enumeration of possible competition status values.

Table

Value	Description
open	The competition is open for applications
closed	The competition is no longer accepting applications
custom	A custom status

Formats

A JSON example of this model.

"open"

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: CompetitionStatusOptions.yaml
type: string
enum:
  - open
  - closed
  - custom
description: |-
  The set of values accepted for competition status
  - `open`: The competition is open for applications
  - `closed`: The competition is no longer accepting applications
  - `custom`: A custom status

The TypeSpec code for this model.

/** The set of values accepted for competition status
 * - `open`: The competition is open for applications
 * - `closed`: The competition is no longer accepting applications
 * - `custom`: A custom status
 */
@Versioning.added(CommonGrants.Versions.v0_2)
enum CompetitionStatusOptions {
  open,
  closed,
  custom,
}

Changelog

Version	Changes	Schema
0.2.0	Added `CompetitionStatusOptions` enum	CompetitionStatusOptions.yaml

CompetitionForms

Set of forms that need to be completed to apply to the competition.

Table

Property	Type	Required	Description
forms	record<FormBase>	Yes	The forms for the competition
validation	record	No	The validation rules for the competition forms

Formats

A JSON example of this model.

{
  "forms": {
    "formA": {
      "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "title": "Form A",
      "createdAt": "2025-01-01T00:00:00Z",
      "lastModifiedAt": "2025-01-01T00:00:00Z"
    },
    "formB": {
      "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e60",
      "title": "Form B",
      "createdAt": "2025-01-01T00:00:00Z",
      "lastModifiedAt": "2025-01-01T00:00:00Z"
    }
  },
  "validation": {
    "required": ["formA"]
  }
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: CompetitionForms.yaml
type: object
properties:
  forms:
    $ref: "#/$defs/RecordFormBase"
    description: The forms for the competition
  validation:
    $ref: "#/$defs/RecordUnknown"
    description: The validation rules for the competition forms
required:
  - forms
unevaluatedProperties:
  not: {}
examples:
  - forms:
      formA:
        id: b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a
        name: Form A
        title: Form A
        description: Form A description
        instructions: Form A instructions
        jsonSchema:
          $id: formA.json
          type: object
          properties:
            name:
              first:
                type: string
              last:
                type: string
            email:
              type: string
            phone:
              type: string
        uiSchema:
          type: VerticalLayout
          elements:
            - type: Group
              label: Name
              elements:
                - type: Control
                  scope: "#/properties/name/first"
                - type: Control
                  scope: "#/properties/name/last"
            - type: Control
              scope: "#/properties/email"
            - type: Control
              scope: "#/properties/phone"
        mappingToCommonGrants:
          name:
            firstName:
              field: name.first
            lastName:
              field: name.last
          emails:
            primary:
              field: email
          phones:
            primary:
              field: phone
        mappingFromCommonGrants:
          name:
            first:
              field: name.firstName
            last:
              field: name.lastName
          email:
            field: emails.primary
          phone:
            field: phones.primary
        createdAt: 2025-01-01T17:01:01
        lastModifiedAt: 2025-01-02T17:30:00
      formB:
        id: b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a
        name: Form A
        title: Form A
        description: Form A description
        instructions: Form A instructions
        jsonSchema:
          $id: formA.json
          type: object
          properties:
            name:
              first:
                type: string
              last:
                type: string
            email:
              type: string
            phone:
              type: string
        uiSchema:
          type: VerticalLayout
          elements:
            - type: Group
              label: Name
              elements:
                - type: Control
                  scope: "#/properties/name/first"
                - type: Control
                  scope: "#/properties/name/last"
            - type: Control
              scope: "#/properties/email"
            - type: Control
              scope: "#/properties/phone"
        mappingToCommonGrants:
          name:
            firstName:
              field: name.first
            lastName:
              field: name.last
          emails:
            primary:
              field: email
          phones:
            primary:
              field: phone
        mappingFromCommonGrants:
          name:
            first:
              field: name.firstName
            last:
              field: name.lastName
          email:
            field: emails.primary
          phone:
            field: phones.primary
        createdAt: 2025-01-01T17:01:01
        lastModifiedAt: 2025-01-02T17:30:00
    validation:
      required:
        - formA
        - formB
description: Set of forms that need to be completed to apply to the competition.
$defs:
  RecordFormBase:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: FormBase.yaml
  RecordUnknown:
    type: object
    properties: {}
    unevaluatedProperties: {}

The TypeSpec code for this model.

/** Set of forms that need to be completed to apply to the competition. */
@example(Examples.Competition.forms)
@Versioning.added(CommonGrants.Versions.v0_2)
model CompetitionForms {
  /** The forms for the competition */
  forms: Record<Models.FormBase>;

  /** The validation rules for the competition forms */
  validation?: Record<unknown>;
}

Changelog

Version	Changes	Schema
0.2.0	Added `CompetitionForms` model	CompetitionForms.yaml

CompetitionTimeline

The key dates in the competition’s timeline.

Table

Property	Type	Required	Description
openDate	Event	No	The start date of the competition
closeDate	Event	No	The end date of the competition
otherDates	record<Event>	No	The date the competition was created

Formats

A JSON example of this model.

{
  "openDate": {
    "name": "Open Date",
    "eventType": "singleDate",
    "date": "2025-01-01"
  },
  "closeDate": {
    "name": "Close Date",
    "eventType": "singleDate",
    "date": "2025-01-30"
  },
  "otherDates": {
    "reviewPeriod": {
      "name": "Application Review Period",
      "eventType": "dateRange",
      "startDate": "2025-02-01",
      "endDate": "2025-02-28"
    }
  }
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: CompetitionTimeline.yaml
type: object
properties:
  openDate:
    $ref: Event.yaml
    description: The start date of the competition
  closeDate:
    $ref: Event.yaml
    description: The end date of the competition
  otherDates:
    $ref: "#/$defs/RecordEvent"
    description: The date the competition was created
unevaluatedProperties:
  not: {}
examples:
  - openDate:
      name: Open Date
      eventType: singleDate
      date: 2025-01-01
    closeDate:
      name: Close Date
      eventType: singleDate
      date: 2025-01-30
    otherDates:
      reviewPeriod:
        name: Application Review Period
        eventType: dateRange
        startDate: 2025-02-01
        endDate: 2025-02-28
description: Key dates in the competition's timeline.
$defs:
  RecordEvent:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: Event.yaml

The TypeSpec code for this model.

/** Key dates in the competition's timeline. */
@example(Examples.Competition.keyDates)
@Versioning.added(CommonGrants.Versions.v0_2)
model CompetitionTimeline {
  /** The start date of the competition */
  openDate?: Fields.Event;

  /** The end date of the competition */
  closeDate?: Fields.Event;

  /** The date the competition was created */
  otherDates?: Record<Fields.Event>;
}

Changelog

Version	Changes	Schema
0.2.0	Added `CompetitionTimeline` model	CompetitionTimeline.yaml