@thejob/schema 2.0.5 → 2.0.7

package/src/job/job-taxonomy.util.ts

@@ -0,0 +1,111 @@
+import {
+  JOB_TAXONOMY,
+  type JobCategory,
+  type JobIndustry,
+  type JobSubCategory,
+} from "./job-taxonomy.constant.js";
+
+/**
+ * Taxonomy lookups + industry derivation.
+ *
+ * Hand-written (unlike job-taxonomy.constant.ts, which is generated) — the generator
+ * will not overwrite this file.
+ *
+ * WHY DERIVE INDUSTRY INSTEAD OF ASKING FOR IT
+ * `industry` is redundant: every subCategory name is globally unique and every industry
+ * belongs to exactly one category, so a subCategory already determines both. Asking an
+ * LLM to pick the industry *as well* asks it to re-derive what it just implied — and
+ * measured across ~57k enriched jobs it derived differently 15.9% of the time (e.g.
+ * "Data Science" filed under "Software & Web Development" rather than "Data, AI &
+ * Analytics"). 89.5% of those were a sibling industry under the SAME category: the right
+ * neighbourhood, the wrong box. Deriving in code removes that failure mode entirely
+ * rather than validating against it — a mismatch must never cost us the posting.
+ *
+ * WHY CATEGORY IS STILL ASKED FOR, NOT DERIVED
+ * The reverse (derive category from the subCategory too) measured 98.5% agreement, but
+ * the disagreements showed the MODEL was usually right and the tree wrong: a "Financial
+ * Analyst" tagged `business_intelligence` derives to Technology, while the model said
+ * Finance — and it is a finance job that uses BI tools. The category captures what the
+ * job IS; a subCategory's position in the tree does not. So the model keeps choosing it.
+ */
+
+/** subCategory -> the industry that owns it. */
+const INDUSTRY_OF_SUB = new Map<string, JobIndustry>(
+  JOB_TAXONOMY.flatMap((c) =>
+    c.industries.flatMap((i) => i.subCategories.map((s) => [s, i.industry] as const)),
+  ),
+);
+
+/** subCategory -> the category that owns it (via its industry). */
+const CATEGORY_OF_SUB = new Map<string, JobCategory>(
+  JOB_TAXONOMY.flatMap((c) =>
+    c.industries.flatMap((i) => i.subCategories.map((s) => [s, c.category] as const)),
+  ),
+);
+
+/** industry -> the category that owns it. */
+const CATEGORY_OF_INDUSTRY = new Map<string, JobCategory>(
+  JOB_TAXONOMY.flatMap((c) => c.industries.map((i) => [i.industry, c.category] as const)),
+);
+
+/** The industry a subCategory belongs to, or undefined if it is not a known subCategory. */
+export function industryOfSubCategory(sub: string): JobIndustry | undefined {
+  return INDUSTRY_OF_SUB.get(sub);
+}
+
+/** The category a subCategory belongs to, or undefined if unknown. */
+export function categoryOfSubCategory(sub: string): JobCategory | undefined {
+  return CATEGORY_OF_SUB.get(sub);
+}
+
+/** The category an industry belongs to, or undefined if unknown. */
+export function categoryOfIndustry(industry: string): JobCategory | undefined {
+  return CATEGORY_OF_INDUSTRY.get(industry);
+}
+
+/** The industries under a category (empty if the category is unknown). */
+export function industriesOfCategory(category: string): readonly JobIndustry[] {
+  return JOB_TAXONOMY.find((c) => c.category === category)?.industries.map((i) => i.industry) ?? [];
+}
+
+/** The subCategories under an industry (empty if the industry is unknown). */
+export function subCategoriesOfIndustry(industry: string): readonly JobSubCategory[] {
+  for (const c of JOB_TAXONOMY) {
+    for (const i of c.industries) if (i.industry === industry) return i.subCategories;
+  }
+  return [];
+}
+
+/**
+ * Derive a job's industry from its category + subCategories. This is the function that
+ * replaces asking the model for `industry`.
+ *
+ * Rule: the first subCategory that sits INSIDE the given category wins. Preferring the
+ * category keeps the model's judgement about what the job is (see the file header) while
+ * still deriving a structurally coherent industry; measured on ~57k jobs, 98.7% of those
+ * with a real category and real subCategories have at least one subCategory inside it.
+ *
+ * Falls back, in order:
+ *  1. no category given -> the first known subCategory's own industry;
+ *  2. no subCategory sits in the category -> undefined (caller keeps whatever it had,
+ *     or stores null; we never drop a posting over this).
+ *
+ * Order matters: `subCategories` is the model's own ranking, most relevant first.
+ */
+export function deriveIndustry(
+  category: string | null | undefined,
+  subCategories: readonly string[] | null | undefined,
+): JobIndustry | undefined {
+  const subs = (subCategories ?? []).filter((s) => INDUSTRY_OF_SUB.has(s));
+  if (subs.length === 0) return undefined;
+
+  if (category) {
+    const inCategory = subs.find((s) => CATEGORY_OF_SUB.get(s) === category);
+    if (inCategory) return INDUSTRY_OF_SUB.get(inCategory);
+    // The model's subCategories all sit outside its chosen category. Rather than force
+    // an industry that contradicts the category, leave it unset.
+    return undefined;
+  }
+
+  return INDUSTRY_OF_SUB.get(subs[0]);
+}

package/src/job/job.schema.ts

@@ -251,6 +251,18 @@ export const JobSchema = object({
 
   reports: array().of(UserIdAndCreatedAtSchema).optional().label("Reports"),
 
+  // Taxonomy fields are constants (see job-taxonomy.constant.ts), stored as slugs and
+  // translated for display. They are deliberately NOT `oneOf`-constrained here: a value
+  // outside the taxonomy must be DROPPED, never a reason to reject the posting. Yup
+  // `oneOf` fails the whole object, so one stale subCategory would cost a user their
+  // entire job on the create/edit form, and a single drifted LLM value would bin an
+  // otherwise-good enriched job.
+  //
+  // Callers sanitize instead: jobs-service's sanitizeTaxonomy() coerces unknown values
+  // to null / filters them out of the array before validation. Taxonomies change over
+  // time (values get renamed, retired, added), so stored jobs will always outlive the
+  // enum — being lenient here is what lets the taxonomy evolve without a migration
+  // gate on every write.
   category: string().nullable().optional().label("Category"),
 
   industry: string().nullable().optional().label("Industry"),

package/src/page/page.schema.ts

@@ -53,11 +53,27 @@ export const PageSchema = object()
       .nullable()
       .default(null)
       .label("Logo"),
+    // Taxonomy (see job-taxonomy.constant.ts): category -> industry -> subCategory,
+    // stored as slugs and translated for display. As on JobSchema, these are NOT
+    // `oneOf`-constrained: a value that drifts out of the taxonomy must be dropped,
+    // never a reason to reject the whole page. `categories` is the top level (kept
+    // required for backward compatibility); `industries` and `subCategories` are the
+    // deeper levels the tree picker fills in when a leaf auto-selects its parents.
     categories: array()
       .of(string().trim().required())
       .required()
       .min(1)
       .label("Categories"),
+    industries: array()
+      .of(string().trim().required())
+      .optional()
+      .default([])
+      .label("Industries"),
+    subCategories: array()
+      .of(string().trim().required())
+      .optional()
+      .default([])
+      .label("Sub Categories"),
     socialAccounts: array()
       .of(SocialAccountSchema)
       .optional()