Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a schemaVersion property #225

Closed
danbri opened this issue Jan 15, 2015 · 15 comments
Closed

Add a schemaVersion property #225

danbri opened this issue Jan 15, 2015 · 15 comments
Assignees
Labels
guidelines docs examples Work on our supporting materials rather than on schema definitions schema.org vocab General top level tag for issues on the vocabulary

Comments

@danbri
Copy link
Contributor

danbri commented Jan 15, 2015

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

@danbri danbri added schema.org vocab General top level tag for issues on the vocabulary guidelines docs examples Work on our supporting materials rather than on schema definitions needs review labels Jan 15, 2015
@danbri danbri self-assigned this Jan 15, 2015
@akuckartz
Copy link

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

@akuckartz
Copy link

@lanthaler What is your view on this ?

@danbri
Copy link
Contributor Author

danbri commented Jan 16, 2015

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
Copy link
Collaborator

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
Copy link
Contributor Author

danbri commented Jan 19, 2015

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
Copy link

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

@danbri
Copy link
Contributor Author

danbri commented Jan 19, 2015

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 danbri added this to the sdo-stantz release milestone Jan 21, 2015
@danbri
Copy link
Contributor Author

danbri commented Jan 29, 2015

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
Copy link
Contributor Author

danbri commented Apr 16, 2015

@tmarshbing
Copy link

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
Copy link
Contributor

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

@danbri danbri reopened this Apr 17, 2015
@danbri
Copy link
Contributor Author

danbri commented Apr 17, 2015

@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
Copy link
Contributor Author

danbri commented Apr 22, 2015

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.

@danbri danbri closed this as completed Apr 22, 2015
@tmarshbing
Copy link

@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
Copy link
Contributor Author

danbri commented May 15, 2015

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
guidelines docs examples Work on our supporting materials rather than on schema definitions schema.org vocab General top level tag for issues on the vocabulary
Projects
None yet
Development

No branches or pull requests

5 participants