Fix the date problem

[chrisdotcode]

There are about three or so issues that are related to date parsing that will require changes to the schema and the parser in tandem.

• Seasons should be allowed in dates, Support yyyy-season date format #180. Rejected
• Dates in YYYY-MM and YYYY should be valid, start/endDates with only YYYY-MM should be valid #142.
• Allows the empty string in endDate to represent the present, Add custom date validator #150.
• Add custom date parser (maybe?), Add custom date validator #150. Rejected. However, we still might be able to salvage some of the PRed code.
• Figure out how to represent ongoing work, How to represent present work? #199.

This is the "master issue" I'll use to keep track of what they are.

[chrisdotcode]

I'm really not on board with adding a custom date parser, because anything "custom", is by definition, not machine readable.

The intent of that issue was that technically-valid ISO8601 dates were not getting parsed, and I think once that is solved, we should stop at that point.

[KOLANICH]

I think we need neither separate fields for season and years, nor a custom parser. We should just combine startDate and endDate into a subschema dateRange and use it everywhere instead of date.

[chrisdotcode]

Can you provide examples of what you think that field should look like?

[KOLANICH]

A bit better to use tuples for that.

date:["2015-01-01","2015-12-31"]//2015 year
date:["2015-03-01","2015-05-31"]//spring`2015
date:["2015-01-01","2015-03-31"]//1st quarter of 2015

The pretty-printing behavior is implementation defined because it is highly dependent on culture and location. For example "spring2015" will be Sept, Oct, Nov in countries in the southern hemisphere. Or "summer2015" will include May in Britain but won't in Russia. If you mean session in educational institutions it also will have another boundaries. It'd be very hard to deal with all these.
So, no custom parsers, no seasons, no another decorative crap which will deal tons of butthurt.

[thomasdavis]

I agree that we should keep dates simply as machine readable, tooling around input and output of dates in resume.jsons can always address the problem.

[chrisdotcode]

@KOLANICH I like a list of dates. It also handles the case I just ran into where I did something in 2012, then did it again in 2015. Representing that with only a string confers no semantic meaning.

Unfortunately, in your proposed solution, there's no way to tell when you finished working for a location. Which I see as vital. Maybe a stillContributing/stillWorking boolean?

As per @thomasdavis, I think we should think about dropping date as a string, and just use actual JS Date objects.

[stp-ip]

multiple date tuples using JS dateobjects + current boolean +1

[chrisdotcode]

Turns out I overlooked the word "tuple" in @KOLANICH's suggestion.

Multiple occurrences could therefore be represented as:

