Work-in-progress mechanisms: webschemas and the ‘pending’ area

Introduction

This page explains two “how we work” practical mechanisms: webschemas.org and the “pending” section.

Both were adopted in 2016 as part of our efforts to work more transparently and more clearly in public view, making proposals and changes more accessible for collaborators who are not necessarily “project insiders” or computer programmers. The process is now more transparent, but also a little more complex.

If you are in a hurry, all you need to know is that the webschemas site is the in-progress development draft of the schema.org site, and that both sites have a “pending” section where proposals for new vocabulary can be found. If you want the details, read on…

In the early days of schema.org, here is how things looked to non-insiders:

1. mysterious stuff happened, with some email discussions.
2. a new official release was officially released at schema.org.

We have gradually been improving on this. Schema.org has a more explicit notion of “work in progress” now – you can see  everything up to the minute as it is being created, refined and changed. Since 2015 this has been done via the GitHub system, however Git is a complex technical system created for programmers to manage software. We wanted to be more inclusive, which meant finding a way to share in-progress designs in an easy Web-based way.
Schema.org vs webschemas.org and the “pending” section(s) explained

There are two sites, the “official” site based around the schema.org domain, but now also a “work in progress” site based at webschemas.org. The official site is updated to a new numbered release (e.g. 3.0, and 3.1 recently, we’re working towards 3.2) every few weeks.

The update happens with an official sign-off from all the members of the project steering group.

These updates are prepared in full public view using the webschemas.org drafting site, which changes much faster (often several times a day). Unlike the official schema.org, the contents of webschemas.org are only approved by the project webmaster (currently Dan Brickley). It may contain numerous bugfixes that are not yet officially released, but it may also contain bugs, inconsistencies, and under-reviewed designs that do not have the support of the wider community or the steering group.

That explains the role of “schema.org” (official, updates approved by steering group) versus “webschemas.org” (work in progress, updates approved by project’s webmaster). To recap:

• You can see the official schema.org releases at
  http://schema.org/docs/releases.html (updates every few weeks)
• You can see the work-in-progress “webmaster’s best effort” draft of the next release summarized at http://webschemas.org/docs/releases.html (updates every few hours)

Extensions and sub-sections

Both of these sites are organized around schema.org’s dictionary of terms, mainly what we call “types” e.g. “Person“, “Event“, “CreativeWork“, and what we call “properties”, e.g. “alumni“, “priceCurrency“, “startDate“. Each term is based in one section of the site. We use internet subdomains to organize these sections, except for the core which is simply at schema.org. The site sections are “core” (for the basic heart of the project), “bib” (bibliographic, book-centric), “health-lifesci” (medical etc.), “auto”  (cars, vehicles, automobiles, etc.). There is also a section called “pending” with a slightly special status. All of these sections are just parts of our site, and have an officially released version on schema.org, as well as an up-to-the-minute (but more unstable) draft working version on webschemas.org too.

The Pending section is the place where we put relatively self-contained new terms for review and development. It is important to remember that many changes are also made to schema.org’s existing core and extension-based vocabulary: “pending” is just for new ideas. For example, if we are exploring a change to the definition of “Person” you would find draft new materials at http://webschemas.org/Person.

As I write this on 2016-08-19, if you look at http://pending.schema.org/Course
you can see the last official snapshot of pending from our 3.1 release earlier in August
(which is now a bit obsoleted by subsequent progress). Whereas if you look at
http://pending.webschemas.org/Course you can see today’s most recent
draft of the next release (and which may have changed by the time you read this).
As explained above, the webschemas version may not be complete, agreed, well designed or properly checked or reviewed. But it should reflect the latest rough consensus from community discussions. We may well change the webschemas version again slightly tomorrow; this is our form of “working in public”, and working as a distributed, international collaboration.

Broadly, webschemas.org is for the relatively small community of people actively collaborating on schema designs, whereas schema.org is for the entire world. There is a slightly out of date (but somewhat reviewed) version of pending in the official schema.org. If you are considering experimentally implementing these, you will probably want to glance at the corresponding webschemas page to see if things are actively changing. We anticipate that some proposals may sit relatively unchanged for weeks, months or longer as “pending” proposals while we gather implementor feedback; others may move swiftly into schema.org’s core within days or weeks.

Future developments

In future the project may start pushing out updates to all of its extension sections (bib, health-lifesci etc.) much more regularly. Whatever we do for those we’ll probably do for the pending section too. It is admittedly confusing to have two pending sections, we at least need to label them as “the one that has carefully composed definitions but might be out of date” (i.e. pending.schema.org) vs “the one that is up to date but may have bugs, mistakes, inconsistencies, or lack wider consensus“(i.e. pending.webschemas.org).

Author: Dan Brickley, schema.org Community Group chair, 2016-08-19.