JSON Resume – 5th Birthday and New Features | Hacker News Reader

JSON Resume – 5th Birthday and New Features

jsonresume.org

Instead of going with an ad-hoc schema, I wish JSON Resume built on top of data structures standardized by Schema.org. They cover most of the concepts required—https://schema.org/Person, https://schema.org/skills, https://pending.schema.org/knowsAbout, the list goes on.

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.

I personally don't disagree, we've always thought it best to leverage other peoples work first.

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

> 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.

> Why not just one field?

Sales tax calculations by region.

> 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.

[0] https://developers.google.com/search/docs/guides/intro-struc...

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.

Ah interesting, I hadn't thought of those use cases.

I recall getting a chuckle out of the honorifics drop-down menu on the Rolls-Royce contact form. https://www.rolls-roycemotorcars.com/en-GB/information/conta...

I would imagine that most software would work perfectly fine with two values:

* 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.

> 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).

I seem to recall X.400/X.500 did a lot of work on how to represent names.

Maybe if you could find a copy of those specs pity that the ISO and ITU where always so restrictive and dam expensive.

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.

Or lazy loaded json as stream of objects

Well, you can already parse JSON SAX-style. Or with newline delimiters.

Its not super great but i’ve become a fan of doing this:

{ “name”: “Michael Scott”, “age”: 40, “_comments”: [“”] }

Literally the "hot comments" pattern ;)

Pro tip, just creating your own schema. Tailor it to your theme.

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.

I use JSON to store my resume, and Latex to format it.

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

  tex.print('\\cventry{' .. value["year"] .. '}{' .. value["degree"] .. '}{' .. value["school"] .. '}{' .. value["location"] .. '}{}{' .. value["specialty"] .. '}')

end

```

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:

https://github.com/matthewbauer/resume

Thank you! and thanks for not forcing bibtex into it.

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

YAML + mostly markdown: https://github.com/john-bokma/resume-pandoc

Creates LaTeX or PDF.

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.)

> (Careful sending any easily editable format

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.

So, I am working on a "better resume" product for developers: https://fizbuz.com

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?

We haven't done a good job of showing casing community tooling. It is on our high priority list. That being said, you can scroll through https://github.com/search?o=desc&q=jsonresume&s=updated&type... to get an idea of what is out there.

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".

https://imgur.com/a/4qVeeca

One of the examples has a number of missing values (,,) and the literal 'undefined', starting around the Education section https://registry.jsonresume.org/beeman

Thanks! I will let the user know.

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 :-)

By the 10th birthday, you should have implemented the LinkedIn export as well ;-)

baha

I linked in another comment -> https://joshuatz.com/projects/web-stuff/linkedin-profile-to-...

Slowly getting there

Aside:

> 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.

https://github.com/jsonresume/resume-cli/pull/294

maybe have a good css sheet for print styles and encourage people to print -> save as pdf?

How much traction is this getting in job-tech startups? For instance, LinkedIn, Indeed, etc., as well as applicant tracking systems, and so forth.

> LinkedIn, Indeed, etc.,

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.

A developer built a bookmarklet that does it thought -> https://joshuatz.com/projects/web-stuff/linkedin-profile-to-...

Works surprisingly well.

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.

Congrats. I remember the HN discussion 5 years ago, and appreciated it then too.

I wish it was called yamlresume.org instead of jsonresume.org.

Json is not designed for humans.

yamlresume.org is available.

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.

Tried it out, but got "Error: could not handle the request"

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).

The post is from 2018.

That is my bad, static site generator where you input the date manually. Fixing now.

Reply on news.ycombinator.com