@common-grants/core 0.1.0-alpha.9 → 0.1.1

package/README.md

@@ -45,7 +45,7 @@ namespace CustomAPI.CustomModels;
 // Define a custom field
 model Agency extends CustomField {
   name: "Agency";
-  type: CustomFieldType.string;
+  fieldType: CustomFieldType.string;
 
   @example("Department of Transportation")
   value: string;
@@ -76,13 +76,14 @@ using CommonGrants.Routes;
 using TypeSpec.Http;
 
 @tag("Search")
-@route("/opportunities")
+@route("/common-grants/opportunities")
 namespace CustomAPI.CustomRoutes {
   alias OpportunitiesRouter = Opportunities;
 
-  // Use the default model for list but custom model for read
+  // Use the default model for list but custom model for read and search
   op list is OpportunitiesRouter.list;
   op read is OpportunitiesRouter.read<CustomModels.CustomOpportunity>;
+  op search is OpportunitiesRouter.search<CustomModels.CustomOpportunity>;
 }
 ```
 
@@ -100,9 +101,7 @@ import "./routes.tsp"; // Import the routes from above
 using TypeSpec.Http;
 
 /** Description of your API goes here */
-@service({
-  title: "Custom API",
-})
+@service(#{ title: "Custom API" })
 namespace CustomAPI;
 ```
 

package/lib/api.tsp

@@ -1,27 +1,44 @@
 // Import Schemas.and Routes to make them available outside the package
 import "./core/index.tsp";
 import "@typespec/http";
+import "@typespec/openapi";
 
 using TypeSpec.Http;
+using TypeSpec.OpenAPI;
 
 /** 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 with the "required" tag in this specification.
  */
-@service({
-  title: "CommonGrants Base API",
-})
+@service(#{ title: "CommonGrants Base API" })
+@tagMetadata(
+  "optional",
+  #{ description: "Endpoints that MAY be implemented by CommonGrants APIs" }
+)
+@tagMetadata(
+  "required",
+  #{
+    description: "Endpoints that MUST be implemented by all CommonGrants APIs",
+  }
+)
+@tagMetadata(
+  "Opportunities",
+  #{ description: "Endpoints related to funding opportunities" }
+)
 namespace CommonGrants.API;
 
 @tag("Opportunities")
-@route("/opportunities")
+@route("/common-grants/opportunities")
 namespace Opportunities {
   alias Router = Routes.Opportunities;
 
   @tag("required")
-  op List is Router.list;
+  op list is Router.list;
 
   @tag("required")
-  op Read is Router.read;
+  op read is Router.read;
+
+  @tag("optional")
+  op search is Router.search;
 }

package/lib/core/fields/address.tsp

@@ -0,0 +1,86 @@
+namespace CommonGrants.Fields;
+
+/** A mailing address. */
+@example(Examples.Address.apartment)
+model Address {
+  /** The primary street address line. */
+  street1: string;
+
+  /** Additional street address information (e.g., apartment number, suite, etc.). */
+  street2?: string;
+
+  /** The city or municipality name. */
+  city: string;
+
+  /** The state, province, or region name. */
+  stateOrProvince: string;
+
+  /** The country name or ISO country code. */
+  country: string;
+
+  /** The postal or ZIP code for the address. */
+  postalCode: string;
+
+  /** The latitude coordinate of the address location. */
+  latitude?: numeric;
+
+  /** The longitude coordinate of the address location. */
+  longitude?: numeric;
+
+  /** Additional geospatial data in GeoJSON format. */
+  geography?: Record<unknown>;
+}
+
+/** A collection of addresses. */
+@example(Examples.Address.personalCollection)
+@example(Examples.Address.orgCollection)
+model AddressCollection {
+  /** The primary address for a person or organization. */
+  primary: Address;
+
+  /** Additional addresses keyed by a descriptive label (e.g., "work", "home", "international"). */
+  otherAddresses?: Record<Address>;
+}
+
+namespace Examples.Address {
+  const apartment = #{
+    street1: "123 Main St",
+    city: "Anytown",
+    stateOrProvince: "CA",
+    country: "US",
+    postalCode: "12345",
+  };
+
+  const orgAddress = #{
+    street1: "456 Main St",
+    street2: "Suite 100",
+    city: "Anytown",
+    stateOrProvince: "CA",
+    country: "US",
+    postalCode: "12345",
+  };
+
+  const international = #{
+    street1: "123 Rue Principale",
+    city: "Montreal",
+    stateOrProvince: "QC",
+    country: "CA",
+    postalCode: "H2Y 1C6",
+  };
+
+  const personalCollection = #{
+    primary: Examples.Address.apartment,
+    otherAddresses: #{
+      work: Examples.Address.apartment,
+      home: Examples.Address.apartment,
+    },
+  };
+
+  const orgCollection = #{
+    primary: Examples.Address.orgAddress,
+    otherAddresses: #{
+      satellite: Examples.Address.orgAddress,
+      international: Examples.Address.international,
+    },
+  };
+}

