RFC JSON Resume support

[berkes]

Summary

Allow ones profile to be requested and downloaded in JSON resume format.

https://jsonresume.org/

Proposed by DoeNietZoMoeilijk 🥔 in a toot

@Flockingbird I just remembered https://jsonresume.org/ is a thing - is that something you'd see yourself supporting?

Basic example

As a member with a Flockingbird profile
When I want to share my resumé
Then I want to connect to existing tooling that can format my profile into a neat resumé
So that I can export, host or format a professional resumé from my profile.

As a member with an as of yet unfilled Flockingbird profile
And an existing resumé (exportable) in JSON resum format
When I want to fill my Flockingbird profile
Then I want to upload that JSON resumé
Or I want to provide an URL where this can be found
So that I can import my existing resumé into my Flockingbird profile.

Motivation

Having a JSON Resume format of the profile allows us to connect to any tools and services that
can read such a JSON Resume in order to generate a PDF, online static page etc.

Being able to import a JSON Resume format allows members to fill their profile quickly from existing content.

Detailed design

TODO: describe how JSON resume format maps to flockingbird fields and data.

Presented on example.com/m/@[email protected]/resume.json. This should be dynamically updated: it is just another presentation of the profile.
Alternatively, current member can down download a variant of this file.

resume.json endpoint must only present publicly visible data. resume.json download contains all data, including private data.

The resume.json does not replace existing API endpoints.
The resume.json is not a replacement for "profile exports" data requests, but can be a part of that.

An import is one-time only. So when a member uploads a file, it is imported only once. And when a user provides a URL to a json resume for importing, the server downloads it once, and then processes it once.

Import may replace entirely existing fields and data. Or it may merge, leaving existing data in place and only adding new items.
Either a checkbox or UI to choose which to use, should be present, or a clear explanation which one we chose, is present,

Please reference Domain
Model (TODO write)
terminology for existing terms and usage.

Drawbacks

• Import is a somewhat complex feature, in itself. Allowing import of resume.json format will be next to import of CSV, as a CSV is the chosen and preferred format for instance admins to pre-fill their instance with.
• Resume JSON is not an official standard, and can and will change. We should be able to adapt to such changes.
• JSON format allows for easier data harvesting by other parties. For some members this will be welcomed, for others there should be an opt-out. But in that case, the opt-out should be generic and for the entire public profile, not just the JSON format thereof.
• Since we already provide microformats and schema.org in the public profile markup, the JSON could alternatively be generated with external and dedicated "resume microformat to JSON Resume" converter software. But since that is not easy nor currently available (AFAIK), this not straightforward.
• Providing a "live" resume.json endpoint might turn a Flockingbird profile into just a proxy or data carrier. It does offer incentives to keep the flockingbird version up to date, so the network effect is slightly diminished, but not gone.
• Providing an import, might increase the amount of people who generate a profile and then forget about it, causing "dead profiles" to become all-present. It is unclear whether an import feature will increase this problem.

Alternatives

• hResume http://microformats.org/wiki/hresume
• www.xmlresume.org
• https://europa.eu/europass/
• https://schema.org/Person

Adoption strategy

It can be built in several phases.
Import should be considered after the CSV import has been implemented.

How we teach this

Documentation about where to find the endpoint.
A button showing the export or download with format JSON resume.
Link tags in the HTML header pointing to the version for machines.
A menu item or link, showing where one can import. This link could (also) be present on the edit screen.

Unresolved questions

• TBD: how to map to - and from JSON format schema to our data structure.
• TBD: should imports replace- or merge with- existing data?