Job

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/himalayas-app/json-schema/himalayas-app-job-schema.json",
  "title": "Job",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/himalayas-app-api-openapi.json#/components/schemas/Job",
  "type": "object",
  "required": [
    "title",
    "excerpt",
    "companyName",
    "companySlug",
    "companyLogo",
    "employmentType",
    "seniority",
    "currency",
    "salaryPeriod",
    "locationRestrictions",
    "timezoneRestrictions",
    "categories",
    "parentCategories",
    "description",
    "pubDate",
    "expiryDate",
    "applicationLink",
    "guid"
  ],
  "properties": {
    "title": {
      "type": "string",
      "description": "Job title"
    },
    "excerpt": {
      "type": "string",
      "description": "Short summary of the job (first few sentences of the description)"
    },
    "companyName": {
      "type": "string",
      "description": "Name of the hiring company"
    },
    "companySlug": {
      "type": "string",
      "description": "Canonical company slug for filtering and stable lookups"
    },
    "companyLogo": {
      "type": "string",
      "format": "uri",
      "description": "URL of the company logo image"
    },
    "employmentType": {
      "type": "string",
      "description": "Type of employment. 'Contractor' includes freelance and contract roles.",
      "enum": [
        "Full Time",
        "Part Time",
        "Contractor",
        "Temporary",
        "Intern",
        "Volunteer",
        "Other"
      ]
    },
    "minSalary": {
      "type": [
        "number",
        "null"
      ],
      "description": "Minimum salary in the pay period specified by salaryPeriod (default annual), in the currency field. Null if not disclosed."
    },
    "maxSalary": {
      "type": [
        "number",
        "null"
      ],
      "description": "Maximum salary in the pay period specified by salaryPeriod (default annual), in the currency field. Null if not disclosed."
    },
    "seniority": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Entry-level",
          "Mid-level",
          "Senior",
          "Manager",
          "Director",
          "Executive"
        ]
      },
      "description": "Required seniority levels. A job may accept multiple levels (e.g., both Mid-level and Senior)."
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code for the salary",
      "enum": [
        "USD",
        "AUD",
        "EUR",
        "JPY",
        "GBP",
        "CAD",
        "CHF",
        "CNY",
        "HKD",
        "NZD",
        "SGD",
        "SEK",
        "KRW",
        "NOK",
        "INR",
        "MXN",
        "TWD",
        "ZAR",
        "BRL",
        "IDR",
        "PHP",
        "THB",
        "CLP",
        "CZK",
        "DKK",
        "HUF",
        "ILS",
        "TRY",
        "PLN"
      ]
    },
    "locationRestrictions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Location"
      },
      "description": "Countries where candidates must be located to be eligible. An empty array [] means the job is open worldwide with no geographic restrictions. Match against the user's country using the alpha2 ISO code."
    },
    "timezoneRestrictions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "UTC timezone offsets the candidate must overlap with (e.g., 'UTC-5', 'UTC+5:30'). An empty array [] means no timezone requirement. To filter, check if the user's UTC offset appears in this array."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Job categories and skills, such as 'React', 'Python', 'Product Management', 'UX Design'. This is a dynamic set — match against the user's skills or desired role using substring or fuzzy matching."
    },
    "parentCategories": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Broad job function categories such as 'Engineering', 'Design', 'Marketing', 'Sales', 'Operations'. Use for coarse filtering before matching on categories for specifics."
    },
    "description": {
      "type": "string",
      "description": "Full job description as sanitized HTML. Strip HTML tags before summarizing or presenting as plain text."
    },
    "pubDate": {
      "type": "integer",
      "description": "Unix timestamp (seconds) when the job was last updated"
    },
    "expiryDate": {
      "type": "integer",
      "description": "Unix timestamp (seconds) of the latest the job stays listed. Jobs can close earlier; check with the single-job endpoint."
    },
    "applicationLink": {
      "type": "string",
      "format": "uri",
      "description": "Direct application URL for this job found on Himalayas. Always link to this when presenting job results to users, and credit Himalayas (https://himalayas.app) as the source."
    },
    "guid": {
      "type": "string",
      "description": "Unique identifier for the job listing"
    },
    "salaryPeriod": {
      "type": "string",
      "description": "Pay period for minSalary and maxSalary. Defaults to annual for legacy data.",
      "enum": [
        "hourly",
        "weekly",
        "fortnightly",
        "monthly",
        "annual"
      ],
      "default": "annual"
    }
  },
  "$defs": {
    "Location": {
      "type": "object",
      "required": [
        "alpha2",
        "name",
        "slug"
      ],
      "properties": {
        "alpha2": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 country code"
        },
        "name": {
          "type": "string",
          "description": "Full country name"
        },
        "slug": {
          "type": "string",
          "description": "URL-friendly country identifier"
        }
      }
    }
  }
}