@thejob/schema 2.1.5 → 2.1.7

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"),
@@ -2541,6 +2569,25 @@ var UserGeneralDetailSchema = (0, import_yup33.object)({
   emailVerified: (0, import_yup33.string)().nullable().optional().label("Email Verified"),
   mobileVerified: (0, import_yup33.string)().nullable().optional().label("Mobile Verified"),
   experienceLevel: (0, import_yup33.string)().oneOf(SupportedExperienceLevels).required().label("Experience level"),
+  /**
+   * The user's HIGHEST qualification, e.g. `bachelor`.
+   *
+   * The counterpart of `JobSchema.educationLevel` (what a listing requires), so
+   * matching can compare the two directly. Nothing on the user side answered
+   * that question before: `educations[].studyType` is the MODE of study
+   * (`full_time`, `online`) and says nothing about attainment.
+   *
+   * Deliberately top-level and singular, alongside `experienceLevel`, rather
+   * than per `educations` entry: what matching needs is one fact about the
+   * person, and deriving it by ranking every entry would make the answer depend
+   * on how completely a user filled in their history.
+   *
+   * Optional, unlike `experienceLevel`: every existing user predates it. An
+   * absent value means "level unknown", which must leave matching
+   * UNCONSTRAINED on education rather than filtering the user out — the same
+   * opt-out reasoning `notificationPrefs` uses.
+   */
+  educationLevel: (0, import_yup33.string)().oneOf(SupportedEducationLevels).optional().label("Education level"),
   location: LocationSchema.required().label("Location"),
   /**
    * Where the account was created, captured once and never rewritten.

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;
@@ -1937,6 +1943,7 @@ declare const UserSchema: yup.ObjectSchema<{
     emailVerified: string | null | undefined;
     mobileVerified: string | null | undefined;
     experienceLevel: NonNullable<ExperienceLevel | undefined>;
+    educationLevel: EducationLevel | undefined;
     location: {
         placeId?: string | null | undefined;
         state?: string | null | undefined;
@@ -2144,6 +2151,7 @@ declare const UserSchema: yup.ObjectSchema<{
     emailVerified: undefined;
     mobileVerified: undefined;
     experienceLevel: undefined;
+    educationLevel: undefined;
     location: {
         placeId: undefined;
         country: undefined;
@@ -2196,6 +2204,7 @@ declare const UserGeneralDetailSchema: yup.ObjectSchema<{
     emailVerified: string | null | undefined;
     mobileVerified: string | null | undefined;
     experienceLevel: NonNullable<ExperienceLevel | undefined>;
+    educationLevel: EducationLevel | undefined;
     location: {
         placeId?: string | null | undefined;
         state?: string | null | undefined;
@@ -2230,6 +2239,7 @@ declare const UserGeneralDetailSchema: yup.ObjectSchema<{
     emailVerified: undefined;
     mobileVerified: undefined;
     experienceLevel: undefined;
+    educationLevel: undefined;
     location: {
         placeId: undefined;
         country: 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;
@@ -1937,6 +1943,7 @@ declare const UserSchema: yup.ObjectSchema<{
     emailVerified: string | null | undefined;
     mobileVerified: string | null | undefined;
     experienceLevel: NonNullable<ExperienceLevel | undefined>;
+    educationLevel: EducationLevel | undefined;
     location: {
         placeId?: string | null | undefined;
         state?: string | null | undefined;
@@ -2144,6 +2151,7 @@ declare const UserSchema: yup.ObjectSchema<{
     emailVerified: undefined;
     mobileVerified: undefined;
     experienceLevel: undefined;
+    educationLevel: undefined;
     location: {
         placeId: undefined;
         country: undefined;
@@ -2196,6 +2204,7 @@ declare const UserGeneralDetailSchema: yup.ObjectSchema<{
     emailVerified: string | null | undefined;
     mobileVerified: string | null | undefined;
     experienceLevel: NonNullable<ExperienceLevel | undefined>;
+    educationLevel: EducationLevel | undefined;
     location: {
         placeId?: string | null | undefined;
         state?: string | null | undefined;
@@ -2230,6 +2239,7 @@ declare const UserGeneralDetailSchema: yup.ObjectSchema<{
     emailVerified: undefined;
     mobileVerified: undefined;
     experienceLevel: undefined;
+    educationLevel: undefined;
     location: {
         placeId: undefined;
         country: 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"),
@@ -2364,6 +2392,25 @@ var UserGeneralDetailSchema = object30({
   emailVerified: string28().nullable().optional().label("Email Verified"),
   mobileVerified: string28().nullable().optional().label("Mobile Verified"),
   experienceLevel: string28().oneOf(SupportedExperienceLevels).required().label("Experience level"),
+  /**
+   * The user's HIGHEST qualification, e.g. `bachelor`.
+   *
+   * The counterpart of `JobSchema.educationLevel` (what a listing requires), so
+   * matching can compare the two directly. Nothing on the user side answered
+   * that question before: `educations[].studyType` is the MODE of study
+   * (`full_time`, `online`) and says nothing about attainment.
+   *
+   * Deliberately top-level and singular, alongside `experienceLevel`, rather
+   * than per `educations` entry: what matching needs is one fact about the
+   * person, and deriving it by ranking every entry would make the answer depend
+   * on how completely a user filled in their history.
+   *
+   * Optional, unlike `experienceLevel`: every existing user predates it. An
+   * absent value means "level unknown", which must leave matching
+   * UNCONSTRAINED on education rather than filtering the user out — the same
+   * opt-out reasoning `notificationPrefs` uses.
+   */
+  educationLevel: string28().oneOf(SupportedEducationLevels).optional().label("Education level"),
   location: LocationSchema.required().label("Location"),
   /**
    * Where the account was created, captured once and never rewritten.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thejob/schema",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "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"),

package/src/user/general-detail.schema.ts

@@ -1,5 +1,8 @@
 import { number, object, string } from "yup";
-import { SupportedExperienceLevels } from "../common/common.constant.js";
+import {
+  SupportedEducationLevels,
+  SupportedExperienceLevels,
+} from "../common/common.constant.js";
 import { LocationSchema } from "../location/location.schema.js";
 import {
   SupportedSignupContextSources,
@@ -30,6 +33,28 @@ export const UserGeneralDetailSchema = object({
     .oneOf(SupportedExperienceLevels)
     .required()
     .label("Experience level"),
+  /**
+   * The user's HIGHEST qualification, e.g. `bachelor`.
+   *
+   * The counterpart of `JobSchema.educationLevel` (what a listing requires), so
+   * matching can compare the two directly. Nothing on the user side answered
+   * that question before: `educations[].studyType` is the MODE of study
+   * (`full_time`, `online`) and says nothing about attainment.
+   *
+   * Deliberately top-level and singular, alongside `experienceLevel`, rather
+   * than per `educations` entry: what matching needs is one fact about the
+   * person, and deriving it by ranking every entry would make the answer depend
+   * on how completely a user filled in their history.
+   *
+   * Optional, unlike `experienceLevel`: every existing user predates it. An
+   * absent value means "level unknown", which must leave matching
+   * UNCONSTRAINED on education rather than filtering the user out — the same
+   * opt-out reasoning `notificationPrefs` uses.
+   */
+  educationLevel: string()
+    .oneOf(SupportedEducationLevels)
+    .optional()
+    .label("Education level"),
   location: LocationSchema.required().label("Location"),
   /**
    * Where the account was created, captured once and never rewritten.