Job Posting Page Schema

One open role at one store: a JobPosting with a clean title, pay range and closing date, hired by the Organization from the homepage and based at the store from its location page.

When To Use It

Use on the page for one open job that people can apply for. Each role gets its own page and its own JobPosting.

The employer is the Organization from the homepage, by @id. The work location is the store, with the same @id as its location page, and its address repeated because Google reads the job location on its own.

How The Pieces Connect

Every node has a stable @id. A node is written out once, where it belongs, and everywhere else it is referenced by that @id alone. This is the map for this page, generated from the output below.

Nodes and the @id links between them
@idDefined onTypeReferenced by
/careers/store-associate-portland/#webpageThis pageWebPageTop-level node
/careers/store-associate-portland/#breadcrumbThis pageBreadcrumbListWebPage.breadcrumb
/careers/store-associate-portland/#jobThis pageJobPostingWebPage.mainEntity
/stores/portland/#locationThis pagePlaceNested in JobPosting.jobLocation
/#organizationHomepageOnlineStoreJobPosting.hiringOrganization
/#websiteHomepageWebSiteWebPage.isPartOf

The Builder

One function turns the page's data into the whole graph. It drops anything Google would reject instead of shipping it half built. The input below includes rows it is meant to drop, so you can see the logic work.

// Job posting page schema: one open role at one of the store's locations.
// JobPosting with the hiring Organization from the homepage by @id, the work
// location as the same store @id used on the location page, salary and
// expiry, plus the page's WebPage and BreadcrumbList.

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
const COUNTRY = /^[A-Z]{2}$/;
const CURRENCY = /^[A-Z]{3}$/;

const clean = (v) => (typeof v === 'string' ? v.trim() : v);
const isUrl = (v) => typeof v === 'string' && /^https:\/\/[^\s]+$/.test(v);
const compact = (obj) => {
  if (Array.isArray(obj)) {
    const out = obj.map(compact).filter((v) => v !== undefined);
    return out.length ? out : undefined;
  }
  if (obj && typeof obj === 'object') {
    const out = {};
    for (const [k, v] of Object.entries(obj)) {
      const c = compact(v);
      if (c !== undefined) out[k] = c;
    }
    return Object.keys(out).length ? out : undefined;
  }
  return obj === null || obj === '' ? undefined : obj;
};

function breadcrumb(trail, id) {
  const items = (trail || []).filter((c) => c.name && isUrl(c.url));
  if (items.length < 2) return undefined;
  return {
    '@type': 'BreadcrumbList',
    '@id': id,
    itemListElement: items.map((c, i) => ({ '@type': 'ListItem', position: i + 1, name: clean(c.name), item: c.url })),
  };
}

const EMPLOYMENT = { full_time: 'FULL_TIME', part_time: 'PART_TIME', contract: 'CONTRACTOR', temporary: 'TEMPORARY', intern: 'INTERN', seasonal: 'TEMPORARY' };
const UNIT = { hour: 'HOUR', week: 'WEEK', month: 'MONTH', year: 'YEAR' };

// Pay: a single figure or a range, never a range that runs backwards.
function salary(pay) {
  if (!pay || !CURRENCY.test(pay.currency || '') || !UNIT[pay.per]) return undefined;
  const min = Number(pay.min);
  const max = Number(pay.max);
  let value;
  if (Number.isFinite(min) && Number.isFinite(max) && min > 0 && max > min) value = { minValue: min, maxValue: max };
  else if (Number.isFinite(min) && min > 0) value = { value: min };
  else return undefined;
  return { '@type': 'MonetaryAmount', currency: pay.currency, value: { '@type': 'QuantitativeValue', ...value, unitText: UNIT[pay.per] } };
}

