Support Certification rating with scale, e.g. EPREL ratings: B(A to G)

[duckladydinh]

Problem

Certification has been published (requested in #3230). However, there isn't yet an attribute in the schema to represent the rating of a certification. For example:

• EPREL certifications would have ratings in the form of Rating(Best to Worst), e.g. B(A to G), C(A to G)...
• EPEAT, ENERGY STAR certifications would have textual ratings, e.g. Gold, Silver, Bronze...
• Vehicle certifications in France, Germany... would also have textual rating such as A, B, C...

Currently, we can't find a suitable attribute on Certification to best represent it. According to the name, we think that Certification::hasMeasurement may look like a good attribute to represent the rating BUT... it doesn't support rating with a textual scale like EPREL because it is a QuantitativeValue with min/max values being Number rather than Text.

Proposal

Therefore, we would like to propose make Certification::hasMeasurement a Rating instead of a QuantitativeValue whose best/worst value attributes can be both Text. Or maybe if you know that this property is used for something else, we can consider adding a completely new rating property to it.

Thanks a lot

[mfhepp]

If that change is needed, please do not remove QuantitativeValue, but rather add an additional type to the range of hasMeasurement. I would argue that the majority of measurements in other usages of this property are quantitative in nature.

And I would also recommend using QualitativeValue rather than Rating. Or all three.

[MatthiasWiesmann]

At least for EPREL, I would recommend that the URL (the one present in the QR-code) is used (maybe along the rating, but then the problem of inconsistencies arises).

[MichaelLinck]

If that change is needed, please do not remove QuantitativeValue, but rather add an additional type to the range of hasMeasurement. I would argue that the majority of measurements in other usages of this property are quantitative in nature.

And I would also recommend using QualitativeValue rather than Rating. Or all three.

I wouldn't expect many or any of the values to be quantitative. Can you name examples where you would expect the value of a certification to be quantitative?

Energy Star - no value or value is either empty or "Most Efficient"
European Energy Label - Value is a string in range A - G
Cradle to Cradle - Value is a string in the range Platinum - Bronze
EPEAT - Value is in the range Gold - Bronze
GOTS - No Value
FSC - Value is one of [100%, Mix, Recycled]

What does a Quantitative Value add aside from confusion about which one to use?

[MichaelLinck]

At least for EPREL, I would recommend that the URL (the one present in the QR-code) is used (maybe along the rating, but then the problem of inconsistencies arises).

I kind of figured that that would just be the "url" that all "things" have. I'd expect the URL of a certification to be its QR Code when applicable.

[mfhepp]

What does a Quantitative Value add aside from confusion about which one to use?

In Schema.org, we have a global scope for properties, which means that schema:hasMeasurement has the same semantics, i.e. the same range, domain, and textual definition, no matter whether it is applied to schema:Certification as in this proposal, or any other type to which it has been in use for a long time.

You cannot change the semantics of a global property just for a subset of types or new usages.

Hence, you could have to chose e.g. one of the following alternatives:

1. Define a new property like schema:certificationRating, similar to schema:contentRating or schema:starRating with a range of your choice (e.g. schema:Rating).
2. Reuse schema:hasMeasurement and add either schema:QualitativeValue, schema:Rating, or both to its range.
3. Same like option 2, but using a creating a sub-property of schema:hasMeasurement like schema:certificationRating and adding schema:Rating to the range of this new property.

[MichaelLinck]

3. ame like option 2,

I got your points about not changing the name of any fields or violating schema.org semantics and we are not proposing such a change. My question was:
Can you name an example where a QuantitativeValue actually has any useful meaning w.r.t. a Certification?
I can't think of one, so I think even having it there only causes confusion so we propose to remove it - and thus remove "hasMeasurement" - in order to avoid confusing people with what we mean by a measurements in the context of a certification. (if the certified thing has measurements, they can always be properties of that thing)

QualitativeValue doesn't seem particularly useful because it doesn't capture the essence of most certifications which are to define a range (generally non-numerical) and a value that falls somewhere within that range to indicate if the certified thing meets a high bar or not.

End Result: I would go with your option 1: a new CertificationRating type and a corresponding property "certificationRating" on Certification.

The inherited rating types "AggregateRating" and "ContentRating" Seem pretty clearly unintentional artifacts, rather than purposeful inclusions.

[mfhepp]

3. ame like option 2,

I got your points about not changing the name of any fields or violating schema.org semantics and we are not proposing such a change. My question was: Can you name an example where a QuantitativeValue actually has any useful meaning w.r.t. a Certification?

That one is easy: Think of certifications that contain (1) the information that the product passes the requirements and (2) the exact measurement or characteristic, e.g. in g CO2 per 100 km, the uptime in any SLA standard, the energy consumption of a building according to the German Energieausweis, which communicates (1) a qualitative rating value and (2) the exact value in kwh/m^2.

But my point was a different one: If you want to use the existing schema:hasMeasurement property for your purpose/proposal, then you must **not change the range of that property; you could only expand it to include additional types.

The example in the current version shows how to use existing, authoritative URIs for standardized certifications, like so

  "hasCertification": {
    "@type": "Certification",
    "@id": "https://eprel.ec.europa.eu/qr/1779994",
    "url": "https://eprel.ec.europa.eu/screen/product/dishwashers2019/1779994"
  },

You could use several existing properties for achieving what you seem to aim at:

• https://schema.org/identifier (maybe in combination with https://schema.org/PropertyValue)
• https://schema.org/name
• https://schema.org/sameAs

I can't think of one, so I think even having it there only causes confusion so we
propose to remove it - and thus remove "hasMeasurement" - in order to avoid
confusing people with what we mean by a measurements in the context of a
certification. (if the certified thing has measurements, they can always be
properties of that thing).

I strongly oppose removing schema:hasMeasurement from certification, as there are several use-cases in the automotive and the housing industry in which you will want to indicate (1) that you meet a category of certification (like "A+") and with which actual value (like "39.45 Goblings per light-year").

End Result: I would go with your option 1: a new CertificationRating type and a corresponding property "certificationRating" on Certification.

While this is a possible approach, it is pretty costly in terms of added vocabulary size. In general, we try to reuse existing types and properties in schema.org when this is feasible, and I think there are better ways of modeling what you seem to need.

By the way, did you have a detailed look at the examples given at https://schema.org/Certification? There are quite some.

Here are a few alternative routes to consider (just sketches, may not be 100% valid as given):

Proposal 1: Using schema:name, schema:sameAs´, and schema:url`, requires no change to the vocabulary, like so:

{
    "@context": "https://schema.org/",
    "@type": "Product",
    "name": "Water heater",
    "description": "Large capacity water heater"
    },
    "hasCertification": {
      "@type": "Certification",
      "name": "A+",
      "sameAs": "https://id.acme.com/level_a_plus",
      "url": "https://docs.acme.com/level_a_plus_explained",
      "hasMeasurement": {
        "@type": "QuantitativeValue",
        "schema:name": "CO2e",
        "value": 0.00001,
        "unitCode": "KGM"
    },

For schema:sameAs, one can use authoritative identifiers (e.g. URNs, Wikidata, GS1 URIs), for schema:url the URLs of human-readable definitions.

The use of @id in some example indicates that the value of this certification is exactly the one standard rating; as soon as you add meta-data like measurements, it is better to use schema:sameAs, as one would otherwise collate all related data.

Proposal 2: Using schema:value on add schema:Certification (very clean, minor change to the vocabulary, intuitive name value:

Add schema:Certification to the domain of value and tweak the text from *The value of a QuantitativeValue (including Observation) or property value node. * to The value of a QuantitativeValue (including Observation), Certification, or property value node.

Proposal 3: Make schema:Certification a subtype of schema:PropertyValue (pretty clean, you get all the flexibility from the property-value mechanism and keep the specificity of the Certification type (i.e. you know that it is a certification. )

This is actually my favorite.

The inherited rating types "AggregateRating" and "ContentRating" Seem pretty clearly unintentional artifacts, rather than purposeful inclusions.

I think this assessment is based on a misunderstanding of some underlying design decisions in schema.org: Due to the type hierarchy and global property scopes, it will happen that properties that are not commonly used on more specific types will be shown as valid (like "volcanoes can have fax numbers"). There is currently no mechanism to indivate "recommended" properties.

[MichaelLinck]

I appreciate your responsiveness and discussion, but worry that you're erring on the side of assuming that I don't understand things that I actually understand quite while from my experience working with schema.org in a crawling context and on certifications related topics in particular.

Before we get further into this, I should maybe point out that I have worked on this schema together with Matthias Wiesmann from the start, and introduced the Merchant Center feedspec version for it. Also that we actively leverage this version. I'm not speaking on this topic with a lack of experience.

Also, I'm working with the creator of schema.org - Guha - on how to shape this attribute so that it best fits the open source/data commons usecases. I will address your points in detail but I ask that you also read my answers as clearly as possible.

3. ame like option 2,

I got your points about not changing the name of any fields or violating schema.org semantics and we are not proposing such a change. My question was: Can you name an example where a QuantitativeValue actually has any useful meaning w.r.t. a Certification?

That one is easy: Think of certifications that contain (1) the information that the product passes the requirements and (2) the exact measurement or characteristic, e.g. in g CO2 per 100 km, the uptime in any SLA standard, the energy consumption of a building according to the German Energieausweis, which communicates (1) a qualitative rating value and (2) the exact value in kwh/m^2.

I see, so if a given specific attribute of the thing being certified is the one most relevant to the certificate, you would include it here (in addition to it being an attribute of the thing already). I can see that that could be feasible on some cases, though it's less likely to look that way in practice. Usually you find that detail after you follow the link from the certification attribute to the certificate, where you can find additional information about the product being certified. In that case, you would hope to see schema.org for the product on the certification body's website and you can treat all the attributes that you find there as authoritative.

But my point was a different one: If you want to use the existing schema:hasMeasurement property for your purpose/proposal, then you must **not change the range of that property; you could only expand it to include additional types.

Yep, totally agreed.

The example in the current version shows how to use existing, authoritative URIs for standardized certifications, like so

  "hasCertification": {
    "@type": "Certification",
    "@id": "https://eprel.ec.europa.eu/qr/1779994",
    "url": "https://eprel.ec.europa.eu/screen/product/dishwashers2019/1779994"
  },

Yes, adding a rating or certificationRating attribute would be really helpful so that it becomes

 "hasCertification": {
   "@type": "Certification",
   "@id": "https://eprel.ec.europa.eu/qr/1779994",
   "@[certification]Rating":  {
      "@bestRating": "A"
      "@ratingValue": "B"
      "@ratingWorstRating": "G"
   }
   "url": "https://eprel.ec.europa.eu/screen/product/dishwashers2019/1779994"
 },

You could use several existing properties for achieving what you seem to aim at:

• https://schema.org/identifier (maybe in combination with https://schema.org/PropertyValue)
• https://schema.org/name
• https://schema.org/sameAs

I can't think of one, so I think even having it there only causes confusion so we
propose to remove it - and thus remove "hasMeasurement" - in order to avoid
confusing people with what we mean by a measurements in the context of a
certification. (if the certified thing has measurements, they can always be
properties of that thing).

I strongly oppose removing schema:hasMeasurement from certification, as there are several use-cases in the automotive and the housing industry in which you will want to indicate (1) that you meet a category of certification (like "A+") and with which actual value (like "39.45 Goblings per light-year").

Theoretically, sure, but in practice the website that contains the Thing itself, the one that has the certification, probably doesn't include those values. Instead you'd find them on the certification body's website where the "Thing" is listed again with only the values that the certification body cares about.

End Result: I would go with your option 1: a new CertificationRating type and a corresponding property "certificationRating" on Certification.

While this is a possible approach, it is pretty costly in terms of added vocabulary size. In general, we try to reuse existing types and properties in schema.org when this is feasible, and I think there are better ways of modeling what you seem to need.

But it would just inherit from Rating, same as "ContentRating." It wouldn't introduce any new attributes.

Of course, we could just apply Rating directly and put it as a Rating property on the Certification. The only reason to introduce a "CertificationRating" type would be some clarity of the usecase but the CertificationRating doesn't really need any additional attributes besides what's already on the rating.

By the way, did you have a detailed look at the examples given at https://schema.org/Certification? There are quite some.

Yes. I also developed the original schema.org proposal for the type together with Matthias and designed and launched the Merchant Center feedspec for it. The examples on schema.org site are all missing the rating which is always required by usecases that would consume the certification from the entity that is listing the "Thing" itself, and generally put any particular values that are quantitative in nature on the product/thing being certified.

Generally, from what I see in the actual certification landscape, I don't see the many of the Measurements being on the product as listed by a merchant/CSS or Brand. I would instead expect to pull them directly from the certification body's website by following the ceritification's URL. This is where I would find a trustworthy "Thing" that was certified where I can look at the exact attributes that that certifier cares about as attributes of the thing. For example - https://eprel.ec.europa.eu/screen/product/washingmachines2019/1658650 (Thing is a dishwasher, all the values attributes of the thing, the certification still only needs the rating)

Here are a few alternative routes to consider (just sketches, may not be 100% valid as given):

Proposal 1: Using schema:name, schema:sameAs´, and schema:url`, requires no change to the vocabulary, like so:

{
    "@context": "https://schema.org/",
    "@type": "Product",
    "name": "Water heater",
    "description": "Large capacity water heater"
    },
    "hasCertification": {
      "@type": "Certification",
      "name": "A+",
      "sameAs": "https://id.acme.com/level_a_plus",
      "url": "https://docs.acme.com/level_a_plus_explained",

This mixes the concept of the url of the certification with a url of a general explanation of the type of certification. It can't be followed to get the certificate and find additional information about the specific product on the certifiers website. Being able to follow that link and finding the correct product at the target is a very important part of validating that the certificate is being applied honestly/without error.

  "hasMeasurement": {
    "@type": "QuantitativeValue",
    "schema:name": "CO2e",
    "value": 0.00001,
    "unitCode": "KGM"
},

For `schema:sameAs`, one can use authoritative identifiers (e.g. URNs, Wikidata, GS1 URIs), for `schema:url` the URLs of human-readable definitions.

The use of `@id` in some example indicates that the value of this certification is exactly the one standard rating; as soon as you add meta-data like measurements, it is better to use `schema:sameAs`, as one would otherwise collate all related data.

**Proposal 2:** Using [`schema:value`](https://schema.org/value) on add [`schema:Certification`](https://schema.org/Certification) (very clean, minor change to the vocabulary, intuitive name `value`:

I don't think this is clean because it would separate the value from the max and min.

Add schema:Certification to the domain of value and tweak the text from *The value of a QuantitativeValue (including Observation) or property value node. * to The value of a QuantitativeValue (including Observation), Certification, or property value node.

Proposal 3: Make schema:Certification a subtype of schema:PropertyValue (pretty clean, you get all the flexibility from the property-value mechanism and keep the specificity of the Certification type (i.e. you know that it is a certification. )

This is actually my favorite.

I may be missing something, but it seems that it doesn't fit the need of non-numerical ranges. The fields on Rating really are the best fit and easy and neat to separate from the other kinds of properties. Using Rating directly or extending it with a type that defines no new fields, really is the most pragmatic of the options I see here.

The inherited rating types "AggregateRating" and "ContentRating" Seem pretty clearly unintentional artifacts, rather than purposeful inclusions.

I think this assessment is based on a misunderstanding of some underlying design decisions in schema.org: Due to the type hierarchy and global property scopes, it will happen that properties that are not commonly used on more specific types will be shown as valid (like "volcanoes can have fax numbers"). There is currently no mechanism to indivate "recommended" properties.

No, I understand that. I'm merely checking if you agree that using those specific fields for our purpose is probably not the right thing to do because they have other semantic implications and aren't on the Certification type to serve a particular intent.

[MichaelLinck]

Just to be clear: I'm OK with keeping hasMeasurement. It might be adopted, so I don't feel strongly about removing it.

I do feel pretty strongly that the type we add is either "Rating" or a type that inherits from "Rating" but doesn't need to add new fields to Rating. This will serve the need that we know we actually have when we implement a relevant crawling implementation.

[MatthiasWiesmann]

So did we reach some form of agreement?

[duckladydinh]

Hey @MatthiasWiesmann

So did we reach some form of agreement?

I think one agreement we have reached is to keep hasMeasurement unchanged and will assign the certification value to a separate property. The remaining question is which property? There are 2 choices:

1. Do we want a completely new property? (as @MichaelLinck suggested)
2. Do we want to make schema:Certification a subtype of some other schema (e.g. schema:PropertyValue) and use the inherited property instead? (as @mfhepp suggested)

Hi @mfhepp , so about your third proposal

Make schema:Certification a subtype of schema:PropertyValue

What do you think of making schema:Certification a subtype of schema:Rating instead of schema:PropertyValue?

The reason is because minValue and maxValue of schema:PropertyValue may not be the best way to describe the certification rating from our experience (e.g. in case of EPREL, A is the max while G is the min which is a reverse of their alphabetical ordering). Our existing data shows that merchants confuse these two all the time. On the other hand, we find the bestRating and worstRating of schema:Rating a much more reasonable description of the certification rating scale. WDYT?

[MichaelLinck]

There are some properties that we might want to add if we inherit from Rating instead of CreativeWork.

I would tend to agree that the concept of CreativeWork is, on the surface, a tad awkward for a certification, but it has a few fields that apply well:
"about"
"accountablePerson"
"acquireLicensePage"
"license"
"material" - and similar
"offers"
"provieder/publisher etc.."

So it actually has a lot of fields where the applicability to a Certification are reasonably clear. I would have also recommended reusing either the ContentRating or AggregateRating, except that I see those as really specifically communicating a rating other than a CertificationRating. ContentRating is very media specific. Aggregate rating is meant as a plurality of opinions.

This means that inheriting from Rating would probably also imply defining more properties on the Certification type itself that we currently inherit from CreativeWork, just to get 3 fields that we need.

[duckladydinh]

@mfhepp as noted by @MichaelLinck in the last comment, I didn't know that schemas can't have multiple inheritance. So if we change the super class of Certification, it breaks many existing properties, which, I assume, is not good.

So @mfhepp and @MatthiasWiesmann, I think the only reasonable choice left is to have a new property, let's say certificationRating, and make it a schema:Rating. WDYT?

[mfhepp]

This means that inheriting from Rating would probably also imply defining more properties on the Certification type itself that we currently inherit from CreativeWork, just to get 3 fields that we need.

This could be solved by manually adding Certification to the domain of these three properties. In schema.org, we have been using this approach quite frequently, i.e. liberating the usage of properties from the type hierarchy in order to avoid artificial types/classes that are needed just to capture property usage.

[duckladydinh]

@mfhepp

manually adding Certification to the domain of these three properties

IIUC, you mean, we have a way to make these 3 properties of schema:Rating (bestValue, worstValue and ratingValue) part of schema:Certification without changing its super type, right? If that's the case, I think we have reached an agreement.

But honestly, I am still not familiar with how it can be done. Would you mind sharing an example?

Thanks a lot

[mfhepp]

You would simple add schema:Certification to the value list for schema:domainIncludes of each of the three properties in the /data/schema.ttl file.

Hope that helps!

PS: In that file, the schema namespace is the default, hence you will find :foo instead of schema:foo in the Turtle syntax.

Edit: When doing so, one must put extra diligence on

1. checking that the meaning of the property is actually suited for all old and new usages, so that we are not abusing/stretching a property. It will also reduce our ability to redefine that property later on, because any change must fit all established uses.
2. Checking that the textual definition fits all old and new usages. It can be challenging to strike a balance between a wording that fits all usages while providing enough information for users (e.g. recommended units or values).
3. Providing at least one example for the usage and linking that to a) the property and b) the newly added class.

If the last two tasks are difficult, it could be better to define a sub-property that differs by the existing property only by the description and examples, and then add only that new property to the range of your class.

These are more general hints for similar scenarios.

[mfhepp]

I think the most productive way to proceed would be to discuss a complete example in JSON-LD. Anybody willing to craft it or several alternatives?

[duckladydinh]

I think the most productive way to proceed would be to discuss a complete example in JSON-LD. Anybody willing to craft it or several alternatives?

So since no one else willing, I'll look into crafting it but since I am unfamiliar with schema.org in general, it will take some time 😅.

[duckladydinh]

Hey @mfhepp @MatthiasWiesmann and @MichaelLinck , so here are 2 examples I created using JSON-LD, is this what you are looking for?

Example for adding a new property of type schema:Rating as @MichaelLinck suggested

{
  "@context": "https://schema.org/",
  "@type": "Product",
  "name": "LED",
  "hasCertification": {
    "@type": "Certification",
    "issuedBy": {
      "@type": "Organization",
      "name": "European Commission"
    }	
    "name": "EPREL",
    "certificationIdentification": "859905",
    "certificationRating": {
      "@type": "Rating",
      "ratingValue": "E",
      "bestRating": "A",
      "worstRating": "G"
    },
    "url": "https://eprel.ec.europa.eu/screen/product/lightsources/859905"
  }
}

Example for somehow making the 3 properties of schema:Rating available on schema:Certification without changing its super type as @mfhepp suggested

{
  "@context": "https://schema.org/",
  "@type": "Product",
  "name": "LED",
  "hasCertification": {
    "@type": "Certification",
    "issuedBy": {
      "@type": "Organization",
      "name": "European Commission"
    }	
    "name": "EPREL",
    "certificationIdentification": "859905",
    "ratingValue": "E",
    "bestRating": "A",
    "worstRating": "G"
    "url": "https://eprel.ec.europa.eu/screen/product/lightsources/859905"
  }
}

---

Honestly, both look good to me, so I think if one looks good to you, we have the agreement and can start implementing it.

[duckladydinh]

@mfhepp / @MatthiasWiesmann Do you have any further feedbacks?

If not, I'll start making a PR for the first approach (adding the certificationRating property) this week.

[duckladydinh]

So some links for preview

• Approach 1: Add property certificationRating to schema:Certification: https://1-dot-schema-org-experiment.ey.r.appspot.com/certificationRating (commit)
• Approach 2: Copy rating attributes to schema:Certification: https://2-dot-schema-org-experiment.ey.r.appspot.com/Certification (commit)

Note: In all cases, I need to remove some text from the rating attributes

• bestRating: Remove "If bestRating is omitted, 5 is assumed."
• worstRating: Remove "If worstRating is omitted, 1 is assumed."

So @mfhepp / @MatthiasWiesmann , if both look fine, let's go with approach 1 as @MichaelLinck suggested since it allows us to comment on the property specially for certification.

Pull Request for Approach 1: #3504 (as you can see, I made 2 changes so if you don't agree, I'll switch to 2).

[alex-jansen]

Before looking at a pull request I would like to see the opinion of GS1 given that we took care in #3230 to make sure gs1:CertificationDetails and schema:Certification are compatible. @mgh128 and @philarcher can you review this proposal to add a new certificationRating property (with values of existing type Rating to schema:certification?

[duckladydinh]

Also @alex-jansen and @mgh128 and @philarcher, just 1 suggestion regarding the GS1 link. As existing fields between gs1:CertificationDetails and schema:Certification do not have to correspond 1:1 to each other, instead of creating a new gs1.org/voc/certificationRating link, I have discussed with @MichaelLinck and think that we can reuse the https://gs1.org/voc/certificationValue link instead. That way, we don't change anything in GS1. WDYT?

[mgh128]

I agree with @duckladydinh that https://www.gs1.org/voc/certificationValue is appropriate and already sufficient for expressing a rating, without a need to create a gs1:certificationRating property.

We (GS1) could consider improving the definition of https://www.gs1.org/voc/certificationValue to make this clearer.
@philarcher - do you agree?

[philarcher]

@philarcher - do you agree?

Yes! Thanks Mark.

[alex-jansen]

Great, thanks for the quick feedback everyone!

[duckladydinh]

Thanks, @alex-jansen and everyone for your help. Thank you.