Job Posting Schema Framework

const ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?(Z|[+-]\d{2}:\d{2})?)?$/;

function isAbsoluteUrl(value) {
  return typeof value === "string" && /^https?:\/\/[^\s/?#]+\.[^\s/?#]+(?:[/?#]\S*)?$/i.test(value);
}

// Returns the ISO 8601 string unchanged (timezone offset kept), or null if unparseable.
function toIsoDateTime(value) {
  if (typeof value !== "string") return null;
  const text = value.trim();
  const m = text.match(ISO_DATE_TIME);
  if (!m) return null;
  const [, y, mo, d, h = "00", mi = "00", s = "00"] = m;
  const date = new Date(Date.UTC(+y, +mo - 1, +d));
  if (date.getUTCMonth() !== +mo - 1 || date.getUTCDate() !== +d) return null;
  if (+h > 23 || +mi > 59 || +s > 59) return null;
  return text;
}

function toIsoDate(value) {
  const iso = toIsoDateTime(value);
  return iso ? iso.slice(0, 10) : null;
}

// Drops null, undefined, "", [] and {} recursively.
function compact(value) {
  if (Array.isArray(value)) {
    const items = value.map(compact).filter((v) => v !== undefined);
    return items.length ? items : undefined;
  }
  if (value && typeof value === "object") {
    const out = {};
    for (const [key, v] of Object.entries(value)) {
      const c = compact(v);
      if (c !== undefined) out[key] = c;
    }
    return Object.keys(out).length ? out : undefined;
  }
  return value === null || value === undefined || value === "" ? undefined : value;
}

function passesPageGates(source) {
  if (source.indexable === false) return false;
  if (source.canonicalUrl && source.url && source.canonicalUrl !== source.url) return false;
  return source.contentVisible !== false;
}


const EMPLOYMENT_TYPES = ["FULL_TIME", "PART_TIME", "CONTRACTOR", "TEMPORARY", "INTERN", "VOLUNTEER", "PER_DIEM", "OTHER"];
const SALARY_UNITS = ["HOUR", "DAY", "WEEK", "MONTH", "YEAR"];
const CREDENTIAL_CATEGORIES = ["high school", "associate degree", "bachelor degree", "professional certificate", "postgraduate degree"];

function toCountryCode(value) {
  const code = String(value || "").toUpperCase();
  return /^[A-Z]{2}$/.test(code) ? code : null;
}

function buildJobPlace(location) {
  const country = toCountryCode(location.country);
  if (!country) return null; // addressCountry is required on every jobLocation
  return {
    "@type": "Place",
    address: {
      "@type": "PostalAddress",
      streetAddress: location.street,
      addressLocality: location.locality,
      addressRegion: location.region,
      postalCode: location.postalCode,
      addressCountry: country
    }
  };
}

function buildBaseSalary(salary) {
  if (!salary) return null;
  const currency = String(salary.currency || "").toUpperCase();
  const unitText = String(salary.unit || "").toUpperCase();
  if (!/^[A-Z]{3}$/.test(currency) || !SALARY_UNITS.includes(unitText)) return null;
  const { value, min, max } = salary;
  if (value == null && (min == null || max == null || min > max)) return null; // a value, or a valid range
  return {
    "@type": "MonetaryAmount",
    currency,
    value: {
      "@type": "QuantitativeValue",
      value: value ?? null,
      minValue: value == null ? min : null,
      maxValue: value == null ? max : null,
      unitText
    }
  };
}

function buildJobPostingSchema(source, now = new Date()) {
  // (a) Page gates: indexable, self-canonical, a single job visible on this leaf page.
  if (!passesPageGates(source)) return null;

  // (b) Required: title, description (HTML, not the title), datePosted, hiringOrganization.
  const datePosted = toIsoDateTime(source.datePosted);
  const org = source.hiringOrganization || {};
  if (!source.title || !source.descriptionHtml || !datePosted || !org.name) return null;
  if (source.descriptionHtml.trim() === source.title.trim()) return null;

  // Expired postings must not keep active markup.
  const validThrough = toIsoDateTime(source.validThrough);
  if (validThrough && Date.parse(validThrough) < now.getTime()) return null;

  // Either-or: jobLocation, or applicantLocationRequirements for fully remote jobs.
  const jobLocation = (source.locations || []).map(buildJobPlace).filter(Boolean);
  const applicantCountries = (source.remoteEligibleCountries || []).map(toCountryCode).filter(Boolean);
  const isRemote = source.fullyRemote === true;
  if (isRemote && !applicantCountries.length && !jobLocation.length) return null; // TELECOMMUTE needs a country
  if (!isRemote && !jobLocation.length) return null;

  // (c) Required + recommended properties, only when the source has them.
  const schema = {
    "@context": "https://schema.org",
    "@type": "JobPosting",
    title: source.title,
    description: source.descriptionHtml,
    datePosted,
    validThrough,
    hiringOrganization: {
      "@type": "Organization",
      name: org.name,
      sameAs: isAbsoluteUrl(org.url) ? org.url : null,
      logo: isAbsoluteUrl(org.logo) ? org.logo : null
    },
    jobLocation,
    jobLocationType: isRemote ? "TELECOMMUTE" : null,
    applicantLocationRequirements: isRemote
      ? applicantCountries.map((code) => ({ "@type": "Country", name: code }))
      : null,
    // (d) Custom rules: enums, salary range, booleans.
    employmentType: (source.employmentTypes || []).filter((t) => EMPLOYMENT_TYPES.includes(t)),
    baseSalary: source.postedByEmployer ? buildBaseSalary(source.salary) : null, // only employers provide baseSalary
    directApply: typeof source.directApply === "boolean" ? source.directApply : null,
    identifier: source.requisitionId && {
      "@type": "PropertyValue",
      name: org.name,
      value: String(source.requisitionId)
    },
    educationRequirements: CREDENTIAL_CATEGORIES.includes(source.education) ? {
      "@type": "EducationalOccupationalCredential",
      credentialCategory: source.education
    } : null,
    experienceRequirements: Number.isInteger(source.monthsOfExperience) && source.monthsOfExperience >= 0 ? {
      "@type": "OccupationalExperienceRequirements",
      monthsOfExperience: source.monthsOfExperience
    } : null,
    experienceInPlaceOfEducation: typeof source.experienceInPlaceOfEducation === "boolean"
      ? source.experienceInPlaceOfEducation
      : null
  };

  // (e) Strip empty values.
  return compact(schema);
}

// Usage:
// const source = {
//   "url": "https://www.example.com/careers/senior-technical-seo-analyst",
//   "canonicalUrl": "https://www.example.com/careers/senior-technical-seo-analyst",
//   "indexable": true,
//   "contentVisible": true,
//   "title": "Senior Technical SEO Analyst",
//   "descriptionHtml": "<p>Own technical SEO for a 40,000 page ecommerce catalog.</p><ul><li>Audit crawling, rendering and indexing</li><li>Ship structured data with engineering</li></ul><p>Hybrid schedule, three days a week in our Waltham office.</p>",
//   "datePosted": "2026-09-28",
//   "validThrough": "2026-12-31T23:59:00-05:00",
//   "hiringOrganization": {
//     "name": "Example Retail Group",
//     "url": "https://www.example.com",
//     "logo": "https://www.example.com/images/logo-square.png"
//   },
//   "locations": [
//     {
//       "street": "50 Main Street",
//       "locality": "Waltham",
//       "region": "MA",
//       "postalCode": "02453",
//       "country": "US"
//     }
//   ],
//   "fullyRemote": false,
//   "employmentTypes": [
//     "FULL_TIME"
//   ],
//   "postedByEmployer": true,
//   "salary": {
//     "currency": "USD",
//     "min": 110000,
//     "max": 135000,
//     "unit": "YEAR"
//   },
//   "directApply": true,
//   "requisitionId": "SEO-2026-114",
//   "education": "bachelor degree",
//   "monthsOfExperience": 48,
//   "experienceInPlaceOfEducation": true
// };
// const schema = buildJobPostingSchema(source); // null when a gate or required property fails

import re
from datetime import date, datetime, timezone

ISO_DATE_TIME = re.compile(r"^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?(Z|[+-]\d{2}:\d{2})?)?$")
ABSOLUTE_URL = re.compile(r"^https?://[^\s/?#]+\.[^\s/?#]+(?:[/?#]\S*)?$", re.I)


def is_absolute_url(value):
    return isinstance(value, str) and bool(ABSOLUTE_URL.match(value))


# Returns the ISO 8601 string unchanged (timezone offset kept), or None if unparseable.
def to_iso_date_time(value):
    if not isinstance(value, str):
        return None
    text = value.strip()
    m = ISO_DATE_TIME.match(text)
    if not m:
        return None
    y, mo, d = int(m[1]), int(m[2]), int(m[3])
    try:
        date(y, mo, d)
    except ValueError:
        return None
    if int(m[4] or 0) > 23 or int(m[5] or 0) > 59 or int(m[6] or 0) > 59:
        return None
    return text


def to_iso_date(value):
    iso = to_iso_date_time(value)
    return iso[:10] if iso else None


# Drops None, "", [] and {} recursively.
def compact(value):
    if isinstance(value, list):
        items = [c for c in (compact(v) for v in value) if c is not None]
        return items or None
    if isinstance(value, dict):
        out = {k: c for k, c in ((k, compact(v)) for k, v in value.items()) if c is not None}
        return out or None
    return None if value is None or value == "" else value


def passes_page_gates(source):
    if source.get("indexable") is False:
        return False
    if source.get("canonicalUrl") and source.get("url") and source["canonicalUrl"] != source["url"]:
        return False
    return source.get("contentVisible") is not False


EMPLOYMENT_TYPES = ["FULL_TIME", "PART_TIME", "CONTRACTOR", "TEMPORARY", "INTERN", "VOLUNTEER", "PER_DIEM", "OTHER"]
SALARY_UNITS = ["HOUR", "DAY", "WEEK", "MONTH", "YEAR"]
CREDENTIAL_CATEGORIES = ["high school", "associate degree", "bachelor degree", "professional certificate", "postgraduate degree"]


def to_country_code(value):
    code = str(value or "").upper()
    return code if re.fullmatch(r"[A-Z]{2}", code) else None


def parse_instant(value):
    text = value.replace("Z", "+00:00") if "T" in value else value + "T00:00:00+00:00"
    parsed = datetime.fromisoformat(text)
    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)


