Repository navigation
back to basics - what is recognized-entity for? #140
Description
Thank you everyone of a productive discussion on the call today. I'm writing this ticket while thoughts are fresh in my head.
What's a recognized entity (r-e) credential for?
There were some good points about not "overloading" the r-e credential. STating clearly what it's for helps to avoid such overloading. In my view, the r-e serves one purpose - it's for a list-owner to say to a list member "you are on my list" in way that can be cryptographically chained". The list can have varying degrees of formality:
- Ted's list of friends might include Phil
- The local football club has a list of members
- ACME maintains a list of employees
- The UK Companies house maintains a list of registered UK companies
- The UN maintains a list of member state registers.
The r-e spec is designed for all these levels of formality - because it's just a way to say (in a cryptographically verifiable way) - "you are on my list". Do we all agree on that?
List membership ID vs cryptographic linking ID
If we agree the first point then the follow on inevitability is that list owners usually have a unique identifier for the members of their list - for example Australian Business Number 12345678911. This is the ID that is often in a public register - and correspondingly must have a home in the r-e credential. This identifier will (should?) always be different to the did of member - because the registered ID is created by the list owner whilst the did is created by the list member. These two IDs serve very different purposes
- the list owner's ID is very often what a verifier wants to know - "are you really this AU business 12345678911?
- the did of the member is what allows the cryptographic chaining - because it's what signs the chained credential. The chain is then verified by checking that the issuer did of the chained credential (eg an invoice) is the same as the subject sis of the r-e credential.
So both of these identifiers are fundamentally necessary in every r-e. Without the subject registeredID, the verifier doesn't know who you are. Without the subject did there is no way to verify a chain - which kind of defeats the purpose of the r-e in the first place.
this is an omission in the current data model - as there's no place to specify the ID as known to the list owner.
Membership often comes with some kind of Scope
- Teds list of friends might distinguish between family and friends
- ACME's list of employees may carry a role and may need to distinguish between contractors and permanents.
- A company register will always specify a "legal form" (company, parthership, not-for-profit, etc). Here's the Ausrtlaian business register's list of legal forms https://abr.business.gov.au/Help/EntityTypeList.
- An accreditation authority will usually define scope as a list of standards of quality schemes against which the subject (certifier) is accredited to assess against.
- and so on.
In most cases, this recognition scope is not about actions. What we agreed today is that there are different kinds of recognitionScope and that a recognised action is only one of them. A company register is not going to specify a list of actions (unless "anything that a company can legally do" is an action worth recognising) but they very much will want to specify the legal form.
It is this recognition scope area that is both the most complex and the place where I think this group has jumped to one type of scope (an issue action constrained by a schema). For now I'd like to seek consensus that
- we need to support the breadth of recognitionScope use cases. That doesn't preclude recognizedActions but I don't think it's the right semantic for a general recognitionScope - it'll cause the same confusion and discussion we've been having. A list of actions is one type of thing that could be in a recognitionScope
- we need NOT make sure that the validation rules for every scope are in the r-e credential. In many cases, these validation rules MUST be defined at a different layer (ie over the graph derived from many credentials). That's because the validation often starts at the linked credential not the r-e - for example, when verifying an invoice VC, I may ask "is there a linked r-e where r-e subject did == invoice issuer did AND is the r-e registeredId == invoice sellerId?" That (very common) kind of rule has to be attached to the invoice not the to the r-e.
so this is less of an "omission" in the current data model, more like an unintended narrowing of purpose and possible over-reliance on one kind of validation method.
How UNTP DIA handles this
is documented here https://untp.unece.org/docs/specification/DigitalIdentityAnchor. However please note that we need to do another iteration over this to further improve alignment with r-e. There's also things in there that dont need to be in W3C r-e as thay are just DIA specifc properties. nevertheless, the two properties in the DIA data model that I wish were int he W3C r-e credential are
- registeredId (ie how the list owner idenfies the subject)
- recognitionScope (is the generalisation of "recognizedTo, recognisedAs, etc)
Activity
msporny commentedon Oct 13, 2026
The group might also want to consider what schema.org did here: https://schema.org/identifier#eg-0373
... it feels like
registeredIdandregisteredSchemeis (somewhat) re-creating whatidentifierandPropertyValuedoes usingpropertyIDandvalue, plusidentifiercan be a string or a URL as well.hmm, couple of ways we could go about this, just brainstorming right now, not really attached to any of these yet. First, some thoughts:
Generalizing them into a broader category might make the concepts more difficult to understand. If we wanted to generalize, alternatives to
recognitionScopeincluderecognitionDomain,recognizedCapacity,recognizedEntitlementand possiblyrecognizedFor(acting as X / doing Y).recognizedAsstrikes me as a bit strange, because it's on theRecognizedEntityobject, so things like identifiers, who they are recognizedBy and the rules that go along with that recognition, and other properties of the entity seem strange to be put under arecognizedAsproperty... why are we separating these properties out from the properties associated with the entity? Why not just put these properties (which are basically all the things inRegisteredIdentity) on theRecognizedEntityobject? If we do that, then we're just back to having a bunch of properties (likeidentifierandrecognizedToand possiblyrecognitionScopeon theRecognizedEntityobject).I've taken a look at https://untp.unece.org/docs/specification/DigitalIdentityAnchor/ and have some concerns around the data modelling there, which seems to mix a registration record w/ the entity itself. My concern is that is leaking into the data model here in ways that blur what we're trying to model here. Perhaps we should take some time on the next call to talk through this (exactly what are we trying to model here, and how do people elegantly extend the base primitive we have).
It may be that we absorb parts of DIA into RE (as you suggest above), or we rearrange RE so that it's easier for DIA to extend it.
msporny commentedon Oct 13, 2026
We discussed this issue on the call today and we are going to raise a pull request that re-uses
identifierfrom schema.org to express an identifier for the RecognizedEntity (as a URI, primarily, but could also be a more expressive object per schema.org).onthebreeze commentedon Oct 13, 2026
And then we agreed that this registeredID thing is a property of the registration entity that we would add and for which I'd propose a data model. So perhaps the way forward is that I update the draft UNTP DIA to be a recognised entity credential with a new
registrationproperty - then this group decides how much of that registration property to formalise in the W3C spec?grouping all our needs into
registrationis a great idea by the way @msporny. Also solves the registeredId issue - because it now becomes simply the id property of registration.msporny commentedon Oct 14, 2026
@onthebreeze wrote:
I was reminded yesterday that this is a pattern we're following in two other market verticals: Identification cards (driver's licenses, student IDs, first responder IDs) -- see the
identificationDocumentexample:https://w3id.org/identification#example-a-basic-example-of-the-identification-document-credential-expressed-as-json-ld
... and Vehicle titles, registration and insurance -- see the
owner.hasCertificationfield:http://w3id.org/vvc#example-a-verifiable-credential-representing-a-vehicle-title
Those are
registration-like mechanisms. TheVehicleTitleis also kinda-sorta a type of "registration", though one that is heavily biased by trying to match paper vehicle titles today (which leave a lot to be desired from a data modelling standpoint, so I wouldn't let it influence your direction too heavily). Just food for thought as you go about your remodeling attempt.iherman commentedon Oct 16, 2026
This was discussed during the vcwg meeting on 14 October 2026.
View the transcript
w3c/vc-recognized-entities#140
manu: Here's issue 140 -- it's an existential question about what we're actually doing. Good news is that we made some good forward progress on this yesterday. We're getting more interest in the RE spec from different market verticals.
manu: Initially it was education and vital records and UNTP and supply chain stuff, GS1, brought in use cases. Now we also have DPP and people from Switzerland.
manu: Lots of great uses of this -- the group is struggling with how big the scope ought to be for the work and can we provide a minimum set of primitives for use across all these different verticals.
manu: So the question came up -- how does one say that you recognize a particular entity under a particular scope -- and say that it's limited to say, Australia or Japan or whatever.
manu: We're going to raise PRs to try and answer that question over the next week or two and that we have a handle on the problem now too. It might be through a simple property like "registration" that talks about the regulation, scope, and those types of things -- without breaking existing use cases.
manu: We have consensus in the group to address this we think and the plan is to define a property for this and test against the use cases from groups that have raised this or asked about it.
manu: I think that's where we are right now and it's the last big issue in the spec before CR.
Carolynn: You aren't trying to model scope?
manu: We are trying to do that -- we will have a solution to your problem, we believe we will be able to express scope with some of the future PRs.
Carolynn: Ok, thank you.
brent: Awesome, that was a fun little deep dive. Thank you, Carolynn for starting us off.
brent: Kayode you're next on the queue.
kezike: Quick update first -- we've been going through outstanding issues these last few weeks. We have been making sure we have a handle on them and figuring out which we want to address before CR.
kezike: One of them we've made good progress on but there's still an ask for this group that is around BBS support and another that is around enabling the holder in the three party flow -- to enable an exchange to be explicitly terminated by them rather than just abandonment.
kezike: We filed an issue in the VC data model issue tracker for this.
msporny commentedon Oct 19, 2026
I made an attempt at a PR to address this issue here: PR #142
msporny commentedon Oct 31, 2026
PR #142 has been merged, closing.