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

Add a mechanism to support product certifications #3230

Open
MatthiasWiesmann opened this issue Dec 8, 2022 · 42 comments
Open

Add a mechanism to support product certifications #3230

MatthiasWiesmann opened this issue Dec 8, 2022 · 42 comments
Assignees
@danbri
Labels
no-issue-activity Discuss has gone quiet. Auto-tagging to encourage people to re-engage with the issue (or close it!). Queued for Editorial Work Editor needs to turn issues/PRs into final code and release notes.

Comments

@MatthiasWiesmann
Copy link
Contributor

Many objects can bear some form of certification, Organizations can be ISO certified, Food products can be Organic or Vegan, a person can be a certified professional. There are certifications for many domains: regulatory, organizational, recycling, food, efficiency, educational, ecological, etc.

Certifications can be first party (the certification authority makes the claim), second-party (an authorized party makes the claim), or self-certification (recipient of the certification makes the claim). Some certifications have a unique identifier, for instance the FSC (Forest Stewardship Council).

Some schema.org objects have support for some specific certifications, for instance Product has hasEnergyConsumptionDetails, Person and Organization have hasCredential, but these are very specific. Adding specific attributes for all possible certification is not feasible.

A certification would be an object with the following properties:

  • A certification unique identifier
  • A certification authority
  • A certifying organization (for second party)
  • A certification measurement (energy efficiency, CO² emissions).
  • The object of the certification (could be about).

Certification could descend from CreativeWork
@danbri
Copy link
Contributor

danbri commented Dec 8, 2022 via email

@github-actions github-actions bot added the no-issue-activity Discuss has gone quiet. Auto-tagging to encourage people to re-engage with the issue (or close it!). label Mar 9, 2023
@schemaorg schemaorg deleted a comment from github-actions bot Mar 14, 2023
@danbri
Copy link
Contributor

danbri commented Mar 14, 2023

I discussed this with @alex-jansen and @MatthiasWiesmann

Context - This is a proposal from Google based on our experience consuming schema.org Product and Organization markup and working with similar data from online merchants. If it were accepted, it would make it easier for us and others to understand certifications of products and organisations.

Another overview:

Schema.org currently only supports a limited and specific set of product certifications, like energy efficiency labels (see #2670). There are many other types of certifications that can be attached to products, but also organisations. Certifications can be legal (FCC mark), administrative (ISO 9001), ethical (organic food, carbon neutral), or religious (kosher or halal food). Since consumers are increasingly interested in knowing the certifications of products and merchants, we believe that adding a small amount of vocabulary to allow a structured way of expressing certification characteristics would benefit the ecosystem. Note that this proposal only a mechanism to describe certifications, not to verify them.

Matthias prepared a doc last year which I think is best to just share. I would like to see some attention from both Verifiable Credentials perspective, digital certification in general, and also (at least in terms of terminology) Education/skills, e.g. various terms relating to credentials.

Please take a look: Certifications in Schema.org. They have also been considering the possibility of proposing a type above Educational Occupational Credential and below Creative Work. Would that make sense?

/cc @philbarker @philarcher @msporny

@msporny
Copy link

msporny commented Mar 14, 2023 •
edited

I would like to see some attention from both Verifiable Credentials perspective, digital certification in general, and also (at least in terms of terminology) Education/skills, e.g. various terms relating to credentials.

Good that you tagged @philarcher on this particular item. I know for a fact that they've got stuff going on in that space and they're very active in the Verifiable Credentials work: https://www.gs1.org/voc/certification

Please take a look: Certifications in Schema.org. They have also been considering the possibility of proposing a type above Educational Occupational Credential and below Creative Work.

Yes, there is active work in this area and an interoperability plugfest kicking off soon (we had 25+ implementers at the last education-related plugfest using JSON-LD + VCs). If we work fast enough, we might be able to get a schema.org-compatible VC being issued for the plugfest. It would be drop-in compatible w/ existing schema.org content published in web pages (but in this case, digitally verifiable that the certification/education certificate is valid). /cc @dmitrizagidulin @kayaelle @longpd @philbarker

Would that make sense?

Yes!!! It makes a ton of sense, and is the sort of convergence w/ schema.org that we have been hoping for since the start of the VC work.

Just connecting people for now, we might want to get all of these folks on a call at some point to hammer out a strategy. At present, stuff is already happening w/o schema.org's involvement... but I think we'd all like it much better if schema.org was involved and we had a solid schema.org story around education credentials and certifications.

@github-actions github-actions bot removed the no-issue-activity Discuss has gone quiet. Auto-tagging to encourage people to re-engage with the issue (or close it!). label Mar 15, 2023
@danbri danbri self-assigned this Apr 1, 2023
@danbri danbri added the Queued for Editorial Work Editor needs to turn issues/PRs into final code and release notes. label Apr 1, 2023
@alex-jansen
Copy link
Contributor

Wanted to see if we can move this forward, I indeed do see overlap and therefore benefits in aligning with https://www.gs1.org/voc/certification. @philbarker, @philarcher

@github-actions
Copy link

github-actions bot commented Aug 1, 2023

This issue is being nudged due to inactivity.

@github-actions github-actions bot added the no-issue-activity Discuss has gone quiet. Auto-tagging to encourage people to re-engage with the issue (or close it!). label Aug 1, 2023
@adamml
Copy link

adamml commented Oct 12, 2023

I was wondering if there is any movement on this one.

It looks like it would be really helpful for some things I'm thinking about and working on.

It also looks like it would also satisfy some of the requirements of #2879 and #2934.

Also, are comments on the linked document welcome?

@alex-jansen
Copy link
Contributor

Hi Adam, planning to pick this up soon again, so comments in the linked doc are more than welcome!

@alex-jansen
Copy link
Contributor

alex-jansen commented Dec 11, 2023 •
edited

Drafted a new Certification type, branch: https://github.com/schemaorg/schemaorg/pull/new/certification
Staging site: https://1-dot-schema-experiment.uc.r.appspot.com/Certification

Please take a look, comments more than welcome: @msporny @MatthiasWiesmann @adamml @philarcher @philbarker

@danbri
Copy link
Contributor

danbri commented Dec 11, 2023

Thanks @alex-jansen - thanks for moving this along. Looking forward to comments from folks pinged here!

@jvandriel
Copy link

I do hope those you pinged have the correct credentials to log in to the staging site. ;-)