def build_job_place(location):
    country = to_country_code(location.get("country"))
    if not country:
        return None  # addressCountry is required on every jobLocation
    return {
        "@type": "Place",
        "address": {
            "@type": "PostalAddress",
            "streetAddress": location.get("street"),
            "addressLocality": location.get("locality"),
            "addressRegion": location.get("region"),
            "postalCode": location.get("postalCode"),
            "addressCountry": country,
        },
    }


def build_base_salary(salary):
    if not salary:
        return None
    currency = str(salary.get("currency") or "").upper()
    unit_text = str(salary.get("unit") or "").upper()
    if not re.fullmatch(r"[A-Z]{3}", currency) or unit_text not in SALARY_UNITS:
        return None
    value, low, high = salary.get("value"), salary.get("min"), salary.get("max")
    if value is None and (low is None or high is None or low > high):
        return None  # a value, or a valid range
    return {
        "@type": "MonetaryAmount",
        "currency": currency,
        "value": {
            "@type": "QuantitativeValue",
            "value": value,
            "minValue": low if value is None else None,
            "maxValue": high if value is None else None,
            "unitText": unit_text,
        },
    }


def build_job_posting_schema(source, now=None):
    now = now or datetime.now(timezone.utc)
    # (a) Page gates: indexable, self-canonical, a single job visible on this leaf page.
    if not passes_page_gates(source):
        return None

    # (b) Required: title, description (HTML, not the title), datePosted, hiringOrganization.
    date_posted = to_iso_date_time(source.get("datePosted"))
    org = source.get("hiringOrganization") or {}
    title, description = source.get("title"), source.get("descriptionHtml")
    if not title or not description or not date_posted or not org.get("name"):
        return None
    if description.strip() == title.strip():
        return None

    # Expired postings must not keep active markup.
    valid_through = to_iso_date_time(source.get("validThrough"))
    if valid_through and parse_instant(valid_through) < now:
        return None

    # Either-or: jobLocation, or applicantLocationRequirements for fully remote jobs.
    job_location = [p for p in (build_job_place(l) for l in source.get("locations") or []) if p]
    applicant_countries = [c for c in (to_country_code(v) for v in source.get("remoteEligibleCountries") or []) if c]
    is_remote = source.get("fullyRemote") is True
    if is_remote and not applicant_countries and not job_location:
        return None  # TELECOMMUTE needs a country
    if not is_remote and not job_location:
        return None

    months = source.get("monthsOfExperience")
    # (c) Required + recommended properties, only when the source has them.
    schema = {
        "@context": "https://schema.org",
        "@type": "JobPosting",
        "title": title,
        "description": description,
        "datePosted": date_posted,
        "validThrough": valid_through,
        "hiringOrganization": {
            "@type": "Organization",
            "name": org["name"],
            "sameAs": org.get("url") if is_absolute_url(org.get("url")) else None,
            "logo": org.get("logo") if is_absolute_url(org.get("logo")) else None,
        },
        "jobLocation": job_location,
        "jobLocationType": "TELECOMMUTE" if is_remote else None,
        "applicantLocationRequirements": (
            [{"@type": "Country", "name": code} for code in applicant_countries] if is_remote else None
        ),
        # (d) Custom rules: enums, salary range, booleans.
        "employmentType": [t for t in source.get("employmentTypes") or [] if t in EMPLOYMENT_TYPES],
        "baseSalary": build_base_salary(source.get("salary")) if source.get("postedByEmployer") else None,
        "directApply": source.get("directApply") if isinstance(source.get("directApply"), bool) else None,
        "identifier": source.get("requisitionId") and {
            "@type": "PropertyValue",
            "name": org["name"],
            "value": str(source["requisitionId"]),
        },
        "educationRequirements": {
            "@type": "EducationalOccupationalCredential",
            "credentialCategory": source.get("education"),
        } if source.get("education") in CREDENTIAL_CATEGORIES else None,
        "experienceRequirements": {
            "@type": "OccupationalExperienceRequirements",
            "monthsOfExperience": months,
        } if isinstance(months, int) and not isinstance(months, bool) and months >= 0 else None,
        "experienceInPlaceOfEducation": (
            source.get("experienceInPlaceOfEducation")
            if isinstance(source.get("experienceInPlaceOfEducation"), bool) else None
        ),
    }

    # (e) Strip empty values.
    return compact(schema)

