Add a metadata section

[chrisdotcode]

This will be an object with an arbitrary amount of key/value pairs, containing any information.

Example use cases are information for themes, user information, and notes.

Speaking of notes, my other idea is to call this metadata section "notes", and make it either be a k/v pairset, or string with notes, which is more useful for non-technical users.

[stp-ip]

I vote for having it as meta-data as it is more generic. One can have various notes within this k/v store.

[stp-ip]

Non-technical users should not per se add notes in the json data itself, but use an editor, which can easily number keys for notes ("note1", "note2").

[chrisdotcode]

Sure.

[hacksalot]

+1. We've been using a similar construct (meta) over in FRESH for some time, would help to have this in the JRS standard.

[olivif]

metadata sounds good to me. +1 for the kv implementation.

[aloisdg]

👍

[colindean]

Is this for a single metadata object in the resume document, or effectively a reserved key in any object, metadata, that can describe that particular object?

I think it's the former, while #133 is the latter.

[phumke]

I'd like to see this in every object within the document as opposed to a single top level. As long as it's optional I don't see this as a source of too much pain.

Could be worth adding to #223 ?

[aloisdg]

@phumke I am against. The file is going to be a lot more heavy.

[phumke]

@aloisdg it will be heavier, but it provides much deeper filtering and searching.

[aloisdg]

@phumke You want to query object by version? I am not sure that I understand.

[colindean]

@aloisdg see #133. It'd be nice to include arbitrary metadata on an object, something that only means something to the author or a reader that takes action on certain special metadata.

[aloisdg]

I took the time to read #133 . This is more tags than metada alas semver.(but you dont like the term tag). Nice issue by the way.

I think it's the former, while #133 is the latter.

Yes. As @stp-ip wrote, we are heading for the first solution aka one header metadata to rules them all.

For the second, I am still against because of the weight of this. I dont think it should be in the schema (at least for now). I see two solutions:

• A tool to manage the split. The second idea is a meta jsonresume. It splits a file to export a list of resumes based on metadata.
• Each template/tool support metadata. It is going to be a lot of works I think.

It is same problem than the support of different languages.

[phumke]

True, the metadata and different languages really start to add a lot of weight to the full master resume. I still think the metadata is useful at levels lower than the top, in which case the question becomes how to handle this. The idea of splitting this out into separate files is interesting. Quick pros and cons:

Separate Files:

• Keeps the JSON resume lighter
• No single source of truth - full master resume becomes a set of files (hard to manage without additional tooling on top)

Single File:

• Heavier JSON resume (again need tooling to read the files and not get lost in syntax)
• Single source of truth

Long and short of it, both solutions need more tooling support. I agree with @aloisdg, maybe we stick with a single metadata for V1 and pin multiple metadata for post-V1.

[stp-ip]

Just to clarify and jump in on the discussion.

The idea here was to have a top level metadata section/object.
In there display information, filtering information and additional hidden information for specific tools can be moved. This does add weight to the resume, but not to the core data. That's the reason it's a separate section at the top level. Basically resume and metadata are the first sections.

I already provided a filtering schema idea within metadata and a substitution mechanism.
We could make it more generic to be able for tools to use it easily.

One thing to specify would be how to add metadata to a section/attribute etc.
My rough ideas were:

metadata.filter = [{
  "volunteering": {
    "keywords": [
      "pro-bono"
      ],
     "attributes": [
       "work['greenpeace'].project['saving whales'].role",
     ]
  }
}]

...
metadata.substitute = [{
  "section": "work['gardner AG']",
  "substitute": {
    "description.markdown" : "Markdown enabled description.",
    "description.html" : "HTML enabled description."
    },
  }],
...

Within JSON schema it is possible to reference another document and therefore multifile metadata files might be supported. I just think the metadata weight is not so bad as to complicate the storage method.

[thomasdavis]

The metadata attribute will generally be filled by third parties and pretty transparent to most users.

We could pretty much copy what they have over at FRESH. (Thanks @hacksalot )

I also agree with just meta that they used. We tried to be very strict to keeping one word property names with the rest of the spec.