package/lib/core/fields/custom-field.tsp

@@ -8,6 +8,7 @@ namespace CommonGrants.Fields;
 enum CustomFieldType {
   string,
   number,
+  integer,
   boolean,
   object,
   array,
@@ -25,7 +26,7 @@ enum CustomFieldType {
  * model Agency extends CustomField {
  *   name: "agency";
  *
- *   type: CustomFieldType.string;
+ *   fieldType: CustomFieldType.string;
  *
  *   @example("Department of Transportation")
  *   value: string;
@@ -42,13 +43,13 @@ enum CustomFieldType {
   Examples.CustomField.eligibilityTypes,
   #{ title: "Array field for eligibility types" }
 )
-@doc("A custom field on a model") // Overrides internal docstrings when emitting OpenAPI
+@doc("A custom field on a model")
 model CustomField {
   /** Name of the custom field */
   name: string;
 
   /** The JSON schema type to use when de-serializing the `value` field */
-  type: CustomFieldType;
+  fieldType: CustomFieldType;
 
   /** Link to the full JSON schema for this custom field */
   schema?: url;
@@ -69,7 +70,7 @@ namespace Examples.CustomField {
   /** An example of a string custom field */
   const programArea = #{
     name: "programArea",
-    type: CustomFieldType.string,
+    fieldType: CustomFieldType.string,
     value: "Healthcare Innovation",
     description: "Primary focus area of the grant program",
     schema: "https://example.com/program-areas.json",
@@ -78,7 +79,7 @@ namespace Examples.CustomField {
   /** An example of an array custom field */
   const eligibilityTypes = #{
     name: "eligibilityType",
-    type: CustomFieldType.array,
+    fieldType: CustomFieldType.array,
     value: #["nonprofit", "academic"],
     description: "Types of eligible organizations",
   };

package/lib/core/fields/email.tsp

@@ -0,0 +1,35 @@
+import "../types.tsp";
+
+namespace CommonGrants.Fields;
+
+/** An email address. */
+alias Email = Types.email; // Exposes Email from CommonGrants.Fields
+
+/** A collection of email addresses. */
+@example(Examples.Email.personalCollection)
+model EmailCollection {
+  /** The primary email address for a person or organization. */
+  primary: Types.email;
+
+  /** Additional email addresses keyed by a descriptive label (e.g., "work", "personal", "support"). */
+  otherEmails?: Record<Types.email>;
+}
+
+namespace Examples.Email {
+  const personalCollection = #{
+    primary: "john.doe@example.com",
+    otherEmails: #{
+      work: "john.doe@work.com",
+      personal: "john.doe@gmail.com",
+      school: "john.doe@school.edu",
+    },
+  };
+
+  const orgCollection = #{
+    primary: "info@example.com",
+    otherEmails: #{
+      support: "support@example.com",
+      marketing: "marketing@example.com",
+    },
+  };
+}

package/lib/core/fields/event.tsp

@@ -2,26 +2,119 @@ import "../types.tsp";
 
 namespace CommonGrants.Fields;
 
-using CommonGrants.Types;
+using Types;
 
 // ########################################
-// Model definition
+// Event type
 // ########################################
 
-/** Description of an event that has a date (and possible time) associated with it */
-@example(Examples.Event.deadline, #{ title: "Application deadline with time" })
-@example(Examples.Event.openDate, #{ title: "Opening date without time" })
-model Event {
+/** Type of event (e.g., a single date, a date range, or a custom event)
+ *
+ * - singleDate: A single date (and possible time)
+ * - dateRange: A period of time with a start and end date
+ * - other: Other event type (e.g., a recurring event)
+ */
+enum EventType {
+  /** A single date with no time */
+  singleDate,
+
+  /** A range of dates with no time */
+  dateRange,
+
+  /** Other event type */
+  other,
+}
+
+// ########################################
+// Event
+// ########################################
+
+/** Union of all event types */
+union Event {
+  /** A single date event */
+  singleDate: SingleDateEvent,
+
+  /** A date range event */
+  dateRange: DateRangeEvent,
+
+  /** Other event type */
+  other: OtherEvent,
+}
+
+// ########################################
+// Event base
+// ########################################
+
+/** Base model for all events */
+@discriminator("eventType")
+model EventBase {
   /** Human-readable name of the event (e.g., 'Application posted', 'Question deadline') */
   name: string;
 
+  /** Type of event */
+  eventType: EventType;
+
+  /** Description of what this event represents */
+  description?: string;
+}
+
+// ########################################
+// Single date event
+// ########################################
+
+/** Description of an event that has a date (and possible time) associated with it */
+@example(Examples.Event.postedDate, #{ title: "Opportunity posted date" })
+@example(Examples.Event.closeDate, #{ title: "Opportunity close date" })
+model SingleDateEvent extends EventBase {
+  /** Type of event */
+  eventType: EventType.singleDate;
+
   /** Date of the event in in ISO 8601 format: YYYY-MM-DD */
   date: isoDate;
 
   /** Time of the event in ISO 8601 format: HH:MM:SS */
   time?: isoTime;
+}
 
-  /** Description of what this event represents */
+// ########################################
+// Date range event
+// ########################################
+
+/** Description of an event that has a start and end date (and possible time) associated with it */
+@example(Examples.Event.performancePeriod, #{ title: "Period of performance" })
+@example(Examples.Event.applicationPeriod, #{ title: "Application period" })
+model DateRangeEvent extends EventBase {
+  /** Type of event */
+  eventType: EventType.dateRange;
+
+  /** Start date of the event in ISO 8601 format: YYYY-MM-DD */
+  startDate: isoDate;
+
+  /** Start time of the event in ISO 8601 format: HH:MM:SS */
+  startTime?: isoTime;
+
+  /** End date of the event in ISO 8601 format: YYYY-MM-DD */
+  endDate: isoDate;
+
+  /** End time of the event in ISO 8601 format: HH:MM:SS */
+  endTime?: isoTime;
+}
+
+// ########################################
+// Custom event
+// ########################################
+
+/** Description of an event that is not a single date or date range */
+@example(Examples.Event.infoSessions, #{ title: "Info sessions" })
+model OtherEvent extends EventBase {
+  /** Type of event */
+  eventType: EventType.other;
+
+  /** Details of the event's timeline (e.g. "Every other Tuesday") */
+  details?: string;
+
+  /** Description of the event */
+  @example("Applications begin being accepted")
   description?: string;
 }
 
@@ -31,17 +124,46 @@ model Event {
 
 namespace Examples.Event {
   /** An example of a deadline event with a specific time */
-  const deadline = #{
-    name: "Application Deadline",
+  const closeDate = #{
+    name: "Opportunity close date",
+    eventType: EventType.singleDate,
     date: isoDate.fromISO("2024-12-31"),
     time: isoTime.fromISO("17:00:00"),
-    description: "Final submission deadline for all grant applications",
+    description: "Opportunity closes for all applications",
   };
 
-  /** An example of an opening date without a specific time */
-  const openDate = #{
-    name: "Open Date",
+  /** An example of an opportunity posted date without a specific time */
+  const postedDate = #{
+    name: "Application posted date",
+    eventType: EventType.singleDate,
     date: isoDate.fromISO("2024-01-15"),
-    description: "Applications begin being accepted",
+    description: "Opportunity is posted publicly",
+  };
+
+  /** Period of application for the grant */
+  const applicationPeriod = #{
+    name: "Application period",
+    eventType: EventType.dateRange,
+    startDate: isoDate.fromISO("2024-01-01"),
+    endDate: isoDate.fromISO("2024-01-31"),
+    endTime: isoTime.fromISO("17:00:00"),
+    description: "Primary application period for the grant opportunity",
+  };
+
+  /** Period of performance for the grant */
+  const performancePeriod = #{
+    name: "Period of Performance",
+    eventType: EventType.dateRange,
+    startDate: isoDate.fromISO("2024-01-01"),
+    endDate: isoDate.fromISO("2024-12-31"),
+    description: "Period of performance for the grant",
+  };
+
+  /** Info sessions for the opportunity */
+  const infoSessions = #{
+    name: "Info sessions",
+    eventType: EventType.other,
+    details: "Every other Tuesday at 10:00 AM during the application period",
+    description: "Info sessions for the opportunity",
   };
 }

package/lib/core/fields/index.tsp

@@ -2,6 +2,13 @@ import "./custom-field.tsp";
 import "./metadata.tsp";
 import "./money.tsp";
 import "./event.tsp";
+import "./address.tsp";
+import "./name.tsp";
+import "./phone.tsp";
+import "./pcs.tsp";
+import "./email.tsp";
+
+using TypeSpec.JsonSchema;
 
 /** A standard set of fields, e.g. `money` that can be reused across models
  *
@@ -17,4 +24,5 @@ import "./event.tsp";
  * }
  * ```
  */
+@jsonSchema
 namespace CommonGrants.Fields;

package/lib/core/fields/money.tsp

@@ -2,13 +2,13 @@ import "../types.tsp";
 
 namespace CommonGrants.Fields;
 
-using CommonGrants.Types;
+using Types;
 
 // ########################################
 // Model definition
 // ########################################
 
-/** A monetary amount and the currency in which its denominated */
+/** A monetary amount and the currency in which it's denominated */
 @example(Examples.Money.usdWithCents, #{ title: "US dollars and cents" })
 @example(
   Examples.Money.euroWithoutCents,

package/lib/core/fields/name.tsp

@@ -0,0 +1,30 @@
+namespace CommonGrants.Fields;
+
+/** A person's name. */
+@example(Examples.Name.janeDoe)
+model Name {
+  /** Honorific prefix (e.g., Mr., Mrs., Dr., Prof.). */
+  prefix?: string;
+
+  /** The person's first or given name. */
+  firstName: string;
+
+  /** The person's middle name or names. */
+  middleName?: string;
+
+  /** The person's last name or family name. */
+  lastName: string;
+
+  /** Name suffix (e.g., Jr., Sr., III, Ph.D.). */
+  suffix?: string;
+}
+
+namespace Examples.Name {
+  const janeDoe = #{
+    prefix: "Dr.",
+    firstName: "Jane",
+    middleName: "Edward",
+    lastName: "Doe",
+    suffix: "Jr.",
+  };
+}

package/lib/core/fields/pcs.tsp

@@ -0,0 +1,112 @@
+namespace CommonGrants.Fields;
+
+/** A Philanthropy Classification System (PCS) term.
+ *
+ * The PCS is a hierarchical classification system for categorizing data related to
+ * philanthropic activities. It supports the following classes:
+ * - Organization types
+ * - Subjects
+ * - Population groups
+ * - Transaction types
+ * - Support strategies
+ *
+ * See https://taxonomy.candid.org/ for more information.
+ */
+@example(Examples.PCS.orgTypeTerm)
+model PCSTerm {
+  /** The plain language PCS term. */
+  term: string;
+
+  /** The class to which the PCS term belongs. */
+  class: PCSClass;
+
+  /** The code for this PCS term. */
+  @pattern("^[A-Z]{2}[0-9]{6}$")
+  @example("UC000000")
+  code: string;
+
+  /** Description of the PCS term */
+  description?: string;
+}
+
+// #########################################################
+// PCSClass
+// #########################################################
+
+/** The class to which the PCS term belongs. */
+enum PCSClass {
+  orgTypes: "Organization types",
+  subjects: "Subjects",
+  populationGroups: "Population groups",
+  transactionTypes: "Transaction types",
+  supportStrategies: "Support strategies",
+}
+
+// #########################################################
+// PCS class types
+// #########################################################
+
+/** A Philanthropy Classification System (PCS) term for organization types.
+ *
+ * See https://taxonomy.candid.org/organization-type for more information.
+ */
+model PCSOrgType extends PCSTerm {
+  /** The PCS term for the organization type. */
+  class: PCSClass.orgTypes;
+}
+
+/** A Philanthropy Classification System (PCS) term for the subject of the grant.
+ *
+ * See https://taxonomy.candid.org/subjects for more information.
+ */
+model PCSSubject extends PCSTerm {
+  /** The PCS term for the subject. */
+  class: PCSClass.subjects;
+}
+
+/** A Philanthropy Classification System (PCS) term for populations served.
+ *
+ * See https://taxonomy.candid.org/populations for more information.
+ */
+model PCSPopulation extends PCSTerm {
+  /** The PCS term for the population. */
+  class: PCSClass.populationGroups;
+}
+
+/** A Philanthropy Classification System (PCS) term for support strategies.
+ *
+ * See https://taxonomy.candid.org/support-strategies for more information.
+ */
+model PCSSupportStrategy extends PCSTerm {
+  /** The PCS term for the support strategy. */
+  class: PCSClass.supportStrategies;
+}
+
+/** A Philanthropy Classification System (PCS) term for transaction types.
+ *
+ * See https://taxonomy.candid.org/transaction-types for more information.
+ */
+model PCSTransactionType extends PCSTerm {
+  /** The PCS term for the transaction type. */
+  class: PCSClass.transactionTypes;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.PCS {
+  const orgTypeTerm = #{
+    term: "Hospital",
+    class: PCSClass.orgTypes,
+    description: "Institutions with the primary purpose of providing in-patient physical and mental health services...",
+    code: "EO000000",
+  };
+
+  const subjectTerm = #{
+    term: "Education",
+    class: PCSClass.subjects,
+    description: "All formally constituted educational institutions (except art and performing art schools) and projects or activities...",
+    code: "SB000000",
+  };
+}

package/lib/core/fields/phone.tsp

@@ -0,0 +1,65 @@
+namespace CommonGrants.Fields;
+
+/** A phone number. */
+@example(Examples.Phone.mobile)
+@example(Examples.Phone.withExtension)
+model Phone {
+  /** The international country code (e.g., "+1" for US/Canada). */
+  @pattern("^\\+[1-9][0-9]{1,3}$")
+  countryCode: string;
+
+  /** The local phone number without the country code. */
+  number: string;
+
+  /** Optional extension number for the phone line. */
+  extension?: string;
+
+  /** Indicates whether this is a mobile/cell phone number. */
+  isMobile?: boolean = false;
+}
+
+// #########################################################
+// Phone Collection
+// #########################################################
+
+/** A collection of phone numbers for a person. */
+@example(Examples.Phone.personalCollection)
+@example(Examples.Phone.orgCollection)
+model PhoneCollection {
+  /** The person's primary phone number. */
+  primary: Fields.Phone;
+
+  /** The person's fax number, if applicable. */
+  fax?: Fields.Phone;
+
+  /** Additional phone numbers not covered by the standard fields. */
+  otherPhones?: Record<Fields.Phone>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Phone {
+  const mobile = #{ countryCode: "+1", number: "444-456-1230", isMobile: true };
+
+  const home = #{ countryCode: "+1", number: "333-456-1230", isMobile: false };
+
+  const withExtension = #{
+    countryCode: "+1",
+    number: "555-123-4567",
+    extension: "123",
+    isMobile: false,
+  };
+
+  const personalCollection = #{ primary: mobile, otherPhones: #{ home: home } };
+
+  const orgCollection = #{
+    primary: mobile,
+    fax: withExtension,
+    otherPhones: #{
+      support: #{ countryCode: "+1", number: "333-456-1230", isMobile: false },
+      marketing: #{ countryCode: "+1", number: "444-456-1230", isMobile: true },
+    },
+  };
+}