Add JSON-LD LC Working Drafts

[lanthaler]

No description provided.

[tobie]

We're trying to migrate all references to structured JSON objects rather than HTML strings. Think you could change those? Thanks!

[lanthaler]

Sure, the only reason I put in the HTML string at the moment is to include both the timestamped version and a link to the latest version (according W3C pubrules). Is there a way to do that with JSON objects? The drafts are currently in last call.

You could also include them as they are now and I will convert them to JSON objects once both specs have REC status.

[tobie]

So the way this is generally handled is by adding two entries, one timestamped (e.g.: "WEBSOCKETS-API-20110929") and one not (e.g.: "WEBSOCKETS-API"). That said, we could enable pointing to /TR all the time by adding a shortName property to each W3C spec entry. I've had other use cases for that feature, so that's certainly something we could look into.

[lanthaler]

Or, to make it work across standardization orgs, by adding a latestVersion property. That way it would also work for Internet-Drafts at IEFT for instance.

[tobie]

+@darobin would like your thoughts on this.

[marcoscaceres]

On 15/04/2013, at 9:35, Tobie Langel notifications@github.com wrote:

So the way this is generally handled is by adding two entries, one timestamped (e.g.: "WEBSOCKETS-API-20110929") and one not (e.g.: "WEBSOCKETS-API"). That said, we could enable pointing to /TR all the time by adding a shortName property to each W3C spec.

Please don't do the above. There is no justifiable use case for pointing to a date draft. Only include links to the latest published version.

Having dated links in the bibliography is a huge maintenance nightmare and should be actively discouraged.

If for some reason (I can't think of any rational one) an author wants to link to date draft, then respec should XHR the spec and grab the date link programmatically.

I've had other use cases for that feature, so that's certainly something we could look into.

I think we should actively work towards discouraging people to link to date drafts. This would fix a lot of issues in the bibliography.

[tobie]

I tend to agree with you @marcoscaceres, but iirc @darobin thinks otherwise.

[lanthaler]

Please don't do the above. There is no justifiable use case
for pointing to a date draft. Only include links to the latest
published version.

Well.. the "use case" is the W3C manual of style (http://www.w3.org/2001/06/manual/#ref-section) which explicitly says to cite the most specific identifier:

"For example, usually you would link the title to http://www.w3.org/TR/1999/REC-html401-19991224 rather than to http://www.w3.org/TR/html4/"

[marcoscaceres]

@lanthaler the W3C is wrong. That's also not a use case, that's just an example of misguided advice from over a decade ago. Since then, we learned that pointing to date versions leads to confusion and other more serious issues (e.g., people implementing out of date specs - sometimes on purpose and then freezing on a dated spec - and then blaming the spec for pointing to a dated version).

[lanthaler]

I’m not sure I agree. If a specification depends on another specification it typically depends on a very specific version which is not automatically the latest version. At the time of writing (and freezing) the spec, the best one can do is to clearly reference the current version of the other specification and include a link to the latest version of that spec. Specs change – that’s the whole point of versioning them.

[marcoscaceres]

@lanthaler How you would normatively reference and implement a dated implementation with no test suite? Or do you propose keeping a test suite for every dated version so that all specs bugs are codefied per spec version?

[darobin]

Whoa whoa whoa.

Let's not have a rehash of the versioned specs debate here, shall we?

Some notes:

• I do think that there are occasional use cases to link to a specific version of a spec. For instance: "Since the latest Unicorn Riding specification introduced a major compatibility problem, we here refer to UNICORN-RIDING-19770315. Yes it only happens when there has been a social breakdown, but social breakdowns happen and spec authors should have the tools to handle them.
• I don't care what the manual of style says, by default references should be to the latest version. Otherwise they always go stale.
• I really don't see having some clearly identified dated versions in the DB as "a huge maintenance nightmare". I've been maintaining this DB for 4 years now and we're doing okay, thank you very much.
• I don't think that it makes sense to have a reference contain both the dated and the live version of a draft. One can argue for issues in using either style, but using both at once certainly brings up the union of the issues plus the problem that you might get one implementer using one and another the other. You could address that by pointing out which one to use, but in that case why not just use that one in the reference.
• ReSpec is not about to start issuing XHR requests to specs just to grab their dates. We're trying to be faster, not slower.

So, all in all, I think that the current system works. I don't think that we should add a field to support referring to both dated and live versions of a spec. So in this specific instance I reckon that a JSONified reference pointing to just the latest (or conversely, the same with a dated name pointing to the dated version) would be wunderbar.

Thanks!

[marcoscaceres]

On Monday, April 15, 2013 at 4:02 PM, Robin Berjon wrote:

Whoa whoa whoa.
Let's not have a rehash of the versioned specs debate here, shall we?

Sure, but seems @lanthaler didn't get the memo back in 2002: we don't do dated in normative references no more :)

Some notes:
I do think that there are occasional use cases to link to a specific version of a spec. For instance: "Since the latest Unicorn Riding specification introduced a major compatibility problem, we here refer to UNICORN-RIDING-19770315. Yes it only happens when there has been a social breakdown, but social breakdowns happen and spec authors should have the tools to handle them.

People doing that should not add their entries into the main DB. Those are for personal/informative use, it seems - and the community does not benefit from having those dated version in the main DB.

I don't care what the manual of style says, by default references should be to the latest version. Otherwise they always go stale.
I really don't see having some clearly identified dated versions in the DB as "a huge maintenance nightmare". I've been maintaining this DB for 4 years now and we're doing okay, thank you very much.

I guess it's subjective. I find the having to constantly update references very frustrating. Also find seeing out of date references very frustrating. Having PRs allows the maintainers to catch bad references going into the main DB.

I don't think that it makes sense to have a reference contain both the dated and the live version of a draft. One can argue for issues in using either style, but using both at once certainly brings up the union of the issues plus the problem that you might get one implementer using one and another the other. You could address that by pointing out which one to use, but in that case why not just use that one in the reference.
ReSpec is not about to start issuing XHR requests to specs just to grab their dates. We're trying to be faster, not slower.

That's ok. But we should encourage best practice too (i.e., not pointing to dated versions and limiting the number of dated version in the DB).

So, all in all, I think that the current system works. I don't think that we should add a field to support referring to both dated and live versions of a spec. So in this specific instance I reckon that a JSONified reference pointing to just the latest (or conversely, the same with a dated name pointing to the dated version) would be wunderbar.

wunderbar indeed… so long as it's the latest one :)

Marcos Caceres

[lanthaler]

Well.. references for WDs have to be updated anyway as soon as they go into CR, PR, or become a REC. Especially for work in progress as this it makes sense to reference a dated version IMHO.

That being said, if you prefer to have an entry to just the latest version. I’ll just update the PR – definitely less work than discussing it here :-P

[marcoscaceres]

@lanthaler yes, please update it. Sorry you got dragged into an old old old debate. Some of us have been seriously burnt by the dated spec model in the past (it's why you see so many WGs moving to a "Living Standard" model).

[lanthaler]

@lanthaler yes, please update it.

Done