{
  "@context": "https://schema.org",
  "@type": "JobPosting",
  "title": "Senior Technical SEO Analyst",
  "description": "<p>Own technical SEO for a 40,000 page ecommerce catalog.</p><ul><li>Audit crawling, rendering and indexing</li><li>Ship structured data with engineering</li></ul><p>Hybrid schedule, three days a week in our Waltham office.</p>",
  "datePosted": "2026-09-28",
  "validThrough": "2026-12-31T23:59:00-05:00",
  "hiringOrganization": {
    "@type": "Organization",
    "name": "Example Retail Group",
    "sameAs": "https://www.example.com",
    "logo": "https://www.example.com/images/logo-square.png"
  },
  "jobLocation": [
    {
      "@type": "Place",
      "address": {
        "@type": "PostalAddress",
        "streetAddress": "50 Main Street",
        "addressLocality": "Waltham",
        "addressRegion": "MA",
        "postalCode": "02453",
        "addressCountry": "US"
      }
    }
  ],
  "employmentType": [
    "FULL_TIME"
  ],
  "baseSalary": {
    "@type": "MonetaryAmount",
    "currency": "USD",
    "value": {
      "@type": "QuantitativeValue",
      "minValue": 110000,
      "maxValue": 135000,
      "unitText": "YEAR"
    }
  },
  "directApply": true,
  "identifier": {
    "@type": "PropertyValue",
    "name": "Example Retail Group",
    "value": "SEO-2026-114"
  },
  "educationRequirements": {
    "@type": "EducationalOccupationalCredential",
    "credentialCategory": "bachelor degree"
  },
  "experienceRequirements": {
    "@type": "OccupationalExperienceRequirements",
    "monthsOfExperience": 48
  },
  "experienceInPlaceOfEducation": true
}