@msporny
Copy link

msporny commented Dec 11, 2023

I do hope those you pinged have the correct credentials to log in to the staging site. ;-)

I certainly don't. :)

That said, some feedback:

  • It would be nice if there was a simple human-readable description of what the certification meant.
  • It would be good to link to documentation about what the certification means.
  • The Certifications really feel like a job for Verifiable Credentials, which are compatible w/ schema.org. At present, you just have to trust that the website isn't lying about their certifications, a certification that's digitally signed would be more trustworthy.
  • It feels like alignment among the certification bodies on how these certifications are expressed would be good, but I expect a huge amount of work. That said, it's work that's worth doing to improve supply chain security/auditability.

Hope that helps. :)

@alex-jansen
Copy link
Contributor

alex-jansen commented Dec 11, 2023 •
edited

Thanks for the lightning-quick comments :)

Staging site (and comment above) updated: https://1-dot-schema-experiment.uc.r.appspot.com/Certification. Hope this is accessible?

@jvandriel
Copy link

Can see it now. Thanks!

@jvandriel
Copy link

jvandriel commented Dec 11, 2023 •
edited

I noticed on the staging site that Certification is a subtype of StructuredValue but wasn't it meant to be a subtype of CreativeWork, or has that changed?

Not that I have anything against that, I'm just wondering.

@alex-jansen
Copy link
Contributor

Forgot to mention that one of the goals of this attempt is to be compatible with GS1 https://www.gs1.org/voc/CertificationDetails. Specifically asking @philarcher for feedback in that area

@msporny Can you provide some specific suggestions related to Verifiable Credentials, either to change or extend the current draft proposal?

Agree that aligning with certification bodies (including governments) and getting some standardization in this area would certainly be ideal.

@msporny
Copy link

msporny commented Dec 11, 2023

Staging site (and comment above) updated: https://1-dot-schema-experiment.uc.r.appspot.com/Certification. Hope this is accessible?

Now that I can see the site, a number of my comments don't apply, namely:

  • You are relying on name/description for human-readable description -- please use those fields in the examples.
  • It looks like you're seeking alignment w/ GS1 -- good! :)

Other thoughts (after seeing the site):

... and here's what it could look like as a W3C Verifiable Credential. The benefit of doing so is that you get a cryptographic proof that the certification body has certified the product and they stand behind that certification:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://schema.org"
  ],
  "id": "http://certification.example/credentials/3732",
  "type": [
    "VerifiableCredential",
    "CertificationCredential"
  ],
  "issuer": "https://certification.example/issuers/14",
  "validFrom": "2023-01-01T19:23:24Z",
  "credentialSubject": {
    "type": "Product",
    "hasCertification": {
      "type": "Certification",
      "name": "CO2 Measured",
      "certificationStatus": "CertificationActive",
      "authority": {
        "type": "Organisation",
        "name": "CO2 Trust",
        "url": "https://www.co2trust.com/"
      },
      "logo": "https://www.co2trust.com/c02-measured-logo.jpg",
      "hasMeasurement": {
        "type": "QuantitativeValue",
        "name": "CO2e",
        "value": 0.158,
        "unitCode": "KGM"
      }
    }
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-rdfc-2019",
    "created": "2023-12-11T14:58:20Z",
    "verificationMethod": "https://certification.example/issuers/14#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z5dqTceMhzmpFSfwEphYDnWJJiAtcGaitiZ2FgpRWEcLJmfQBRMUpaTi
hmhpdHbiMJN9Ranx1PXLaGSePQjV74nLC"
  }
}

