Add a schemaVersion property

[danbri]

Proposal:
"The schemaVersion property is a relation between a CreativeWork (that typically contains structured data) and a specific version of a schema used in that document. The value can either be a version identifier string e.g. 1.2 or a URL to a (typically unchanging) snapshot of the document."

This is part of a larger proposal - see @danbri 's mail to public vocabs 2014-01-29.

This can be used by publishers to clarify the version of a (potentially changing) vocabulary. While it is designed for use with schema.org, it is also applicable to other "living standard" vocabularies such as Dublin Core and FOAF which evolve without changing their main namespace URI. URL valued properties are recommended in cases where a document uses multiple vocabularies, to avoid ambiguity.

For example,

    <div itemscope itemid="" itemtype="http://schema.org/CreativeWork">
        <meta itemprop="schemaVersion" content="http://schema.org/versions/1.92/"/>
    </div>

    <div itemscope itemtype="http://schema.org/Person">
      <span itemprop="name">Fred Bloggs</span>
    </div>

... could be used to indicate that the definitions from v.19

[akuckartz]

Is that really what is needed? Several vocabulary communities are discussing how versioning can be avoided.

[akuckartz]

@lanthaler What is your view on this ?

[danbri]

It's a hybrid approach, the core is an unversioned 'living standard' approach but with archived snapshots of releases. Some audiences (e.g. other standards efforts, or in conservative/cautious environments) are uncomfortable making unconstrained reference to works-in-progress, so this proposed property gives a mechanism that they can use without creating a proliferation of versioned type/property URIs. Metadata about stability etc is better kept out of band than in URLs - this was learned clearly in the Dublin Core and FOAF projects too.

Anyway I'm working on a writeup which I'll share here before anything is finalised...

[lanthaler]

I think this a good compromise and agree with @danbri that the URLs should definitely stay version-less. I wonder if it wouldn’t make more sense to keep this more generic and just call it “version” instead of “schemaVersion”. Using “schemaVersion” to specify a “version of a schema used in that document” gives you too little information if you don't know what schema was used. Furthermore, what does schemaVersion mean on a schema/vocabulary itself? Is it the schema that was used to create this schema/vocabulary? So my proposal would be to introduce a generic property “version” and perhaps a separate property “schema”. Then it is possible to express things such as

{
  "@type": "CreativeWork",
  "schema" : {
    "@id": "....",
    "version": "2.3.1"
  }
}

[danbri]

Thanks. Calling it schemaVersion allows us to be more focussed and explicit
in documentation. Otherwise we end up saying something pretty woolly like
"the version number of this item" rather than talking about vocabularies
etc.

On 18 January 2015 at 20:48, Markus Lanthaler notifications@github.com
wrote:

I think this a good compromise and agree with @danbri that the URLs should
definitely stay version-less. I wonder if it wouldn’t make more sense to
keep this more generic and just call it “version” instead of
“schemaVersion”. Using “schemaVersion” to specify a “version of a schema
used in that document” gives you too little information if you don't know
what schema was used. Furthermore, what does schemaVersion mean on a
schema/vocabulary itself? Is it the schema that was used to create this
schema/vocabulary? So my proposal would be to introduce a generic property
“version” and perhaps a separate property “schema”. Then it is possible to
express things such as

{
"@type": "CreativeWork",
"schema" : {
"@id": "....",
"version": "2.3.1"
}
}

—
Reply to this email directly or view it on GitHub
#225 (comment).

[akuckartz]

The term vocabularyVersion might be a more easily understandable and reusable alternative to schemaVersion.

[danbri]

The word "schema" pretty much comes with the territory around here!

FWIW at W3C back in 1999/2000 we considered renaming RDF Schema to avoid
that word, mostly due to clash of expecations with the XML community who
had begun work on XML Schema (see http://www.w3.org/TR/schema-arch etc.).
So for a while RDFS was entitled "RDF Vocabulary Description Language 1.0:
RDF Schema". But RDFS it remained, and here we are at schema.org.

The word "vocabulary" is a little broader than the RDF usage of "schema",
and encompasses things like SKOS thesauri. But both are pretty vague terms.
And "ontology" of course is lurking nearby.

On 19 January 2015 at 11:59, Andreas Kuckartz notifications@github.com
wrote:

The term vocabularyVersion might be a more easily understandable and
reusable alternative to schemaVersion.

—
Reply to this email directly or view it on GitHub
#225 (comment).

[danbri]

I've just circulated a larger proposal on schema.org versioning that motivated this specific proposal.

https://lists.w3.org/Archives/Public/public-vocabs/2015Jan/0120.html (also linked from description above).

[danbri]

http://sdo-gozer.appspot.com/schemaVersion

[tmarshbing]

I somehow missed that schemaVersion is only on CreativeWork. @danbri, why isn't it more fundamental, so that I can, for example, define the schema version that was used for a Place, Product, or any other Thing?

Also, the suggested URL in the description (http://schema.org/docs/releases.html#v1.91) is different than the previous suggestions above of something like http://schema.org/versions/1.91/. The latter seems more suited to the use cases of referring to a specific term within the version (e.g., http://schema.org/versions/1.92/Person from https://lists.w3.org/Archives/Public/public-vocabs/2015Jan/0120.html).

[thadguidry]

@danbri Extension mechanism should also be allowed to use schemaVersion (if it is not already) and document in Extension proposal.

[danbri]

@tmarshbing it is on CreativeWork as namespace versions are characteristics of documents, rather than the entities described in those documents. It operates at a different level (and granularity). As for the URLs, yes I gave an example that worked now, and which ought to be updated once we get /versions/{foo} working.

[danbri]

I've opened a more implementation-oriented issue w.r.t. /versions/ #441 which includes a note to tweak the example URL here once that is completed. I believe the basic vocabulary addition is handled adequately for now, so will close out this issue in favour of #441. @tmarshbing is that ok for you? this is mostly an admin detail since both are w.r.t. the same release.

[tmarshbing]

@danbri Yes, this now makes sense to me, but I think we could do with an example somewhere that uses schemaVersion. The only examples I've seen so far are in https://lists.w3.org/Archives/Public/public-vocabs/2015Jan/0120.html, which are in 2c, talking about attaching versions to individual terms, which is what threw me off in the first place.

[danbri]

http://schema.org/schemaVersion now uses http://schema.org/version/2.0/ in the example given within the description. A markup example would be nice too, but the issue here is closed.