Thanks for the PR. I'd like @philbarker and @vholland to take a look at this (and #2192) first, as it touches on a bunch of related work.

I'm a little confused. occupationalCategory and relevantOccupation are both properties of JobPosting.

• Why? What's the difference between them?
• The example provided puts the occupational category code into the Occupation object of the relevantOccupation, why not into the occupationalCategory of the JobPosting direct?

Additionally, can we remove or at least loosen the "use O*NET" part of the occupationalCategory definition?

I would like to discuss this in the TalentSignal W3C group, to check with a wider set of people.

@philbarker

I'm a little confused. occupationalCategory and relevantOccupation are both properties of JobPosting

Additionally, can we remove or at least loosen the "use O*NET" part of the occupationalCategory definition?

Perfectly valid questions, but I think they would be better discussed in a separate [new] issue.

This PR specifically only addresses the rangeIncludes of the two properties (occupationalCategory & jobTitle) to allow the use of predefined references.

@RichardWallis OK I'll raise an issue or 2, but I think the issue about the definition change from "use O*NET" is directly relevant to a PR that is only useful if other taxonomies are used.

Also, the PR includes an example which is in question.

@philbarker Good point on the definition for occupationalCategory.

How about:
Category or categories describing the job. Preferably use a taxonomy such as BLS O*NET-SOC. Repeat property for multiple categories.

Do you have suggestions with regard to the proposed examples?

@RichardWallis This is the definition I suggested to to TalentSignal:

Category or categories describing the job. Use a taxonomy such as BLS O*NET-SOC http://www.onetcenter.org/taxonomy.html , ISCO-08 https://www.ilo.org/public/english/bureau/stat/isco/isco08/ or similar. Ideally the taxonomy identifier, category textual label and formal code should be provided, with the property repeated for each applicable value.

Note: for historical reasons any textual label and formal code provided as a literal may be assumed to be from O*NET-SOC

Granted it's a bit wordy, but already people are pointing out that "to correctly specify O'NET, you'd need to also specify the year of the O'NET revision you're talking about." so it may actually not do far enough. I don't know if the note is needed but I am guessing about how current tools dealing with the existing definition will continue to handle strings.

With the hrefs as links:

Category or categories describing the job. Use a taxonomy such as BLS O*NET-SOC, ISCO-08 or similar. Ideally the taxonomy identifier, category textual label and formal code should be provided, with the property repeated for each applicable value.

Note: for historical reasons any textual label and formal code provided as a literal may be assumed to be from O*NET-SOC

It's not 'that' wordy.

@RichardWallis after some discussion in the TalentSignal group, the consensus seems to be for:

A slight change to the definition:

A category describing the job, preferably using a term from a taxonomy such as BLS O*NET-SOC, ISCO-08 or similar, with the property repeated for each applicable value. Ideally the taxonomy should be identified, and both the textual label and formal code for the category should be provided.
Note: for historical reasons, any textual label and formal code provided as a literal may be assumed to be from O*NET-SOC.

An example of how to provide information for which year's edition of O*Net is being used (there's a new edition just coming out, so this will be important):

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "JobPosting",
  "name": "Systems Research Engineer",
  "hiringOrganization": {
    "@type": "Organization",
    "name": "ACME Software"
  },
  "occupationalCategory": {
     "@type": "CategoryCode",
     "inCodeSet": {
          "@type": "CategoryCodeSet",
          "name": "O*Net-SOC",
          "dateUpdated": "2019",
          "url": "https://www.onetonline.org/"
       },
     "codeValue": "15-1211.00",
     "name": "Computer Systems Analysts",
     "url": "https://www.onetonline.org/link/summary/15-1121.00"
 } 
}
</script>

Still undecided on on using JobPosting property relevantOccupation Vs occupationalCategory. I guess options are to give examples of both (add example above to your existing example) or to provide examples only as instances of @type Occupation (i.e. have no JobPosting top level object) until that question is resolved.

@philbarker thanks for this feedback.

For occupationalCategory we have three challenges here:

1. Expanding its range to include CategoryCode. I believe we are in agreement on that.

2. The anomaly that its domain includes both JobPosting and Occupation .
   The result of this situation, which arose via issue Proposal for new Occupation type #1698 (implemented in V3.5), is that when marking up a JobPosting, you can either use the occupationalCategory property, or reference an Occupation, via the relevantOccupation property, and then use the occupationalCategory for that Occupation, or both.
   Do we want to maintain this dual approach?
   It is understandable that you would want to define the occupationalCategory for an Occupation that is not associated with a JobPosting. Equally, you would want to define the occupationalCategory for a JobPosting without having to create a full Occupation description of the relevantOccupation property.

3. If we want to keep both options, how do we construct a succinct set of examples for JobPosting that do not confuse the heck out of those that view them?

1. yes, we are in full agreement
2. I don't know (sorry). Being able to link a JobPosting to an Occupation is very useful, necessary for some use cases surrounding a person who practises some occupation looking for a job. I think we want to keep this, in some ways it is a better solution that just having a category code. Specifying occupationalCategory via a blank Occupation object isn't too bad, no worse that specifying price via an Offer, but I suspect there is a lot of historical code generating job adverts that uses occupationalCategory as a direct property of JobPosting.
3. Yep, that's the problem.

But this problem is not introduced by this pull request. I suggest trimming the examples so that they don't make point 3 worse, and attempt to address this via a separate issue. After that we can put back the more extensive examples.

Here's a trimmed version of the O*Net 2019 example (which also fixes error of dateUpdated for dateModified):

{
  "@context": "http://schema.org/",
  "@type": "Occupation",
  "occupationalCategory": {
     "@type": "CategoryCode",
     "inCodeSet": {
          "@type": "CategoryCodeSet",
          "name": "O*Net-SOC",
          "dateModified": "2019",
          "url": "https://www.onetonline.org/"
       },
     "codeValue": "15-1211.00",
     "name": "Computer Systems Analysts",
     "url": "https://www.onetonline.org/link/summary/15-1121.00"
 } 
}
</script>

Perhaps we should expand the example to use some other properties of Occupation like qualifications or estimatedSalary.

I am not opposed to allowing DefinedTerm for jobTitle, but I rarely see controlled vocabularies here. The titles tend to be more like "Coding Ninja" than "Software Engineer".

Applied discussed change to description of occupationalCategory
Example replaced with one provided by @philbarker
Updated one previous example of using occupationalCategory on JobPosting so that there are now two variations available.

/cc @danbri This PR should be OK to merge now.
Area might benefit from a future review of examples, and/or an overview document for guidance around Occupations, JobPostings etc.

Why did we remove occupationalCategory from JobPosting? This breaks a lot of existing markup on the web.

AFAIK, we didn't remove occupationalCategory from JobPosting, we just didn't use it in the examples.

It looks like it moved in schema.rdfa? I understand the change, but I miss webschemas.org as an easier way to review changes.