@thejob/schema 2.1.5 → 2.1.6

package/dist/index.cjs

@@ -594,6 +594,26 @@ var PageSchema = (0, import_yup12.object)().shape({
 var import_yup13 = require("yup");
 var SkillSchema = (0, import_yup13.object)({
   name: (0, import_yup13.string)().trim().required().label("Skill Name"),
+  /**
+   * The taxonomy concept this skill resolved to, assigned by thejob-taxonomy-service
+   * via `POST /normalize/batch`. Stable slug, e.g. "power-bi".
+   *
+   * Normalization is ADDITIVE and never authoritative over `name`: the raw string a
+   * job was posted with is always preserved, and these two fields are written
+   * alongside it. That is what makes a wrong match, a taxonomy re-run, or a service
+   * outage recoverable rather than a data loss.
+   *
+   * Optional and nullable because they genuinely are absent in two normal cases,
+   * neither of which is an error:
+   *   - the term did not resolve (~22% of mentions are a long tail the taxonomy has
+   *     no concept for yet), and the raw `name` stands alone;
+   *   - the document predates normalization and has not been re-processed.
+   *
+   * Consumers must therefore read `conceptName ?? name`, never `conceptName` alone.
+   */
+  conceptId: (0, import_yup13.string)().optional().nullable().label("Concept ID"),
+  /** Canonical display name for `conceptId`, e.g. "Power BI". See `conceptId`. */
+  conceptName: (0, import_yup13.string)().optional().nullable().label("Concept Name"),
   logo: (0, import_yup13.object)({
     light: (0, import_yup13.string)().required().label("Light Logo"),
     dark: (0, import_yup13.string)().optional().nullable().label("Dark Logo")
@@ -799,7 +819,15 @@ var JobSchema = (0, import_yup18.object)({
   designation: (0, import_yup18.string)().optional().nullable().label("Designation"),
   employmentType: (0, import_yup18.string)().required().label("Employment type"),
   workMode: (0, import_yup18.string)().required().label("Work mode"),
-  skills: (0, import_yup18.array)().of(SkillSchema.pick(["name", "logo"]).required().label("Skill")).nullable().optional().label("Skills"),
+  /**
+   * `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.
+   */
+  skills: (0, import_yup18.array)().of(
+    SkillSchema.pick(["name", "logo", "conceptId", "conceptName"]).required().label("Skill")
+  ).nullable().optional().label("Skills"),
   bookmarks: (0, import_yup18.array)().of(UserIdAndCreatedAtSchema).optional().label("Bookmarks"),
   embedding: (0, import_yup18.object)({
     vector: (0, import_yup18.array)((0, import_yup18.number)().required()).optional().label("Embedding vector"),

package/dist/index.d.cts

@@ -437,6 +437,8 @@ declare const JobSchema: ObjectSchema<{
     employmentType: string;
     workMode: string;
     skills: {
+        conceptId?: string | null | undefined;
+        conceptName?: string | null | undefined;
         name: string;
         logo: {
             dark?: string | null | undefined;
@@ -1736,6 +1738,8 @@ declare const FeedbackSchema: yup.ObjectSchema<{
 
 declare const SkillSchema: yup.ObjectSchema<{
     name: string;
+    conceptId: string | null | undefined;
+    conceptName: string | null | undefined;
     logo: {
         dark?: string | null | undefined;
         light: string;
@@ -1749,6 +1753,8 @@ declare const SkillSchema: yup.ObjectSchema<{
     updatedAt: number | undefined;
 }, yup.AnyObject, {
     name: undefined;
+    conceptId: undefined;
+    conceptName: undefined;
     logo: null;
     tags: "";
     shortId: undefined;

package/dist/index.d.ts

@@ -437,6 +437,8 @@ declare const JobSchema: ObjectSchema<{
     employmentType: string;
     workMode: string;
     skills: {
+        conceptId?: string | null | undefined;
+        conceptName?: string | null | undefined;
         name: string;
         logo: {
             dark?: string | null | undefined;
@@ -1736,6 +1738,8 @@ declare const FeedbackSchema: yup.ObjectSchema<{
 
 declare const SkillSchema: yup.ObjectSchema<{
     name: string;
+    conceptId: string | null | undefined;
+    conceptName: string | null | undefined;
     logo: {
         dark?: string | null | undefined;
         light: string;
@@ -1749,6 +1753,8 @@ declare const SkillSchema: yup.ObjectSchema<{
     updatedAt: number | undefined;
 }, yup.AnyObject, {
     name: undefined;
+    conceptId: undefined;
+    conceptName: undefined;
     logo: null;
     tags: "";
     shortId: undefined;

package/dist/index.js

@@ -417,6 +417,26 @@ var PageSchema = object10().shape({
 import { array as array6, object as object11, string as string8 } from "yup";
 var SkillSchema = object11({
   name: string8().trim().required().label("Skill Name"),
+  /**
+   * The taxonomy concept this skill resolved to, assigned by thejob-taxonomy-service
+   * via `POST /normalize/batch`. Stable slug, e.g. "power-bi".
+   *
+   * Normalization is ADDITIVE and never authoritative over `name`: the raw string a
+   * job was posted with is always preserved, and these two fields are written
+   * alongside it. That is what makes a wrong match, a taxonomy re-run, or a service
+   * outage recoverable rather than a data loss.
+   *
+   * Optional and nullable because they genuinely are absent in two normal cases,
+   * neither of which is an error:
+   *   - the term did not resolve (~22% of mentions are a long tail the taxonomy has
+   *     no concept for yet), and the raw `name` stands alone;
+   *   - the document predates normalization and has not been re-processed.
+   *
+   * Consumers must therefore read `conceptName ?? name`, never `conceptName` alone.
+   */
+  conceptId: string8().optional().nullable().label("Concept ID"),
+  /** Canonical display name for `conceptId`, e.g. "Power BI". See `conceptId`. */
+  conceptName: string8().optional().nullable().label("Concept Name"),
   logo: object11({
     light: string8().required().label("Light Logo"),
     dark: string8().optional().nullable().label("Dark Logo")
@@ -622,7 +642,15 @@ var JobSchema = object16({
   designation: string13().optional().nullable().label("Designation"),
   employmentType: string13().required().label("Employment type"),
   workMode: string13().required().label("Work mode"),
-  skills: array8().of(SkillSchema.pick(["name", "logo"]).required().label("Skill")).nullable().optional().label("Skills"),
+  /**
+   * `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.
+   */
+  skills: array8().of(
+    SkillSchema.pick(["name", "logo", "conceptId", "conceptName"]).required().label("Skill")
+  ).nullable().optional().label("Skills"),
   bookmarks: array8().of(UserIdAndCreatedAtSchema).optional().label("Bookmarks"),
   embedding: object16({
     vector: array8(number5().required()).optional().label("Embedding vector"),

package/package.json

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

package/src/job/job.schema.ts

@@ -69,8 +69,18 @@ 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.
+   */
   skills: array()
-    .of(SkillSchema.pick(["name", "logo"]).required().label("Skill"))
+    .of(
+      SkillSchema.pick(["name", "logo", "conceptId", "conceptName"])
+        .required()
+        .label("Skill"),
+    )
     .nullable()
     .optional()
     .label("Skills"),

package/src/skill/skill.schema.ts

@@ -3,6 +3,29 @@ import { DbDefaultSchema } from "../common/common.schema.js";
 
 export const SkillSchema = object({
   name: string().trim().required().label("Skill Name"),
+
+  /**
+   * The taxonomy concept this skill resolved to, assigned by thejob-taxonomy-service
+   * via `POST /normalize/batch`. Stable slug, e.g. "power-bi".
+   *
+   * Normalization is ADDITIVE and never authoritative over `name`: the raw string a
+   * job was posted with is always preserved, and these two fields are written
+   * alongside it. That is what makes a wrong match, a taxonomy re-run, or a service
+   * outage recoverable rather than a data loss.
+   *
+   * Optional and nullable because they genuinely are absent in two normal cases,
+   * neither of which is an error:
+   *   - the term did not resolve (~22% of mentions are a long tail the taxonomy has
+   *     no concept for yet), and the raw `name` stands alone;
+   *   - the document predates normalization and has not been re-processed.
+   *
+   * Consumers must therefore read `conceptName ?? name`, never `conceptName` alone.
+   */
+  conceptId: string().optional().nullable().label("Concept ID"),
+
+  /** Canonical display name for `conceptId`, e.g. "Power BI". See `conceptId`. */
+  conceptName: string().optional().nullable().label("Concept Name"),
+
   logo: object({
     light: string().required().label("Light Logo"),
     dark: string().optional().nullable().label("Dark Logo"),