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
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": "049b4b15-f219-4037-901e-cd95ac32fbc8",
  "title": "Healthcare Innovation Research Grant",
  "description": "Funding for innovative healthcare delivery solutions",
  "status": {
    "value": "open",
    "description": "Opportunity is actively accepting applications"
  },
  "funding": {
    "totalAmountAvailable": {
      "amount": "1000000.00",
      "currency": "USD"
    },
    "minAwardAmount": {
      "amount": "10000.00",
      "currency": "USD"
    },
    "maxAwardAmount": {
      "amount": "50000.00",
      "currency": "USD"
    },
    "minAwardCount": 5,
    "maxAwardCount": 20,
    "estimatedAwardCount": 10
  },
  "keyDates": {
    "postDate": {
      "name": "Opportunity posted",
      "eventType": "singleDate",
      "date": "2024-03-01",
      "description": "Opportunity is posted publicly"
    },
    "closeDate": {
      "name": "Opportunity closed",
      "eventType": "singleDate",
      "date": "2024-04-30",
      "description": "Opportunity is closed to 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-03-01",
        "endDate": "2024-04-30",
        "description": "Applications are accepted during this period"
      }
    }
  },
  "source": "https://grants.gov/opportunity/123",
  "customFields": {
    "programArea": {
      "name": "programArea",
      "type": "string",
      "value": "Healthcare Technology",
      "description": "The primary focus area for this grant"
    },
    "eligibilityType": {
      "name": "eligibilityType",
      "type": "string",
      "value": "Non-profit organizations",
      "description": "The type of organizations eligible to apply"
    }
  },
  "createdAt": "2024-02-28T12:00:00Z",
  "lastModifiedAt": "2024-02-28T12:00:00Z"
}

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
  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;

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

  /** Additional custom fields specific to this opportunity */
  customFields?: Record<CustomField>;

  // Spreads the fields from the Metadata model into the Opportunity model
  ...SystemMetadata;

The Python code for this model.

from datetime import date, datetime, time
from uuid import UUID
from common_grants_sdk.schemas.fields import Event, Money, CustomField, CustomFieldType
from common_grants_sdk.schemas.models import (
    OpportunityBase,
    OppFunding,
    OppStatus,
    OppStatusOptions,
    OppTimeline,
)

opportunity = OpportunityBase(
    id=UUID("049b4b15-f219-4037-901e-cd95ac32fbc8"),
    title="Healthcare Innovation Research Grant",
    description="Funding for innovative healthcare delivery solutions",
    status=OppStatus(
        value=OppStatusOptions.OPEN,
        description="Opportunity is actively accepting applications"
    ),
    funding=OppFunding(
        total_amount_available=Money(amount="1000000.00", currency="USD"),
        min_award_amount=Money(amount="10000.00", currency="USD"),
        max_award_amount=Money(amount="50000.00", currency="USD"),
        min_award_count=5,
        max_award_count=20,
        estimated_award_count=10
    ),
    key_dates=OppTimeline(
        app_opens=Event(
            name="Application Opens",
            date=date(2024, 3, 1),
            description="Applications begin being accepted"
        ),
        app_deadline=Event(
            name="Application Deadline",
            date=date(2024, 4, 30),
            time=time(17, 0, 0),
            description="Final deadline for all submissions"
        ),
        other_dates={
            "anticipatedAward": Event(
                name="Anticipated award date",
                date=date(2025, 3, 15),
                description="When we expect to announce awards for this opportunity."
            )
        }
    ),
    source="https://grants.gov/opportunity/123",
    custom_fields={
        "programArea": CustomField(
            name="programArea",
            type=CustomFieldType.STRING,
            value="Healthcare Technology",
            description="The primary focus area for this grant"
        ),
        "eligibilityType": CustomField(
            name="eligibilityType",
            type=CustomFieldType.STRING,
            value="Non-profit organizations",
            description="The type of organizations eligible to apply"
        )
    },
    created_at=datetime(2024, 2, 28, 12, 0, 0),
    last_modified_at=datetime(2024, 2, 28, 12, 0, 0)
)

OppStatus

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

Table

