Define last update date within spec or implementation

[oupala]

The last update of the resume should be an important information.

Outdated resumes are useless.

[KOLANICH]

This should be implementation-defined. Don't make users manually insert the date, let the implementation to capture it automatically.

[aloisdg]

We talked about it here : #49 and here : #204

[stp-ip]

Done in #259

[aloisdg]

@KOLANICH The user shouldn't manipulate the json directly.

[KOLANICH]

@aloisdg Then clarify in the docs what JSON Resume is intended to be and what it isn't. If its main purpose is API for machine-to-machine interaction, then you should specify the whole REST API. If its purpose is to be machine-readable document format, I think we don't need the version and update date fields stored in a document itself (because they are not resume itself, they are metadata about resume document, they mustn't and cannot be part of document itself), they should be captured in implementation-defined way either from database, or from fs file attributes, or from version control system or from anything the entity rendering the doc wants. If they are meant it to be both, you need 2 different specs, one is for document contents (semantics must be preserved as authored (syntax can be optionally normalized/beautified)), another is for API envelope (feel free to include all the metadata you want into API response) to retrieve this documents.

UPD: fixed some errors and clarified a bit

[aloisdg]

@KOLANICH That's a good point.

[stp-ip]

The whole point of having the meta section was to have it for machine interaction. It is bundled with the resume as it's data about the resume. Sure a user can edit it, but every meta data you provide will be editable. We already clarified, that meta is mainly for machine interaction.

[KOLANICH]

For machine-to-machine interaction API there should be another specification. The document itself should not have this fields - they say nothing about the person, they are not resume contents, they should not be there. A machine-readable document should stay the same as long as it has the same data. What is data? It is the purpose of the document. So date of document modification is not data, since it doesn't say us about person's skills. It says facts about the document, it is metadata, it should be stored separately, if it were a part of a document it would lie. API responses can vary from request to request, more, it is often meant to vary because responses are often meant to be generated in real time. You can wrap your jsonresume document into API if you want m2m, as you can wrap any other doc.

[stp-ip]

The idea was to have the base data (personal resume data + meta data) as a machine readable format aka the schema. The actual document being exported aka your resume document is a completely different thing.
The schema is there for being machine readable and splitting up this data into resume data and meta data seems wrong in my opinion.

The date changed, the canonical link etc. are meta data about the resume and therefore should be located as closely as possible to resume data. Furthermore having to store and keep 2 documents up to date seems like a huge complication.

In my view the resume schema is the machine readable part including machine data.
The exported resume is different. There no meta data should be included as it should be human readable or easily understandable/shareable.

[KOLANICH]

Furthermore having to store and keep 2 documents up to date seems like a huge complication.

It doesn't, because API schema doesn't need to know anything about resume schema (without metadata)

{
    //the metadata specified in this spec
    resume:{
        //this object is resume document as black box, it can be even not JSON Resume
    }
}

For search requests API you can say that it has encoded paths in resume tree. For example you can just put resume documents into MongoDB and just use its API as a search API.

In this way you can update the spec for API more seldom than the spec for doc.

In my view the resume schema is the machine readable part including machine data.

JSON is both machine and human readable. In my view the requrements are
1 you can use JSON Resume for resume authoring because JSON is human-readable.
2 you can use tools with fancy GIU to author it because it is machine-writable
3 you can use tools to transform it in fancy non-machine-readable representation like PDF or html
4 you can store it into file and a file in a git repo
5 you can map it on db structure and search and analyse it
6 you can easily write a tool doing with it everything what you like.

In fact you can store everything you want inside a document, but I don't think it is the right design for a piece which can be used as a storage format.

[stp-ip]

I agree with most of your points.

But I don't think for the schema/storage format we should take into account the possibility of an API layer on top. That's tooling around it and not something we should rely on to be available for the storage format.

Additionally having the meta data stored and defined within the storage format makes it easier for tooling to use it and easier for people to use the format/schema without fancy tooling aka back it up, store it within a git repo etc.

I agree that we should document the use of the meta section and make clear, that it should not be edited by hand.

[KOLANICH]

I don't think for the schema/storage format we should take into account the possibility of an API layer on top.

Again, it can be not an API layer. It can be anything. I propose to just move all the metainformation which is possible to move out of scope of JSON Resume spec.

Additionally having the meta data stored and defined within the storage format makes it easier for tooling to use it and easier for people to use the format/schema without fancy tooling aka back it up, store it within a git repo etc.

In this case the date of modification is stored as file system attribute. There is no need to store it in a file itself.

[stp-ip]

The direction you are proposing is to basically not define meta data or if it is defined, as a separate meta data definition. I think this leads to more complexity to start with. Currently the resume data and the meta data are defined within one schema, but are actually quite separate. There is nothing preventing us from splitting it up later.

I think that for ease of use and standardization it makes sense to leave it as it is currently aka having the meta data defined within the schema. Defining that it might be file system attribute, separate meta data file, API definition etc. leads to more complexity. We are already going really slow and separating and complicating further seems to spread us even thinner. I appreciate your thoughts and I agree with some of them, but I think we have to agree to disagree on the issue "should meta data be separate".

Let's leave it for now and see, what others are thinking.

[KOLANICH]

The direction you are proposing is to basically not define meta data

Exactly this.

I think this leads to more complexity to start with.

Do you really think that reading time from Git, file system attributes or json field from API response make lot of complexity into the applications? In fact this simplifies the spec.: if there was no such a field in the spec, the tools would be able treat it in own way. In this case this will be not a part of spec, but a feature of implementation. And this is good: each implementation will be able to have it implemented in the way more suitable for that implementation: job website will store it as a column in a DB, desktop app will fetch fs attributes and VCS data.

There is nothing preventing us from splitting it up later.

In Russia we have a proverb "there is no anything more permanent than [anything] temporary". You know, it will be a pain to introduce non-backward-compatible changes.

[stp-ip]

The direction you are proposing is to basically not define meta data

Exactly this.

Just to clarify. You don't wanna define any meta data or just no last update field?

I think this leads to more complexity to start with.

Do you really think that reading time from Git, file system attributes or json field from API response make lot of complexity into the applications? In fact this simplifies the spec.: if there was no such a field in the spec, the tools would be able treat it in own way. In this case this will be not a part of spec, but a feature of implementation. And this is good: each implementation will be able to have it implemented in the way more suitable for that implementation: job website will store it as a column in a DB, desktop app will fetch fs attributes and VCS data.

Yeah it simplifies the spec, but complicates the tooling as no clear standard way of retrieving the last modification is provided.

There is nothing preventing us from splitting it up later.

In Russia we have a proverb "there is no anything more permanent than [anything] temporary". You know, it will be a pain to introduce non-backward-compatible changes.

Didn't wanna rip it out without someone else giving their opinion. I agree that we have to decide on it before releasing the finished v1.0.0 so.

[KOLANICH]

Just to clarify. You don't wanna define any meta data or just no last update field?

Some metadata is surely needed to be defined inside. This metadata is spec version because without it introducing non-backward-compatible changes such as repurposing properties will be more problematic. There surely will be some point when we'll have to introduce them to develop further. But all the metadata which can be moved out should be moved out, for example no permalinks in JSON Resume schema, permalinks vary from site to site and if you wanna to send your resume to multiple services you will not have to do any modifications to them. Permalinks can go dead because a website can change its internal structure. In some cases you cannot know permalink in advance, for example if permalink is generated from SHA256 of document. So no permalinks in schema. I hope I gave you the understanding what kind of things should not be included in schema.

Yeah it simplifies the spec, but complicates the tooling as no clear standard way of retrieving the last modification is provided.

Yes, it does, a bit (I don't consider one syscall to capture the date from FS or a few syscalls + some strings and regexes to capture them from git as much complications). But good tools (in my opinion) will not rely on that property and will retrieve metadata from more reliable sources anyway.

[stp-ip]

The permalink issue is something for a separate issue. If you feel that should be discussed, please open a separate issue.

It's not just the complication introduced into the tooling, but the variability on the various data sources the different tools use. With the data within the schema it is defined, where it relies. So just stop here for now. Agree to disagree and wait for some other opinions. The issue is reopened so we can revisit this before we officially release any new version.

[oupala]

In my idea, I would make a difference between the functional last update date, and the technical last update date.

If I restore my resume from a backup, or if I copy it a on new harddrive, the technical update date would be modified, but the functional update should not be updated.

This is why I think that the last update date, which is in my mind the functional last update date, should be a new field in the resume json file. This field is a metadata, but should rely into the json file as it is very tightly linked to the data and should be settable manually by the user.

If a json resume editor want to set this field automatically on save, no problem, just edit the corresponding metadata field. But it should always be possible to edit it manually, by hand, by the user.

[KOLANICH]

If I restore my resume from a backup, or if I copy it a on new harddrive, the technical update date would be modified, but the functional update should not be updated.

1 You (or a tool) can take it from version control system if you use it. Using VCSs for text formats is nearly always a good idea.
2 When you restore whole disk image, there is no such an issue at all.
3 For the case you use file-level backup solutions, keep in mind that in fact you can put timestamp of your own choice into a FS, OSes provide API for that.
The Posix one:
man 2 utimensat

utimensat, futimens - change file timestamps with nanosecond precision
...
int utimensat(int dirfd, const char *pathname, const struct timespec times[2], int flags);
int futimens(int fd, const struct timespec times[2]);
...
With utimensat() the file is specified via the pathname given in pathname. With futimens() the file whose timestamps are to be updated is specified via an open file descriptor, fd.

Windows also has the API for the same purpose.
Backup software and archivers make use of such API to restore timestamps. The examples are :
man 1 rsync

-t, --times preserve modification times

Or for Acronis True Image Home, which also has file-level backup and restore capabilities

Set current date and time for recovered files - you can choose whether to recover the file date and time from the backup or assign the files the current date and time. By default the file date and time from the backup will be assigned.

[oupala]

@KOLANICH My point was about having a functional last update date which would be managed almost manually.

All your answer is about how to manage automatically a technical last update date.

You may have missed my point, but we're not talking about the same thing.

I know that there is many ways to manage metadata (VCS, rsync with --times) that are well known for experts.

I'm thinking about non-experts peoples, the one that save their resume on an usb key, then copy ot somewhere else...

When a manually set metadata is set about last update date, it should override any technical last update date. That's my point.

[KOLANICH]

My point was about having a functional last update date which would be managed almost manually.
All your answer is about how to manage automatically a technical last update date.

You CAN manage it both manually and automatically. By default it is managed automatically.

I'm thinking about non-experts peoples

Non-expert people don't even need to know anything under the hood, the software will do everything for them and the only thing they need to use is a nice GUI.

When a manually set metadata is set about last update date, it should override any technical last update date. That's my point.

Again. You CAN set "technical" update datetime manually to the datetime you want. Since you can do it (you can really put there anything you like, it can be be completely fake and wrong, it is not enforced by the OSes and FSes) there is absolutely no need to add additional fields for the same purpose. This will only increase mess for everyone: dumb people will use it for date unwillingly introducing misinformation to the software, dumb software developers will develop software relying on it, smart developers will have to take this field into account somehow, smart users dealing with dumb software will have to use this field. You won't be able to eliminate this field once introduced. Don't open Pandora's box.

[oupala]

I have to say that we don't agree on this point.

I still think that a functional last update date is useful and could be optional. Only those who need it will set it in their resume.

[stp-ip]

I do understand both solutions and I still think it is cleaner to define it within the spec. Then tools know this should be used and smart users wouldn't check the FS metadata.

One thing so we shouldn't do is make it optional. This will lead to the points mentioned by @KOLANICH.
So either enforce update date in the spec being the only source of truth or remove it.

[KOLANICH]

One thing so we shouldn't do is make it optional. This will lead to the points mentioned by @KOLANICH.
So either enforce update date in the spec being the only source of truth or remove it.

You cannot enforce ban on implementation-defined additional features like taking date from the FS or git by the spec. Especially the ones wanted by everybody. So mess will go on.

And I'm strictly against of making this field mandatory.

[stp-ip]

I do like your persistence and will remove the date field in the next revision. So the basis of the discussion is on the conservative side.

[oupala]

Keep the field and make it optional.

If the mess predicted by @KOLANICH appears, we'll remove the field.

But the predicted mess can also never appear, and everyone will be happy.

It would be a shame to be unable to set the last update date as a metadata, managed and stored in the content of the resume.

[thomasdavis]

lastModified should be done via implementation. That being said, as an ecosystem we should encourage sensible defaults. In the version 1.0.0 release it won't be an official property. But will leave it in for now.

[stp-ip]

When we decide on lastModified being an implementation detail, we should remove it. One can always add it optionally, but not supporting it = removing it.

[stp-ip]

So action here:

• Remove lastModified
• Close issue
• Revisit issue post-v1

[thomasdavis]

After re-reading @KOLANICH opinions, I agree, that JSON Resume is at best a simple display format. All technical layers would have to be built on top.

Issue will be marked as High Priority to remove lastUpdate from proposed v1 -> #259