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.

Sign up for GitHub

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

Jump to bottom

A proposal for two new types: Guide & Recommendation#2405

Closed
gmackenz opened this issue Nov 19, 2019 · 8 comments
Closed

A proposal for two new types: Guide & Recommendation #2405

gmackenz opened this issue Nov 19, 2019 · 8 comments

Comments

@gmackenz
Copy link
Contributor

gmackenz commented Nov 19, 2019 •
edited

Guide, a new subtype of CreativeWork
Thing > CreativeWork > Guide

This is allow us to markup pages that are Guide pages in content, that recommend specific products or services, or aspects of a thing for a user to consider.

A Guide may represent a Buying Guide (example) and detail aspects of products or services for a user to consider.

A Guide may represent a Product Guide (example) and recommend specific products or services.

A Guide may represent a Ranked List (example) and recommend specific products or services with ranks.

Relevant existing properties most likely to be used with Guide:

about
What this guide is about across all of its reviews/recommendations - hiking boots, TVs, etc.
hasPart
hasPart would contain multiple Reviews or Recommendations that are part of this guide.
reviewAspect
(Add this property to Guide and propose expanding the expected types of reviewAspect to include PropertyValue as well as the existing Text)
A common aspect shared across all sub-Reviews and Recommendations. For example: all recommendations (“Budget Pick”, “Top Pick”, “Best Value” ), all look at “price” and “quality” as aspects of the review.

=====================================================================

Recommendation, a subtype of Review
Thing > CreativeWork > Review > Recommendation

Recommendations are Reviews that suggest or propose something as the best option or best course of action.

Recommendations may be for products or services, or other concrete things, as in the case of a ranked list or product guide. A Guide may list multiple recommendations for different categories. For example, in a Guide about which TVs to buy, the author may have several Recommendations.

Relevant existing properties:

category
Each Recommendation may set the category property to be the type of Recommendation—for example ““Best Value”, “Budget Pick”, “Best for Families”, “Best for 2019”.
@gmackenz
Copy link
Contributor Author

Examples for above:

BuyingGuide - How to Shop for Hiking Boots
This is an example of a buying guide based on the site
https://www.rei.com/learn/expert-advice/hiking-boots.html
It tells users about the different aspects of hiking boots to consider when determining which one to buy.
Version 1, very simple:

{
  "@context": "schema.org",
  "@type": "Guide",
  "about": "Hiking Boots",
  "name": "How to Choose Hiking Boots",
  "text": "Choosing the right hiking boots is a matchmaking process. Your dream hiking boots need to sync with how and where you hike. ...",
  "reviewAspect": [
    "Types",
    "Components",
    "Fit"  
  ],
}

Version 2, nested Guides:

{
  "@context": "schema.org",
  "@type": "Guide",
  "about": "Hiking Boots",
  "name": "How to Choose Hiking Boots",
  "text": "Choosing the right hiking boots is a matchmaking process. Your dream hiking boots need to sync with how and where you hike. ...",
  "reviewAspect": [
    "Types",
    "Components",
    "Fit"  
  ],
  "hasPart": [
    {
      "@type": "Guide",
      "about": "Types"
      "name": "Types of Hiking Boots"
      "reviewAspect": [
       "Hiking shoes",
       "Day hiking boots",
       "Backpacking boots"  
     ],
     "Text": "Hiking shoes: Low-cut models with flexible midsoles are excellent for day hiking. Some ultralight backpackers may even choose trail-running shoes for long-distance journeys…"
    },
    {
      "@type": "Guide",
      "about": "Components"
      "name": "Hiking Boot Components"
      "reviewAspect": [
       "Hiking Boot Uppers",
       "Hiking Boot Midsoles",
       "Hiking Boot Internal Support",
       "Hiking Boot Outsoles",
       "Crampon Compatibility",  
     ],
     "Text": "Hiking Boot Uppers
Materials impact a boot's weight, breathability, durability and water resistance.
Full-grain leather: Full-grain leather offers..."
    },
    {
      "@type": "Guide",
      "about": "Fit"
      "name": "Hiking Boot Fit"
     "Text": "Hiking boots should fit snug everywhere, tight nowhere and offer room to wiggle your toes. Try them on at the end of the day (after feet swell) and with the socks you plan to wear.
Know your size. It's best to have your foot's length, width and arch length measured on a specially calibrated fit .."
    },
  ]
}

