Opportunity

OpportunityBase

A funding opportunity, such as a grant or loan. It shares its identity fields with OppRef, including the OppIds collection under identifiers added in v0.5. Since v0.5 it also records who is offering the money under funders, an OrgRefCollection, which replaces the deprecated agency custom field for opportunities.

Table

Property	Type	Required	Description
id	uuid	Yes	Globally unique id for the opportunity
title	string	Yes	Title or name of the funding opportunity
identifiers	OppIds	No	System and registry-specific identifiers for the 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
funders	OrgRefCollection	No	Organization(s) offering the funding for this opportunity
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",
  "identifiers": {
    "systemId": {
      "registry": {
        "code": "opp:grants.gov:system"
      },
      "id": "018f2e77-3a4b-7c1d-9e2f-abcdef123456"
    },
    "opp:us:fon": {
      "registry": {
        "code": "opp:us:fon",
        "url": "https://commongrants.org/registries/opp-us-fon"
      },
      "id": "HHS-2026-ACF-OCC-YD-0001"
    },
    "opp:us:aln": {
      "registry": {
        "code": "opp:us:aln",
        "url": "https://commongrants.org/registries/opp-us-aln"
      },
      "id": "93.575"
    }
  },
  "status": {
    "value": "open",
    "description": "The opportunity is currently accepting applications"
  },
  "description": "This program provides funding to small businesses to help them grow and create jobs",
  "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
  },
  "funders": {
    "primary": {
      "id": "018f2e77-4b5c-7d2e-9f3a-bcdef1234567",
      "name": "Health Resources and Services Administration",
      "identifiers": {
        "otherIds": {
          "org:grants.gov:agency": {
            "registry": {
              "code": "org:grants.gov:agency"
            },
            "id": "HRSA"
          }
        }
      }
    }
  },
  "keyDates": {
    "postDate": {
      "name": "Opportunity 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"
      }
    }
  },
  "acceptedApplicantTypes": [
    {
      "value": "individual",
      "description": "An individual applicant"
    }
  ],
  "source": "http://example.com",
  "customFields": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "lastModifiedAt": "2019-08-24T14:15:22Z"
}

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
  identifiers:
    $ref: OppIds.yaml
    description: System and registry-specific identifiers for the 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
  funders:
    $ref: OrgRefCollection.yaml
    examples:
      - primary:
          id: 018f2e77-4b5c-7d2e-9f3a-bcdef1234567
          name: Health Resources and Services Administration
          identifiers:
            otherIds:
              org:grants.gov:agency:
                registry:
                  code: org:grants.gov:agency
                id: HRSA
    description: Organization(s) offering the funding for this opportunity
  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.