Property	Type	Required	Description
value	OppStatusOptions	Yes	The status value
customValue	string	No	The display value for a custom status
description	string	No	A human-readable description of the status

Formats

A JSON example of this model.

{
  "value": "open",
  "description": "Opportunity is actively accepting applications"
}

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 value, from a predefined set of options
  customValue:
    type: string
    description: A custom status value
  description:
    type: string
    description: A human-readable description of the status
required:
  - value
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.

model OppStatus {
  /** The status value, from a predefined set of options */
  value: OppStatusOptions;

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

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

// ########################################
// Opportunity status model examples

The Python code for this model.

from common_grants_sdk.schemas.models import OppStatus, OppStatusOptions

status = OppStatus(
    value=OppStatusOptions.OPEN,
    description="Opportunity is actively accepting applications"
)

custom_status = OppStatus(
    value=OppStatusOptions.CUSTOM,
    custom_value="review",
    description="Opportunity is in review by the program team"
)

OppStatusOptions

The set of values accepted for opportunity status.

Table

Value	Description
forecasted	Opportunity is anticipated, but not yet accepting applications
open	Opportunity is actively accepting applications
closed	Opportunity is no longer accepting applications
custom	Custom opportunity status defined within the record

Formats

A JSON example of this model.

"open"

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

The TypeSpec code for this model.

  open,
  closed,
  custom,
}

// ########################################
// Opportunity status model

The Python code for this model.

from common_grants_sdk.schemas.models import OppStatusOptions

status_value = OppStatusOptions.OPEN

OppFunding

Details about the funding available for an opportunity.

Table

Property	Type	Required	Description
totalAmountAvailable	Money	No	Total amount of funding available
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.

{
  "totalAmountAvailable": {
    "amount": "1000000.00",
    "currency": "USD"
  },
  "minAwardAmount": {
    "amount": "10000.00",
    "currency": "USD"
  },
  "maxAwardAmount": {
    "amount": "50000.00",
    "currency": "USD"
  },
  "minAwardCount": 5,
  "maxAwardCount": 20,
  "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
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.

from common_grants_sdk.schemas.fields import Money
from common_grants_sdk.schemas.models import OppFunding

funding = OppFunding(
    total_amount_available=Money(amount="1000000.00", currency="USD"),
    min_award_amount=Money(amount="10000.00", currency="USD"),
    max_award_amount=Money(amount="50000.00", currency="USD"),
    min_award_count=5,
    max_award_count=20,
    estimated_award_count=10
)

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 in the opportunity timeline

Formats

A JSON example of this model.

{
  "postDate": {
    "name": "Opportunity posted",
    "eventType": "singleDate",
    "date": "2024-03-01",
    "description": "Applications begin being accepted"
  },
  "closeDate": {
    "name": "Opportunity closed",
    "eventType": "singleDate",
    "date": "2024-04-30",
    "time": "17:00:00",
    "description": "Final deadline for all submissions"
  },
  "otherDates": {
    "applicationPeriod": {
      "name": "Application period",
      "eventType": "dateRange",
      "startDate": "2024-03-01",
      "endDate": "2024-04-30",
      "description": "Applications are accepted during this period"
    },
    "infoSessions": {
      "name": "Information session",
      "eventType": "other",
      "details": "Every Tuesday at 10:00 AM in March",
      "description": "Information session about the opportunity"
    },
    "anticipatedAward": {
      "name": "Anticipated award date",
      "eventType": "singleDate",
      "date": "2025-03-15",
      "description": "When we expect to announce awards for this opportunity."
    }
  }
}

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.
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.

from datetime import date, time
from common_grants_sdk.schemas.fields import Event
from common_grants_sdk.schemas.models import OppTimeline

timeline = OppTimeline(
    app_opens=Event(
        name="Application Opens",
        date=date(2024, 3, 1),
        description="Applications begin being accepted"
    ),
    app_deadline=Event(
        name="Application Deadline",
        date=date(2024, 4, 30),
        time=time(17, 0, 0),
        description="Final deadline for all submissions"
    ),
    other_dates={
        "anticipatedAward": Event(
            name="Anticipated award date",
            date=date(2025, 3, 15),
            description="When we expect to announce awards for this opportunity."
        )
    }
)