function buildJobPostingPageSchema(source) {
  const site = source.site || {};
  const page = source.page || {};
  const job = source.job || {};
  const where = job.location || {};
  if (!isUrl(site.url) || !isUrl(page.url) || !job.title || !job.descriptionHtml) return null;
  if (!ISO_DATE.test(job.datePosted || '')) return null;

  // A posting past its closing date is not marked up at all; Google asks for
  // expired jobs to be removed, not left with a past validThrough.
  const today = (source.today || new Date().toISOString()).slice(0, 10);
  if (ISO_DATE.test(job.validThrough || '') && job.validThrough < today) return null;

  // The title is the job title only: no codes, pay, dates or exclamation marks.
  const title = clean(job.title).replace(/\s*[(#].*$/, '').replace(/!+/g, '').trim();

  const remote = job.remoteCountries && job.remoteCountries.length;
  const onsite = where.street && where.city && COUNTRY.test(where.country || '');
  if (!remote && !onsite) return null;

  const root = site.url.replace(/\/+$/, '');
  const pageUrl = page.url;
  const jobId = `${pageUrl}#job`;

  const posting = compact({
    '@type': 'JobPosting',
    '@id': jobId,
    title,
    description: job.descriptionHtml.trim(),
    identifier: job.reference ? { '@type': 'PropertyValue', name: clean(site.name) || 'Job reference', value: String(job.reference) } : undefined,
    datePosted: job.datePosted,
    validThrough: ISO_DATE.test(job.validThrough || '') ? `${job.validThrough}T23:59:59${job.timezoneOffset || 'Z'}` : undefined,
    employmentType: [].concat(job.employmentType || []).map((t) => EMPLOYMENT[t]).filter(Boolean),
    hiringOrganization: { '@id': `${root}/#organization` },
    // The work site is the store from its location page: same @id, with the
    // address repeated because Google reads jobLocation on its own.
    jobLocation: onsite
      ? {
          '@type': 'Place',
          '@id': isUrl(where.locationPageUrl) ? `${where.locationPageUrl}#location` : undefined,
          name: clean(where.name),
          address: {
            '@type': 'PostalAddress',
            streetAddress: clean(where.street),
            addressLocality: clean(where.city),
            addressRegion: clean(where.region),
            postalCode: clean(where.postalCode),
            addressCountry: where.country,
          },
        }
      : undefined,
    jobLocationType: remote && !onsite ? 'TELECOMMUTE' : undefined,
    applicantLocationRequirements: remote
      ? job.remoteCountries.filter((c) => COUNTRY.test(c)).map((c) => ({ '@type': 'Country', name: c }))
      : undefined,
    baseSalary: salary(job.pay),
    directApply: typeof job.directApply === 'boolean' ? job.directApply : undefined,
    experienceRequirements: Number.isInteger(job.monthsExperience) && job.monthsExperience > 0
      ? { '@type': 'OccupationalExperienceRequirements', monthsOfExperience: job.monthsExperience }
      : undefined,
    experienceInPlaceOfEducation: job.monthsExperience > 0 ? true : undefined,
  });

  const crumbs = breadcrumb(page.breadcrumbs, `${pageUrl}#breadcrumb`);
  const webpage = compact({
    '@type': 'WebPage',
    '@id': `${pageUrl}#webpage`,
    url: pageUrl,
    name: clean(page.title) || title,
    isPartOf: { '@id': `${root}/#website` },
    breadcrumb: crumbs ? { '@id': crumbs['@id'] } : undefined,
    mainEntity: { '@id': jobId },
  });

  return { '@context': 'https://schema.org', '@graph': [webpage, crumbs, posting].filter(Boolean) };
}

The Logic As A Flowchart

The same logic as the builder above, drawn for readers who do not write code. Every Yes moves down. A No that runs out to the line on the right stops everything, and no schema is output. Where the path splits, exactly one branch is taken. Each step was run against the builder itself before this page was published: 42 test cases, all passing.

  1. A page for one open job
  2. 1Site has an https URL?the home page addressNo: no schema
    Yes
  3. 2Page has an https URL?the address of this pageNo: no schema
    Yes
  4. 3Has a job title?the title shown on the pageNo: no schema
    Yes
  5. 4Has a description?the full description, in HTMLNo: no schema
    Yes
  6. 5Posting date is a calendar date?written as YYYY-MM-DDNo: no schema
    Yes
  7. 6Still open?the closing date, when given, has not passedNo: no schema
    Yes
  8. 7Has a full work address, or countries to work from?a street, a city and a 2-letter country, or a list of countries for remote workNo: no schema
    Yes
  9. Where is the work done?decides how the location is written
    At a workplace
    The address is the job location
    Remote only
    Marked as telecommute, with the countries applicants can work from
    A workplace, with remote work from listed countries
    Both the address and the countries are given
  10. Two or more breadcrumbs with a name and an https link?the trail shown on the page
    Yes
    A BreadcrumbList is added and linked from the page
    No
    No BreadcrumbList
  11. Build the linked nodesWebPage and JobPosting, with the hiring organization pointing at the homepage Organization by @id. Anything optional that is missing or invalid is left out
  12. Output WebPage and JobPosting
    No schema

Validation

The output above was run through the SchemaCDN validator, which checks every rule in Google's documentation for each feature. It was validated together with the homepage graph, so the @id links resolve. Result: no errors, and eligible for:

Breadcrumb Job posting

Left Out On Purpose

  • The requisition number and the exclamation mark in the title. Google wants the job title alone; the number goes in identifier.
  • An employer rating. Employer ratings belong on review sites, not on the employer's own careers page.
  • Remote work fields, because the role is on site.

Implementation Checklist

  • Keep the title to the job title itself, with no codes, pay or punctuation.
  • Give validThrough a time and timezone, and take the posting down when it closes.
  • Write pay as a range with a unit (hour, month, year) that matches the page.
  • Use the store's full street address for an on-site role.
  • Keep the description the same as the visible one, in HTML.

Other Page Types