+1 to FRESH implementation without their exact defined sub properties.

[aloisdg]

Agreed. Lets go for one top metadata object inspired by FRESH.

For v1 -> One metadata to rules them all.
For vNext -> more metada everywhere. (we will talk about this again after the shipping of v1)

[colindean]

I’m OK with this, but hesitant because I’ll have to rethink how to represent the separate things if I move my resume to JSON resume before the inclusion of per-object metadata in the standard. I started to do so, but hit the aforementioned block...

[thomasdavis]

Some more notes on meta

• Shouldn't affect the resume if removed e.g. it should render and still test in most environments
• Vendors will also be encouraged to just attach non official properties in there

[aloisdg]

@colindean You can write your own exporter from your json to this spec. The tool can be use later. It will be a kind of babel ;)

[stp-ip]

We should definitely add the rule that each tool needs to prefix their metadata with their tool name, if it's specific to the tool and not available in the standard.

[aloisdg]

@stp-ip "vendor prefix"?

[stp-ip]

The idea would be to have schema specific meta data. Such as specific filter data, substitution data etc. - meta.filters and meta.substitute as an example.
And on the other hand you have data from tools not standardized by JSONresume. This should go into prefixed sections such as meta.resumeCLI.versionUsed or meta.resumeRegistry.publishURL.

[stp-ip]

Thanks to the input from @thomasdavis I think we could streamline some of the structure ideas for meta:
The general idea is having one source of truth in a text-only style, which is the basic resume. Everything else such as pretty display enabled text, localization, filtering would be meta data within the meta section.

For enhanced or display data added text we could use a form of:

...
meta.enhancedText = [
  {"work['gardner AG'].description.markdown" : "Markdown enabled description."},
  {"work['gardner AG'].description.html" : "HTML enabled description."}
  ]
...

If none is given for a specific language, it defaults to the basic resume data. Basically it's overwrite only.

---

For filtering:

...
meta.filters = [{
  "volunteering": {
    "keywords": [
      "pro-bono"
      ],
     "attributes": [
       "work['greenpeace'].project['saving whales'].role",
       "work['greenpeace'].project['saving whales'].name"
     ]
  }
}]
...

Basically it's grouping via keywords and/or attributes/fields into a tag here volunteering, which could be used like:

resume export --format=pdf --show-filter=volunteering [fileName] # shows only items referenced in selected remote filter
resume export --format=pdf --show-filter=volunteering,social [fileName] # shows only items referenced in selected remote filters
resume export --format=pdf --hide-filter=volunteering [fileName] # hides items referenced in selected remote filter

---

For languages/localization:

...
meta.localization = [{
  "de": [
    {"work['gardner AG'].description" : "Deutsche Übersetzung der Beschreibung."},
    {"work['gardner AG'].name" : "Gärtner AG"}
    ]
  }
]
...

Localization can be done manually or via a tool. The only thing is that we specify how it is done in the schema. It's overwrite only, so it falls back to the basic data, if it's not overwritten.

Feedback always welcome.

[aloisdg]

Looks good! +1

[olivif]

Added in #237

[chrisdotcode]

Fantastic. This is one of the most important v1.0.0 changes in my opinion.

---

It seems, though, that metadata properties cannot be nested, and can only be strings or numbers? I'm actually against that: IMO, metadata should be infinitely and arbitrarily extensible.

Seems I was reading the wrong commit. Metadata is an object now, correct?

[olivif]

@chrisdotcode I am not sure I understand where/how this is being enforced (string and numbers only).

I just created this example locally and ran the tests, all good.

{
    "meta": {
        "whatever": {
            "x" : "dsdsds",
            "y" : [],
            "z": {
                "z1": 1,
                "z2": "2"
            }
        }
    }
}

[chrisdotcode]

@olivif Seems I had read the wrong commit. We're all good.

[stp-ip]

Not completely added as meta.filter, meta.localization and meta.enhancedText are not yet added.

[evanplaice]

Closing as the metadata section has been added, resolving this issue. Create new issues to discuss specifically any additional extensions to the meta section.