Differentiating geographic region vs specific locations in SpecialAnnouncement

[vholland]

Some of the early markup we are seeing for SpecialAnnouncement has different needs related to locations:

1. The geographic region the announcement relates to. For example, a shelter-in-place order for a city or state.

2. The specific location like a business or testing facility. For example, special opening hours for a supermarket.

3. A geographic region and specific locations. For example, locations where children in a particular city can get free meals.

I propose the following:

• The existing spatialCoverage property for the applicable region if needed.
• Creating a new property announcementLocation for specific sites related to the announcement. The expected type for anouncementLocation is LocalBusiness.

As an example:

{
  "@context": "http://schema.org/",
  "@type": "SpecialAnnouncement",
  "category": "https://www.wikidata.org/wiki/Q81068910",
  "name": "Breakfast and lunch for school children",
  "text": "The city of Boston will provide free breakfast and lunch meals will be provided for school age children attending Boston schools.",
  "datePosted": "2020-03-17",
  "newsUpdatesAndGuidelines": "https://www.bostonpublicschools.org/Page/8098",
  "spatialCoverage": {
    "@type": "City",
    "name": "Boston, MA"
  },
  "announcementLocation": [
    {
      "@type": "School",
      "name": "Charlestown High School",
      "address": {
        "@type": "PostalAddress",
        "streetAddress": "240 Medford Street",
        "addressLocality": "Charlestown",
        "addressRegion": "Massachusetts"
      }
    },
    {
      "@type": "School",
      "name": "East Boston High School",
      "address": {
        "@type": "PostalAddress",
        "streetAddress": "86 White Street",
        "addressLocality": "Charlestown",
        "addressRegion": "Massachusetts"
      }
    }
  ]
}

This would also help prevent people from overloading about with extraneous information.

cc: @danbri @tmarshbing

[danbri]

@vholland this fits with what I've been seeing too.

The use of "about" was in our longstanding tradition of trying to re-use properties where possible. I think in this case it wasn't a terrible starting point, but I prefer the direction you outline here as it captures the common case of there being a general spatial coverage as well as specific locations mentioned in the announcement.

@tmarshbing how does this look to you?

[vholland]

In the interest of expediency, I created PR #2515

[tmarshbing]

I'm not so sure that we need a new property for this. What is the concern with using a combination of spatialCoverage and about instead of spatialCoverage and announcementLocation in the examples above?

More generally, how do we want to specify the location that something applies to? We already have a few *location properties (from/to, home/work, item, ...). I worry that we are going to end up with too many terms for location without people knowing which to use.

[vholland]

I don't think I understand the concern about too many location properties. Do you mean related to SpecialAnnouncement or in general?

My concern is we are changing the definition of about to mean more than "The subject matter of the content." Either authors need to be aware that in the context of SpecialAnnouncement, the about property means the specific location related to the announcement or they stick with the original meaning and it becomes a grab bag of subjects.

[smrgeoinfo]

what about using the existing location and Place?

[danbri]

The problem with "about" is not so much that "subject matter of the content" doesn't cover our case here, but rather that it covers so much else besides. In the way it has been used across schema.org it is an essentially bibliographic notion of "aboutness" or topic, ... as in The Great Gatsby is "about" America, or The Big Lebowski as arguably being "about" the Vietnam War.

Using it here was a quick fix, roughly akin to saying that an e-commerce Product Offer is a page "about" the thing being offered. Sure, it is in some sense true, but there is more to say. For cases where there is a single, obvious, entity of interest we do have a dedicated sub-property https://schema.org/mainEntity but it doesn't seem a good fit in this case where it is not always obvious which entity is the main one.

I'm +1 to having a more geo-flavoured property like announcementLocation so long as we have examples that clarify its role and documentation that makes clear how it relates to any similar terms it could be mistaken for.

[vholland]

@smrgeoinfo I would be fine with schema.org/location except schema.org/Place seems overly broad as the expected type given the use cases listed. I was hoping for something that would guide authors that the property has a narrower scope.

[danbri]

For context, the following relations already exist between CreativeWork and Place:

• spatial (Thing > Property > spatial) "The "spatial" property can be used in cases when more specific properties (e.g. locationCreated, spatialCoverage, contentLocation) are not known to be appropriate."
  • locationCreated (Thing > Property > locationCreated) "The location where the CreativeWork was created, which may not be the same as the location depicted in the CreativeWork."
  • contentLocation (Thing > Property > contentLocation) "The location depicted or described in the content. For example, the location in a photograph or painting."
    • spatialCoverage (Thing > Property > contentLocation > spatialCoverage) The spatialCoverage of a CreativeWork indicates the place(s) which are the focus of the content. It is a subproperty of contentLocation intended primarily for more technical and detailed materials. For example with a Dataset, it indicates areas that the dataset describes: a dataset of New York weather would have spatialCoverage which was the place: the state of New York.

We also (in Pending) have https://schema.org/legislationJurisdiction as a relation between Legislation and places.

[danbri]

Considering the range of the property, it would need to be more than "LocalBusiness" if we are to cover (as we should) announcements from types under Thing > Place > CivicStructure > PlaceOfWorship. So at least adding CivicStructure makes sense.

[tmarshbing]

The argument against about makes sense. Thanks for elaborating the thought process.

I like the idea of using location. This seems like it avoids the ambiguity of about while retaining the simplicity of a more generic property.

[danbri]

I was writing the following when @tmarshbing's comment above appeared. I would be fine with /location too but I do think we could be a bit more specific here, so I will share what I wrote:

I share @tmarshbing 's concern that we avoid having too many uncoordinated terms for places floating around confusing people. I share @vholland's concern that "about" is very broad/vague, and that we are seeing a mix of (one or both of) "geographic region" and "specific location" markup requirements. I think a synthesis is possible.

Here is a revised proposal:

• We add a new property /announcementLocation as a sub-property of /spatialCoverage, attached to /SpecialAnnouncement and with /LocalBusiness and /CivicStructure as expected types.
  • We define it as a sub-property of /spatialCoverage to reflect the fact that the definition of /spatialCoverage ("indicates the place(s) which are the focus of the content.") is still true.
  • Definition "Indicates a specific CivicStructure or LocalBusiness associated with the SpecialAnnouncement. For example, a specific testing facility or business with special opening hours. For a larger geographic region like a quarantine of an entire region, use spatialCoverage."
• I suggest we also update /SpecialAnnouncement to say: "The /about property can be used to indicate entities that are the focus of the announcement. For the common case of locations, use /spatialCoverage for general geographic regions (e.g. ...) , and /announcementLocation to indicate specific locations (e.g. ...). We now recommend /about be used with SpecialAnnouncement only to indicate non-location entities e.g. https://schema.org/RadioStation or https://schema.org/Course that are the focus of the SpecialAnnouncement. Consumers of this markup should be aware that the initial design encouraged the use of /about for locations too.

[tmarshbing]

@danbri , I think your proposal makes sense. Let's move ahead with that so we can get these updates out quickly.

[smrgeoinfo]

workable as a stop gap, but a more 'correct' representation would be something like:
announcement is about event (free lunch being served) (announcements could be about other things-- policy changes, closures, new restrictions, changed restrictions...)
announcement has scope (spatialExtent seems reasonable here)
event has location (the schools)

[danbri]

Ok, thanks everyone. I will merge the PR from @vholland and then tweak it as discussed.

[danbri]

http://webschemas.org/announcementLocation

I still need to tweak /SpecialAnnouncement

[danbri]

We did it! Thanks @vholland for leading on this