@thejob/schema 2.6.0 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thejob/schema",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/job/job.schema.ts

@@ -13,6 +13,7 @@ import { DurationSchema } from "../duration/duration.schema.js";
 import { LocationSchema } from "../location/location.schema.js";
 import { PageSchema } from "../page/page.schema.js";
 import { SkillSchema } from "../skill/skill.schema.js";
+import { ConceptSchema } from "../taxonomy/taxonomy.schema.js";
 import { QuestionType } from "../question/index.js";
 import type {
   TChoiceQuestionSchema,
@@ -70,14 +71,27 @@ export const JobSchema = object({
   workMode: string().required().label("Work mode"),
 
   /**
-   * `conceptId`/`conceptName` carry the taxonomy-service normalization. They are
-   * picked here (not just `name`/`logo`) because SkillSchema is `.noUnknown()`:
-   * an unpicked field that is actually PRESENT fails validation, so omitting them
-   * would reject every normalized job.
+   * `name` is the skill exactly as posted. `concept` is what thejob-taxonomy-service
+   * resolved it to (`vocabulary: skills`), written by jobs-service, never by the
+   * poster: enough of the concept to filter by id and display the canonical name
+   * without a lookup. A copy, so it can go stale after a taxonomy release; see
+   * `taxonomyVersion`.
+   *
+   * Additive, never authoritative: the raw `name` is always kept, so a wrong
+   * match, a taxonomy release or an outage is recoverable by re-normalizing.
+   * `concept` is absent when the term did not resolve (a normal outcome, logged
+   * as a miss on the taxonomy side) or the job predates normalization, so read
+   * `concept?.name ?? name`.
    */
   skills: array()
     .of(
-      SkillSchema.pick(["name", "logo", "conceptId", "conceptName"])
+      SkillSchema.pick(["name", "logo"])
+        .shape({
+          concept: ConceptSchema.pick(["conceptId", "vocabulary", "name", "type"])
+            .nullable()
+            .optional()
+            .default(undefined),
+        })
         .required()
         .label("Skill"),
     )
@@ -283,6 +297,15 @@ export const JobSchema = object({
     .optional()
     .label("Sub Categories"),
 
+  /**
+   * The taxonomy state `skills[].concept` was resolved against (the service's
+   * `taxonomyVersion`, bumped by every release and rollback); behind the current
+   * version means the concepts may be stale. Written by jobs-service with every
+   * skills write: `null` when that write could not be normalized (taxonomy down
+   * or unconfigured), absent on jobs that predate normalization.
+   */
+  taxonomyVersion: number().integer().min(0).nullable().optional().label("Taxonomy Version"),
+
   termsAccepted: boolean()
     .oneOf([true], "Accept terms before proceeding")
     .required("Accept terms before proceeding")

package/src/taxonomy/taxonomy.schema.ts

@@ -192,6 +192,19 @@ export const UnmatchedTermSchema = object({
   )
     .default([])
     .label("Sources"),
+  /**
+   * Where the term was seen, capped: the caller's title and the terms sent with
+   * it. What the resolver reads to tell "CTS" on a chip-design posting from "CTS"
+   * on an ad-tech one; a bare term cannot carry that.
+   */
+  samples: array(
+    object({
+      title: string().optional(),
+      siblings: array(string().required()).default([]),
+    }).required(),
+  )
+    .default([])
+    .label("Samples"),
   resolution: string().oneOf(SupportedUnmatchedResolutions).required().label("Resolution"),
   resolvedConceptId: string().optional().label("Resolved Concept"),
   /** `ambiguous`: the concept exists; the caller gave no context that picked one. */