Evolvability issues with phone and e-mail field design.

[rolandnsharp]

@inadarei

In any message format design it's a good idea to make things that can change be data elements, rather than structural elements. Changing structural elements breaks things, data elements provide evolvability.

Phone and e-mail fields have a lot of variance. People have different types of phones, emails and they don't necessarily limit them to "work" and "personal". Making such assumptions is wrong.

Instead following is what you could do.

This:

email: [
{"type": "work", "value" : string}, // e.g. thomas@facebook.com
{"type": "personal", "value" : string} // thomas@gmail.com
],

is more evolvable than this:

email: {
work: string, // e.g. thomas@facebook.com
personal: string // thomas@gmail.com
}

the same is true for the phone field.

[wdoekes]

While your argument is perfectly valid with regards to the phone field, for the email field it is not.

We're building a resume here, so I'll only specify 1 e-mail: the one I want to be contacted on.

[inadarei]

Ha, well the sample doc had multiple emails and multiple phones so that's what I was going with: http://jsonresume.org/

But I agree, my argument was about general approach. It can be applied to phone numbers, emails or social media links, depending on needs.

[smizell]

It looks like this pattern is already being used for things like skills, hobbies, references, etc. An array of anonymous objects (as proposed here) seems to fit in line with the rest of the document format.

[fredsterss]

Personally I have no idea why you'd want to share work anything with potential employers. I don't want work phone or email when I'm looking at resumes, and I would never share those with a potential employer. The rationale for having multiple makes no sense to me. Both should be constrained to a single entry imo.

Put another way, what is the use-case for having work and / or home for these fields?

[thomasdavis]

More notes at duplicate #50

[thomasdavis]

Put another way, what is the use-case for having work and / or home for these fields?

I can't actually come up with anything, I'm going to vote that we have a simple string for email and phone.

[smizell]

Even if email and phone become strings, I think that website and profiles could benefit from being anonymous objects as proposed by this issue.

{
  "profiles": [
    { "type": string, "url": string }
  ]
}

Where type can be Twitter, Github, etc. and url is the actual URL of the profile.

[thomasdavis]

Makes sense to me, I will set up a page where you can view different versions of the specification and we can start moving towards merging these issues.

[wdoekes]

Put another way, what is the use-case for having work and / or home for these fields?

Back in the days, we had "home" phone and "mobile" phone.

However, since a decade now, (almost) everyone always has their mobile phone with them wherever they go, so that makes that point less valid. On the other hand, perhaps someone is reachable on a phone in a different country during a certain period.

And who says we'll still be using phone numbers in 10 years time?

Thinking out loud here. What about?

contact: [
    {description: "email", uri: "mailto:my@email.com"},
    {description: "phone during week 28", uri: "tel:+321987"},
    {description: "mobile phone", uri: "tel:+1234567"}
]

[fredsterss]

@wdoekes this still seems like unnecessary complexity - it's not like we're trying to define a way to always be able to get in touch with someone no matter what. This isn't a spec for an emergency contact. I think we need to balance brevity and ease of use with utility to the potential employer.

[vote539]

I like @wdoekes's contact array. It is much more future-proof than separate fields for email and phone. This sort-of reminds me of the days when they were drafting the HTML standard, where they put tags that are now obsolete at the top level, and it made things messy.

[thomasdavis]

I'm going to still vote for phone and email as singular fields to give the theme designers an easier job.

When we do new major versions of the specification, we can release tools that auto update your resume.json to the latest spec version. Moving email and phone into a more abstract data type should be trivial if the use case arrises.

[fredsterss]

@thomasdavis +1

[ocram]

@thomasdavis +1 as well

[DonDebonair]

@thomasdavis definitely +1 for simplicity. As a general note I think we should really think hard about the complexity of the schema and keep vigilant that we're not over-engineering things. The first version should not try to support every potential use-case.
Just have a look at resumes you have lying around and see if those contain multiple phonenumbers and/or email addresses for instance :)

[thomasdavis]

Experimenting with a new label called "Decision Needed", this issue has it applied. It means we will be passing something through in the very near future.

[shea256]

What are the options here? Turn email into a list or keep it the way it is?

[DonDebonair]

Options:

• Turn email into a list
• Keep it the way it is
• Make it a simple string <- my preferred option.

[thomasdavis]

Will just ask @opensourcegrrrl what she thinks, if it's a +1 for singular email and phone.

Then we will make the commit.

[osg]

+1 for singular
On Jul 12, 2014 10:46 AM, "Thomas Davis" notifications@github.com wrote:

Will just ask @opensourcegrrrl https://github.com/opensourcegrrrl what
she thinks, if it's a +1 for singular email and phone.

Then we will make the commit.

—
Reply to this email directly or view it on GitHub
#27 (comment)
.

[thomasdavis]

Ok marked as pull request needed.

email and phone to be changed to types string

[thomasdavis]

This has been added to Change Log as complete, cheers!