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

Differentiating geographic region vs specific locations in SpecialAnnouncement #2514

Closed
vholland opened this issue Mar 30, 2020 · 16 comments
Closed
Assignees

Comments

@vholland
Copy link
Contributor

@vholland vholland commented Mar 30, 2020

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 danbri self-assigned this Mar 30, 2020
@danbri
Copy link
Contributor

@danbri danbri commented Mar 30, 2020

@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 added a commit to vholland/schemaorg that referenced this issue Mar 30, 2020
@vholland
Copy link
Contributor Author

@vholland vholland commented Mar 30, 2020

In the interest of expediency, I created PR #2515

@tmarshbing
Copy link

@tmarshbing tmarshbing commented Mar 30, 2020

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

@vholland vholland commented Mar 30, 2020

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

@smrgeoinfo smrgeoinfo commented Mar 31, 2020

what about using the existing location and Place?

@danbri
Copy link
Contributor

@danbri danbri commented Mar 31, 2020

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

@vholland vholland commented Mar 31, 2020

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

@danbri danbri commented Mar 31, 2020

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

@danbri danbri commented Mar 31, 2020

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

@tmarshbing tmarshbing commented Mar 31, 2020

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

@danbri danbri commented Mar 31, 2020

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

@tmarshbing tmarshbing commented Mar 31, 2020

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

@smrgeoinfo
Copy link

@smrgeoinfo smrgeoinfo commented Mar 31, 2020

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

@danbri danbri commented Mar 31, 2020

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

danbri pushed a commit that referenced this issue Mar 31, 2020
* Issue #2341: Added SportsTeam to the domain for gender.

* Remove file added to wrong branch.

* Issue #2514: Added announcementLocation and updated examples.
danbri added a commit that referenced this issue Mar 31, 2020
@danbri
Copy link
Contributor

@danbri danbri commented Mar 31, 2020

http://webschemas.org/announcementLocation

I still need to tweak /SpecialAnnouncement

danbri added a commit that referenced this issue Apr 1, 2020
this is a new property /announcementLocation and
clarification on when to use it vs /spatialCoverage.
@danbri
Copy link
Contributor

@danbri danbri commented Apr 7, 2020

We did it! Thanks @vholland for leading on this

@danbri danbri closed this as completed Apr 7, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants