@common-grants/core 0.1.0-alpha.6 → 0.1.0-alpha.7

package/README.md

@@ -48,16 +48,17 @@ model Agency extends CustomField {
 
     @example("Department of Transportation")
     value: string;
-    description: "The agency responsible for this opportunity";
-}
 
-// Create a map of custom fields
-model CustomFields extends CustomFieldMap {
-    agency: Agency;
+    description: "The agency responsible for this opportunity";
 }
 
-// Create a custom Opportunity type using the template
-alias CustomOpportunity = Opportunity<CustomFields>;
+// Extend the `OpportunityBase` model to create a new `CustomOpportunity` model
+// that includes the new `Agency` field in its `customFields` property
+model CustomOpportunity extends OpportunityBase {
+    customFields: {
+        agency: Agency;
+    }
+};
 ```
 
 ### Override default routes

package/lib/main.tsp

@@ -9,13 +9,17 @@ import "./routes/index.tsp";
 
 using TypeSpec.Http;
 
-// Define the top-level namespace for the library
+/** The base OpenAPI specification for a CommonGrants API
+ *
+ * In order for an API to be "compliant" with the CommonGrants protocol,
+ * it must implement all of the routes included in this base specification.
+ */
 @service({
-  name: "Base API",
+  title: "Base API",
 })
 namespace CommonGrants.API;
 
-@tag("Search")
+@tag("Opportunities")
 @route("/opportunities")
 namespace Opportunities {
   alias Router = Routes.Opportunities;

package/lib/models/custom-enum.tsp

@@ -0,0 +1,27 @@
+namespace CommonGrants.Models;
+
+/**
+ * A custom enum value, designed to be used as part of a union with known options
+ *
+ * @example How to use this CustomEnumValue in a union
+ *
+ * ```typespec
+ * union OpportunityStatus {
+ *   open: {
+ *       value: "open",
+ *       description?: "Opportunity is actively accepting applications",
+ *   },
+ *   closed: {
+ *       value: "closed",
+ *       description?: "Opportunity is no longer accepting applications",
+ *   },
+ *   custom: CustomEnumValue,
+ * }
+ * ```
+ */
+@doc("Custom value not included in the standard list of options.")
+model CustomEnumValue {
+  value: "custom";
+  customValue: string;
+  description: string;
+}

package/lib/models/custom-field.tsp

@@ -1,7 +1,7 @@
 namespace CommonGrants.Models;
 
 // ########################################
-// Model definition
+// Field types definition
 // ########################################
 
 /** The set of JSON schema types supported by a custom field */
@@ -13,9 +13,27 @@ enum CustomFieldType {
   array,
 }
 
-/** An object that maps field names to CustomField instances */
-model CustomFieldMap is Record<CustomField>;
+// ########################################
+// Models definition
+// ########################################
 
+/** Model for defining custom fields that are specific to a given implementation.
+ *
+ * @example How to define a custom field using this model
+ *
+ * ```typespec
+ * model Agency extends CustomField {
+ *   name: "agency";
+ *
+ *   type: CustomFieldType.string;
+ *
+ *   @example("Department of Transportation")
+ *   value: string;
+ *
+ *   description?: "The agency responsible for managing this opportunity";
+ * }
+ * ```
+ */
 @example(
   CustomFieldExamples.programArea,
   #{ title: "String field for program area" }
@@ -24,6 +42,7 @@ model CustomFieldMap is Record<CustomField>;
   CustomFieldExamples.eligibilityTypes,
   #{ title: "Array field for eligibility types" }
 )
+@doc("A custom field on a model") // Overrides internal docstrings when emitting OpenAPI
 model CustomField {
   /** Name of the custom field */
   name: string;

package/lib/models/event.tsp

@@ -4,10 +4,11 @@ namespace CommonGrants.Models;
 // Model definition
 // ########################################
 
+/** Description of an event that has a date (and possible time) associated with it */
 @example(EventExamples.deadline, #{ title: "Application deadline with time" })
 @example(EventExamples.openDate, #{ title: "Opening date without time" })
 model Event {
-  /** Name of the timeline event (e.g., 'Open Date', 'Deadline') */
+  /** Human-readable name of the event (e.g., 'Application posted', 'Question deadline') */
   name: string;
 
   /** Date of the event in in ISO 8601 format: YYYY-MM-DD */
@@ -16,7 +17,7 @@ model Event {
   /** Time of the event in ISO 8601 format: HH:MM:SS */
   time?: isoTime;
 
-  /** Detailed description of the timeline event */
+  /** Description of what this event represents */
   description?: string;
 }
 

package/lib/models/index.tsp

@@ -5,13 +5,38 @@ import "@typespec/json-schema";
 import "./base.tsp";
 import "./custom-field.tsp";
 import "./money.tsp";
-import "./funding.tsp";
 import "./event.tsp";
-import "./opportunity.tsp";
+import "./metadata.tsp";
+import "./custom-enum.tsp";
+import "./opportunity/index.tsp";
 
 using TypeSpec.JsonSchema;
 
-// Define the top-level namespace for the models
-// and emit these models as JSON schemas
-@jsonSchema
+/** Namespace for CommonGrants models that can be used in API routes */
+@jsonSchema // and emit these models as JSON schemas
 namespace CommonGrants.Models;
+
+/** The base model for a funding opportunity.
+ *
+ * It supports customization by extending the `customFields` property.
+ *
+ * @example How to declare a new Opportunity model with custom fields
+ *
+ * ```typespec
+ * model Agency extends CustomField {
+ *   type: CustomFieldType.string;
+ *
+ *   @example("Department of Transportation")
+ *   value: string;
+ * }
+ *
+ * model NewFields extends CustomFieldMap {
+ *   agency: Agency;
+ * }
+ *
+ * model CustomOpportunity extends OpportunityBase {
+ *   customFields: NewFields;
+ * }
+ * ```
+ */
+alias OpportunityBase = Opportunity.OpportunityBase;

package/lib/models/metadata.tsp

@@ -0,0 +1,41 @@
+namespace CommonGrants.Models;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** Standard system-level metadata about a given record.
+ *
+ * @example How to spread the SystemMetadata props into another record
+ *
+ * ```typespec
+ * model Opportunity {
+ *   id: uuid;
+ *   title: string;
+ *
+ *   // Includes SystemMetadata props in the root of the Opportunity model
+ *   ...SystemMetadata;
+ * }
+ * ```
+ * */
+@example(MetadataExample.system)
+model SystemMetadata {
+  /** The timestamp (in UTC) at which the record was created. */
+  @visibility(Lifecycle.Read)
+  createdAt: utcDateTime;
+
+  /** The timestamp (in UTC) at which the record was last modified. */
+  @visibility(Lifecycle.Read)
+  lastModifiedAt: utcDateTime;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+namespace MetadataExample {
+  const system = #{
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
+  };
+}

package/lib/models/money.tsp

@@ -4,6 +4,7 @@ namespace CommonGrants.Models;
 // Model definition
 // ########################################
 
+/** A monetary amount and the currency in which its denominated */
 @example(MoneyExamples.usdWithCents, #{ title: "US dollars and cents" })
 @example(
   MoneyExamples.euroWithoutCents,

package/lib/models/{funding.tsp → opportunity/funding.tsp}

@@ -1,11 +1,12 @@
-using TypeSpec.Http;
+import "../index.tsp";
 
-namespace CommonGrants.Models;
+namespace CommonGrants.Models.Opportunity;
 
 // ########################################
 // Model definition
 // ########################################
 
+/** Details about the funding available for this opportunity */
 @example(FundingExamples.allFields, #{ title: "All fields defined" })
 @example(
   FundingExamples.awardRange,
@@ -16,11 +17,22 @@ namespace CommonGrants.Models;
   #{ title: "Total funding limit but no award range" }
 )
 model FundingDetails {
+  /** 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;
 }
 

package/lib/models/{opportunity.tsp → opportunity/index.tsp}

@@ -1,55 +1,46 @@
-namespace CommonGrants.Models;
+import "@typespec/json-schema";
+
+import "./status.tsp";
+import "./funding.tsp";
+import "./timeline.tsp";
+
+/** Namespace for CommonGrants models that are specific to funding opportunities */
+@JsonSchema.jsonSchema
+namespace CommonGrants.Models.Opportunity;
 
 // ########################################
 // Model definition
 // ########################################
 
-/** The base model for a funding opportunity.
- *
- * It supports customization by templating the customFields property.
- *
- * @template Fields A CustomFieldMap object with user-defined custom fields,
- * that should be included in a given implementation of the Opportunity model.
- * @example Declare a new Opportunity model with custom fields
- *
- * ```typespec
- * model Agency extends CustomField {
- *   type: CustomFieldType.string;
- *   value: string;
- * }
- *
- * model NewFields extends CustomFieldMap {
- *   agency: Agency;
- * }
- *
- * alias CustomOpportunity = Opportunity<NewFields>;
- * ```
- */
-@example(
-  OpportunityExamples.minimal,
-  #{ title: "Minimal opportunity with required fields only" }
-)
-model Opportunity<Fields = CustomFieldMap> {
+@doc("A funding opportunity") // Overrides internal docstrings when emitting OpenAPI
+model OpportunityBase {
   /** Globally unique id for the opportunity */
+  @visibility(Lifecycle.Read)
   id: uuid;
 
-  /** URL for the original source of the opportunity */
-  source: url;
-
   /** Title or name of the funding opportunity */
   title: string;
 
+  /** Status of the opportunity */
+  status: OppStatus;
+
   /** Description of the opportunity's purpose and scope */
   description: string;
 
   /** Details about the funding available */
   fundingDetails: FundingDetails;
 
-  /** Key dates and milestones in the application process */
-  applicationTimeline?: Event[];
+  /** 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?: Fields;
+  customFields?: Record<CustomField>;
+
+  // Spreads the fields from the Metadata model into the Opportunity model
+  ...SystemMetadata;
 }
 
 // ########################################
@@ -64,11 +55,12 @@ namespace OpportunityExamples {
     title: "Healthcare Innovation Research Grant",
     description: "Funding for innovative healthcare delivery solutions",
     fundingDetails: FundingExamples.allFields,
-    applicationTimeline: #[EventExamples.openDate, EventExamples.deadline],
+    keyDates: #[EventExamples.openDate, EventExamples.deadline],
     customFields: #{
       programArea: CustomFieldExamples.programArea,
       eligibilityType: CustomFieldExamples.programArea,
     },
+    ...MetadataExample.system,
   };
 
   /** A minimal opportunity example with only required fields */
@@ -78,5 +70,6 @@ namespace OpportunityExamples {
     title: "Small Business Innovation Grant",
     description: "Supporting small business innovation projects",
     fundingDetails: FundingExamples.onlyLimit,
+    ...MetadataExample.system,
   };
 }

package/lib/models/opportunity/status.tsp

@@ -0,0 +1,33 @@
+import "@typespec/json-schema";
+import "@typespec/openapi3";
+
+import "../custom-enum.tsp";
+
+namespace CommonGrants.Models.Opportunity;
+
+/** Union of values accepted for opportunity status */
+@JsonSchema.oneOf
+@OpenAPI.oneOf
+@discriminator("value")
+union OppStatus {
+  /** Opportunity is anticipated, but not yet accepting applications */
+  forecasted: {
+    value: "forecasted",
+    description?: "Opportunity is anticipated, but not yet accepting applications",
+  },
+
+  /** Opportunity is actively accepting applications */
+  open: {
+    value: "open",
+    description?: "Opportunity is actively accepting applications",
+  },
+
+  /** Opportunity is no longer accepting applications */
+  closed: {
+    value: "closed",
+    description?: "Opportunity is no longer accepting applications",
+  },
+
+  /** Custom opportunity status */
+  custom: CustomEnumValue,
+}

package/lib/models/opportunity/timeline.tsp

@@ -0,0 +1,42 @@
+import "../event.tsp";
+import "../custom-enum.tsp";
+
+namespace CommonGrants.Models.Opportunity;
+
+// ########################################
+// Model definition
+// ########################################
+
+/** Key dates in the opportunity's timeline, such as when the application opens and closes */
+@example(TimelineExamples.opportunity)
+model OppTimeline {
+  /** The date (and time) at which the opportunity begins accepting applications */
+  appOpens?: Event;
+
+  /** The final deadline for submitting applications */
+  appDeadline?: Event;
+
+  /** An optional map of other key dates in the opportunity timeline
+   *
+   * Examples might include a deadline for questions, anticipated award date, etc.
+   */
+  otherDates?: Record<Event>;
+}
+
+// ########################################
+// Model examples
+// ########################################
+
+namespace TimelineExamples {
+  const opportunity = #{
+    appOpens: EventExamples.openDate,
+    appDeadline: EventExamples.deadline,
+    otherDates: #{
+      anticipatedAward: #{
+        name: "Anticipated award date",
+        date: isoDate.fromISO("2025-03-15"),
+        description: "When we expect to announce awards for this opportunity.",
+      },
+    },
+  };
+}

package/lib/responses/errors.tsp

@@ -1,6 +1,17 @@
 namespace Responses.Error;
 
+/** A standard error response schema, used to create custom error responses
+ *
+ * @example - How to use this model to create custom error response schemas
+ *
+ * ```
+ * import "@typespec/http"
+ *
+ * alias Unauthorized = Error & Http.UnauthorizedResponse
+ * ```
+ */
 @error
+@doc("A non-2xx response schema")
 model Error {
   @example(400)
   status: int32;

package/lib/responses/success.tsp

@@ -8,7 +8,24 @@ model Success {
   message: string;
 }
 
-/** Template for normal response data */
+/** Template for a 200 response with data
+ *
+ * @template T The schema for the value of the `"data"` property in this response
+ * @example How to specify a custom 200 response model
+ *
+ * ```typespec
+ *
+ * // Define a model
+ * model CustomModel {
+ *   id: string;
+ *   description: string;
+ * }
+ *
+ * // Pass that model to the `Ok` template
+ * alias CustomModel200 = Success.Ok<CustomModel>;
+ * ```
+ */
+@doc("A 200 response with data")
 model Ok<T> extends Success {
   // Inherit the 200 status code
   ...Http.OkResponse;
@@ -17,7 +34,24 @@ model Ok<T> extends Success {
   data: T;
 }
 
-/** Template for paginated responses */
+/** Template for a 200 response with paginated list of items
+ *
+ * @template T The schema for the value of the `"items"` property in this response
+ * @example How to specify a custom paginated response model
+ *
+ * ```typespec
+ *
+ * // Define a model
+ * model CustomModel {
+ *   id: string;
+ *   description: string;
+ * }
+ *
+ * // Pass that model to the `Ok` template
+ * alias CustomModelResponse = Success.Paginated<CustomModel>;
+ * ```
+ */
+@doc("A 200 response with a paginated list of items")
 model Paginated<T> extends Success {
   // Inherit the 200 status code
   ...Http.OkResponse;

package/lib/routes/opportunities.tsp

@@ -52,24 +52,24 @@ interface Opportunities {
   /** `GET /opportunities/` Get a paginated list of opportunities
    *
    * @template T Type of the paginated response model.
-   * Must be an extension of Models.Opportunity. Default is Models.Opportunity.
+   * Must be an extension of Models.OpportunityBase. Default is Models.OpportunityBase.
    */
   @summary("List opportunities")
-  @doc("Get a paginated list of opportunities")
+  @doc("Get a paginated list of opportunities, sorted by `lastModifiedAt` with most recent first.")
   @list
-  list<T extends Models.Opportunity = Models.Opportunity>(
+  list<T extends Models.OpportunityBase = Models.OpportunityBase>(
     ...PaginatedQuery,
   ): Success.Paginated<T> | Error.Unauthorized;
 
   /** `GET /opportunities/<id>` View opportunity details
    *
    * @template T Type of the response model.
-   * Must be an extension of Models.Opportunity. Default is Models.Opportunity.
+   * Must be an extension of Models.OpportunityBase. Default is Models.OpportunityBase.
    */
   @summary("View opportunity")
   @doc("View additional details about an opportunity")
   @get
-  read<T extends Models.Opportunity = Models.Opportunity>(
+  read<T extends Models.OpportunityBase = Models.OpportunityBase>(
     @path id: Models.uuid,
   ): Success.Ok<T> | Error.NotFound | Error.Unauthorized;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common-grants/core",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",
@@ -31,7 +31,10 @@
     "format": "prettier --write . && tsp format lib",
     "check:lint": "eslint",
     "check:format": "prettier --check . && tsp format lib --check",
-    "checks": "npm run check:lint && npm run check:format"
+    "checks": "npm run check:lint && npm run check:format",
+    "docs:build": "npx @redocly/cli build-docs tsp-output/@typespec/openapi3/openapi.yaml --output ./dist/redocly.html",
+    "docs:preview": "open ./dist/redocly.html",
+    "docs": "npm run typespec && npm run docs:build && npm run docs:preview"
   },
   "keywords": [
     "typespec",