Product Guide - Best TVs
An example of a product guide based on:
https://thewirecutter.com/reviews/best-tv/
This guide recommends TVs to buyers with different needs- they pick a best overall, a budget pick, etc.

{
  "@context": "schema.org",
  "@type": "Guide",
  "name": "The Best TVs",
  "category": "TVs",
  "hasPart": [
    {
      "@type": "Recommendation",
      "category": "Our pick",
      "name": "The best overall LCD/LED TV",
      "itemReviewed": {
        "@type": "Product",
        "name": "Vizio P-Series F1"  
        "offers": {
           "@type": "Offer",
           "price": "$750",
           "url": "https://wclink.co/link/27778/144709/4/80651?merchant=Best%20Buy"
         }
       },
      "reviewAspect": [
        {
          "@type": "PropertyValue",
          "name": "Available sizes",
          "value": "55, 65, 77 inches",
        },
        {
          "@type": "PropertyValue",
          "name": "HDMI ports",
          "value": "four",
        },
        {
          "@type": "PropertyValue",
          "name": "Smart OS",
          "value": "SmartCast OS",
        }
      ],
      "reviewBody": "The 2018 Vizio P-Series F1 offers everything you need to enjoy a high-end TV experience today. The TV uses full-array local dimming, which produces superior contrast ratios for SD and HD content but also provides the best HDR experience on an LCD TV. The LCD panel has a native 120 Hz refresh ..."
    },
    {
      "@type": "Recommendation",
      "category": "Best budget 4K TV",
      "name": "If you can't spend as much: Best budget 4K TV",
      "itemReviewed": {
        "@type": "Product",
        "name": "TCL 55S517"  
        "offers": {
           "@type": "Offer",
           "Price": "$606",
           "url": "https://wclink.co/link/30228/151537/4/88249?merchant=Walmart"
         }
       },
      "reviewAspect": [
        {
          "@type": "PropertyValue",
          "name": "Available sizes",
          "value": "43, 49, 55, and 65 inches",
        },
        {
          "@type": "PropertyValue",
          "name": "HDMI ports",
          "value": "three",
        },
        {
          "@type": "PropertyValue",
          "Name": "Smart OS",
         "Value": "Roku",
        }
      ],
      "reviewBody": "The TCL 5-Series TV offers image quality on a par with much more expensive TVs and it offers media-streaming services and some extra features that costlier TVs don't have. We still think ..."
    },
    ]
}

Ranked List Guide - Best Cars
A (partial) example of a ranked list guide based on:
https://cars.usnews.com/cars-trucks/best-midsize-cars-for-the-money

This guide is focused on a single categorization, overall best midsize cars, and ranks them within that list.

{
  "@context": "schema.org",
  "@type": "Guide",
  "category": "Best Midsize Cars",
  "name": "12 Best Midsize Cars for the Money in 2019",
  "text": "While manufacturers scramble for a piece of the growing SUV market, many well-known midsize cars continue to offer a lot of features for the money. Most of the twelve models on this list are very familiar to shoppers since they've been around for years. But many of these models have seen recent upgrades that brought advanced safety and infotainment technologies to these well-known names..."
   "hasPart": [
    {
      "@type": "Recommendation",
      "position": 12,
      "itemReviewed": {
        "@type": "Product",
        "name": "2019 Buick Regal",
        "url": "https://cars.usnews.com/cars-trucks/buick/regal/2019"
      },
      "reviewAspect": [
        {
          "@type": "PropertyValue",
          "name": "price",
          "value": "$25,070"
        },
      ],
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": 7.6,
        "bestRating": 10,
        "worstRating": 1,
      }
      "reviewBody": "The 2019 Buick Regal has one of the highest price tags on this list, and its cost of ownership continues to be high. It has the highest fuel cost in the ..."
    },
    {
      "@type": "Recommendation",
      "type": "Best for the Money",
      "position": 11,
      "itemReviewed": {
        "@type": "Product",
        "name": "2019 Ford Fusion",
        "url": "https://cars.usnews.com/cars-trucks/ford/fusion/2019"
      },
      "reviewAspect": [
        {
          "@type": "PropertyValue",
          "name": "price",
          "value": "$22,840"
        },
      ],
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": 8.2,
        "bestRating": 10,
        "worstRating": 1,
      }
      "reviewBody": "It's interesting to note that the 2019 Ford Fusion with its gasoline engine has a higher fuel cost than almost all of its competitors. There are plug-in and hybrid versions of the Fusion that do better in this regard. The hybrid in particular..."
    },  ]
}