@danbri
Copy link
Contributor

danbri commented Dec 11, 2023

Thanks all for the speedy comments :)

@msporny - is it fair to say that this vocabulary (alongside rest of schema.org) ought to be something we can just "drop in" to a Verifiable Credentials description? There's a natural concern that we don't re-invent VCs but since the VC standards don't do domain vocabulary, it feels like some kind of container (VC) vs content (Schema) distinction makes sense, and from your example, appears to look pretty good.

@msporny
Copy link

msporny commented Dec 11, 2023 •
edited

@msporny - is it fair to say that this vocabulary (alongside rest of schema.org) ought to be something we can just "drop in" to a Verifiable Credentials description?

In general, yes, that's a design goal for W3C VCs (at least, among a significant number of us in the W3C VCWG). There are many cases where it "just works".

There's a natural concern that we don't re-invent VCs but since the VC standards don't do domain vocabulary, it feels like some kind of container (VC) vs content (Schema) distinction makes sense, and from your example, appears to look pretty good.

Yes, that's exactly the right mental model... I'm glad it came across that effortlessly. :)

Yes, the example above was trivial to put together. We've found that to be true for many schema.org examples that describe "things" via schema.org. You can just drop that "thing" into the credentialSubject field of a VC, update @type to use type, and @id to use id, and most everything else stays the same.

The @type and @id weirdness is due to a number of folks in the VCWG that don't want to do any JSON-LD processing at all, which resulted in a section around Credential Type-Specific Processing. So, that's the only weirdness that exists and doing that conversion is fairly mechanical.

One of the design goals for W3C Data Integrity has always been: Enable schema.org to express cryptographically verifiable forms of the things it expresses today without any changes to schema.org markup.

That's also true for W3C VCs, modulo the minor changes needed above to get it to fully align. Our hope is that in the future, schema.org will be able to express things where some (or all) of that information is cryptographically verifiable. This will enable search engines to pull together information that it has a much higher confidence in wrt. authorship and accuracy of the information.

@philbarker
Copy link
Contributor

The description states "a person can be a certified professional" but at the only property with Certification in range is hasCertification which is only available on Products and Organizations.

@danbri
Copy link
Contributor

danbri commented Dec 11, 2023

@philbarker if Person were to be added to the domain of hasCertification, can you suggest some basic examples that we should work for education/occupation/skills etc.?

@danbri danbri mentioned this issue Dec 11, 2023
Open
@msporny
Copy link

msporny commented Dec 11, 2023

@philbarker if Person were to be added to the domain of hasCertification, can you suggest some basic examples that we should work for education/occupation/skills etc.?

We've been looking into "Food Safety Certification" in the VC community. That would be a good example to have.

@philbarker
Copy link
Contributor

Manu's example works (thanks Manu). So would Google Cloud Certification. But such things are also an EducationalOccupationalCredential so I was wondering how this Certification, if applied to people, would play with that. (There is also a wee little minefield around Certificate Vs Certification when it comes to Educational and Occupational Credentials.)

@philarcher
Copy link

As you're kindly referencing/using the GS1 work I don't have any red lights here (@mgh128 might have). However, it is worth noting that there is a lot of activity in this area at the moment in our organization and so there may be some future change - but that's more than a year away. For example, a certificate of conformance to a standard should probably have a reference to the standard itself.

What might also be of relevance to the model is the accreditation of the body doing the accrediting. NATA in Australia, UKAS in the UK etc. are the national "Accreditation Services" that do this. So there's a chain from the cert, to the Certification Assessment Body to the Accreditation Service. Basically - not all certificates are equally valuable. Away from the formal system there needs to be room for user feedback and ratings too. If a food product is certified as Kosher by assessment body A, you can have all the cryptographic verifiability you like but if everyone says that certification body B is more trustworthy, well, there's an important user angle there.

@danbri
Copy link
Contributor

danbri commented Dec 12, 2023

@MatthiasWiesmann @alex-jansen can you tweak your draft changes to address these comments, especially making sure we have a few more examples as discussed above?

@alex-jansen
Copy link
Contributor

Apologies, it took me a bit to process all the great feedback. I am addressing all the comments here, and rebuilt the staging site with some more examples. Please review carefully, it is difficult to handcraft complex examples :). Also happy to included other examples if provided, for example for Certifications related to Persons or Services.

Why is Certification not a subtype of CreativeWork ?

Since a Certification is a specific type of a Credential (Accreditation and License are other types of credentials) and EducationalOccupationalCredential is a subtype of CreativeWork it does not fit well. Also, in the GS1 definition, Certification is a basic type, so we feel that is more appropriate here

The description states "a person can be a certified professional" but the only property with Certification in range is hasCertification which is only available on Products and Organizations.

Updated, see staging site. @philbarker would this work?

It would be nice if there was a simple human-readable description of what the certification meant.

