[VC-1161] [VC-1162] updated tn, org-identity and brand owner schemas#32
[VC-1161] [VC-1162] updated tn, org-identity and brand owner schemas#32Arsh-Sandhu wants to merge 5 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the OVC Org Identity, OVC Brand Owner, and TN Allocation credential schemas/docs to v2, aligning them with JSON Schema draft 2020-12 and expanding field descriptions and constraints.
Changes:
- Bump schemas to version
2.0.0, update$schemato draft2020-12, and refresh schema SAIDs inregistry.json. - Revise TN allocation attributes to support array-based number expressions (single numbers + inclusive ranges) and multi-channel scoping.
- Expand documentation in the
index.mdfiles to explain intent, semantics, and edge/rules structure.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 17 comments.
Show a summary per file
| File | Description |
|---|---|
| tn-alloc/tn-alloc.schema.json | Updates TN allocation schema to v2 with richer constraints and revised attributes/edges/rules structure. |
| tn-alloc/index.md | Rewrites TN allocation documentation to explain number expressions, channels, edges, and governance. |
| tn-alloc/example-tn-alloc.json | Updates example payload to match TN allocation v2 structure (numbers array, channel array, updated SAIDs). |
| registry.json | Updates registry entries to new schema SAIDs for tn-alloc, ovc-org-vet, and ovc-brand-owner. |
| ovc-org-vet/rules.json | Removes the standalone rules JSON file. |
| ovc-org-vet/ovc-org-vet.schema.json | Updates OVC Org Identity schema to v2 with stronger patterns/examples and revised attributes/rules/edges. |
| ovc-org-vet/index.md | Updates OVC Org Identity documentation to reflect new intent and field structure. |
| ovc-brand-owner/ovc-brand-owner.schema.json | Updates OVC Brand Owner schema to v2 with stronger patterns/examples and revised attributes/rules/edges. |
| ovc-brand-owner/index.md | Expands OVC Brand Owner documentation and usage guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "o": { | ||
| "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", | ||
| "description": "Issuer-To-Issuee operator: the issuer AID of this ACDC MUST be the issuee AID of the node this edge points to.", | ||
| "type": "string", | ||
| "const": "I2I" | ||
| "default": "I2I", | ||
| "examples": [ |
| "o": { | ||
| "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", | ||
| "description": "Issuer-To-Issuee operator: the issuer AID of this ACDC MUST be the issuee AID of the node this edge points to.", | ||
| "type": "string", | ||
| "const": "I2I" | ||
| "default": "I2I", | ||
| "examples": [ |
|
|
||
| ### Required and optional attributes | ||
|
|
||
| Only `i` (issuee AID) and `dt` (issuance datetime) are required in the attributes block. `vcard` and `goals` are both optional, though in practice a brand owner credential without a `vcard` is of limited use. Both fields may be selectively disclosed. |
Arsh-Sandhu
changed the title
| { | ||
| "description": "Rules section SAID", | ||
| "type": "string" | ||
| }, |
| The `r` (rules) block uses citation-style rules inherited from the credential design: the listed legal identifiers are citations — they point to external registry records. The rules make explicit that: | ||
|
|
||
| - Pointing to an identifier does **not** imply endorsement of or agreement with the cited content (`onlyCommitToPoint`). | ||
| - The credential is not meant to be used in isolation; its semantics are communicated via referencing ACDCs (`useViaEdges`). | ||
| - Verifying the authenticity of the cited external data is the verifier's responsibility (`undefinedVerification`). | ||
| - Revocation of the credential and revocation of the cited data are independent events (`undefinedRevocation`). | ||
| - A `governance` field must identify the governance framework under which the credential was issued. |
| | `issuer` | No | Links to an identity credential (e.g., OVC Org Identity, vLEI) proving the identity of the issuer. Uses `I2I` operator. | | ||
| | `brandauth` | No | Links to a credential proving brand authority — e.g., a trademark registration or license agreement. Uses `I2I` operator. | |
|
|
||
| | Edge | Required in block? | Purpose | | ||
| |---|---|---| | ||
| | `issuer` | No | Links to an identity credential proving the identity of the issuing vetter (OVC). Uses `I2I` operator — the issuer AID of this credential must be the issuee AID of the referenced credential. | |
| | `issuer` | No | Links to an identity credential (e.g., OVC Org Identity, vLEI) proving the identity of the issuer. Uses `I2I` operator. | | ||
| | `brandauth` | No | Links to a credential proving brand authority — e.g., a trademark registration or license agreement. Uses `I2I` operator. | |
|
|
||
| | Edge | Required in block? | Purpose | | ||
| |---|---|---| | ||
| | `issuer` | No | Links to an identity credential proving the identity of the issuing vetter (OVC). Uses `I2I` operator — the issuer AID of this credential must be the issuee AID of the referenced credential. | |
dhh1128
left a comment
dhh1128
left a comment
There was a problem hiding this comment.
Review against the stated success criteria
Thanks @Arsh-Sandhu — solid PR. Mechanically it's in good shape: all three schemas are valid JSON-Schema Draft 2020-12, every $id/nested-block SAID recomputes correctly and matches registry.json, and example-tn-alloc.json validates against the new tn-alloc schema.
Scorecard:
- version ✅ — all
1.0.0→2.0.0(see inline note to confirm the GSMA-trial value). - names ✅ (mostly) — titles use OVC / "Org Identity" / no dossier-vs-credential misuse; residual "org vet" wording noted inline.
- rules ✅ —
governancestatement present in all three (but see the org-identity citation-rules blocker inline). - constraints
⚠️ — strong regexes forv/d/i/ri/s, LEI, E.164,channelenum,LOA; gaps noted inline (E.164 leading zero, unconstrainedu, and the compact-form SAID strings:ovc-org-vet/ovc-brand-ownerpattern-constrain the compactrstring, but tn-alloc's compacta/e/rbranches are baretype: string— pin^E[A-Za-z0-9_-]{43}$for consistency). - examples ✅ (mostly) — most fields have believable examples; see pre-existing
vcardnote below. - docs ✅ — all three have substantial
index.md; defects noted inline + below. - multichannel ✅ (strongest part) — tn-alloc makes
channelan optional["sms","voice"]array (one channel-agnostic credential, no proliferation), and brand-owner usesgoalsto scope channel/purpose. Well reasoned in the docs and exactly the "single type, optional" direction we wanted.
Top things to address: (1) the citation-semantics rules on the org-identity credential, (2) the legalIdentifiers schema↔doc contradiction, (3) the doc defects below.
Pre-existing issues (outside this diff, so not inline — but worth fixing while here)
These live on lines the PR didn't change, so GitHub won't let me anchor a comment:
ovc-org-vet/index.mdLoA table is broken & has typos: the "gold" (LoA 3) row is column-shifted (its<ol>landed in the intended meaning column, with a stray</li></li>and a missing<li>);threshhold→ "threshold";FBAC→ FBCA (correct once, then misspelled 3×);ISO/IEC 2915→ ISO/IEC 29115; LoA 1 row duplicates "tools" ("legalities, tools, governance, tools…").ovc-brand-ownervcard/goalsuseformat: "cesr"on items that are vCard content lines / Aries goal codes (not CESR primitives) — questionableformat. Also thevcardexamplesarray lists individual strings at the array level, so each "example" isn't a valid instance of the array property (wrap as one example array, or move underitems).
Full off-PR write-up is in my review notes; happy to expand on any of these.
| "items": { | ||
| "type": "string", | ||
| "description": "A single E164 telephone number or an inclusive range. Single number: '+' followed by 7-15 digits. Range: two E164 numbers separated by a hyphen (e.g., '+15551230000-+15551239999').", | ||
| "pattern": "^\\+[0-9]{7,15}(-\\+[0-9]{7,15})?$" |
There was a problem hiding this comment.
E.164 regex is slightly too permissive. ^\+[0-9]{7,15}(-\+[0-9]{7,15})?$ allows a leading zero, but E.164 country codes never start with 0. Suggest pinning the first digit non-zero:
^\+[1-9][0-9]{6,14}(-\+[1-9][0-9]{6,14})?$
(Range start≤end and equal-length endpoints can't be enforced in regex — the index.md correctly defers that to verifier evaluation, which is fine.)
| "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" | ||
| ] | ||
| }, | ||
| "u": { |
There was a problem hiding this comment.
u (salt) is unconstrained here and in the other two schemas (type: string, no pattern). Per the "constrain inputs as much as possible" goal, consider a pattern for a 128-bit CESR salt, e.g. ^0A[A-Za-z0-9_-]{22}$.
Also: top-level required is inconsistent across the three schemas — tn-alloc requires u, but ovc-org-vet and ovc-brand-owner make it optional. Pick one convention and apply it uniformly.
| "type": "object", | ||
| "credentialType": "TNAllocationCredential", | ||
| "version": "1.0.0", | ||
| "version": "2.0.0", |
There was a problem hiding this comment.
version: bumped 1.0.0 → 2.0.0 on all three — good (≥ 1.0 and differs from the value on main). Just confirming: the GSMA-trial schemas were at 1.0.0, so 2.0.0 satisfies "must differ from the trial version". If the trial actually shipped something other than 1.0.0, double-check there's no collision.
(Minor: version is a non-standard JSON-Schema keyword — ignored by validators — but it's the existing repo convention, so fine.)
| "type": "object", | ||
| "properties": { | ||
| "type": { | ||
| "description": "Category or source of the identifier (e.g., lei, gleif, gb, che, duns, edgar, domain, linkedin, etc.)", |
There was a problem hiding this comment.
Schema ↔ doc contradiction. This lists domain and linkedin as example type values, but index.md says "Domain names and social media handles are intentionally excluded: they do not unambiguously identify a legal entity." One of the two is wrong — reconcile.
Separately, the example vocabulary differs between schema (gb, che) and doc (uk-crn, che, us-ein). Consider a single controlled vocabulary for type (even just consistent examples).
| "LOA": { | ||
| "description": "Level of Assurance \u2014 a positive number where larger values denote higher assurance (1=bronze, 2=silver, 3=gold). Integer values represent defined tiers; decimal sub-values (e.g., 2.1) allow nuance within a tier. Verifiers should accept any credential where LOA is >= their required threshold.", | ||
| "type": "number", | ||
| "minimum": 0, |
There was a problem hiding this comment.
Redundant bounds. minimum: 0 together with exclusiveMinimum: 0 is contradictory. If LOA can be zero, then eclusive is wrong; if not, then minimum is wrong.
| "type": "string", | ||
| "pattern": "^E[A-Za-z0-9_-]{43}$", | ||
| "examples": [ | ||
| "EAoRVmgPyacjhUxaV0nPwiuUuHMjKDpNZrj7ClofZ-3Z" |
There was a problem hiding this comment.
Stale s example. This uses EAoRVmgPyacjhUxaV0nPwiuUuHMjKDpNZrj7ClofZ-3Z, which is the brand-owner schema's old (pre-PR) SAID; the new $id is EImfvpfRx4YKhTzAzdZzCCjSNmwtY5yw9QlpZirG6OUa. A self-referential s example should show the current schema SAID. (Same old SAID is reused as the brandauth.s example further down.)
|
|
||
| **At least one identifier should be globally unambiguous and portable across jurisdictions** — typically an LEI. National registry IDs (like UK Companies House `gb` or Swiss `che` numbers) are also valid and can coexist with the LEI. | ||
|
|
||
| Domain names and social media handles are intentionally excluded: they do not unambiguously identify a legal entity across jurisdictions. |
There was a problem hiding this comment.
Contradicts the schema: ovc-org-vet.schema.json lists domain and linkedin as example legalIdentifiers types, but here they're "intentionally excluded." Pick one and align both.
|
|
||
| The OVC Org Identity Credential is analogous in intent to the [LE vLEI](https://docs.origincloud.net/start/concepts/creds/vleis) defined by GLEIF (which maps to LoA 3), but its schema is designed to be simpler and to accommodate a wider range of national registry sources. | ||
|
|
||
| <br> |
There was a problem hiding this comment.
Residual "org vet" naming. The title was updated to OVC Org Identity Credential (good), but the body still says "org vet" / "Org vet credentials" in places, and the image assets are org-vet-*.png/.svg. For consistency with the naming goal ("use 'org identity' rather than 'org vet'"), update the prose and consider renaming the image files (and eventually the directory).
No description provided.