@thejob/schema 2.5.0 → 2.7.0

package/package.json

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

package/src/index.ts

@@ -118,6 +118,17 @@ export * from "./skill/skill.schema.js";
 export * from "./billing/billing.schema.js";
 export * from "./billing/billing.constant.js";
 
+/**
+ * Taxonomy schemas and constants (thejob-taxonomy-service: concepts, backbone,
+ * vocabularies, misses, the review queue).
+ *
+ * Constants here are `as const` arrays rather than enums; see the note at the top
+ * of `taxonomy.constant.ts`.
+ */
+export * from "./taxonomy/taxonomy.schema.js";
+export * from "./taxonomy/taxonomy.constant.js";
+export * from "./taxonomy/taxonomy-filter.schema.js";
+
 /**
  * Social account schemas and constants.
  */

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-filter.schema.ts

@@ -0,0 +1,84 @@
+/**
+ * The taxonomy filters: the closed vocabulary of facets each thejob-taxonomy-service
+ * list can filter on. The counterparts of `FeedbackFilterSchema` and
+ * `SkillFilterSchema`, read by the service through `parseFilter`.
+ *
+ * Every facet is a field the matching document schema declares, named as it is
+ * there, OR within a facet and AND across facets. Absent means "no constraint".
+ *
+ * Not facets, and absent for that reason: the reserved list params (`search`,
+ * `page`, `limit`, `sortBy`, `sortDirection`, `fields`) and `vocabulary`, which
+ * the service reserves as the SCOPE of a vocabulary's lists (a concept, node,
+ * miss or draft belongs to exactly one vocabulary, and a list never mixes them).
+ */
+import { boolean, object } from "yup";
+import { enumFacet, rejectUnknownKeys, tokens } from "../common/facet.schema.js";
+import {
+  SupportedAuditStatuses,
+  SupportedProposalFilters,
+  SupportedProposalStatuses,
+  SupportedReleaseKinds,
+  SupportedReleaseStatuses,
+  SupportedTaxonomyNodeKinds,
+  SupportedUnmatchedReasons,
+  SupportedUnmatchedResolutions,
+} from "./taxonomy.constant.js";
+
+const ConceptFilterShape = object({
+  /** Type ids. Open: which types exist is the vocabulary's data. */
+  type: tokens("Type"),
+  /** Category node ids the concept is placed under (`memberships.categoryId`). */
+  categoryId: tokens("Category"),
+  /** True: only live concepts with no backbone home (the uncategorized backlog). */
+  unplaced: boolean().optional().label("Unplaced"),
+}).label("Concept Filter");
+
+export const ConceptFilterSchema = rejectUnknownKeys(ConceptFilterShape, () =>
+  Object.keys(ConceptFilterShape.fields),
+);
+
+const TaxonomyNodeFilterShape = object({
+  kind: enumFacet(SupportedTaxonomyNodeKinds, "Kind"),
+  /** Parent node ids: a node's children. */
+  parentId: tokens("Parent"),
+}).label("Taxonomy Node Filter");
+
+export const TaxonomyNodeFilterSchema = rejectUnknownKeys(TaxonomyNodeFilterShape, () =>
+  Object.keys(TaxonomyNodeFilterShape.fields),
+);
+
+const UnmatchedFilterShape = object({
+  resolution: enumFacet(SupportedUnmatchedResolutions, "Resolution"),
+  reason: enumFacet(SupportedUnmatchedReasons, "Reason"),
+}).label("Unmatched Filter");
+
+export const UnmatchedFilterSchema = rejectUnknownKeys(UnmatchedFilterShape, () =>
+  Object.keys(UnmatchedFilterShape.fields),
+);
+
+const ConceptProposalFilterShape = object({
+  status: enumFacet(SupportedProposalStatuses, "Status"),
+  /** A kind, or `uncategorized`: concept and placement drafts with no home yet. */
+  kind: enumFacet(SupportedProposalFilters, "Kind"),
+}).label("Concept Proposal Filter");
+
+export const ConceptProposalFilterSchema = rejectUnknownKeys(ConceptProposalFilterShape, () =>
+  Object.keys(ConceptProposalFilterShape.fields),
+);
+
+const ReleaseFilterShape = object({
+  kind: enumFacet(SupportedReleaseKinds, "Kind"),
+  status: enumFacet(SupportedReleaseStatuses, "Status"),
+}).label("Release Filter");
+
+export const ReleaseFilterSchema = rejectUnknownKeys(ReleaseFilterShape, () =>
+  Object.keys(ReleaseFilterShape.fields),
+);
+
+const AuditFilterShape = object({
+  status: enumFacet(SupportedAuditStatuses, "Status"),
+}).label("Audit Filter");
+
+export const AuditFilterSchema = rejectUnknownKeys(AuditFilterShape, () =>
+  Object.keys(AuditFilterShape.fields),
+);

package/src/taxonomy/taxonomy.constant.ts

