Adapt incoming JSON to populate renamed fields on the fly

[SethFalco]

Before exporting/displaying the resume, we should probably populate fields in the JSON that have been renamed for backward/forward compatibility. It's a bit annoying, but can't be helped with most of the available themes being severely outdated, or no longer maintained.

Namely the following fields, not sure if anything else need to be done:

• basics.website ← → basics.url
• work.name ← → work.company
• work.website ← → work.url
• volunteer.website ← → volunteer.url

Atm the users are either populating both themselves, or just confused and think JSON Resume is broken.

Related

• https://github.com/jsonresume/resume-website/issues/121

[gsweats]

@SethFalco I have been finding the same thing. I have updated the autumn theme at https://github.com/lorenzodalaqua/jsonresume-theme-autumn/pull/2

If I don't hear from the author, I'm going to rename my fork harvest and try to figure out how to add it to this registry. Must be a simple way.

I am also working on a personalization of the stackoverflow theme.

Any theme in particular you are looking at?

I am working off www.jsonresume.org/schema to try and keep as standard as possible, while also adding url$comment: "url is official, don't use website" type "comments" in the JSON.

My first real task will be swapping out the JSON for JSONC since I love my VS Code validation, but hate not being able to comment JSON files. Think resume or the other engine who I am embarrased to admit I can't remember the name of, may need to be modified to make the JSONC a reality.

TinaCMS / Markdown Variant?

I would also like to use Forestry's new TinaCMS to actually manage a resume as markdown files, with YAML front-matter, then use that like an SSG to build out the resume.jsonc, /resume/ folder with built HTML, JS, etc. and a PDF version. Wouldn't that be nice? Single folder to plop into your existing site. Commented JSON. Next Gen Editor with TinaCMS. 🤤

What about a CUSTOM MAPPING?

Something in resume.json along the lines of

...,
"map_fields": [
"basics.website": "basics.url"
]

Gets a bit gross managing that across different themes. Could see it becoming a huge mess.

Thoughts?

[gsweats]

Coming to your point about users thinking it's broken... maybe error handling and throwing errors, or displaying console errors, about missing fields?

[SethFalco]

throwing errors, or displaying console errors, about missing fields?

This one won't work as-is because all fields are optional. However, we definitely could throw deprecation warnings in the case that the old property name is found, and the new one isn't, then say that it's preferred to use the new property name. Something like that would be added to jsonresume/resume-cli rather than in the registry, though.

What about a CUSTOM MAPPING?

I think solving that in the resume.json file isn't ideal, I'd prefer to see theme developers and our tools take responsibility for this.

For example, this is how I chose to address it in our fork of jsonresume/jsonresume-theme-class, which I'm hoping more themes will do. (Basically adding an if/else to check both properties, prioritizing the up-to-date name.)

Or on the registry, just silently translating old property names so the new ones.

[bookRa]

Took me a lot of head-scratching working with jsonresume-theme-class before I finally read your comment @SethFalco and realized I had installed the original while reading the fork's code and docs 😪

Then it took me a little bit more to realize that resume serve|export --theme class wouldn't work, and that I had to use resume serve|export --theme @jsonresume/jsonresume-theme-class

Although I do appreciate the learning opportunity 😂 , I think a small ⚠️ NOTE ⚠️ in your README would be super helpful to many ppl, especially considering that your fork is the first schema-compliant theme I've come across while going down this JSON vs. Handlebars rabbit-hole

RE your "poly-fill" idea for the registry:

At first I thought it was badass (I'd also add basics.image <-> basics.picture to your list), but then I thought:

"The core maintainers already put in the time and effort to improve the schema, and you even gave it a major version bump 2+ years ago... isn't that the whole point of SemVer?"... My 2¢ is that since jsonresume.org is the central hub where thousands (more?) people come to learn and seek resources, your priority "as an organization" should be to keep that site as accurate and as well-curated as possible, rather than try to accomodate someone who made a beautiful theme 6 years ago and hasn't touched it since.

To that end, I could see a huge value to users by turning jsonresume.org/themes into a well-defined, hierarchical table (or tables) listing all the themes/packages and the latest schema version they depend on. Ex:

All themes are tested daily against resume-schema	Theme	Latest R-S Version	Notes
foo-theme	1.0.1	(preview link, etc)
bar-theme	1.0.0	additional fields for: logo, favorite_movie, etc
baz-theme	v0.0.17	use at your own peril!

Maybe this isn't the concern of the Registry (tbh i know nothing about the registry), but I think that building this kind of automated validation + documentation mechanism would raise the bar for jsonresume for both users ( less confusion, they know JR isn't broken) and for theme developers (If they are neglectful of their project dependency, they will sink lower to the bottom of the themes page).

Also, it feels like the meta.version (or the $schema?) field in the resume.json could play a future role in this 🤔 Maybe the registry could eventually support different schema/API versions with deprecation/EOL support?

Just my 2¢...Realize I'm a year late to this thread, but it's definitely an interesting problem/phenomenon with a huge open source community that, almost by definition, will wax and wane in their motivations to maintain/improve their "plugins" (till they land their next gig 😆 )..

Thanks for helping build this awesome tool! <3

[SethFalco]

I think a small warning NOTE warning in your README would be super helpful to many ppl

By small warning, do you mean a heads-up to make sure one is using the fork instead of the original?

If so, I'd be happy to add a note to the top later with installation and usage instructions that explicitly show @jsonresume/jsonresume-theme-class. Would that suffice, or were you referring to something else?

your priority "as an organization" should be to keep that site as accurate and as well-curated as possible

I agree with this. Unfortunately, with all the maintainers being pre-occupied, things are moving a little slow.

I'll actually work on a tool later to automate checking compliance with the schema. Note, it will take some time before we can integrate the output of such a tool with the website, though.

For example, using Bats, we can run tests against the theme. Then we can know which schema properties impact the output, and can even determine the theme's schema compatibility to make a table similar to what you proposed.

This will help as many themes "support" a certain version, but for whatever reason didn't handle certain properties like certificate etc. Even @jsonresume/jsonresume-theme-class suffers from this, since the original was made before those properties were added and I haven't added it myself yet.

Reference:

• https://github.com/jsonresume/jsonresume-theme-class/issues/26

---

Meanwhile, thanks for the feedback. And for bearing with the tools/themes while it's not exactly in the most user-friendly state.

[bookRa]

add a note to the top later with installation and usage instructions that explicitly show @jsonresume/jsonresume-theme-class. Would that suffice, or were you referring to something else?

Yep! That note would've definitely alleviated my confusion :) so maybe it could help others. Appreciate the info/context!