[iherman]

This is a first draft for a formal vocabulary for Recognized Entities, using the same approach and tooling as in older vocabularies. Couple of remarks.

• The vocabulary is based on the assumption that it is a separate vocabulary from the VC vocabulary; this has not yet been agreed upon. If the decision is to fold into the VC vocabulary, then this yaml file will have to be merged. It worth reviewing it here, though, it is smaller and easier to do so.

• The repository contains all files, ie, the source yaml and template files as well as the generated turtle, jsonld, and html files. Once this becomes a bona fide vocabulary the same github trick will be used to 'hide' the original sources from github.io and, conversely, the generated file from the repository proper.

• In contrast to the VC vocabulary, the context file is also generated (the underlying yml2vocab tool has evolved over the years...)

• Ideally, all terms defined in the spec should have its own URL, preferably via a <dfn> tag. At the moment, the links to the formal definition go to the enclosing section. (I am happy to create a separate PR to add the definition tags, if it is all right with the editors). Done as part of this PR

• Obviously, validUntil and validFrom should be the values defined for VCs. However, in v2.0 of the vc vocabulary the domain of these properties were restricted to a VC or a VP. A RecognizedAction is neither of the two so, in theory, those terms cannot be reused. Solution: remove the domain restriction in v2.1 for VC (the vocabulary should evolve anyway). This was wrong: the domain is a RecognizedEntityCredential which is ok. There are issues on how to force them into the scoped context without redefining the domain, solution may be coming...

• There is a separate issue with the VCDM vocabulary that uses, in the context file, https://schema.org instead of http://schema.org. This is, in my view, a bug, see also Default schema prefix is http://schema.org/ which causes @protected issues with the VCDMv2 context. yml2vocab#57. The vocabulary in this PR bypasses the problem for now by not generating entries for the relevant terms (i.e., name or description) into the context file, but that may still come back biting us. To be solved somewhere else… (B.t.w., the feature of bypassing the context file was is buggy on the deployed version of yml2vocab, a new version is in the making.)

• I was not sure whether the term url in the property list was meant to refer to schema:url or whether it is used locally. For the time being it is not bound to schema, also in view of the previous point. Can be changed easily...

• An aesthetic problem: my Linked Data side is a bit bothered by the usage of the sameAs. This term, in the OWL namespace, is one of the fundamental terms on the Semantic Web. It is not formally wrong to use the same term in another namespace but may be misleading for Linked Data people. Is this now cast in concrete? (I do not think that semantically it would be o.k. to directly use owl:sameAs here.)

---

Preview | Diff

[msporny]

Suggest we don't version this (or anything else). It should go under just /vocab/, IMHO.

[iherman]

Let us not complicate things with github and leave this when we are otherwise o.k. with the content.

(I have no opinion about versioning, I follow the WG's decision on this)

[msporny]

We need to make sure the context file is static and exists under /contexts/v1rc1 to prevent a vendor from shipping it to production and destroying our ability to use the v1 context URL.

[iherman]

Again, let us leave this for whenever we think we are ok with the content.

[msporny]

LGTM as a first draft, with some suggested changes to align with the latest spec.

[iherman]

I have updated the vocabulary and the generated context file using the new yml2vocab feature of explicit scoping (w3c/yml2vocab#59). @dlongley I would appreciate a review of the vocab and the context file.

I am not sure of they way I translated issuer which refers to a Class used in an example but that is not defined elsewhere formally. For the 'generic' properties I scoped all of them to RecognizedEntityCredential because that is what the text says...

[iherman]

This was discussed during the vcwg meeting on 08 September 2026.

View the transcript

Draft vocabulary definition by iherman · Pull Request #122 · w3c/vc-recognized-entities · GitHub

---

[iherman]

The latest changes include

• Using <dfn> for all the terms in the index.html file
• Using the formal definition pointers in the vocabulary (plus some minor bugs taken out)
• Added an initial mermaid diagram for the classes

cc @msporny @dlongley

[iherman]

but I would not expect new vocabulary terms to be created for anything from the core VCDM vocabulary.

If that term is a subclass/subproperty, then I do not see the problem. It, sort of, "inherits" things from VCDM (although, in the RDF world, this terminology is misleading) but it has its local specificities...

[msporny]

@iherman I can't tell how close this PR is to merging? Is there more that needs to be done to it before a merge?

[iherman]

@iherman I can't tell how close this PR is to merging? Is there more that needs to be done to it before a merge?

I am sure there will be updates and improvement of the vocabulary, but that is fine to happen in subsequent PR-s.

However... this PR includes changes on the index.html file (the added dfn-s) I am not sure those have been reviewed.

B.t.w., once we have decided on the final URL for the context file (URL that should now redirect to the one generated by this PR), all examples in the spec document will have to be updated, adding a reference to that context.

[msporny]

We shouldn't commit the vocabulary.ttl, vocabulary.jsonld, vocabulary.html files, as those can be auto-generated from the vocabulary.yml during the publishing/build process.

There are also some re-definitions of schema.org that we don't want to do here.

[iherman]

We shouldn't commit the vocabulary.ttl, vocabulary.jsonld, vocabulary.html files, as those can be auto-generated from the vocabulary.yml during the publishing/build process.

Yes, that is the goal. But that requires a completely new action, and a modification of the current one (to avoid unnecessary echidna actions). Note that a separate echidna script for the threat model is also missing.

Wouldn't it be better to do the GH actions in a separate PR after we merge this? Once everything is operational we can remove the generated files from the repository.

[msporny]

@iherman wrote:

leave the files unprocessed in the repo and set up a separate PR for the GH actions

I meant the one above.

If you want me to, I can rewrite the history of this PR to remove the auto-generated files, and then we can do a clean merge.

I agree with you, this PR is already big, we don't need to make it bigger. The auto-generation is just an Editorial thing that can be done later on the main branch (I'm happy to take an action to do it). Once that's done, we'll auto-generate and publish the vocabulary files to the ED draft space and can manually copy the proper files to the appropriate v1rc1 location.

[iherman]

If you want me to, I can rewrite the history of this PR to remove the auto-generated files, and then we can do a clean merge.

What happens if I modify the .gitignore file on my end to disregard the original files that should not be on the repo? I would prefer that because I do need a local processing of the yml file to check this We do not have a .gitignore file on the repo, so I can use a local, .gitignore-d .gitignore...

Be careful not to remove the .mmd file. At the moment that is done by hand, and should be added to the final pages. Maybe at some point it will be generated as well (see w3c/yml2vocab#63).

[TallTed]

Despite, or because of, its size, this PR looks OK to me.

[iherman]

@msporny I have removed the to-be-generated files from the vocabulary folder, as agreed. There some other things to do, notably

• create the necessary github actions
• adding the registration term
• maybe optimizing the context file more
• set up redirections for the vocab and context

But I would prefer to merge this PR first and take those one by one. If you agree, could you merge?

[iherman]

@msporny will you merge it or should I (I am not sure I should merge a PR for a document that I am not an editor of)

[msporny]

@msporny will you merge it or should I (I am not sure I should merge a PR for a document that I am not an editor of)

I'm working on cleaning up the history (merge conflicts, files that shouldn't have been checked in, etc.) now, I will merge once I get it all cleaned up.

[msporny]

Editorial, multiple reviews, changes requested and made, no objections, merging.

[msporny]

@iherman I had to do some extensive rebasing to fix the conflicts and merge history, let me know if I ended up breaking something.