@doc("A funding opportunity")
@Versioning.added(CommonGrants.Versions.v0_1)
model OpportunityBase {
  // Identity fields shared with the OppRef reference model
  ...OppRef;

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

  /** Organization(s) offering the funding for this opportunity */
  @example(Examples.OrgRef.funders)
  @Versioning.added(CommonGrants.Versions.v0_5)
  funders?: OrgRefCollection;

  /** 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 */
  customFields?: Record<CustomField>;

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

The Python code for this model.

from .opp_status import OppStatus
from .opp_timeline import OppTimeline
from common_grants_sdk.utils.custom_fields import (
    add_custom_fields,
    get_custom_field_value,
)

if TYPE_CHECKING:
    from common_grants_sdk.extensions.specs import CustomFieldSpec

V = TypeVar("V")  # Unbound to support both BaseModel subclasses and primitives

# The opportunity's custom-fields container. Defaults to the protocol's untyped
# representation (``dict[str, CustomField]``), so the bare ``OpportunityBase``
# behaves exactly as a concrete model; plugin authors parameterize it with a typed
# ``CustomFieldSet`` (``OpportunityBase[OpportunityFields]``) for concrete access.
CF = te.TypeVar("CF", default="dict[str, CustomField]")


class OpportunityBase(SystemMetadata, CommonGrantsBaseModel, Generic[CF]):
    """Base model for a funding opportunity, generic over its custom-fields container."""

    model_config = ConfigDict(populate_by_name=True)

    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(

The TypeScript code for this model.

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

export const OpportunityBaseSchema = z
  .object({
    /** Globally unique id for the Opportunity */
    id: UuidSchema,

    /** Title or name of the funding Opportunity */
    title: z.string(),

    /** Status of the Opportunity */
    status: OppStatusSchema,

    /** Description of the Opportunity's purpose and scope */
    description: z.string(),

    /** Details about the funding available */
    funding: OppFundingSchema.nullish(),

    /**
     * Organization(s) offering the funding for this Opportunity: one required
     * primary organization plus any others keyed by role.
     */
    funders: OrgRefCollectionSchema.optional(),

    /** Key dates for the Opportunity */
    keyDates: OppTimelineSchema.nullish(),

    /** The type of applicant for the opportunity */
    acceptedApplicantTypes: z.array(ApplicantTypeSchema).nullish(),

    /** URL for the original source of the Opportunity */
    source: z.url().nullish(),

    /** Additional custom fields specific to this Opportunity */
    customFields: z.record(z.string(), CustomFieldSchema).nullish(),

    /**
     * System and registry-specific identifiers for the Opportunity, sealed to
     * the base registries (FON, ALN) plus `systemId` and `otherIds`.
     */
    identifiers: OppIdsSchema.optional(),
  })
  .extend(SystemMetadataSchema.shape);

// ############################################################################
// Opportunity details model
// ############################################################################

Changelog

Version	Changes	Schema
0.5.0	Added `identifiers` field Added `funders` field	OpportunityBase.yaml
0.2.0	Added `acceptedApplicantTypes` field	OpportunityBase.yaml
0.1.0	Added `OpportunityBase` model	OpportunityBase.yaml

OpportunityDetails

A funding opportunity with additional details, like available competitions. Since v0.5 it also lists the awards the opportunity produced under awards, a list of AwdRef entries, so a consumer can see what an opportunity funded without searching awards by opportunityId.

An entry is a reference, not the award record: GET /awards/<id> is the canonical record only where an implementation serves the award routes, and otherwise the entry’s identifiers, where the publisher supplies them, are the key for joining the award in another system. A consumer must not assume a reference can be dereferenced through this API. An absent awards means the implementation does not publish this link for the record, while an empty array means it does and no awards are known. Entries carry no ordering guarantee.

Table

Property	Type	Required	Description
id	uuid	Yes	Globally unique id for the opportunity
title	string	Yes	Title or name of the funding opportunity
identifiers	OppIds	No	System and registry-specific identifiers for the 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
funders	OrgRefCollection	No	Organization(s) offering the funding for this opportunity
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
awards	array<AwdRef>	No	Awards that resulted from this opportunity, as references. Each entry references an award that resulted from this opportunity; the award's `opportunity.id`, when it is published, is this record's `id`. An entry is a reference, not the award record: `GET /awards/<id>` is the canonical record only where an implementation serves the award routes, and otherwise the entry's `identifiers`, where the publisher supplies them, are the key for joining the award in another system. A consumer must not assume a reference can be dereferenced through this API. Absent means the implementation does not publish this link for the record, and an empty array means the link is published and no awards are known. Entries carry no ordering guarantee.

Formats

A JSON example of this model.

{
  "competitions": [
    {
      "id": "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a",
      "opportunity": {
        "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
        "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"
    }
  ],
  "awards": [
    {
      "id": "01912a8b-7c3d-7894-abcd-ef1234567890",
      "title": "Community Health Center Capital Improvement Grant",
      "identifiers": {
        "systemId": {
          "registry": {
            "code": "awd:grants.gov:system"
          },
          "id": "01912a8b-7c3d-7894-abcd-ef1234567890"
        },
        "awd:us:fain": {
          "registry": {
            "code": "awd:us:fain",
            "url": "https://commongrants.org/registries/awd-us-fain"
          },
          "id": "H80CS00001"
        }
      }
    }
  ],
  "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "title": "Small business grant program",
  "identifiers": {
    "systemId": {
      "registry": {
        "code": "opp:grants.gov:system"
      },
      "id": "018f2e77-3a4b-7c1d-9e2f-abcdef123456"
    },
    "opp:us:fon": {
      "registry": {
        "code": "opp:us:fon",
        "url": "https://commongrants.org/registries/opp-us-fon"
      },
      "id": "HHS-2026-ACF-OCC-YD-0001"
    },
    "opp:us:aln": {
      "registry": {
        "code": "opp:us:aln",
        "url": "https://commongrants.org/registries/opp-us-aln"
      },
      "id": "93.575"
    }
  },
  "status": {
    "value": "open",
    "description": "The opportunity is currently accepting applications"
  },
  "description": "This program provides funding to small businesses to help them grow and create jobs",
  "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
  },
  "funders": {
    "primary": {
      "id": "018f2e77-4b5c-7d2e-9f3a-bcdef1234567",
      "name": "Health Resources and Services Administration",
      "identifiers": {
        "otherIds": {
          "org:grants.gov:agency": {
            "registry": {
              "code": "org:grants.gov:agency"
            },
            "id": "HRSA"
          }
        }
      }
    }
  },
  "keyDates": {
    "postDate": {
      "name": "Opportunity 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"
      }
    }
  },
  "acceptedApplicantTypes": [
    {
      "value": "individual",
      "description": "An individual applicant"
    }
  ],
  "source": "http://example.com",
  "customFields": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "lastModifiedAt": "2019-08-24T14:15:22Z"
}

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
  awards:
    type: array
    items:
      $ref: AwdRef.yaml
    description: |-
      Awards that resulted from this opportunity, as references.

      Each entry references an award that resulted from this opportunity; the
      award's `opportunity.id`, when it is published, is this record's `id`.
      An entry is a reference, not the award record: `GET /awards/<id>` is the
      canonical record only where an implementation serves the award routes,
      and otherwise the entry's `identifiers`, where the publisher supplies
      them, are the key for joining the award in another system. A consumer
      must not assume a reference can be dereferenced through this API.

      Absent means the implementation does not publish this link for the
      record, and an empty array means the link is published and no awards are
      known. Entries carry no ordering guarantee.
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[];

  /** Awards that resulted from this opportunity, as references.
   *
   * Each entry references an award that resulted from this opportunity; the
   * award's `opportunity.id`, when it is published, is this record's `id`.
   * An entry is a reference, not the award record: `GET /awards/<id>` is the
   * canonical record only where an implementation serves the award routes,
   * and otherwise the entry's `identifiers`, where the publisher supplies
   * them, are the key for joining the award in another system. A consumer
   * must not assume a reference can be dereferenced through this API.
   *
   * Absent means the implementation does not publish this link for the
   * record, and an empty array means the link is published and no awards are
   * known. Entries carry no ordering guarantee.
   */
  @Versioning.added(CommonGrants.Versions.v0_5)
  awards?: AwdRef[];

Changelog

Version	Changes	Schema
0.5.0	Added `awards` field	OpportunityDetails.yaml
0.2.0	Added `OpportunityDetails` model	OpportunityDetails.yaml

OppRef

A reference to an opportunity, previewing the key fields a consumer needs to identify it and look it up or join it to another response. Appears wherever another record points to an opportunity, such as the opportunity an award resulted from. Since v0.5 it also carries OppIds under identifiers, so a consumer can match the opportunity on a published registry code rather than the hosting system’s own id.

Table

Property	Type	Required	Description
id	uuid	Yes	Globally unique id for the opportunity
title	string	Yes	Title or name of the funding opportunity
identifiers	OppIds	No	System and registry-specific identifiers for the opportunity

Formats

A JSON example of this model.

{
  "id": "018f2e77-3a4b-7c1d-9e2f-abcdef123456",
  "title": "Health Center Capital Improvement Program",
  "identifiers": {
    "opp:us:fon": {
      "registry": {
        "code": "opp:us:fon",
        "url": "https://commongrants.org/registries/opp-us-fon"
      },
      "id": "HHS-2026-ACF-OCC-YD-0001"
    }
  }
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OppRef.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
  identifiers:
    $ref: OppIds.yaml
    description: System and registry-specific identifiers for the opportunity
required:
  - id
  - title
unevaluatedProperties:
  not: {}
examples:
  - id: 018f2e77-3a4b-7c1d-9e2f-abcdef123456
    title: Health Center Capital Improvement Program
    identifiers:
      opp:us:fon:
        registry:
          code: opp:us:fon
          url: https://commongrants.org/registries/opp-us-fon
        id: HHS-2026-ACF-OCC-YD-0001
description: |-
  A reference to an opportunity, previewing the key fields a consumer needs
  to identify it and look it up or join it to another response. Appears
  wherever another record points to an opportunity, such as the opportunity
  an award resulted from.

The TypeSpec code for this model.

/** A reference to an opportunity, previewing the key fields a consumer needs
 * to identify it and look it up or join it to another response. Appears
 * wherever another record points to an opportunity, such as the opportunity
 * an award resulted from.
 */
@example(Examples.Opportunity.ref)
@Versioning.added(CommonGrants.Versions.v0_1)
model OppRef {
  /** 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;

  /** System and registry-specific identifiers for the opportunity */
  @Versioning.added(CommonGrants.Versions.v0_5)
  identifiers?: OppIds;

Changelog

Version	Changes	Schema
0.5.0	Added `identifiers` field	OppRef.yaml
0.1.0	Added `OppRef` model	OppRef.yaml

OppIds

A collection of identifiers associated with an opportunity, keyed by registry code. It extends the generic IdentifierCollection with the base identifiers CommonGrants defines for opportunities. Additional registries can be published under otherIds.

Table

Property	Type	Required	Description
systemId	SystemId	No	The hosting system's own identifier for this record.
otherIds	record<Identifier>	No	Additional identifiers keyed by their registry code, for registries the protocol does not define as a base identifier on the model.
opp:us:fon	OppIdFon	No	The opportunity's Funding Opportunity Number (FON).
opp:us:aln	OppIdAln	No	The opportunity's Assistance Listing Number (ALN).

Formats

A JSON example of this model.

{
  "systemId": {
    "registry": {
      "code": "opp:grants.gov:system"
    },
    "id": "018f2e77-3a4b-7c1d-9e2f-abcdef123456"
  },
  "opp:us:fon": {
    "registry": {
      "code": "opp:us:fon",
      "url": "https://commongrants.org/registries/opp-us-fon"
    },
    "id": "HHS-2026-ACF-OCC-YD-0001"
  },
  "opp:us:aln": {
    "registry": {
      "code": "opp:us:aln",
      "url": "https://commongrants.org/registries/opp-us-aln"
    },
    "id": "93.575"
  }
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OppIds.yaml
type: object
properties:
  opp:us:fon:
    $ref: OppIdFon.yaml
    description: The opportunity's Funding Opportunity Number (FON).
  opp:us:aln:
    $ref: OppIdAln.yaml
    description: The opportunity's Assistance Listing Number (ALN).
allOf:
  - $ref: IdentifierCollection.yaml
unevaluatedProperties:
  not: {}
examples:
  - systemId:
      registry:
        code: opp:grants.gov:system
      id: 018f2e77-3a4b-7c1d-9e2f-abcdef123456
    opp:us:fon:
      registry:
        code: opp:us:fon
        url: https://commongrants.org/registries/opp-us-fon
      id: HHS-2026-ACF-OCC-YD-0001
    opp:us:aln:
      registry:
        code: opp:us:aln
        url: https://commongrants.org/registries/opp-us-aln
      id: "93.575"
description: |-
  A collection of identifiers associated with an opportunity.

  Extends the generic identifier collection with the base identifiers CommonGrants
  defines for opportunities. Additional registries can be published under `otherIds`.

The TypeSpec code for this model.

/** A collection of identifiers associated with an opportunity.
 *
 * Extends the generic identifier collection with the base identifiers CommonGrants
 * defines for opportunities. Additional registries can be published under `otherIds`.
 */
@example(Examples.Opportunity.identifiers)
@Versioning.added(CommonGrants.Versions.v0_5)
model OppIds extends Fields.IdentifierCollection {
  /** The opportunity's Funding Opportunity Number (FON). */
  `opp:us:fon`?: OppIdFon;

  /** The opportunity's Assistance Listing Number (ALN). */
  `opp:us:aln`?: OppIdAln;

Changelog

Version	Changes	Schema
0.5.0	Added `OppIds` model	OppIds.yaml

OppIdFon

An opportunity’s Federal Opportunity Number (FON), assigned by the awarding agency and published on the notice of funding opportunity. It pins registry.code to opp:us:fon.

Table

Property	Type	Required	Description
registry	record	No	Registry-level facts shared by every record in this registry.
id	string	No	The primary identifier string, when the registry has a single canonical value. May be omitted for registries with no natural primary; consumers should read `allIds` in that case.
allIds	array<object>	No	Every known identifier for this record in this registry, including archived values.

Formats

A JSON example of this model.

{
  "registry": {
    "code": "opp:us:fon",
    "url": "https://commongrants.org/registries/opp-us-fon"
  },
  "id": "HHS-2026-ACF-OCC-YD-0001"
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OppIdFon.yaml
type: object
properties:
  registry:
    type: object
    properties:
      code:
        type: string
        const: opp:us:fon
        description: Canonical CommonGrants registry code, `<schema>:<scope>:<prop>` (e.g. `org:us:ein`).
      url:
        type: string
        format: uri
        description: Link to the catalog entry for this registry.
    unevaluatedProperties:
      not: {}
    description: Registry-level facts shared by every record in this registry.
  id:
    type: string
    description: |-
      The primary identifier string, when the registry has a single canonical value.

      May be omitted for registries with no natural primary; consumers should read
      `allIds` in that case.
  allIds:
    type: array
    items:
      type: object
      properties:
        id:
          type: string
          description: The identifier string.
        status:
          $ref: IdentifierStatus.yaml
          description: Whether the identifier is currently valid or retired.
      required:
        - id
        - status
      unevaluatedProperties:
        not: {}
    description: Every known identifier for this record in this registry, including archived values.
unevaluatedProperties:
  not: {}
examples:
  - registry:
      code: opp:us:fon
      url: https://commongrants.org/registries/opp-us-fon
    id: HHS-2026-ACF-OCC-YD-0001
description: An opportunity's Funding Opportunity Number (FON), assigned by the awarding agency.

The TypeSpec code for this model.

/** An opportunity's Funding Opportunity Number (FON), assigned by the awarding agency. */
@example(Examples.Opportunity.fon)
@Versioning.added(CommonGrants.Versions.v0_5)

Changelog

Version	Changes	Schema
0.5.0	Added `OppIdFon` model	OppIdFon.yaml

OppIdAln

An opportunity’s Assistance Listing Number (ALN), formerly the CFDA number, which ties it to its federal assistance program. It pins registry.code to opp:us:aln.

Table

Property	Type	Required	Description
registry	record	No	Registry-level facts shared by every record in this registry.
id	string	No	The primary identifier string, when the registry has a single canonical value. May be omitted for registries with no natural primary; consumers should read `allIds` in that case.
allIds	array<object>	No	Every known identifier for this record in this registry, including archived values.

Formats

A JSON example of this model.

{
  "registry": {
    "code": "opp:us:aln",
    "url": "https://commongrants.org/registries/opp-us-aln"
  },
  "id": "93.575"
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OppIdAln.yaml
type: object
properties:
  registry:
    type: object
    properties:
      code:
        type: string
        const: opp:us:aln
        description: Canonical CommonGrants registry code, `<schema>:<scope>:<prop>` (e.g. `org:us:ein`).
      url:
        type: string
        format: uri
        description: Link to the catalog entry for this registry.
    unevaluatedProperties:
      not: {}
    description: Registry-level facts shared by every record in this registry.
  id:
    type: string
    description: |-
      The primary identifier string, when the registry has a single canonical value.

      May be omitted for registries with no natural primary; consumers should read
      `allIds` in that case.
  allIds:
    type: array
    items:
      type: object
      properties:
        id:
          type: string
          description: The identifier string.
        status:
          $ref: IdentifierStatus.yaml
          description: Whether the identifier is currently valid or retired.
      required:
        - id
        - status
      unevaluatedProperties:
        not: {}
    description: Every known identifier for this record in this registry, including archived values.
unevaluatedProperties:
  not: {}
examples:
  - registry:
      code: opp:us:aln
      url: https://commongrants.org/registries/opp-us-aln
    id: "93.575"
description: An opportunity's Assistance Listing Number (ALN), formerly the CFDA number.

The TypeSpec code for this model.

/** An opportunity's Assistance Listing Number (ALN), formerly the CFDA number. */
@example(Examples.Opportunity.aln)
@Versioning.added(CommonGrants.Versions.v0_5)

Changelog

Version	Changes	Schema
0.5.0	Added `OppIdAln` model	OppIdAln.yaml

OppStatus

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

Table

Property	Type	Required	Description
value	OppStatusOptions	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": "open",
  "description": "The opportunity is currently 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 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: 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)
@Versioning.added(CommonGrants.Versions.v0_1)
model OppStatus is Fields.ExtensibleEnumT<OppStatusOptions>;

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,
        description="A custom status value",
    )
    description: Optional[str] = Field(
        default=None,
        description="A human-readable description of the status",
    )

The TypeScript code for this model.

export const OppStatusOptionsEnum = z.enum(["forecasted", "open", "closed", "custom"]);

export const OppStatusSchema = z.object({
  /** The status value */
  value: OppStatusOptionsEnum,

  /** A custom status value */
  customValue: z.string().nullish(),

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

Changelog

Version	Changes	Schema
0.1.0	Added `OppStatus` model	OppStatus.yaml

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.

/** 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
 */
@Versioning.added(CommonGrants.Versions.v0_1)
enum OppStatusOptions {
  forecasted,
  open,
  closed,
  custom,
}

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]

The TypeScript code for this model.

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

Changelog

Version	Changes	Schema
0.1.0	Added `OppStatusOptions` enum	OppStatusOptions.yaml

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.

{
  "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
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" })
@Versioning.added(CommonGrants.Versions.v0_1)
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;

  /** Estimated number of awards that will be granted */
  estimatedAwardCount?: 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,
        description="Total amount of funding available for this opportunity",
    )
    min_award_amount: Optional[Money] = Field(
        default=None,
        description="Minimum amount of funding granted per award",
    )
    max_award_amount: Optional[Money] = Field(
        default=None,
        description="Maximum amount of funding granted per award",
    )
    min_award_count: Optional[int] = Field(
        default=None,
        description="Minimum number of awards granted",
    )
    max_award_count: Optional[int] = Field(
        default=None,
        description="Maximum number of awards granted",
    )
    estimated_award_count: Optional[int] = Field(
        default=None,
        description="Estimated number of awards that will be granted",
    )

The TypeScript code for this model.

    /** Details about the funding available for this opportunity that don't fit other fields */
    details: z.string().nullish(),

    /** Total amount of funding available */
    totalAmountAvailable: MoneySchema.nullish(),

    /** Minimum amount of funding granted per award */
    minAwardAmount: MoneySchema.nullish(),

    /** Maximum amount of funding granted per award */
    maxAwardAmount: MoneySchema.nullish(),

    /** Minimum number of awards granted */
    minAwardCount: z.number().int().nullish(),

    /** Maximum number of awards granted */
    maxAwardCount: z.number().int().nullish(),

    /** Estimated number of awards that will be granted */
    estimatedAwardCount: z.number().int().nullish(),
  })
  .strict();

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

Changelog

Version	Changes	Schema
0.1.0	Added `OppFunding` model	OppFunding.yaml

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": "Opportunity 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"
    }
  }
}

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: Opportunity 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)
@Versioning.added(CommonGrants.Versions.v0_1)
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,
        description="The date (and time) at which the opportunity is posted",
    )
    close_date: Optional[Event] = Field(
        default=None,
        description="The date (and time) at which the opportunity closes",
    )
    other_dates: Optional[dict[str, Event]] = Field(
        default=None,
        description="An optional map of other key dates or events in the opportunity timeline",
    )

The TypeScript code for this model.

    /** The date (and time) at which the opportunity is posted */
    postDate: EventSchema.nullish(),

    /** The date (and time) at which the opportunity closes */
    closeDate: EventSchema.nullish(),

    /** An optional map of other key dates or events in the opportunity timeline */
    otherDates: z.record(z.string(), EventSchema).nullish(),
  })
  .strict();

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

Changelog

Version	Changes	Schema
0.1.0	Added `OppTimeline` model	OppTimeline.yaml