Skip to content

Commit b8f6c5e

Browse files
resmoresmo
committed
refactorings
1 parent a65c160 commit b8f6c5e

File tree

8 files changed

+345
-27
lines changed

8 files changed

+345
-27
lines changed

‎Makefile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,8 @@ install: update
1717

1818
run:
1919
mkdocs serve -w docs
20+
21+
schema-doc:
22+
rm -f docs/how/ojobpub-schema.md
23+
echo "---\nhide:\n- toc\n---" > docs/how/ojobpub-schema.md
24+
jsonschema-markdown --no-footer --resolve ojobpub.json >> docs/how/ojobpub-schema.md

‎docs/how/ojobpub-format.md‎

Lines changed: 12 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,12 @@
1-
# oJobPub JSON Format
1+
# About oJobPub JSON Format
22

3-
oJobPub is our minimalistic data format as JSON, containing meta infos about the job and a short job description, a summary. It is **not** meant to have all possible data of a job posting: e.g. the process of application is and will not be covered.
4-
5-
Before we go to oJobPub JSON, let's clearify two terms:
6-
7-
- JSON
8-
- JSON Schema
9-
10-
## What is JSON
11-
12-
JSON (JavaScript Object Notation) is an open, lightweight, text-based data structure format used to store and interchange data. Primarly for machines to write and read while still writable and readable by humans.
13-
14-
## What is a JSON Schema
15-
16-
[JSON Schema](https://json-schema.org) is an IETF standard providing a format for what JSON data is required for a given application and how to interact with it: Applying such standards for a JSON document enforces consistency and data validity.
3+
oJobPub is our minimalistic data format in JSON ([Wikipedia](https://en.wikipedia.org/wiki/JSON)), containing meta infos about your job openings.
174

185
## oJobPub JSON
196

20-
A possible output could look like the sample below, however, some of the (blue) keys (e.g. `workload` or `jobDescription`) are optional while others are required (e.g. `jobTitle`). This is why we also provide a [oJobPub JSON Schema](https://raw.githubusercontent.com/letsemploy/schema/refs/heads/main/v1/ojobpub.json) and an online validator tool [validator.letsemploy.org](https://validator.letsemploy.org) to allow verification of the data structure. Atlassian Inc. made a [JSON Schema Viewer](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2Fojobpub%2Fschema%2Frefs%2Fheads%2Fmain%2Fv1%2Fojobpub.json) to browse through the schema.
21-
22-
23-
!!! note
24-
JSON might look complicated if you're not familiar with it, but don't worry — you won't have to write it by hand. Once this format is finalized, we'll provide tools to help you generate and validate the structure.
25-
267
In the following sample, we see first an `employer` object containing infos about the company: *name*, *location*, *industry*, (main website) *url*.
278

28-
Later we find a list of vacancies, called *jobs*. In the sample, we only see one vacancy/job but there is currently no limit how many job entries you add.
9+
Later we find a list of jobs. In the sample, we only see one job but there is currently no limit how many job entries you add.
2910

3011
```json
3112
{
@@ -81,7 +62,15 @@ Later we find a list of vacancies, called *jobs*. In the sample, we only see one
8162
```
8263

8364
1. The `employer` json object with minimal information about the employer.
84-
2. The list of `vacancies` objects with meta information about the job openings.
65+
2. The list of `jobs` objects with meta information about the job openings.
66+
67+
68+
!!! note
69+
JSON might look complicated if you're not familiar with it, but don't worry — you won't have to write it by hand. Once this format is finalized, we'll provide tools to help you generate and validate the structure.
70+
71+
Some of the (blue) keys (e.g. `workload` or `description`) are optional while others are required (e.g. `title`).
72+
73+
This is why we provide a [oJobPub JSON Schema](ojobpub-schema.md) (also see [GitHub](https://github.com/letsemploy/schema)) and an online validator tool [validator.letsemploy.org](https://validator.letsemploy.org) to allow verification of the data structure.
8574

8675
!!! tip
8776
While not all properties are required for a valid file, we highly recommend you fill out as much metadata as possible.

‎docs/how/ojobpub-schema.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
hide:
3+
- toc
4+
---
5+
# oJobPub - Open Job Publishing Initiative
6+
7+
JSON Schema missing a description, provide it using the `description` key in the root of the JSON document.
8+
9+
### Type: `object`
10+
11+
> ⚠️ Additional properties are not allowed.
12+
13+
| Property | Type | Required | Possible values | Deprecated | Default | Description | Examples |
14+
| -------- | ---- | -------- | --------------- | ---------- | ------- | ----------- | -------- |
15+
| version | `const` | ✅ | `1.0` | | | Version of the oJobPub schema | |
16+
| lastUpdated | `string` | ✅ | Format: [`date-time`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date when the oJobPub feed was last updated | |
17+
| employer | `object` | ✅ | object | | | | |
18+
| employer.name | `string` | ✅ | Length: `1 <= string <= 255` | | | | |
19+
| employer.location | `object` | ✅ | object | | | | |
20+
| employer.location.city | `string` | | string | | | City | |
21+
| employer.location.country | `string` | | Length: `2 <= string <= 2` | | | Country code as ISO 3166-1 alpha-2: see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | |
22+
| employer.industry | `string` | | Length: `1 <= string <= 255` | | | | |
23+
| employer.url | `string` | | Format: [`uri`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | | |
24+
| jobs | `array` | ✅ | object | | | | |
25+
| jobs[].language | `string` | ✅ | Length: `2 <= string <= 2` | | | Language of the job description as ISO 639-1:2002. See https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes | |
26+
| jobs[].publishedAt | `string` | ✅ | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date when the job was first published | |
27+
| jobs[].startDate | `string` | | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date when the job starts | |
28+
| jobs[].endDate | `string` | | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date when the job ends | |
29+
| jobs[].applyBefore | `string` | | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date until the job is valid | |
30+
| jobs[].category | `string` | | Length: `string <= 255` | | | Category of the job: e.g. Engineering, Marketing, Salesq | |
31+
| jobs[].referenceId | `string` | | Length: `string <= 255` | | | Employer's job reference ID | |
32+
| jobs[].title | `string` | ✅ | Length: `string <= 255` | | | Title of the job | |
33+
| jobs[].description | `string` | | Length: `string <= 1000` | | | Description of the job | |
34+
| jobs[].jobType | `string` | ✅ | `permanent` `contract` `internship` `apprenticeship` `temporary` `volunteer` `freelance` | | | | |
35+
| jobs[].experienceLevel | `string` | | `junior` `mid` `senior` `lead` `manager` `director` `executive` | | | Experience level required for the job | |
36+
| jobs[].workLoad | `object` | | object | | | Expected workload in percentage for the job | |
37+
| jobs[].workLoad.minPercentage | `number` | | `0 <= x <= 100` | | | | |
38+
| jobs[].workLoad.maxPercentage | `number` | | `0 <= x <= 100` | | | | |
39+
| jobs[].workType | `string` | | `remote` `on-site` `hybrid` | | | Type of work for the job | |
40+
| jobs[].salary | `object` | | object | | | Salary range for the job | |
41+
| jobs[].salary.min | `number` | | `0 <= x ` | | | Minimum salary to expect | |
42+
| jobs[].salary.max | `number` | | `0 <= x ` | | | Maximum salary to expect | |
43+
| jobs[].salary.currency | `string` | | Length: `3 <= string <= 3` | | | Currency as ISO 4217: see https://en.wikipedia.org/wiki/ISO_4217 | |
44+
| jobs[].salary.interval | `string` | | `hourly` `daily` `weekly` `monthly` `yearly` | | | Min/max salary interval, e.g. per hour, per month, per year | |
45+
| jobs[].tags | `array` | | Length: `string <= 28` | | | Key words for the job | |
46+
| jobs[].locations | `array` | ✅ | object | | | Locations of the job | |
47+
| jobs[].locations[].city | `string` | | string | | | City | |
48+
| jobs[].locations[].country | `string` | | Length: `2 <= string <= 2` | | | Country code as ISO 3166-1 alpha-2: see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | |
49+
| jobs[].url | `string` | ✅ | Format: [`uri`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | URL of the job's full description | |
50+
51+
52+
---
53+
54+
# Definitions
55+
56+
## location
57+
58+
No description provided for this model.
59+
60+
#### Type: `object`
61+
62+
| Property | Type | Required | Possible values | Deprecated | Default | Description | Examples |
63+
| -------- | ---- | -------- | --------------- | ---------- | ------- | ----------- | -------- |
64+
| city | `string` | | string | | | City | |
65+
| country | `string` | | Length: `2 <= string <= 2` | | | Country code as ISO 3166-1 alpha-2: see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | |
66+
67+
## job
68+
69+
No description provided for this model.
70+
71+
#### Type: `object`
72+
73+
> ⚠️ Additional properties are not allowed.
74+
75+
| Property | Type | Required | Possible values | Deprecated | Default | Description | Examples |
76+
| -------- | ---- | -------- | --------------- | ---------- | ------- | ----------- | -------- |
77+
| language | `string` | ✅ | Length: `2 <= string <= 2` | | | Language of the job description as ISO 639-1:2002. See https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes | |
78+
| publishedAt | `string` | ✅ | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date when the job was first published | |
79+
| title | `string` | ✅ | Length: `string <= 255` | | | Title of the job | |
80+
| jobType | `string` | ✅ | `permanent` `contract` `internship` `apprenticeship` `temporary` `volunteer` `freelance` | | | | |
81+
| locations | `array` | ✅ | object | | | Locations of the job | |
82+
| locations[].city | `string` | | string | | | City | |
83+
| locations[].country | `string` | | Length: `2 <= string <= 2` | | | Country code as ISO 3166-1 alpha-2: see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | |
84+
| url | `string` | ✅ | Format: [`uri`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | URL of the job's full description | |
85+
| startDate | `string` | | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date when the job starts | |
86+
| endDate | `string` | | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date when the job ends | |
87+
| applyBefore | `string` | | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | Date until the job is valid | |
88+
| category | `string` | | Length: `string <= 255` | | | Category of the job: e.g. Engineering, Marketing, Salesq | |
89+
| referenceId | `string` | | Length: `string <= 255` | | | Employer's job reference ID | |
90+
| description | `string` | | Length: `string <= 1000` | | | Description of the job | |
91+
| experienceLevel | `string` | | `junior` `mid` `senior` `lead` `manager` `director` `executive` | | | Experience level required for the job | |
92+
| workLoad | `object` | | object | | | Expected workload in percentage for the job | |
93+
| workLoad.minPercentage | `number` | | `0 <= x <= 100` | | | | |
94+
| workLoad.maxPercentage | `number` | | `0 <= x <= 100` | | | | |
95+
| workType | `string` | | `remote` `on-site` `hybrid` | | | Type of work for the job | |
96+
| salary | `object` | | object | | | Salary range for the job | |
97+
| salary.min | `number` | | `0 <= x ` | | | Minimum salary to expect | |
98+
| salary.max | `number` | | `0 <= x ` | | | Maximum salary to expect | |
99+
| salary.currency | `string` | | Length: `3 <= string <= 3` | | | Currency as ISO 4217: see https://en.wikipedia.org/wiki/ISO_4217 | |
100+
| salary.interval | `string` | | `hourly` `daily` `weekly` `monthly` `yearly` | | | Min/max salary interval, e.g. per hour, per month, per year | |
101+
| tags | `array` | | Length: `string <= 28` | | | Key words for the job | |

‎docs/stylesheets/extra.css‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
[data-md-color-scheme="black"] {
22
--md-primary-fg-color: #0a1318;
3-
}
3+
}
4+
.md-grid {
5+
max-width: 1440px;
6+
}

‎mkdocs.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ nav:
1313
- Solution: solution.md
1414
- How:
1515
- Quickstart: how/index.md
16-
- ojobpub.json: how/ojobpub-format.md
16+
- About ojobpub.json: how/ojobpub-format.md
17+
- ojobpub Schema: how/ojobpub-schema.md
1718
- FAQ: faq.md
1819
- Project: project.md
1920

@@ -64,14 +65,15 @@ plugins:
6465
- search
6566
- minify:
6667
minify_html: true
68+
6769
copyright: |
6870
LetsEmploy.org © 2025
6971
7072
extra:
7173
generator: true
7274
social:
7375
- icon: fontawesome/brands/github
74-
link: https://github.com/ojobpub/docs
76+
link: https://github.com/letsemploy/docs
7577

7678
extra_css:
7779
- stylesheets/extra.css

0 commit comments

Comments
 (0)