@gmackenz gmackenz mentioned this issue Dec 11, 2019
Merged
@gmackenz gmackenz mentioned this issue Dec 21, 2019
Closed
16 tasks
danbri added a commit that referenced this issue Jan 2, 2020
@danbri
removed duplicate labels
6f65683 
/cc @gmackenz #2405
@RichardWallis
Copy link
Contributor

Not so sure that the generically useful term Guide should be narrowly used for purchase/buying guides only.

What about travel guides (a set of travel instructions), tour guides (person that guides you round a tourist destination), mountain guides (person that directs you up a mountain), restaurant guides (recommended restaurants), usage guides (the best way to use or operate a tool or product), etc.?

@gmackenz
Copy link
Contributor Author

gmackenz commented Jan 8, 2020 •
edited

So do you prefer a general type of Guide and then specific sub-Guide-types of TravelGuide, BuyingGuide, ProductGuide, etc? Or just the latter subtypes as subtypes of CreativeWork?

@RichardWallis
Copy link
Contributor

I don't think a general Guide type (with sub types) would be that helpful as the general word has subtly differing meanings in various domains.

I was thinking along the lines of just creating ProductGuide.

@kaylareedhanson
Copy link

I think the Guide spec as-is is reasonable for some other types of Guides.

From your examples (travel guides, tour guides, mountain guides, restaurant guides, usage guides), I think the big differentiation is whether or not the Guide is a piece of content (eg derives from CreativeWork) or whether the Guide is a Person/Occupation. I think as a CreativeWork sub type category that this is general enough. For Person or Occupation definitions, it's clearly not the right schema.

If that naming collision is not ok, renaming Guide to BuyingGuide (you could imagine a guide that recommended http://schema.org/Service s instead of Product s) seems like a fine way to move forward for the proposed product/buying guide intent.

Examples of other non-Product CreativeWork guides in line with previous examples:

Restaurant Guide:
https://ny.eater.com/maps/best-new-york-restaurants-38-map

{
  "@context": "schema.org",
  "@type": "Guide",
  "category": "Restaurants",
  "name": "The 38 Essential Restaurants in New York City, Winter 2020",
  "text": "Welcome to the Eater 38, an elite collection of restaurants from across the city that define New York City’s dining scene right now..."
   "hasPart": [
    {
      "@type": "Recommendation",
      "position": 1,
      "itemReviewed": {
        "@type": "Restaurant",
        "name": "Liebman’s Deli",
        "url": "http://liebmansdeli.com/"
      },
      "reviewAspect": [
        "overstuffed sandwiches",
        "chip-like fries and gravy"
      ],
      "reviewBody": "Jewish deli in its most nostalgic form can be found at Liebman’s in Riverdale, a small and diner-like institution ..."
    },
    // more items from the list...
    ]
}

Travel Guide
https://theblondeabroad.com/top-things-to-do-in-new-york-at-christmas/

{
  "@context": "schema.org",
  "@type": "Guide",
  "category": "Travel",
  "name": "Top Things to Do in New York at Christmas",
  "text": "New York City is a truly magical place to spend the holidays. With giant Christmas trees, ice skating rinks, Broadway shows, and more, it’s a true winter wonderland. If you’re not sure what to do this holiday season..."
   "hasPart": [
    {
      "@type": "Recommendation",
      "itemReviewed": {
        "@type": "Place",
        "name": "Bryant Park Winter Village",
        "url": "http://bryantpark.org/amenities/bank-of-america-winter-village-at-bryant-park"
      },
      "reviewAspect": [
        "ice skating"
      ],
      "reviewBody": "Bryant Park is known for holding events. In fact, they hold over 1,000 free activities, classes, and events a year. Winter Village has ice skating, a rinkside bar, a food hall, and holiday shops..."
    },
    // more items from the list...
    ]
}

What do you think?

@RichardWallis
Copy link
Contributor

Implemented in PR #2426

@xuanthang2102
Copy link

Travel Guide
https://netdepdalat.com/

@podrabinek
Copy link

Travel guide scheme - https://whythisplace.com/things-to-do-in-madrid/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests

5 participants
@kaylareedhanson @podrabinek @gmackenz @RichardWallis @xuanthang2102