References Date and Affiliation

[justinphelps]

It could be useful to add "date" and "company" and possibly "relation" to references e.g., { name: 'John Smith', date: '2016-03-03', company: 'Pied Piper', relation: 'peer - same department'. reference: "Erlich is great work with. You can assign him high level tasks and be assured that they'll be completed on or ahead of schedule. Working with Erlich was easy and enjoyable as he could interact with technical and business people alike, meeting the needs of both with speed and accuracy. I look forward to working with Erlich in the future." },

[corbob]

I second this. A Resume Builder I was using has this for references:

[stp-ip]

How about something along the lines of:

    "references": {
      "additionalProperties": false,
      "description": "reference section with summary and list of references",
      "properties": {
        "references": {
          "description": "list of references",
          "items": {
            "additionalProperties": false,
            "properties": {
              "entity": {
                "additionalProperties": false,
                "description": "entity details",
                "properties": {
                  "description": {
                    "description": "entity's primary activity",
                    "type": "string"
                  },
                  "image": {
                    "description": "url or src of an image, photo or logo",
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "description": "url of the entity website",
                    "format": "uri",
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ],
                "type": "object"
              },
              "name": {
                "description": "name of the reference",
                "type": "string"
              },
              "reference": {
                "description": "reference text",
                "type": "string"
              },
              "role": {
                "description": "role/position of the reference at affiliated entity",
                "type": "string"
              }
            },
            "required": [
              "reference",
              "entity"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "summary": {
          "description": "continous text summarizing or adding context to the full reference section",
          "type": "string"
        }
      },
      "type": "object"
    },

Basically looking like this within an example:

  "references": {
    "references": [
      {
        "name": "Stephan Mark",
        "reference": " Person was a great employee, who turned up to work at least once a week. He exceeded my expectations when it came to doing nothing.",
        "entity": {
          "name": "Entity of Things",
          "description": "A good things entity",
          "url": "http://xyz.example.com",
          "image": "https://example.com/assets/entity.svg"
        },
        "role": "Senior Software Engineer"
      }
    ],
    "summary": "My references are great due to specific items. For contact details about my references please reach out directly"
  },

[thomasdavis]

Very good suggestions.

1. We should try to re-use as many field names where it makes sense, so instead of relation or role we should use position as we do in the work
2. We have been avoiding nesting objects where possible and I think listing the workplace as an object might be overkill rather than a simply company string (of which I am also not sure of)
3. date is also questionable

Where my reluctance is coming from, is that most recruiters or employers will generally ask after certain stages of the interview process for your reference contact details. You rarely want to share them outright, and their details are likely to change often out of your control, so you would prefer to only find them when the time comes.

I do understand the need for conveying the quality of your reference though.

I'm sort of jumping all over the place here too so I will follow up tomorrow.

Might be nice to get some examples of how references are done in the real world.

[stp-ip]

Very good suggestions.

1. We should try to re-use as many field names where it makes sense, so instead of `relation` or `role` we should use `position` as we do in the `work`

Within our current naming I agree. But in the general idea of making a lot more fields and names more general and therefore re-used role might be better. Another separate discussion, but wanted to get some feedback on the general structure here besides the name.

2. We have been avoiding nesting objects where possible and I think listing the workplace as an object might be overkill rather than a simply company string (of which I am also not sure of)

Probably depends on the overall picture. It is the same company structure reused in a few other sections, so easy to work with. If that is not a reused section a single company string could work as well. Company does add quite a bit of context in my mind. Say a John Doe CTO from Github might be a much better reference than John Doe CTO from neverHeardOfCompany.

3. `date` is also questionable

Agreed. Not sure it adds a lot of context.

Where my reluctance is coming from, is that most recruiters or employers will generally ask after certain stages of the interview process for your reference contact details. You rarely want to share them outright, and their details are likely to change often out of your control, so you would prefer to only find them when the time comes.

I do understand the need for conveying the quality of your reference though.

I'm sort of jumping all over the place here too so I will follow up tomorrow.

Might be nice to get some examples of how references are done in the real world.

Reluctance for Company? I partially agree. Company could change, but it might have still be a relevant reference of this specific person at that specific Company. Contact details on the other hand are probably something that shouldn't be in the schema as they are changing and do have privacy issues being inside the schema. There was a lengthy discussion https://github.com/jsonresume/resume-schema/issues/2 on this.