@@ -0,0 +1,127 @@
+/**
+ * Taxonomy vocabulary (thejob-taxonomy-service).
+ *
+ * Every value here is stored in Mongo and compared as a literal by the service,
+ * so the strings are data, not style. Two conventions differ from the rest of the
+ * package, both deliberate:
+ *
+ * 1. **`as const` arrays, not enums.** The service compares and assigns these as
+ *    string literals (`status: 'draft'`) in hundreds of places; a TS string enum
+ *    would make every one of them a type error. The array is the single list,
+ *    and the type is derived from it, the same way as `SupportedSalaryCurrencies`.
+ * 2. **Some values keep underscores** (`spoken_language`, `new_concept`,
+ *    `rolled_back`). They are stored as written; changing one is a data
+ *    migration, not a rename.
+ */
+
+/** Who owns a concept. Only `seed` may be rewritten by a re-seed. */
+export const SupportedConceptSources = ["seed", "manual", "import"] as const;
+export type ConceptSource = (typeof SupportedConceptSources)[number];
+
+/** Who owns a backbone node or a vocabulary. Only `seed` may be rewritten by a re-seed. */
+export const SupportedTaxonomySources = ["seed", "manual"] as const;
+export type TaxonomySource = (typeof SupportedTaxonomySources)[number];
+
+/** The three levels of a vocabulary's backbone, root first. */
+export const SupportedTaxonomyNodeKinds = ["category", "subcategory", "group"] as const;
+export type TaxonomyNodeKind = (typeof SupportedTaxonomyNodeKinds)[number];
+
+/** Cheap rules that reject a miss before any model sees it, per vocabulary. */
+export const SupportedPrefilterRules = [
+  "spoken_language",
+  "no_letters",
+  "url_or_email",
+  "fragment",
+] as const;
+export type PrefilterRule = (typeof SupportedPrefilterRules)[number];
+
+/** Triage state of a miss. */
+export const SupportedUnmatchedResolutions = ["pending", "added", "rejected"] as const;
+export type UnmatchedResolution = (typeof SupportedUnmatchedResolutions)[number];
+
+/** Why a miss is not a gap: the term names several concepts and no context picked one. */
+export const SupportedUnmatchedReasons = ["ambiguous"] as const;
+export type UnmatchedReason = (typeof SupportedUnmatchedReasons)[number];
+
+/**
+ * What approving a proposal does. `concept`: a new concept. `alias`: another name
+ * for an existing concept. `placement`: a home for a concept that has none.
+ */
+export const SupportedProposalKinds = ["concept", "alias", "placement"] as const;
+export type ProposalKind = (typeof SupportedProposalKinds)[number];
+
+/** The review queue's filter: a kind, or `uncategorized` (drafts with no home yet). */
+export const SupportedProposalFilters = [...SupportedProposalKinds, "uncategorized"] as const;
+export type ProposalFilter = (typeof SupportedProposalFilters)[number];
+
+export const SupportedProposalStatuses = ["draft", "approved", "discarded"] as const;
+export type ProposalStatus = (typeof SupportedProposalStatuses)[number];
+
+export const SupportedProposalMessageRoles = ["operator", "model"] as const;
+export type ProposalMessageRole = (typeof SupportedProposalMessageRoles)[number];
+
+/** The resolver's judgement of a miss against the concepts it was shown. */
+export const SupportedResolverVerdicts = [
+  "same",
+  "narrower",
+  "broader",
+  "related",
+  "new_concept",
+  "out_of_scope",
+] as const;
+export type ResolverVerdict = (typeof SupportedResolverVerdicts)[number];
+
+/** A human's check of one auto-accepted key. */
+export const SupportedAuditStatuses = ["pending", "correct", "wrong"] as const;
+export type AuditStatus = (typeof SupportedAuditStatuses)[number];
+
+/** Where a batch of key writes came from. */
+export const SupportedReleaseKinds = ["seed", "manual", "review", "auto"] as const;
+export type ReleaseKind = (typeof SupportedReleaseKinds)[number];
+
+export const SupportedReleaseStatuses = ["open", "rolled_back"] as const;
+export type ReleaseStatus = (typeof SupportedReleaseStatuses)[number];
+
+/**
+ * How a term resolved. `exact` and `canonical` are deterministic key hits,
+ * `fuzzy` a scored search hit above the threshold, `none` no answer.
+ */
+export const SupportedMatchTypes = ["exact", "canonical", "fuzzy", "none"] as const;
+export type MatchType = (typeof SupportedMatchTypes)[number];
+
+/** The service's maintenance jobs, as started from the API or the schedule. */
+export const SupportedTaxonomyJobKinds = [
+  "describe-concepts",
+  "retype-concepts",
+  "generate-aliases",
+  "alias-backfill",
+  "close-gaps",
+  "propose-placements",
+  "place-unplaced",
+  "calibrate-placement",
+  "reseed",
+  "reindex",
+  "calibrate-resolver",
+  "golden",
+  "resolve-backlog",
+] as const;
+export type TaxonomyJobKind = (typeof SupportedTaxonomyJobKinds)[number];
+
+export const SupportedTaxonomyJobStates = ["running", "succeeded", "failed", "cancelled"] as const;
+export type TaxonomyJobState = (typeof SupportedTaxonomyJobStates)[number];
+
+/** `<vocabulary>_<slug>`, e.g. `skills_power-bi`. The vocabulary is the part before `_`. */
+export const CONCEPT_ID_PATTERN = /^[a-z][a-z0-9-]*_[a-z0-9-]+$/;
+
+/** Never `_`: concept ids use it to separate the vocabulary from the slug. */
+export const VOCABULARY_ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** Backbone node ids, e.g. `CAT_01_TECH`. Interpolated into search filters, so nothing else is allowed. */
+export const TAXONOMY_NODE_ID_PATTERN = /^[A-Za-z0-9_]{1,64}$/;
+
+/** A concept type id, e.g. `programming_language`. */
+export const CONCEPT_TYPE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+
+/** Schedule bounds, in hours: the floor protects the AI budget, the ceiling keeps it a schedule. */
+export const SCHEDULE_MIN_HOURS = 1;
+export const SCHEDULE_MAX_HOURS = 24 * 30;