One of the examples has a number of missing values (,,) and the literal 'undefined', starting around the Education section
https://registry.jsonresume.org/beeman
Uh, there was already an XML format for this, I remember doing my CV with it. Nobody ever asked to see it or use it, so I stopped updating it. I learnt a few years later that some HR/recruiter systems do use it, behind the scenes, to talk to each other, they just never surface it.
Why would this surface more often...? The HR industry is not made by coders, they live in MSWord and GDocs.
I'm thinking of using it (or a slightly hacked modification) because I keep a "master" resume in a messy LaTeX doc with lots of crap I usually filter out, and with variable accuracy in things like dates. But if I change careers, it will be useful because I'll have all that material ready to put back in.
Even while you're searching, having your different versions based on a single source of truth helps you keep everything consistent.
And you can then convert your source data to MSWord or other formats. It outputs HTML, so it's already a click away.
(Careful sending any easily editable format to some recruiters, they're liable to "enhance" it for you.)
Of course, I only send PDFs (closest you can get to non-editable without going exotic).
Personally, these days I just export my LinkedIn bio and then tailor to the particular application. Unless LI starts exposing this, I have no real use for it.
For concepts not covered by Schema.org (I spotted only one, “interests”) the project could implement custom extensions until they are adopted by the shared vocabulary.
> After everyone's input, we decided to just opt for one field `name` because simply first/last/family name does not work across cultures.
Thank you so much for this! Me and family members struggle filling forms because of this on a regular basis.
Another pet peeve of mine are address fields. Why not just one field? People are smart enough to write down their address. Not everyone has a zip code or a street number, or streets for that matter.
> People are smart enough to write down their address.
Not usually.
In this scenario, given its use for display on a user page, it may make sense.
For most other cases, this doesn't pan out. Here in the US, for example, the general public has little sense of how to properly write addresses with floor, apartment, unit, or suite numbers. Folks routinely put things in the wrong order or use the wrong symbol or abbreviation. Others make up nonsense and genuinely think what they have is correct. Developers and geeks aren't immune; I've seen forms that reflect an inadequate understanding of addresses.
Yeah, if you work for a company that has to run any kind of validation on addresses, you learn quickly most people cannot type their address in correctly at all. My take: Make it as dumb and straightforwardly painfully obvious as possible.
Coincidentally enough, we just got through writing a nest of regexps to retrospectively validate about 2K user entered addresses, and they turned out to be surprisingly well entered, probably about 98% parsable. In this case the user was entering a field called "street" and we were validating down to a number followed by a street type (e.g ST) and a few local wrinkles such as additions like "RD1" for rural addresses. The most common error, which we brute force corrected, were various misspellings of "crescent". We did not however attempt to unpack the street number, which fortunately was not required.
Actually, Person does inherit a generic “name” property from its parent (Thing). You could support a subset of the spec (“name” but not “firstName”). It’d be very cool if I could have a single structured data representation that could be displayed in a neat resume format while being consumable by others (say, Google[0]).
PS. Agreed on your name handling philosophy, I use a single “name” property wherever requirements allow.
I've always gone with title, first name, middle name(s), last name, suffix; all optional (or requiring that at least one of first and last name exists), all representable in Unicode, space allowed but no line breaks, each part no longer than 300 characters.
In theory that might not cover everything, but I've never been able to come up with a counter example. Schema.org seems to take a very similar approach. Of course assembling that back together is culture dependant and depends on your use case. If you only need a simple name field that's easier.
Is there any reason not to use a singular field for this? It seems so much simpler to just give the user one input field and it would cover all scenarios.
Apparently a single field works fine in a resume builder. But consider a more complex app that does all of the following: display the name in various lists, has a detail view on that user, greets the user, talks about the person in third person (a report or similar). In each of those cases you ideally want to treat the name differently.
Even in English the detail view might show George Walker Bush Jr (the legal name as the person might input it), while in the list you have to safe space and revert to George W. Bush. Greeting the person as "Hello George Walker Bush Jr" is silly, you want to say "Hello George" or "Hello Mr. Bush", depending on how formal you want to be.
In languages such as Japanese you might end up generating honorifics on the fly. You can't do that if you can't parse the name.
> Trying to decide what level of formality and/or honorifics is appropriate in a specific case seems insane.
I once worked at an Australian bank that had a massive SQL function, prob 500+ lines long, for getting the salutation right in mailshots. As well as the usual Mr/Mrs/Dr/etc options, it had decades worth of special cases, largely derived from complaints from VIPs.
e.g. Retired navy officers, professors emeritus, former Members of Parliament, archbishops and rabbis, a rather pompous husband of a female Lord Mayor,...
Except you are assuming you can reliably make decisions about how a person's name should be used based on your classification scheme for names. First, your classification scheme will not cover all users (see the famous https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-...). Second, your use cases will not match all users. You may consider "Hello Firstname" to be an appropriate informal greeting and "Hello Mr. Lastname" to be an appropriate formal greeting, but even for people having a first name and a last name, this is not universally true.
The only person qualified to say how a name can appropriately be used is the owner of that name. If you need a greeting, ask the user how they would prefer to be addressed. If you need to show their name to others, ask how they would prefer their name to be displayed. If you need their name as understood by some government agency, ask for their name according to that government agency (note: this is not necessarily the same for all agencies; people do not necessarily have one single legal name).
If you don't want to overwhelm the user, you can have a "Display name" or "Legal name" field depending on what is relevant to your application and use that as the default. But you should provide overrides for every case where you are using their name in a different context.
If this sounds complicated, it is because names are complicated. I have seen too many people with names that don't fit the typical pattern of Firstname Lastname (composed solely of ASCII letters) get frustrated with systems that do not support them. I will not ever assume I can know how to manipulate or use someone's name without them needing to tell me. Nor will I assume their name must fit within some predefined character set or length.
While you make good point I think I actually do pretty well on the falshoods with the scheme laid out in the grandparent comment. The cases I violate are:
- I assume everyone has at least one name (not strictly true, but close enough to true for people using the internet)
- I assume every name can be mapped to unicode (I don't even know how I would fix that assumption)
- I assume all names fit in some fixed length (I give more space than the British passport and more than I can display in most situations)
- Even though I don't assume that people have a first name or that people have a last name I assume everyone has at least one of the two
I find all of these assumptions reasonable, and your scheme of "Display Name" and "Legal Name" shares most of these assumptions, or would share them in any reasonable implementation (You can't allow names that use gigabytes of space, so there will be some length limit, and most implementations will use unicode).
Of course using a name after decomposing it isn't easy. I will concede that asking the user is easier and more reliable, but it does come with drawbacks as well.
I was mostly thinking about "Hello Firstname" and "Mr. Lastname". I know several people who, due to the commonness of their first name, go by their last name. For these people "Hello Lastname" is the correct informal greeting. I know others that go by their initials, and "Hello INITIALS" is the correct informal greeting. For these people, addressing them by their first name actually sounds more formal, and maybe even a little insensitive as it's against their preference. There is just no way for a system to know this without asking.
But yeah, within the universe of ways to handle names, your schema comes pretty close to the ideal. I just think it's worth considering the ways it can still fail. "People consider their first names an appropriate informal greeting" is an assumption that definitely fails in some cases.
Another place I've seen systems get this wrong is generating default avatars using first letter of first and last name as initials. For someone who goes by the initials of their first and middle names, this produces confusing initials. If someone goes by the name H. G. Wells, showing them as "Herbert" or "HW" is confusing. "HG" would be better. It fits the space for 2 letters and is more likely to be recognized as them.
Per Wikipedia, the man most recognized by the name Liberace was known as "Lee" to his friends, "Walter" to his family, but had the first name "Władziu". Referring to the person by first name or by initials is likely to cause confusion. Again, there's just no way to know.
Not trying to tear down your schema here, just provide some context for readers of the thread in general about the additional complexities that can still arise. Thanks for the interesting discussion.
You don't have to use the schema of schema.org. You can provide your own semantics (and build on pre-existing ones, like schema.org). The point is that you can provide information that is human readable and machine-processable (either through HTML or formats like JSON-LD).
At this level, they won't care for an open format as they can just ask you to reenter all the info in their own form.
They assume if you are effectively looking for a job a 10~30 min data entry for each of these sites won't deter you. Or worse, you'll get tired of entering your data again and again, and won't go to their smaller competitors even if they make more efforts to accommodate you.
I did the whole dance a year ago, and a candidate's time seems to be the least valuable resource in the system (or it's used as a currency to price how much you are dedicated to getting that job)
This is true in our experience. We had visions of exporting Linked in profiles to the schema but about a year after launch LinkedIn completely disable API access to user profiles making it virtually impossibly.
LaTeX + ORG mode is an easy way to get some literate programming features while also still using a real typesetting engine. You can reuse my setup here:
Yeah, I've done the same, though I kind of went egregiously over the top (academic website with vue.js + tex resume with all kinds of machinery generated from a bunch of yaml files): https://github.com/paultopia/websiterevision2017
As someone who doesn't do any kind of web dev it seems like this isn't designed for my use case. E.g. things like Android or iOS development didn't seem to be present, let alone more niche things like embedded, graphics, etc.
Gotta love the "undefined" next to "Egghead Instructor" on one of the example resumes, given that Egghead's pitch is "Learn the best JavaScript tools and frameworks from industry pros".
Very cool to see this progressing! I remember reading about this site in college. One tip, I think the HTTPS site is requesting HTTP resources for CSS/Google Fonts, which Chrome blocks, so I can't see the themes in their full glory :-)
It took me way too long to realize resume meant résumé (written summary of my experiences) instead of resume (to continue)! I was thinking JSON Resume was the next version of JSON, maybe adding the ability to have comments in JSON.
Still puzzling to me, how hard it is to generate PDF documents.
I assume this is not using Latex, since that would be a gigantic dependency to pull in.
What is/was jsonresume using? Why did it break?
PS: Also pdf export on wikipedia has been broken for years now. Seems to be a hard problem.
Any information about light-weight pdf generators that work and produce decent pdfs documents would be appreciated.
Really great to see some activity. I thought the project was dead, no offense. Are the problems around an excellent MS Word and PDF versions intractable? Just asking since I don't know node.js/json world well.
57 comments
[ 3.2 ms ] story [ 143 ms ] threadWhy would this surface more often...? The HR industry is not made by coders, they live in MSWord and GDocs.
Even while you're searching, having your different versions based on a single source of truth helps you keep everything consistent.
And you can then convert your source data to MSWord or other formats. It outputs HTML, so it's already a click away.
(Careful sending any easily editable format to some recruiters, they're liable to "enhance" it for you.)
Of course, I only send PDFs (closest you can get to non-editable without going exotic).
Personally, these days I just export my LinkedIn bio and then tailor to the particular application. Unless LI starts exposing this, I have no real use for it.
For concepts not covered by Schema.org (I spotted only one, “interests”) the project could implement custom extensions until they are adopted by the shared vocabulary.
Though one of the largest discussions we had on the specification was the definition of what a name was -> https://github.com/jsonresume/resume-schema/issues/4
After everyone's input, we decided to just opt for one field `name` because simply first/last/family name does not work across cultures.
When we looked at schema.orgs definition of Person, they went down the avenue of trying to split the name up which still wouldn't fit all use cases.
https://schema.org/Person
Thank you so much for this! Me and family members struggle filling forms because of this on a regular basis.
Another pet peeve of mine are address fields. Why not just one field? People are smart enough to write down their address. Not everyone has a zip code or a street number, or streets for that matter.
Sales tax calculations by region.
Not usually.
In this scenario, given its use for display on a user page, it may make sense.
For most other cases, this doesn't pan out. Here in the US, for example, the general public has little sense of how to properly write addresses with floor, apartment, unit, or suite numbers. Folks routinely put things in the wrong order or use the wrong symbol or abbreviation. Others make up nonsense and genuinely think what they have is correct. Developers and geeks aren't immune; I've seen forms that reflect an inadequate understanding of addresses.
PS. Agreed on your name handling philosophy, I use a single “name” property wherever requirements allow.
[0] https://developers.google.com/search/docs/guides/intro-struc...
In theory that might not cover everything, but I've never been able to come up with a counter example. Schema.org seems to take a very similar approach. Of course assembling that back together is culture dependant and depends on your use case. If you only need a simple name field that's easier.
Even in English the detail view might show George Walker Bush Jr (the legal name as the person might input it), while in the list you have to safe space and revert to George W. Bush. Greeting the person as "Hello George Walker Bush Jr" is silly, you want to say "Hello George" or "Hello Mr. Bush", depending on how formal you want to be.
In languages such as Japanese you might end up generating honorifics on the fly. You can't do that if you can't parse the name.
* What do you want to be called?
* (for some cases) What is your legal name?
Trying to decide what level of formality and/or honorifics is appropriate in a specific case seems insane. Just let the user decide.
I once worked at an Australian bank that had a massive SQL function, prob 500+ lines long, for getting the salutation right in mailshots. As well as the usual Mr/Mrs/Dr/etc options, it had decades worth of special cases, largely derived from complaints from VIPs.
e.g. Retired navy officers, professors emeritus, former Members of Parliament, archbishops and rabbis, a rather pompous husband of a female Lord Mayor,...
The only person qualified to say how a name can appropriately be used is the owner of that name. If you need a greeting, ask the user how they would prefer to be addressed. If you need to show their name to others, ask how they would prefer their name to be displayed. If you need their name as understood by some government agency, ask for their name according to that government agency (note: this is not necessarily the same for all agencies; people do not necessarily have one single legal name).
If you don't want to overwhelm the user, you can have a "Display name" or "Legal name" field depending on what is relevant to your application and use that as the default. But you should provide overrides for every case where you are using their name in a different context.
If this sounds complicated, it is because names are complicated. I have seen too many people with names that don't fit the typical pattern of Firstname Lastname (composed solely of ASCII letters) get frustrated with systems that do not support them. I will not ever assume I can know how to manipulate or use someone's name without them needing to tell me. Nor will I assume their name must fit within some predefined character set or length.
- I assume everyone has at least one name (not strictly true, but close enough to true for people using the internet)
- I assume every name can be mapped to unicode (I don't even know how I would fix that assumption)
- I assume all names fit in some fixed length (I give more space than the British passport and more than I can display in most situations)
- Even though I don't assume that people have a first name or that people have a last name I assume everyone has at least one of the two
I find all of these assumptions reasonable, and your scheme of "Display Name" and "Legal Name" shares most of these assumptions, or would share them in any reasonable implementation (You can't allow names that use gigabytes of space, so there will be some length limit, and most implementations will use unicode).
Of course using a name after decomposing it isn't easy. I will concede that asking the user is easier and more reliable, but it does come with drawbacks as well.
But yeah, within the universe of ways to handle names, your schema comes pretty close to the ideal. I just think it's worth considering the ways it can still fail. "People consider their first names an appropriate informal greeting" is an assumption that definitely fails in some cases.
Another place I've seen systems get this wrong is generating default avatars using first letter of first and last name as initials. For someone who goes by the initials of their first and middle names, this produces confusing initials. If someone goes by the name H. G. Wells, showing them as "Herbert" or "HW" is confusing. "HG" would be better. It fits the space for 2 letters and is more likely to be recognized as them.
Per Wikipedia, the man most recognized by the name Liberace was known as "Lee" to his friends, "Walter" to his family, but had the first name "Władziu". Referring to the person by first name or by initials is likely to cause confusion. Again, there's just no way to know.
Not trying to tear down your schema here, just provide some context for readers of the thread in general about the additional complexities that can still arise. Thanks for the interesting discussion.
Maybe if you could find a copy of those specs pity that the ISO and ITU where always so restrictive and dam expensive.
I linked in another comment -> https://joshuatz.com/projects/web-stuff/linkedin-profile-to-...
Slowly getting there
At this level, they won't care for an open format as they can just ask you to reenter all the info in their own form.
They assume if you are effectively looking for a job a 10~30 min data entry for each of these sites won't deter you. Or worse, you'll get tired of entering your data again and again, and won't go to their smaller competitors even if they make more efforts to accommodate you.
I did the whole dance a year ago, and a candidate's time seems to be the least valuable resource in the system (or it's used as a currency to price how much you are dedicated to getting that job)
A developer built a bookmarklet that does it thought -> https://joshuatz.com/projects/web-stuff/linkedin-profile-to-...
Works surprisingly well.
Here is my resume (as YAML): https://github.com/pauldotknopf/resume/blob/staging/resume.y...
This file is consumed and used in a very small ad-hoc project, specifically for my format: https://github.com/pauldotknopf/resume/blob/staging/statik-r...
Here is the final result: https://resume.pknopf.com/
Easy maintenance. Maximum flexibility. Low tooling.
Here is a snippet:
```
\begin{luacode}
require("lualibs.lua")
local file = io.open('data.json')
local jsonstring = file:read('*a')
file.close()
local jsonData = utilities.json.tolua(jsonstring)
-- Header -- local personal = jsonData["personal"]
-- Education -- local education = jsonData["education"]
tex.print('\\section{Education}')
for key, value in pairs (education) do
end```
https://github.com/matthewbauer/resume
Creates LaTeX or PDF.
We plan on shipping API support so that developers can build better experiences on top of the data (alternate rendering engines, import/export, etc).
I'd love to see about supporting export to JSON Resume. Is there a list of ecosystem tools that speak this format?
https://imgur.com/a/4qVeeca
{ “name”: “Michael Scott”, “age”: 40, “_comments”: [“”] }
> resume export resume.pdf (Currently broken, help needed)
https://jsonresume.org/getting-started/
Any news here?
Still puzzling to me, how hard it is to generate PDF documents. I assume this is not using Latex, since that would be a gigantic dependency to pull in. What is/was jsonresume using? Why did it break?
PS: Also pdf export on wikipedia has been broken for years now. Seems to be a hard problem.
Any information about light-weight pdf generators that work and produce decent pdfs documents would be appreciated.
Json is not designed for humans.
There are multiple projects on GitHub that generate resumes from yaml.
The new concept is a lambda function that pulls from a gist. It would not be very hard to do something similar with yaml.
Wish I knew more. I don't think it's the HN Hug of Death™ because I was able to get it to complain about my malformed JSON earlier (since fixed).