Opportunity

OpportunityBase

A funding opportunity, such as a grant or loan.

Table

Property	Type	Required	Description
id	uuid	Yes	Globally unique id for the opportunity
title	string	Yes	Title or name of the funding opportunity
status	OppStatus	Yes	Status of the opportunity
description	string	Yes	Description of the opportunity's purpose and scope
funding	OppFunding	No	Details about the funding available
keyDates	OppTimeline	No	Key dates for the opportunity, such as when the application opens and closes
acceptedApplicantTypes	array<ApplicantType>	No	The type of applicant for the opportunity
source	url	No	URL for the original source of the opportunity
customFields	record<CustomField>	No	Additional custom fields specific to this opportunity
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

A JSON example of this model.

{
  "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "title": "Small business grant program",
  "status": {
    "value": "forecasted",
    "customValue": "Sample string value",
    "description": "Sample string value"
  },
  "description": "This program provides funding to small businesses to help them grow and create jobs",
  "createdAt": "2025-10-16T16:16:09.313Z",
  "lastModifiedAt": "2025-10-16T16:16:09.313Z",
  "funding": {
    "details": "Sample string value",
    "totalAmountAvailable": {
      "amount": "-100.5",
      "currency": "Sample string value"
    },
    "minAwardAmount": {
      "amount": "-100.5",
      "currency": "Sample string value"
    },
    "maxAwardAmount": {
      "amount": "-100.5",
      "currency": "Sample string value"
    },
    "minAwardCount": 10,
    "maxAwardCount": 10,
    "estimatedAwardCount": 10
  },
  "keyDates": {
    "postDate": {
      "name": "Sample string value",
      "eventType": "singleDate",
      "date": "2025-10-16",
      "description": "Sample string value",
      "time": "16:16:09"
    },
    "closeDate": {
      "name": "Sample string value",
      "eventType": "singleDate",
      "date": "2025-10-16",
      "description": "Sample string value",
      "time": "16:16:09"
    },
    "otherDates": {
      "property": {
        "name": "Sample string value",
        "eventType": "singleDate",
        "date": "2025-10-16",
        "description": "Sample string value",
        "time": "16:16:09"
      }
    }
  },
  "acceptedApplicantTypes": [
    {
      "value": "individual",
      "customValue": "Sample string value",
      "description": "Sample string value"
    }
  ],
  "source": "https://example.com",
  "customFields": {
    "property": {
      "name": "Sample string value",
      "fieldType": "string",
      "value": "Sample value",
      "schema": "https://example.com",
      "description": "Sample string value"
    }
  }
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OpportunityBase.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: Globally unique id for the opportunity
  title:
    type: string
    examples:
      - Small business grant program
    description: Title or name of the funding opportunity
  status:
    $ref: OppStatus.yaml
    description: Status of the opportunity
  description:
    type: string
    examples:
      - This program provides funding to small businesses to help them grow and create jobs
    description: Description of the opportunity's purpose and scope
  funding:
    $ref: OppFunding.yaml
    description: Details about the funding available
  keyDates:
    $ref: OppTimeline.yaml
    description: Key dates for the opportunity, such as when the application opens and closes
  acceptedApplicantTypes:
    type: array
    items:
      $ref: ApplicantType.yaml
    description: The type of applicant for the opportunity
  source:
    type: string
    format: uri
    description: URL for the original source of the opportunity
  customFields:
    $ref: "#/$defs/RecordCustomField"
    description: Additional custom fields specific to this opportunity
  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
  - title
  - status
  - description
  - createdAt
  - lastModifiedAt
description: A funding opportunity
$defs:
  RecordCustomField:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: CustomField.yaml

The TypeSpec code for this model.

model OpportunityBase {
  /** Globally unique id for the opportunity */
  @visibility(Lifecycle.Read)
  id: uuid;

  /** Title or name of the funding opportunity */
  @example("Small business grant program")
  title: string;

  /** Status of the opportunity */
  status: OppStatus;

  /** Description of the opportunity's purpose and scope */
  @example("This program provides funding to small businesses to help them grow and create jobs")
  description: string;

  /** Details about the funding available */
  funding?: OppFunding;

  /** Key dates for the opportunity, such as when the application opens and closes */
  keyDates?: OppTimeline;

  /** The type of applicant for the opportunity */
  @Versioning.added(CommonGrants.Versions.v0_2)
  acceptedApplicantTypes?: ApplicantType[];

  /** URL for the original source of the opportunity */
  source?: url;

  /** Additional custom fields specific to this opportunity */

The Python code for this model.

class OpportunityBase(SystemMetadata, CommonGrantsBaseModel):
    """Base model for a funding opportunity with all core fields."""

    id: UUID = Field(..., description="Globally unique id for the opportunity")
    title: str = Field(..., description="Title or name of the funding opportunity")
    status: OppStatus = Field(..., description="Status of the opportunity")
    description: str = Field(
        ...,
        description="Description of the opportunity's purpose and scope",
    )
    funding: Optional[OppFunding] = Field(
        default=None,
        description="Details about the funding available",
    )
    key_dates: Optional[OppTimeline] = Field(
        default=None,
        alias="keyDates",
        description="Key dates for the opportunity, such as when the application opens and closes",
    )
    source: Optional[HttpUrl] = Field(
        default=None,
        description="URL for the original source of the opportunity",
    )
    custom_fields: Optional[dict[str, CustomField]] = Field(
        default=None,
        alias="customFields",
        description="Additional custom fields specific to this opportunity",
    )

OpportunityDetails

A funding opportunity with additional details, like available competitions.

Table

Property	Type	Required	Description
id	uuid	Yes	Globally unique id for the opportunity
title	string	Yes	Title or name of the funding opportunity
status	OppStatus	Yes	Status of the opportunity
description	string	Yes	Description of the opportunity's purpose and scope
funding	OppFunding	No	Details about the funding available
keyDates	OppTimeline	No	Key dates for the opportunity, such as when the application opens and closes
acceptedApplicantTypes	array<ApplicantType>	No	The type of applicant for the opportunity
source	url	No	URL for the original source of the opportunity
customFields	record<CustomField>	No	Additional custom fields specific to this opportunity
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.
competitions	array<CompetitionBase>	No	The competitions associated with the opportunity

Formats

A JSON example of this model.

{
  "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "title": "Small business grant program",
  "status": {
    "value": "forecasted",
    "customValue": "Sample string value",
    "description": "Sample string value"
  },
  "description": "This program provides funding to small businesses to help them grow and create jobs",
  "createdAt": "2025-10-16T16:16:09.362Z",
  "lastModifiedAt": "2025-10-16T16:16:09.362Z",
  "funding": {
    "details": "Sample string value",
    "totalAmountAvailable": {
      "amount": "-100.5",
      "currency": "Sample string value"
    },
    "minAwardAmount": {
      "amount": "-100.5",
      "currency": "Sample string value"
    },
    "maxAwardAmount": {
      "amount": "-100.5",
      "currency": "Sample string value"
    },
    "minAwardCount": 10,
    "maxAwardCount": 10,
    "estimatedAwardCount": 10
  },
  "keyDates": {
    "postDate": {
      "name": "Sample string value",
      "eventType": "singleDate",
      "date": "2025-10-16",
      "description": "Sample string value",
      "time": "16:16:09"
    },
    "closeDate": {
      "name": "Sample string value",
      "eventType": "singleDate",
      "date": "2025-10-16",
      "description": "Sample string value",
      "time": "16:16:09"
    },
    "otherDates": {
      "property": {
        "name": "Sample string value",
        "eventType": "singleDate",
        "date": "2025-10-16",
        "description": "Sample string value",
        "time": "16:16:09"
      }
    }
  },
  "acceptedApplicantTypes": [
    {
      "value": "individual",
      "customValue": "Sample string value",
      "description": "Sample string value"
    }
  ],
  "source": "https://example.com",
  "customFields": {
    "property": {
      "name": "Sample string value",
      "fieldType": "string",
      "value": "Sample value",
      "schema": "https://example.com",
      "description": "Sample string value"
    }
  },
  "competitions": [
    {
      "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
      "opportunityId": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
      "title": "Sample string value",
      "status": {
        "value": "open",
        "customValue": "Sample string value",
        "description": "Sample string value"
      },
      "forms": {
        "forms": {
          "property": {
            "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
            "name": "Sample string value",
            "createdAt": "2025-10-16T16:16:09.362Z",
            "lastModifiedAt": "2025-10-16T16:16:09.362Z",
            "description": "Sample string value",
            "version": "Sample string value",
            "instructions": "Sample string value",
            "jsonSchema": {},
            "uiSchema": {},
            "mappingToCommonGrants": {},
            "mappingFromCommonGrants": {},
            "customFields": {
              "property": {
                "name": "Sample string value",
                "fieldType": "string",
                "value": "Sample value",
                "schema": "https://example.com",
                "description": "Sample string value"
              }
            }
          }
        },
        "validation": {}
      },
      "createdAt": "2025-10-16T16:16:09.362Z",
      "lastModifiedAt": "2025-10-16T16:16:09.362Z",
      "description": "Sample string value",
      "instructions": "Sample string value",
      "keyDates": {
        "openDate": {
          "name": "Sample string value",
          "eventType": "singleDate",
          "date": "2025-10-16",
          "description": "Sample string value",
          "time": "16:16:09"
        },
        "closeDate": {
          "name": "Sample string value",
          "eventType": "singleDate",
          "date": "2025-10-16",
          "description": "Sample string value",
          "time": "16:16:09"
        },
        "otherDates": {
          "property": {
            "name": "Sample string value",
            "eventType": "singleDate",
            "date": "2025-10-16",
            "description": "Sample string value",
            "time": "16:16:09"
          }
        }
      },
      "acceptedApplicantTypes": [
        {
          "value": "individual",
          "customValue": "Sample string value",
          "description": "Sample string value"
        }
      ],
      "customFields": {
        "property": {
          "name": "Sample string value",
          "fieldType": "string",
          "value": "Sample value",
          "schema": "https://example.com",
          "description": "Sample string value"
        }
      }
    }
  ]
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OpportunityDetails.yaml
type: object
properties:
  competitions:
    type: array
    items:
      $ref: CompetitionBase.yaml
    description: The competitions associated with the opportunity
allOf:
  - $ref: OpportunityBase.yaml
unevaluatedProperties:
  not: {}
description: A funding opportunity with additional details, like available competitions.

The TypeSpec code for this model.

/** A funding opportunity with additional details, like available competitions. */
@Versioning.added(CommonGrants.Versions.v0_2)
model OpportunityDetails extends OpportunityBase {
  /** The competitions associated with the opportunity */
  competitions?: CompetitionBase[];
}

OppStatus

The status of an opportunity, such as whether it is accepting applications.

Table

Property	Type	Required	Description
value	OppStatusOptions	Yes	The status of the opportunity, from a predefined set of options
customValue	string	No	A custom value for the status
description	string	No	A human-readable description of the status

Formats

A JSON example of this model.

{
  "value": "forecasted",
  "customValue": "Sample string value",
  "description": "Sample string value"
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OppStatus.yaml
type: object
properties:
  value:
    $ref: OppStatusOptions.yaml
    description: The status of the opportunity, from a predefined set of options
  customValue:
    type: string
    description: A custom value for the status
  description:
    type: string
    description: A human-readable description of the status
required:
  - value
unevaluatedProperties:
  not: {}
examples:
  - value: open
    description: The opportunity is currently accepting applications
  - value: custom
    customValue: archived
    description: The opportunity is archived and shouldn't appear in search results
description: The status of the opportunity

The TypeSpec code for this model.

// ########################################

/** The status of the opportunity */
@example(Examples.OppStatus.custom)
@example(Examples.OppStatus.default)
model OppStatus {
  /** The status of the opportunity, from a predefined set of options */
  value: OppStatusOptions;

  /** A custom value for the status */
  customValue?: string;

  /** A human-readable description of the status */

The Python code for this model.

class OppStatus(CommonGrantsBaseModel):
    """Represents the status of a funding opportunity."""

    value: OppStatusOptions = Field(
        ...,
        description="The status value, from a predefined set of options",
    )
    custom_value: Optional[str] = Field(
        default=None,
        alias="customValue",
        description="A custom status value",
    )
    description: Optional[str] = Field(
        default=None,
        description="A human-readable description of the status",
    )

OppStatusOptions

The set of values accepted for opportunity status.

Table

Value	Description
forecasted	The opportunity is forecasted and not yet open for applications
open	The opportunity is open for applications
closed	The opportunity is no longer accepting applications
custom	A custom status

Formats

A JSON example of this model.

"forecasted"

The JSON Schema for this model.

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

The TypeSpec code for this model.

 * - `closed`: The opportunity is no longer accepting applications
 * - `custom`: A custom status
 */
enum OppStatusOptions {
  forecasted,
  open,
  closed,

The Python code for this model.

class OppStatusOptions(StrEnum):
    """The status of the opportunity."""

    FORECASTED = "forecasted"
    OPEN = "open"
    CUSTOM = "custom"
    CLOSED = "closed"

    def __lt__(self, other):
        """Define the order of status transitions."""
        order = {
            self.FORECASTED: 0,
            self.OPEN: 1,
            self.CUSTOM: 2,
            self.CLOSED: 3,
        }
        return order[self] < order[other]

OppFunding

Details about the funding available for an opportunity.

Table

Property	Type	Required	Description
details	string	No	Details about the funding available for this opportunity that don't fit other fields
totalAmountAvailable	Money	No	Total amount of funding available for this opportunity
minAwardAmount	Money	No	Minimum amount of funding granted per award
maxAwardAmount	Money	No	Maximum amount of funding granted per award
minAwardCount	integer	No	Minimum number of awards granted
maxAwardCount	integer	No	Maximum number of awards granted
estimatedAwardCount	integer	No	Estimated number of awards that will be granted

Formats

A JSON example of this model.

{
  "details": "Sample string value",
  "totalAmountAvailable": {
    "amount": "-100.5",
    "currency": "Sample string value"
  },
  "minAwardAmount": {
    "amount": "-100.5",
    "currency": "Sample string value"
  },
  "maxAwardAmount": {
    "amount": "-100.5",
    "currency": "Sample string value"
  },
  "minAwardCount": 10,
  "maxAwardCount": 10,
  "estimatedAwardCount": 10
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OppFunding.yaml
type: object
properties:
  details:
    type: string
    description: Details about the funding available for this opportunity that don't fit other fields
  totalAmountAvailable:
    $ref: Money.yaml
    description: Total amount of funding available for this opportunity
  minAwardAmount:
    $ref: Money.yaml
    description: Minimum amount of funding granted per award
  maxAwardAmount:
    $ref: Money.yaml
    description: Maximum amount of funding granted per award
  minAwardCount:
    type: integer
    description: Minimum number of awards granted
  maxAwardCount:
    type: integer
    description: Maximum number of awards granted
  estimatedAwardCount:
    type: integer
    description: Estimated number of awards that will be granted
unevaluatedProperties:
  not: {}
examples:
  - totalAmountAvailable:
      amount: "1000000.00"
      currency: USD
    minAwardAmount:
      amount: "10000.00"
      currency: USD
    maxAwardAmount:
      amount: "50000.00"
      currency: USD
    minAwardCount: 5
    maxAwardCount: 20
    estimatedAwardCount: 10
  - details: This opportunity has a total funding limit of $1,000,000 but no specific award range
    totalAmountAvailable:
      amount: "1000000.00"
      currency: USD
    estimatedAwardCount: 10
  - details: We'll be awarding between $10,000 and $50,000 per recipient
    minAwardAmount:
      amount: "10000.00"
      currency: USD
    maxAwardAmount:
      amount: "50000.00"
      currency: USD
    minAwardCount: 5
    maxAwardCount: 20
description: Details about the funding available for this opportunity

The TypeSpec code for this model.

/** Details about the funding available for this opportunity */
@example(
  Examples.Funding.awardRange,
  #{ title: "Award range but no total limit" }
)
@example(
  Examples.Funding.onlyLimit,
  #{ title: "Total funding limit but no award range" }
)
@example(Examples.Funding.allFields, #{ title: "All fields defined" })
model OppFunding {
  /** Details about the funding available for this opportunity that don't fit other fields */
  details?: string;

  /** Total amount of funding available for this opportunity */
  totalAmountAvailable?: Money;

  /** Minimum amount of funding granted per award */
  minAwardAmount?: Money;

  /** Maximum amount of funding granted per award */
  maxAwardAmount?: Money;

  /** Minimum number of awards granted */
  minAwardCount?: integer;

  /** Maximum number of awards granted */
  maxAwardCount?: integer;

The Python code for this model.

class OppFunding(CommonGrantsBaseModel):
    """Details about the funding available for an opportunity."""

    details: Optional[str] = Field(
        default=None,
        description="Details about the funding available for this opportunity that don't fit other fields",
    )
    total_amount_available: Optional[Money] = Field(
        default=None,
        alias="totalAmountAvailable",
        description="Total amount of funding available for this opportunity",
    )
    min_award_amount: Optional[Money] = Field(
        default=None,
        alias="minAwardAmount",
        description="Minimum amount of funding granted per award",
    )
    max_award_amount: Optional[Money] = Field(
        default=None,
        alias="maxAwardAmount",
        description="Maximum amount of funding granted per award",
    )
    min_award_count: Optional[int] = Field(
        default=None,
        alias="minAwardCount",
        description="Minimum number of awards granted",
    )
    max_award_count: Optional[int] = Field(
        default=None,
        alias="maxAwardCount",
        description="Maximum number of awards granted",
    )
    estimated_award_count: Optional[int] = Field(
        default=None,
        alias="estimatedAwardCount",
        description="Estimated number of awards that will be granted",
    )

OppTimeline

Key dates in the opportunity’s timeline, such as when the application opens and closes.

Table

Property	Type	Required	Description
postDate	Event	No	The date (and time) at which the opportunity is posted
closeDate	Event	No	The date (and time) at which the opportunity closes
otherDates	record<Event>	No	An optional map of other key dates or events in the opportunity timeline Examples might include a deadline for questions, anticipated award date, etc.

Formats

A JSON example of this model.

{
  "postDate": {
    "name": "Sample string value",
    "eventType": "singleDate",
    "date": "2025-10-16",
    "description": "Sample string value",
    "time": "16:16:09"
  },
  "closeDate": {
    "name": "Sample string value",
    "eventType": "singleDate",
    "date": "2025-10-16",
    "description": "Sample string value",
    "time": "16:16:09"
  },
  "otherDates": {
    "property": {
      "name": "Sample string value",
      "eventType": "singleDate",
      "date": "2025-10-16",
      "description": "Sample string value",
      "time": "16:16:09"
    }
  }
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OppTimeline.yaml
type: object
properties:
  postDate:
    $ref: Event.yaml
    description: The date (and time) at which the opportunity is posted
  closeDate:
    $ref: Event.yaml
    description: The date (and time) at which the opportunity closes
  otherDates:
    $ref: "#/$defs/RecordEvent"
    description: |-
      An optional map of other key dates or events in the opportunity timeline

      Examples might include a deadline for questions, anticipated award date, etc.
unevaluatedProperties:
  not: {}
examples:
  - postDate:
      name: Application posted date
      eventType: singleDate
      date: 2024-01-15
      description: Opportunity is posted publicly
    closeDate:
      name: Opportunity close date
      eventType: singleDate
      date: 2024-12-31
      time: 17:00:00
      description: Opportunity closes for all applications
    otherDates:
      anticipatedAward:
        name: Anticipated award date
        eventType: singleDate
        date: 2025-03-15
        description: When we expect to announce awards for this opportunity.
      applicationPeriod:
        name: Application period
        eventType: dateRange
        startDate: 2024-01-01
        endDate: 2024-01-31
        endTime: 17:00:00
        description: Primary application period for the grant opportunity
      performancePeriod:
        name: Period of Performance
        eventType: dateRange
        startDate: 2024-01-01
        endDate: 2024-12-31
        description: Period of performance for the grant
      infoSessions:
        name: Info sessions
        eventType: other
        details: Every other Tuesday
        description: Info sessions for the opportunity
description: Key dates and events in the opportunity's timeline, such as when the opportunity is posted and closes
$defs:
  RecordEvent:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: Event.yaml

The TypeSpec code for this model.

/** Key dates and events in the opportunity's timeline, such as when the opportunity is posted and closes */
@example(Examples.Timeline.opportunity)
model OppTimeline {
  /** The date (and time) at which the opportunity is posted */
  postDate?: Event;

  /** The date (and time) at which the opportunity closes */
  closeDate?: Event;

  /** An optional map of other key dates or events in the opportunity timeline
   *
   * Examples might include a deadline for questions, anticipated award date, etc.
   */
  otherDates?: Record<Event>;
}

The Python code for this model.

class OppTimeline(CommonGrantsBaseModel):
    """Key dates and events in the lifecycle of an opportunity."""

    post_date: Optional[Event] = Field(
        default=None,
        alias="postDate",
        description="The date (and time) at which the opportunity is posted",
    )
    close_date: Optional[Event] = Field(
        default=None,
        alias="closeDate",
        description="The date (and time) at which the opportunity closes",
    )
    other_dates: Optional[dict[str, Event]] = Field(
        default=None,
        alias="otherDates",
        description="An optional map of other key dates or events in the opportunity timeline",
    )