Added to examples.

The Certifications really feel like a job for Verifiable Credentials, which are compatible w/ schema.org.

Added to the examples, thanks @msporny!

Maybe a link to the actual certificate from the certification body would be good

Added 2 examples to illustrate how that would work

Why can't you just re-use the @type field to list `certificationType?

Fair point, I was reusing gs1:certificationType, which states "Indicates the type of certification". This is indeed a bit ambiguous and perhaps redundant, so removed for now. @mgh128 or @philarcher : can you provide guidance?

Why do you need datePublished in addition to validFrom?

The data the certificate is published could be different from the date the certificate is valid. See also gs1:initialCertificationDate vs gs1:certificationStartDate.

@philbarker
Copy link
Contributor

The description states "a person can be a certified professional" but the only property with Certification in range is hasCertification which is only available on Products and Organizations.

Updated, see staging site. @philbarker would this work?

It works on its own terms, but if Certification applies to people as the text in the example implies then it is an EducationOccupationalCredential, which is a subtype of CreativeWork. So it is kind of odd that Certification isn't. Schema.org has that oddness already, all over the place, and I think it is a fair judgement call to put pragmatics and ease of use ahead of ontological purity. So I guess the question is: does modelling this way make Schema.org easier to use?

@alex-jansen
Copy link
Contributor

OK, let's put Certification below CreativeWork (and above EducationOccupationalCredential) to make it easier to understand.

@philbarker
Copy link
Contributor

@alex-jansen

let's put Certification below CreativeWork (and above EducationOccupationalCredential)

no no no! Not above EducationalOccupationalCredential. Not all EducationalOccupationalCredentials are Certifications. They are at the same level.

In occupational credentialing Certification has a quite specific meaning, distinct from Diploma/Certificate/Degree/License etc. Certifications are indicate competence to perform tasks and are time-limited/require renewal to maintain validity. So while it will be useful to be able to say that something is an EOCred and a Certification, that is not true of EOCreds such as Degrees.

@alex-jansen
Copy link
Contributor

ok @philbarker :) Then we put Certification next to EducationalOccupationalCredential and below CreativeWork.

Also ping @msporny and @philarcher to look at the updated staging site, specifically the examples.

@mgh128
Copy link

mgh128 commented Dec 20, 2023

I'm happy to see this discussion and potential interest in what we developed in the GS1 Web Vocabulary for expressing certification details being re-used/adapted for schema.org. I've provided the following summary to provide some background about what was developed and why.

Before version 1.6 of the GS1 Web Vocabulary, gs1:CertificationDetails was a very simple class defining three interdependent properties, each expecting a language-tagged string (or set of these) as their expected value(s), i.e. having a range of rdf:langString :

gs1:certificationAgency
gs1:certificationStandard
gs1:certificationValue

Grouping these together within a repeatable class gs1:CertificationDetails enabled multiple sets of certification details to be expressed for a product.

As a result of work in the GS1 EPCIS/CBV work group, Version 1.6 of the GS1 Web Vocabulary significantly expanded gs1:CertificationDetails with additional properties to make many more of the details typically found on paper certificates or PDF certificates expressible as machine-interpretable data. The following properties were added:

gs1:certificationAgencyURL (a gs1:Organization or schema:Organization identified unambiguously by its URI)
gs1:certificationStartDate
gs1:certificationEndDate
gs1:certificationAuditDate
gs1:certificationSubject
gs1:certificationStatement
gs1:certificationStatus ( a code from code list gs1:CertificationStatus to indicate ACTIVE or INACTIVE )
gs1:certificationIdentification (xsd:string)
gs1:certificationURI
gs1:certificationType
gs1:initialCertificationDate

At the same time, the domain of the property gs1:certification (whose range is gs1:CertificationDetails) was broadened so that it could be expressed for a gs1:Product, gs1:Organization or gs1:Place (or the schema.org equivalents), since it's also possible that an organisation (such as a manufacturer or retailer or restaurant) or a location (such as a specific store or factory) may hold certifications based on audits or inspections of those premises or activities/operations performed there, as well as for any resulting products.

The design of gs1:CertificationDetails is very much certificate-centric and designed to support situations where we might have a certificate that applies to logical combinations of an organisation and a location/place (such as a food hygiene certificate) or a product and a location/place and organisation (such as a certificate that products from a specific food processing factory have been audited to be free from nuts)

I therefore think it's really important to pay particular attention to the definition for gs1:certificationSubject and what it says about the logical AND and OR relations that apply when multiple values are specified and where those values may be of distinct types - e.g. a gs1:Product at a gs1:Place by a gs1:Organization.

As gs1:CertificationDetails is currently formulated, it isn't ideally suited for expressing a claim about a particular product, organisation or location as a single RDF triple. Instead, it's saying that a certificate exists / has been issued by a specified certification agency, based on a specified audit date, that the certificate applies to the logical combination of (products, organisations, places) specified by gs1:certificationSubject and that the certificate has a validity period from its start date to its end date, with the initialCertificationDate indicating the earliest certification date held for that combination. We should probably consider improving that definition to indicate that it is assumed to apply only for continuous unbroken certification since that date, without any lapses.

