WebSchemas/Singularity
Overview
- This 'schema.org singularity' proposal describes a candidate change to schema.org's property naming design, based on feedback in the WebSchemas group.
- It is not a proposal for substantive new vocabulary. Rather, it suggests minor edits to the spelling of property names to remove plural 's'.
- Tantek has suggested that we use the opportunity of this change to reconsider bringing some property names closer to usage elsewhere.
- The schema.org team agreed to move ahead with this proposal on 2012-03-09, details to be worked out here (see action in tracker)
Background:
- Schema.org has many properties whose spelling ends in a final plural 's'.
- The extension mechanism docs describe a naming convention that "Properties start with a lower case letter and are also camelCase. Properties that can take multiple values (such as parents) are plural and those that can take only a single value (such as dateOfBirth) are singular.
- We have an open issue Determining intended cardinality of schema.org properties, from perspective of those wanting to know property cardinality
- Others have commented from a markup perspective that the plural 's' looks odd in both Microdata and RDFa (less so in HTML5's Microdata JSON syntax).
Problem statement
The initial schema.org practice of writing plurals for property names gives rise to markup such as this:
<div itemscope="" itemtype="http://schema.org/SoftwareApplication">
<p itemprop="operatingSystems">OSX 10.6</p>,
<p itemprop="operatingSystems">Windows 7</p>
...
</div>
Feedback suggests that authors, publishers and developers are surprised that we write 'operatingSystems' here, rather than 'operatingSystem'.
Another example (from Movie):
<div itemscope itemtype="http://schema.org/Movie">
<h1 itemprop="name">Pirates of the Carribean: On Stranger Tides (2011)</h1>
<span itemprop="description">Jack Sparrow and Barbossa embark on a quest to
find the elusive fountain of youth, only to discover that Blackbeard and
his daughter are after it too.</span>
Director:
<div itemprop="director" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Rob Marshall</span>
</div>
Writers:
<div itemprop="author" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Ted Elliott</span>
</div>
<div itemprop="author" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Terry Rossio</span>
</div>
, and 7 more credits
Stars:
<div itemprop="actors" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Johnny Depp</span>,
</div>
<div itemprop="actors" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Penelope Cruz</span>,
</div>
<div itemprop="actors" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Ian McShane</span>
</div>
- Note that we write 'director' (singular), 'author' (singular), 'actors' (plural). Even though we describe here two authors.
- This would look similar in RDFa 1.1 Lite.
- Since each itemprop describes a single actor, we might instead expect (abbreviating the example):
<div itemscope itemtype="http://schema.org/Movie">
<h1 itemprop="name">Pirates of the Carribean: On Stranger Tides (2011)</h1>
...
<div itemprop="actor" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Johnny Depp</span>,
</div>
<div itemprop="actor" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Penelope Cruz</span>,
</div>
<div itemprop="actor" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Ian McShane</span>
</div>
This proposal explores ways of achieving this, while preserving documentation of the earlier form so that search engines can handle all variants.
Core Proposal
- For every property name whose final 's' is due to the earlier practice of writing plurals for property names, create a new property with shorter, singular name
- For each previous property name, agree this it is still acceptable (and somehow document this in schema.org for people and machines); but the singular form is preferred
- TODO: check situation regarding classes/types.
- TODO: check other in-progress draft proposals; they likely use the plural idiom.
- Note that this gives us much more flexibility, as the things we say about property cardinality are note directly encoded in the spelling of properties that are used in millions of Web pages.
Discussion
TODO - link me
Details
The following draft list of properties was initially collected by Lin Clark. We should double-check before submitting any final change request.
(See also discussion of alumniOf vs alumnusOf; are there other non-'s' plurals we're missing?)
ACTION (09-03-2012): Dan to add detail to this list, and check each property carefully. (work-in-progress; first the shortlist, then the property definitions)
Notes:
- in some (how many? one?) case, we end up with a class and property that have same name (event/Event). But we have this already (url/URL). Should note in * the intro somewhere to avoid confusion.
- in many cases, plural form is used in the property definition too; these will need reviewing too.
- we should extract a list of those that were initially singular, in case it is plausible to mark their status in schema instead.
- essence of this issue should be extracted into a WebSchemas/StyleGuide.
Candidate list of additions / changes
The italic' singular term is the intended addition to schema.org.
- actors (on Movie, TVSeries, Episode; value is a Person): actor
- albums (on MusicGroup; value is a MusicAlbum): album
- attendees (on Event; value is a Person, or Organization): attendee
- awards (on CreativeWork, or Person; value is Text): award
- blogPosts (on Blog; value is a BlogPosting): blogPost
- colleagues (on Person; value is a Person): colleague
- contactPoints (on Person or Organization); value is a ContactPoint): contactPoint
- employees (on Organization; value is a Person): employee
- encodings (on CreativeWork; value is an MediaObject): encoding
- episodes (on TVSeries, or TVSeason); value is an TVEpisode: episode
- events (on Place, or Organization; value is an Event): event
- founders (on Organization, value is a Person): founder
- maps (on Place, value is a URL): map
- members (on Organization; value is a Organization or Person): member
- parents (on Person; value is a Person): parent, c.f. HistoricalDataSchema
- performers (on Event; value is a Person or Organization): performer
- photos (on Place; value is a ImageObject or Photograph): photo
- reviews (on Offer, Product, Organization, Place, CreativeWork; value is a Review): review
- seasons (on TVSeries; value is a TVSeason): season
- siblings (on Person; value is a Person): sibling, c.f. HistoricalDataSchema
- significantLinks (on WebPage; value is a URL): significantLink
- subEvents (on Event); value is a Event): subEvent, c.f. EventSchemaUpdate
- tracks (on MusicGroup or MusicPlaylist; value is a MusicRecording): track
Unchanged *-s properties
The following property names end in a final '-s', but are not grammatically plural and are 'unchanged by this proposal. The list is kept here for reference.
educationRequirements (on JobPosting; value is Text): educationRequirementacceptsReservationsfrom FoodEstablishment: Either Yes/No, or a URL at which reservations can be made.benefitsfrom JobPosting: (text) Description of benefits associated with the job.caloriesfrom NutritionInformation: (Energy) The number of caloriesmentionsfrom CreativeWork: Indicates that the CreativeWork contains a reference to, but is not necessarily about a concept. Rationale: 3rd person.numberOfEpisodesfrom TVSeason TVSeries: The number of episodes in this season or series.numberOfPagesfrom Book: The number of pages in the book.numTracksfrom MusicPlaylist: The number of tracks in this album or playlist.openingHoursfrom LocalBusiness: The opening hours for a business. Opening hours can be specified as a weekly time range, starting with days, then times per day.publishingPrinciplesfrom CreativeWork: (URL) Link to page describing the editorial principles of the organization primarily responsible for the creation of the CreativeWork.recipeInstructionsfrom Recipe: (text) The steps to make the dish. Rationale: instructions don't necessarily break down very well in different values, see example.workHoursfrom JobPosting: (text) The typical working hours for this job (e.g. 1st shift, night shift, 8am-5pm).- experienceRequirements (the rest of these lacking the
delmarkup; but also have been checked and aren't grammatically plural in the sense addressed here) - expires
- incentives
- ingredients
- keywords
- offers
- qualifications
- responsibilities
- skills
- specialCommitments
RDFa impact
The schema.org team discussed potential impact of this change on RDFa 1.1, since RDFa has a 'chaining' mechanism. See editor's Working Draft for details.
Summary:
- RDFa 1.1 chaining includes a mechanism that allows a typed relationship to be indicated once, yet apply to the entities described by several sibling subelements.
- This requires use of rel= attribute, rather than the property= mechanism used in the RDFa 1.1 Lite profile.
- RDFa WG members (Manu, Stéphane) helped here, and urged that we adopt the WebSchemas/Singularity design; they didn't see a problem w.r.t. RDFa chaining.
- From 1.1 spec: "in many situations the @property and @rel are interchangeable. This is not true for chaining."
Details follow
In this example, the 'dbp-owl:residence' property has two separate values. This creates two links of type 'dbp-owl:residence'; one to the German_Empire URI, the other to the Switzerland URI. The question is whether there is a strong intuition that a property name like 'residence' here should instead be 'residences'. A strong intuition against 'residence' would be evidence against this proposal.
Nobody felt this was a problem, but we record the examples here for the record.
<div about="http://dbpedia.org/resource/Albert_Einstein" rel="dbp-owl:residence">
<span about="http://dbpedia.org/resource/German_Empire"></span>
<span about="http://dbpedia.org/resource/Switzerland"></span>
</div>
Double-checking by using a real schema.org example, Movie (highlighting lines that indicate the actor(s) relationship):
<div vocab="http://schema.org/" typeof="Movie">
<div property="actors" typeof="Person"><span property="name">Johnny Depp</span>,</div>
<div property="actors" typeof="Person"><span property="name">Penelope Cruz</span>,</div>
<div property="actors" typeof="Person"><span property="name">Ian McShane</span></div>
</div>
Can we adjust this so that it chains? yes:
<div vocab="http://schema.org/" typeof="Movie">
<div rel="actors">
<div typeof="Person"><span property="name">Johnny Depp</span>,</div>
<div typeof="Person"><span property="name">Penelope Cruz</span>,</div>
<div typeof="Person"><span property="name">Ian McShane</span></div>
</div>
</div>
Here's a complete example of 'worst case scenario', using the proposed singular wording ie. "actors" -> "actor":
<html>
<head><title>A movie page</title></head>
<body>
<div vocab="http://schema.org/" typeof="Movie">
<div rel="actor">
<div typeof="Person"><span property="name">Johnny Depp</span>,</div>
<div typeof="Person"><span property="name">Penelope Cruz</span>,</div>
<div typeof="Person"><span property="name">Ian McShane</span></div>
</div>
</div>
</body> </html>
This seems pretty OK, but worth documenting. Note that the use of rel="actor" takes us beyond the RDFa 1.1 Lite simple subset of the language.
Related Work
Follow up (June 29th, 2012)
Some properties were missed during the first pass.
Candidate list of additions / changes
The italic singular term is the intended addition to schema.org.
- ingredients (on Recipe; range is Text) => ingredient
- offers (on CreativeWork, MediaObject, Event, and Product; range is a Offer) => offer
Rationale (sent by Stéphane Corlosquet)
'ingredients' from Recipe ought to be singular since 1) its definition is "An ingredient used in the recipe." and 2) the example shows a list of multiple instances of ingredients. Finally 'ingredient' (singular) is consistent with the property defined in the Google documentation for Rich snippets - Recipes and used in microformats, microdata and RDFa. (I know this is not schema.org, but it will make the migration to schema.org markup easier and less error prone).
'offers' is another one that I think should be singular. It is used in CreativeWork, MediaObject, Event, and Product. Maybe it was meant to be the third person, but still that does not make sense: "Event has an Offer" sounds right, but "Event offers an Offer" does not sound right.