Abstract

This document is a sample of what a real specification would like in the future. It has nothing to do with High Resolution Time except for the fact that HRT is used as a sample for the links. It contains various definitions and concepts used by W3C /TR cooks.

Status of This Document

This document isn't meant to change drastically how specifications will look like after the 2018 GRS (great redesign of specifications scheduled for 2018). For that, you can look at ideas such as the 2012 one.

1. Considerations

This document is a reflection on how to change our header links in the beginning of December 2017.

Not all headers included in this document need to be used. The important part is for the tooling to find its stuff and for the users not to be confused too much.

This document contains the advanced ability of selecting which spec you would like to see. Your current specification preference is []. You may change this by using specification preferences. (hint: change your preference to "upcoming" or "ed" and reload this document to see the effect).

2. The Origin of the Proposal

See the notes from the TPAC 2017 session.

The original meaning of latest, upcoming, all can also be found in the Latest versions proposal for leveled specifications.

2.1 Use Cases

3. Shortnames and leveled shortnames

We distinguish between:

with:

When looking at a specification use the shortname URL of a specification, it is not possible to know if you're looking at /latest or /upcoming. One may use specification preferences to set proper expectations.

4. About using level numbers in specification

The title of a specification MAY reflect the <level> of a specification. The dated URL of the specification (aka This Version) and the leveled shortname URL of the specification MUST contain the <level>.

Some Groups feel strongly about the levels of their specification, others prefer not to deal with them. We give the choice.

<Level> is a number, not interpreted by the underlying system except for its sequence order. You may use for example 2, 2.0, 2018.

You may add additional specification metadata headers in your document, such as a "Latest published Level 2 version" for the leveled shortname URL.

5. On obsolete/superceded/rescinded/retired/outdated

5.1 Outdated warning

Currently, we are displaying 2 types of outdated warnings:

  1. For Recommendations that aren't obsolete/superceded/rescinded and don't have a more recent edited recommendation, we indicate that a more recent document with incorporated errata (an Edited CR or an Edited PR) is available.
  2. or we display a note indicated "This version is outdated!".

In all cases, we direct the reader to the leveled shortname URL instead.

6. /latest/

"Latest" will return the most "stabilized" document available. Those links are created automatically for all https://www.w3.org/TR/<shortname>/. For example, https://www.w3.org/hr-time/latest/

As such, it points to the first document in the following list:

  1. the highest level being a CR, an Edited CR, a PR, an Edited PR, or a REC that is not obsolete/superceded/rescinded/retired/outdated
  2. the highest level being a Note if not retired
  3. the lowest level being a WD
  4. the obsolete/superceded/rescinded REC
  5. the retired Note

7. /upcoming/

"upcoming" will return the "tip" document available. Those links are created automatically for all https://www.w3.org/TR/<shortname>/. For example, https://www.w3.org/hr-time/upcoming/

As such, it points to the first document in the following list:

  1. the highest level that is not obsolete/superceded/rescinded/retired/outdated
  2. the obsolete/superceded/rescinded/retired document

8. /ed/

If available, "ed" will redirect to the "nightly build" of the upcoming document.

As such, it redirects to the document known as "editor's draft" that is associated with the upcoming document, if known.

should we just use "Nighlty build" instead of Editor's draft?

9. Canonical version

This represents the preferred URL you want people to use to access the specification. It helps search engines to be able to consolidate the information they have for the individual URLs (such as links to them) on a single, preferred URL. It is either the shortname URL or the leveled shortname URL.

Canonical version header shouldn't differ from rel=canonical.

RFC6596 indicates that the canonical link relation specifies the preferred URL from resources with duplicative or superset content. Sometimes, we do remove content from one published dated version to another, so we're not following RFC6595 strictly. However, we consider the consolidation of search results to take priority here given that one can always access the history of the specification.

10. History

This is intended to replace what used to be "Previous version" and represents the history for all snapshot for a given shortname URL. For example, https://www.w3.org/standards/history/hr-time

History pages aren't handling all snapshots currently. We're looking at changing that.

11. /all/

This represents the list of all non-outdated specifications for all level versions for a given shortname. For example, https://www.w3.org/hr-time/all/

12. This version

This is the dated snapshot of the document:

https://www.w3.org/TR/<YYYY>/<status>-<shortname>-<level>-<YYYY><MM><DD>/, the dated snapshot of a specification. This returns the document for a specific <level> published on a specific date, even if it has been outdated.

with:

Should we stop using "This version" and use "This snapshot" instead? This would avoid confusion with levels, etc.

12. Normative references

For the purpose of normative references, you may use the shortname URL, the leveled shortname URL, or a dated URL depending on the nature of the dependency.

Not using the dated URL will increase the likelyhood of getting borken fragments over the years. We should encourage editing tools and editors to maintain an history of fragments to avoid disappointing the readers.