date: [Date(2012), [Date(April, 5, 2015), Date(April, 7, 2015]]

When the last element in the array is not a tuple, the work is still current.

How do we feel about this suggestion, as compared to using a current boolean?

[stp-ip]

Example:

Duration implied, when using a list
Multi date (past, current, future) example:

date: [
  ["8888-01-01", "9999-01-01"], # future (not current) work
  ["2015-01-01", "9999-01-01"], # current work
  ["2015-01-01"], # current work
  "2013-01", # past work
  ["2013-01-01", "2014-01-01"] # past work
]

Multi duration example:

date: [
  ["2015-01-01", "9999-01-01"], # future duration
  ["2015-01-01"], # openended duration
  ["2013-01", "2014-01"], # one year duration
  ["2013-01", "2013-01"], # one month duration
  "2013", # one year duration
  "2013-01", # one month duration
  "2013-01-01" # one day duration
]

Single duration examples:

date: [["2013-01", "2014-01"]] # one year duration
date: ["2013"] # one year duration
date: [["2013-01"]] # openended duration
date: ["2013-01"] # one month duration

Fixed dates implied, when using a string.
Single date (publications etc.) example:

date: "2015-01-01" # most specific
date: "2015-01" # less specific
date: "2015" # least specific

Sounds as minimalistic as possible. As it should be used by tools not humans, going without the boolean simplifies the standard -> +1.

[KOLANICH]

Maybe a stillContributing/stillWorking boolean?

I suggest not to use boolleans/nulls, just omit the second date for half-opened intervals.

["2015-01-01"]//i'm doing it since 2015 year until now, and at the moment I'm going to do this untill my death

[chrisdotcode]

@KOLANICH I prefer @stp-ip's suggestion of just using a null, because using a tuple complicates the schema a lot.

[KOLANICH]

I don't see how this complicates. Because of the interval is of variable length, let it be a list not a tuple, but a list with maxItems:2 and minItems:1

[chrisdotcode]

Because a single list is more complicated than a list of lists (also, JavaScript has no formal tuple type, either).

That being said, @stp-ip and I were just discussing how using only a trailing null won't adequately handle all date durations. So the null solution by itself insn't entirely adequate.

[stp-ip]

Updated my example to make using null clearer. cc @KOLANICH

[KOLANICH]

JavaScript has no formal tuple type

Tuples and lists are not js types, they are json schema concepts.

[chrisdotcode]

I was not aware of that. In that case, the array of singles/tuples solution handles every possible date case I can think of.

date: [Date(2012), [Date(April, 5, 2015), Date(April, 7, 2015], Date(2015, 10, 16)]

[KOLANICH]

{
    "definitions" : {
        "date" : {
            "description" : "Describes a date (a single day) in ISO 8601 YYYY-MM-DD format.",
            "type" : "string",
            "format" : "date",
            "pattern" : "^\\d{4}-(?:0\\d|1[0-2])-(?:[0-2]\\d|3[01])$"//this should be removed if the validator supports date format
        },
        "dateRange" : {
            "description" : "Describes a continious interval of several dates. The first item is a starting date, the second is an ending one.",
            "type" : "array",
            "minItems" : 1,
            "maxItems" : 2,
            "uniqueItems" : true,
            "items" : {
                "$ref" : "#/definitions/date"
            }
        },
        "uniDate" : {
            "description" : "An universal interval of dates, can be either date or a dateRange.",
            "anyOf" : [{
                    "$ref" : "#/definitions/date"
                }, {
                    "$ref" : "#/definitions/dateRange"
                }
            ]
        }
    },
    "type" : "object",
    "description" : "Test",
    "properties" : {
        "correctD" : {
            "$ref" : "#/definitions/date"
        },
        "correctR" : {
            "$ref" : "#/definitions/dateRange"
        },
        "correctR2" : {
            "$ref" : "#/definitions/dateRange"
        },
        "correctU" : {
            "$ref" : "#/definitions/uniDate"
        },
        "incorrectD1" : {
            "$ref" : "#/definitions/date"
        },
        "incorrectD2" : {
            "$ref" : "#/definitions/date"
        },
        "incorrectD3" : {
            "$ref" : "#/definitions/date"
        },
        "incorrectR1" : {
            "$ref" : "#/definitions/dateRange"
        },
        "incorrectU1" : {
            "$ref" : "#/definitions/uniDate"
        },
        "incorrectD2" : {
            "$ref" : "#/definitions/date"
        },
        "incorrectR2" : {
            "$ref" : "#/definitions/dateRange"
        },
        "incorrectU2" : {
            "$ref" : "#/definitions/uniDate"
        },
        "incorrectD3" : {
            "$ref" : "#/definitions/date"
        },
        "incorrectR3" : {
            "$ref" : "#/definitions/dateRange"
        },
        "incorrectU3" : {
            "$ref" : "#/definitions/uniDate"
        },
        "incorrectU4" : {
            "$ref" : "#/definitions/uniDate"
        },
        "incorrectU5" : {
            "$ref" : "#/definitions/uniDate"
        }
    }
}

{
    "correctD" : "2015-12-01",
    "correctR" : ["2015-12-01"],
    "correctR2" : ["2015-12-01", "2015-12-03"],
    "correctU1" : "2015-12-01",
    "correctU2" : ["2015-12-01"],
    "correctU3" : ["2015-12-01", "2015-12-03"],
    "incorrectD1" : "sdafsfsdfsdfdsfdsf",
    "incorrectD2" : "1970-01-01T00:00:00.000Z",
    "incorrectD3" : "2015-00-01",
    "incorrectR1" : ["2015-12-01", "ololol"],
    "incorrectR2" : ["2015-12-01", "2015-12-03", "2015-12-04"],
    "incorrectR3" : [],
    "incorrectU1" : ["2015-12-01", "ololol"],
    "incorrectU2" : ["2015-12-01", "2015-12-03", "2015-12-04"],
    "incorrectU3" : [],
    "incorrectU4" : "sdafsfsdfsdfdsfdsf",
    "incorrectU5" : "1970-01-01T00:00:00.000Z",
}

[chrisdotcode]

So, building off of all prior said, what are thoughts on the following:

Worked for one day:

{ date: ["2015-12-12"] }

(alternatively:)
{ date: [["2015-12-12", "2015-12-12"]] }

Worked for two months:

{ date: [["2015-12-12", "2016-02-12"]] }

Current work:

{ date: [["2015-12-12"]] }
// that is, an array member with a single element

Worked for one day, two months, and presently:

{ date: [
    "2015-12-11", 
    [["2015-12-12", "2016-02-12"]],
    ["2016-04-05"]
  ]}

This leave an ambiguity open: what happens when you put a singleton array as not the last element (or put one or more singleton arrays in the array)? i.e.,

{ date: [
    "2015-12-11", 
    ["2015-12-12"],
    ["2016-04-05"]
  ]}

Was the finish date the second one? Or the last one?

---

The reason I suggest an array of dates (as opposed to just a single tuple) is because we need to deal with the very real case of repeat work for the same employer.

[stp-ip]

Updated the example #198 (comment) to reflect the current consensus. Much more work for the tools to extract and use dates unfortunately.

[KOLANICH]

Do we really need time periods consisting of different intervals?

[stp-ip]

I would have just enforced durations such as, but @chrisdotcode made a good point, that it would not be needed for tools and could be made shorter.
date: [["2015-01-01","2015-01-01"]] # one day duration

[stp-ip]

Additionally when you enforce durations, how would one represent a year:
date: [["2013", "2014"]] ? would that be one or two years? Would one year be just date: [["2013", "2013"]]

[olivif]

@chrisdotcode sounds great! This will help us make great progress on the Date issues we have open 😄

[dawsbot]

So as a user who wants to make a resume without being a contributor, what is the best way to represent an ongoing job? This could be a deal breaker if there won't be a way to represent ongoing work.

[aloisdg]

For the v0, fill the startDate and not the endDate.

It may change for the v1, this version is not ready. As a user, @dawsonbotsford , what do you think? Do you have an opinion around the subject based on the current thread?

[dawsbot]

I am not understanding the current solution for ongoing jobs.

As a response to your most recent comment @aloisdg, I entirely removed the endDate field. This creates the following ouput. Is this the best that jsonResume can do?

2014-11-01 —

[aloisdg]

@dawsonbotsford It is a free from string. You can choose to write "current" or anything else if you want to. Keep in mind, that you are using a v0 not a v1.

We know that the situation can be better, and we want to change it, #198 and specifically #199 are here for this reason.

[adrianblynch]

Could dates that can't be parsed simply be output as-is?

[chrisdotcode]

@adrianblynch: We prefer not to take that approach because we favor machine readability.

[aloisdg]

For #199, I still think that a endDate set to null is the best way to handle it. A flag current had some glutter. I dont think it worth it.

[adrianblynch]

Without looking into the code, I can't say whether this is straight forward or not, but from a user's point of view, I want to add a date OR I want to specify a non-date like "Present".

@chrisdotcode - What's not machine readable about a string?

[aloisdg]

@adrianblynch null is not enough? If the start is today or in the past and if the end doesnt exist or is in the future, then this job is a current one.

[KOLANICH]

What's not machine readable about a string?

Because a Date object is not a string. We have to serialize it into string because JSON has no Date type. We could have serialized it into unix-time, but it would be not human-editable. So we stick to the standard used in JS to parse and serialize dates to avoid problems. JSONResume is about defining everything in standard way, not about writing any kind of free-form shit everywhere you want, because computers cannot understand free-formed texts good enough and reproducibly enough.

[aloisdg]

We can use RFC3339 like TOML.

date1 = 1979-05-27T07:32:00Z
date2 = 1979-05-27T00:32:00-07:00
date3 = 1979-05-27T00:32:00.999999-07:00

[bartenbach]

Not sure what the status on this is, but it seems partial dates don't validate like
2017-01 or 2017
and adding "Present" obviously doesn't work either.

It doesn't allow an empty string but will allow the field to be removed completely.

Interesting. I'm not sure I like the way this strong-arms you into to providing a specific date down to the exact day.

[jjshoe]

@thomasdavis why not just drop the "format":"date" from the schema for this?

[yxliang01]

+1 for Output as-is when the date can't be parsed to JS date object. We are already in 2017. I guess time to make a decision...

[alienkidmj12]

anyone any ideas my my work history wont accept a null field for latest ?

[HyShai]

It's been 2+ years and this still hasn't been resolved.

[stp-ip]

Thanks @HyShai for taking a continued look into jsonresume. Jsonresume is an open source project and has limited capacity. Having an issue open for 2+ years also means that noone contributed a fix in 2+ years. We are working hard to iterate on jsonresume with a new project called github.com/resumic/schema. We are happily taking contributions over there and still take contributions here.

[darkFunction]

Bit annoying that nobody mentioned this in 3 years but if you're like me and don't really care if it's machine readable, you can use the --force flag to skip validation, eg, resume export --force resume_fr.html --theme Fr_flat

EDIT: my bad, doesn't seem to work for export

As a workaround I modified /usr/local/lib/node_modules/resume-cli/lib/pre-flow and removed the line validateSchema: ['getResume', validateSchema],

[jjshoe]

@stp-ip #198 (comment)

[noraj]

Tomorrow we will be in 2019 and we still can't represent a current job.

[chromedays]

And here we're in 2020.

[rbardini]

I'm able to represent current work with @rbardini/resume-cli, which uses jsonresume-theme-even by default. You can see an example here.

I've opened a few PRs to resume-cli integrating most changes from the fork, which may help solving this.