Within static/master data, any gs1:Product, gs1:Organization or gs1:Place can use gs1:certification to point to one or more relevant instances of gs1:CertificationDetails (in which that product, organisation or place/location is typically included in the logical combination specified via gs1:certificationSubject ). Within EPCIS event data, the epcis:certificationInfo property can link a traceability/visibility event to one or more instances of gs1:CertificationDetails that are relevant to the objects (e.g. products, logistics units, assets), locations or organisations involved in that event.

Over the next day or two, I'll take a closer look at the updated staging site and the examples there and try to provide some feedback on those.

@alex-jansen
Copy link
Contributor

Thank you for the detailed background Mark, very useful to understand the reasoning behind the properties. Interestingly Google started in a similar fashion with 3 properties authority+name+code to for example allow mapping on energy labels (certificates) represented in the EU EPREL database.

We have indeed been looking in particular at gs1:certificationSubject, which we mapped on Schema.org about. We also added a validIn property, which could be considered redundant in that context.

Looking forward to your feedback on the staging site and examples so we can keep things nicely aligned between Schema.org, GS1, and W3C VC.

@alex-jansen
Copy link
Contributor

Ping @philarcher and @mgh128 for GS1 feedback so we can move this forward. Thanks!

@mgh128
Copy link

mgh128 commented Jan 3, 2024

Hi @alex-jansen , all ! Happy New Year!

