diff --git a/lib/staff-field-mapping.mjs b/lib/staff-field-mapping.mjs
index 081a3ea..a41159d 100644
--- a/lib/staff-field-mapping.mjs
+++ b/lib/staff-field-mapping.mjs
@@ -15,15 +15,20 @@
  * @typedef {import("../types/form").StaffFieldDescriptor} StaffFieldDescriptor
  * @typedef {import("../types/form").StaffRenderKind} StaffRenderKind
  *
- * @typedef {object} CustomFieldRow
- * @property {string} name
- * @property {string} label
- * @property {string} data_type
- * @property {string} html_type
- * @property {number | null | undefined} option_group_id
- * @property {number} weight
- * @property {string} "custom_group_id.name"
- * @property {string} "custom_group_id.title"
+ * The CustomFieldRow shape isn't fully expressible in JSDoc because two of
+ * its property names contain dots (the APIv4 joined-field syntax). TypeScript
+ * callers declare their own typed interface for the row; here we use a
+ * permissive shape so the @ts-check pass doesn't complain about the dotted
+ * accesses below.
+ *
+ * @typedef {Record<string, unknown> & {
+ *   name: string;
+ *   label: string;
+ *   data_type: string;
+ *   html_type: string;
+ *   option_group_id: number | null | undefined;
+ *   weight: number;
+ * }} CustomFieldRow
  */
 
 const ORG_GROUP_NAMES = new Set(["Food_Co_op_Organizing"]);
@@ -33,8 +38,8 @@ const ORG_GROUP_NAMES = new Set(["Food_Co_op_Organizing"]);
  * @returns {StaffFieldDescriptor}
  */
 export function mapCustomFieldRow(row) {
-  const groupName = row["custom_group_id.name"];
-  const groupTitle = row["custom_group_id.title"];
+  const groupName = /** @type {string} */ (row["custom_group_id.name"]);
+  const groupTitle = /** @type {string} */ (row["custom_group_id.title"]);
   /** @type {"activity" | "org"} */
   const groupKind = ORG_GROUP_NAMES.has(groupName) ? "org" : "activity";
   const optionGroupId =