I've now reviewed the staging site and examples and have some feedback for you, which I hope is helpful. I'll start with the feedback on the examples because there appears to be a conflict in which the JSON-LD context resource for schema.org is attempting to redefine @protected terms already defined within the JSON-LD context resource for Verifiable Credentials (at https://www.w3.org/ns/credentials/v2 ), so I think you and your team will need to investigate this further to identify the source of that conflict, since all of the schema.org examples should be valid JSON-LD without errors appearing when pasting into https://json-ld.org/playground/

For examples 3, 4 and 6, I'm seeing the following error when pasting into https://json-ld.org/playground/ :

jsonld.SyntaxError: Invalid JSON-LD syntax; tried to redefine a protected term.

Not sure whether that conflict was caused by redefinition within the JSON-LD context for schema.org of @vocab or by mapping “id” to @id and “type” to @type or something else - but this needs further investigation before Examples 3, 4 and 6 can be published, since they really should not be resulting in this kind of error.

Omitting the schema.org JSON-LD context is also not an option, otherwise “Product” will not be mapped to https://schema.org/Product but instead to https://www.w3.org/ns/credentials/issuer-dependent#Product
and even more importantly, hasCertification would not be mapped to https://schema.org/hasCertification but instead to https://www.w3.org/ns/credentials/issuer-dependent#hasCertification , neither of which are what you intended.

Example 5 has two occurrences of the same typo - Organisation instead of Organization
(schema.org does not define a class schema:Organisation - only schema:Organization )

Example 3 also has this same typo, appearing once.

Example 1 has a typo - addres instead of address
Also within example 1, auditDate is not currently being cast to schema:Date within JSON-LD context for schema.org in the same way that is already happens for the Date values for validFrom and expires - so you probably want to fix that so that auditDate, validFrom and expires all result in RDF triples that are structurally similar for their value/object.

I also noticed that even when a DateTime-formatted string is specified as the value of validFrom or expires, the JSON-LD context resource for schema.org nevertheless casts them to a schema:Date type, which is understandable, though somewhat suboptimal since they really should be schema:DateTime types in that situation, though I understand that a JSON-LD context resource can't really inspect the format of the value to distinguish between something formatted like YYYY-MM-DD and something like YYYY-MM-DDThh:mm:ssZ etc. It's tricky when the rdfs:range of a literal property isn't a single data type.

I also have some general feedback about the documentation on the staging site, none of which is a critical error but hopefully a few things you can consider tweaking if you agree:

  1. We're very happy to see cross-references to terms within the GS1 Web Vocabulary - and we'll be happy to provide similar mappings back to schema.org in a future version, even though in some situations, a GS1 property maps to a property path or predicate chain within schema.org - but it should still be doable.
  2. We'd be very happy for you to use the CURIE prefix gs1: when referring to terms within the GS1 Web Vocabulary. This might also be less confusing to readers in the few occasions where we actually use exactly the same property name, e.g. certificationStatus - where you could write 'See also gs1:certificationStatus' rather than 'See also GS1 certificationStatus'.
  3. At GS1, we consider that a gs1:Place might have one or more gs1:CertificationDetails associated with it. A location (such as a food processing factory) or building might have a religious certification if it is consecrated or has been certified as being a location where the processes (e.g. food preparation) are in accordance with particular religious or ethical concerns. A stretch of beach or river might have a certification that designates it as approved for use by naturists or nudists. Just a suggestion - you might consider expanding the rdfs:domain of schema:hasCertification so that a schema:Place could also make use of it, if you see any merit in the kinds of examples given above.
  4. We appreciate the reference to the gs1:CertificationDetails class but I think we'd prefer the wording to say 'Mapped from the gs1:CertificationDetails class in the GS1 Web Vocabulary' rather than 'Mapped from the CertificationDetails type in the GS1 Web Vocabulary'. Although the schema.org documentation appears to use Type rather than Class for complex data types, within the GS1 Web Vocabulary we try to consistently use Class when referring to things that are complex data types / rdfs:Class so that we can use 'Type' when referring to datatypes for literal values that need to be cast as xsd:date, xsd:dateTime, xsd:dateTimeStamp, xsd:boolean etc. I'm not sure I understand why schema.org uses Type almost as a synonym for Class - but the definition for rdf:type is that "The subject is an instance of a class.", even though the name of the rdf:type property is "type" - so maybe that's what caused this interchangeability within schema.org, though I can't help feeling it might also cause confusion, so that's why we try to avoid doing so.
  5. Regarding certificationRegistration I think the use of the word "key" (rather than "identifier") within the property URI and current definition "Registration key with an independent certification body. Typically this key can be used to consult and verify the certification. See also GS1 certificationIdentification." has the potential to cause unwanted confusion with cryptographic public keys that might be used within verifiable credentials that digitally sign assertions about certification details. That's why we avoided using the word "key" when "identifier" was sufficient in our definition for gs1:certificationIdentification. Within GS1 we already struggle with the overloaded term "key" which is used in the sense of "lookup key" when referring to our GS1 identification keys such as GTIN, SSCC, GLN etc. - so when GS1 needs to talk about delegation chains of verifiable credentials for its identification keys, the overloading of the term "key" becomes very tricky and we then always try to qualify it either as 'identification key', 'public key', 'private key', depending on what we're actually referring to, so I can't help feeling that introducing 'registration key' might cause similar confusion if 'certificate identifier' might suffice instead, avoiding such overloading of the word "key" - but that's just my perspective / preference.

I have begun preparing a table of mappings between the properties defined for schema.org/Certification and those defined within the gs1:CertificationDetails class and I'll be happy to share this with you / this thread. I did notice that you have a validIn property, expressing a geographic region or jurisdiction - and this could be a useful additional property for GS1 to consider including within its gs1:CertificationDetails class.

@alex-jansen
Copy link
Contributor

Happy New Year as well Mark and everyone!

Thanks for the review @mgh128, much appreciated! I addressed all comments and published a new version of the staging site.

Example comments:

  • error in JSON-LD playground: I did some experiments and reverting "https://schema.org" and "https://www.w3.org/ns/credentials/v2" in the @context gets rid of the error. I suspect it is indeed related to redeclaring @id to id etc. in verifiable credentials. @msporny FYI, perhaps this is a known issue?
  • Organisation and addres typos: Fixed, thanks!
  • auditDate not being interpreted as Date: This will likely be fixed once the new types are on the public Schema.org site and the JSON-lD playground can see them?
  • DateTime formatted values still being casted to Date: Agreed, but seems a more general problem. @danbri any insights?

Documentation comments:

  • add gs1: prefix: Done
  • add Place to domain of hasCertification: Done
  • use "Class" vs "Type": Done
  • renamed "Key" to "Identification: Done

Please take another look, happy to do one more final round of fine-tuning if needed.

And yes, let's create that detailed cross-reference between gs1:CertificationDetails and Schema.org Certification and keep things aligned.

@mgh128
Copy link

mgh128 commented Jan 4, 2024

Hi @alex-jansen

Thanks for making those updates - they look good to me.

Regarding the problem with 're-defining' @protected definitions from https://www.w3.org/ns/credentials/v2 the issue is not limited to the mappings of "id" : "@id" and "type" : "@type" . For better or for worse, the JSON-LD context resource for https://www.w3.org/ns/credentials/v2 decides that its mappings for these and also a number of other schema.org properties such as
"description": "https://schema.org/description",
"name": "https://schema.org/name"
should be @protected globally within its JSON-LD context resource - not even within a limited scope.

Thankfully, the JSON-LD context resource for schema.org at https://schema.org/docs/jsonldcontext.json doesn't currently use @protected anywhere, so your solution of swapping the sequence of the JSON-LD context resources works for now - but might still break in future if schema.org decides to use @protected.

It's unfortunate that this error was being thrown by a JSON-LD processor and perhaps we can hope that a future version of JSON-LD might require JSON-LD processors to handle this scenario far more elegantly by actually checking whether the redefinition actually conflicts with the existing definition of a mapping. In situations where the VC context resource uses @protected to protect its mappings of "id" : "@id" and a subsequently declared JSON-LD context resource for schema.org defines an identical mapping of "id": "@id" then a more elegant solution would detect a potential redefinition but notice that there is actually no conflict, so the error would not be raised.

Then there is potentially the question of etiquette or best practice in use of @protected - about whether a JSON-LD context resource should be using @protected to protect a mapping to a property defined in an external vocabulary, especially if that external vocabulary might already (or in future) decide to use @protected for the same mappings for its own properties. Until we have a much more elegant solution in JSON-LD processors that doesn't generate needless errors for non-conflicting redefinitions, then perhaps some guidance on the above point would be appropriate - whether in the JSON-LD technical recommendation - or at least in the notes that accompany the W3C Verifiable Credentials vocabulary, to advise that because its JSON-LD context resource protects various mappings that are already expressed in the schema.org JSON-LD context resource, the schema.org JSON-LD resource should be declared first or earlier (at least until the point where the JSON-LD context resource for schema.org also uses @protected !)

In either case, I think @msporny and @danbri need to join the discussion about the @protected issue, at least to understand how to avoid this error now and also in the future, in case schema.org also decides to use @protected in future.

I'll try to provide the mapping table next week.

@alex-jansen alex-jansen mentioned this issue Jan 5, 2024
Closed
@danbri
Copy link
Contributor

danbri commented Jan 5, 2024 via email

@mgh128
Copy link

mgh128 commented Jan 5, 2024

Hi @danbri

Happy New Year!

Yes, it's definitely helpful that "id" is mapped to @id and "type" is mapped to @type (and there may be justification for doing likewise for some of the other @-prefixed special JSON-LD keywords such as @value and @language for the same reason)

The problem is that the JSON-LD context resource for Verifiable Credentials is also doing this same mapping but that they are using @protected to prevent any subsequently processed JSON-LD context resource from redefining these.

That then results in a JSON-LD processing error if the JSON-LD context resource for schema.org is referenced after the JSON-LD context resource for Verifiable Credentials because currently, it's not sufficiently elegant to check whether the second mapping actually conflicts with the first @-protected mapping for "id" or "type" or is just a non-conflicting identical duplicate mapping.

Then, if in future schema.org also decides to use @-protected we run into a further problem because VC is already using @-protected on aliases of "name" to schema:name , "description" to schema:description etc.

In that situation, you'd see this error whether schema.org is declared before or after the VC context resource, resulting in a no-win situation.

My view is that schema.org would be entirely within its rights to make use of @-protected at some point in future to alias "name" to schema:name etc. for properties it defines, but that if it did so, there would then be the problem mentioned above, because VC context resource is already doing exactly that, so the JSON-LD processors would raise an error about redefinition at least until they're smart enough to check whether it's a conflicting redefinition versus a non-conflicting redefinition.

I'm just looking ahead and flagging a future problem that might arise if we're not very careful now.

alex-jansen added a commit that referenced this issue Jan 5, 2024
@alex-jansen
add Certification class #3230
b6355c6
@msporny
Copy link

msporny commented Jan 5, 2024

it's not sufficiently elegant to check whether the second mapping actually conflicts with the first @-protected mapping for "id" or "type" or is just a non-conflicting identical duplicate mapping.

Hmm, that's not my understanding. Unfortunately, I wasn't a part of the details of how to handle this, but my understanding is that duplicate re-definitions to the exact same thing won't throw a protection error. We didn't want to cause the exact problem you are highlighting @mgh128.

/cc @dlongley, @gkellogg, and @davidlehn who know more about this particular feature than I do.

@alex-jansen alex-jansen mentioned this issue Jan 5, 2024
Merged
@dlongley
Copy link

dlongley commented Jan 5, 2024

JSON-LD processors are expected to ignore duplicate mappings, i.e., not throw a "protected term redefinition error" when encountering a term definition that doesn't change the existing protected term definition.

@mgh128
Copy link

mgh128 commented Jan 5, 2024 •
edited

https://www.w3.org/ns/credentials/v2

@dlongley - Many thanks for that clarification. Unfortunately, when JSON-LD processors do throw the "protected term redefinition error", some implementations such as the otherwise very helpful https://json-ld.org/playground/ appear not to be required to provide more helpful details about exactly which protected terms were affected by the redefinition error, so in the absence of a more helpful error message, I've written a quick and dirty bit of JavaScript that compares the JSON-LD context resources for Verifiable Credentials and for schema.org. The specific redefinition conflicts that it found were as follows:

"description" defined in VC as "https://schema.org/description"
and in schema.org as {"@id":"schema:description"}

"name" defined in VC as "https://schema.org/name"
and in schema.org as {"@id":"schema:name"}

So if https://www.w3.org/ns/credentials/v2 can be updated to ensure that its mappings for "name" and "description" become {"@id":"schema:name"} and {"@id":"schema:description"} respectively, then the protected term redefinition error should go away even if the JSON-LD context resource for schema.org is referenced after the JSON-LD context resource for Verifiable Credentials.

My script noticed that there is an apparent conflict between the @protected definition for "@vocab" within VC as "https://www.w3.org/ns/credentials/issuer-dependent#" and the unprotected definition for "@vocab" within schema.org as "http://schema.org/" but for reasons I don't understand, this didn't trigger the protected term redefinition error, presumably because "@vocab" is handled differently by the logic for this error or treated as a special case.

Maybe there's also some best practice that we can extract from this, something like:

If defining mappings to terms sourced from external vocabularies, take extreme care to ensure that the corresponding term expansions/mappings are identical to the corresponding expansions/mappings in the external vocabulary in which those terms are defined, especially when using the same JSON key and especially when defining such expansions/mappings within a scope that uses @protected to prevent redefinition; failure to observe this recommendation may result in unwanted protected term redefinition errors in JSON-LD data in situations where the JSON-LD context resource for the external vocabulary is referenced later than the JSON-LD context resource that contains the non-aligned expansions/mappings within an @protected scope.

Someone can probably improve on that wording but hopefully you all get the gist of what I'm trying to abstract/extract from the lessons learned today.

@dlongley
Copy link

dlongley commented Jan 5, 2024

@mgh128,

...some implementations such as the otherwise very helpful https://json-ld.org/playground/ appear not to be required to provide more helpful details about exactly which protected terms were affected by the redefinition error...

I believe improving the playground to show the details of errors (including which term definitions ran afoul of the protection rules) is on the todo list for improvements in the very near future. If you're using jsonld.js (the library the playground uses), the error details are already present and can be printed out; all that is left to do is render this information in the playground's HTML.

So if https://www.w3.org/ns/credentials/v2 can be updated to ensure that its mappings for "name" and "description" become {"@id":"schema:name"} and {"@id":"schema:description"} respectively...

The right solution is for JSON-LD processors that have bugs that flag these to be fixed; jsonld.js needs updating here so it won't throw since the term definitions are actually the same, despite the semantic sugar that instantiates them being different. This should also produce the desired outcome. We should not add an additional term schema to the credentials v2 context.

If defining mappings to terms sourced from external vocabularies, take extreme care to ensure that the corresponding term expansions/mappings are identical to the corresponding expansions/mappings in the external vocabulary...

I don't think this is necessary. The problem is simply that semantic sugar doesn't constitute a "difference in term definition" -- and should be ignored (or normalized / "expanded away") by processors when comparing term definitions for protection rules. I think this is just a bug with jsonld.js (which may or may not also exist in other processors) that can be remedied.

... for reasons I don't understand, this didn't trigger the protected term redefinition error, presumably because @vocab is handled differently by the logic for this error or treated as a special case.

Yes, to my knowledge, @vocab is not protected in JSON-LD 1.1 implementations, only specific individual terms are.

cc: @davidlehn

danbri pushed a commit that referenced this issue Jan 15, 2024
@alex-jansen
Add Certification class (#3230) (#3441)
51121ce 
* add colorSwatch property (#3423)

* add new return method KeepProduct, #2880

* add Certification class #3230

* add logo to Certification

* renumber Certification examples due to numbering clash

* fix a build error conflict in Certification examples. Temp workaround
@duckladydinh duckladydinh mentioned this issue Mar 5, 2024
Open
@YePhyoAungGhost YePhyoAungGhost mentioned this issue Mar 20, 2024
Closed
@YePhyoAungGhost
Copy link

Thanks Matthias! Do you have a sense for how this application area relates to W3C Verifiable Credentials?
…
On Thu, 8 Dec 2022 at 09:59, Matthias Wiesmann @.> wrote: Many objects can bear some form of certification, Organizations can be ISO certified, Food products can be Organic or Vegan, a person can be a certified professional. There are certifications for many domains: regulatory, organizational, recycling, food, efficiency, educational, ecological, etc. Certifications can be first party (the certification authority makes the claim), second-party (an authorized party makes the claim), or self-certification (recipient of the certification makes the claim). Some certifications have a unique identifier, for instance the FSC (Forest Stewardship Council). Some schema.org objects have support for some specific certifications, for instance Product has hasEnergyConsumptionDetails, Person and Organization have hasCredential, but these are very specific. Adding specific attributes for all possible certification is not feasible. A certification would be an object with the following properties: - A certification unique identifier - A certification authority - A certifying organization (for second party) - A certification measurement (energy efficiency, CO² emissions). - The object of the certification (could be about). Certification could descend from CreativeWork — Reply to this email directly, view it on GitHub <#3230>, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABJSGKWMMGOMFDO5AVK323WMGWRPANCNFSM6AAAAAASX5VMBA . You are receiving this because you are subscribed to this thread.Message ID: @.>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@danbri danbri

Labels
no-issue-activity Discuss has gone quiet. Auto-tagging to encourage people to re-engage with the issue (or close it!). Queued for Editorial Work Editor needs to turn issues/PRs into final code and release notes.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests