beckn / beckn/protocol-specifications-v2
Review schema design guide for references to version
- Dominant language
- No language data
- Stars
- 15
- Forks
- 13
- PR merge metrics
- No merged PRs in 30d
Description
Ensure the Schema Design Guide's treatment of versioning matches what the actual repos do today, and what a static file host (no "latest" fallback, no smart resolution) requires going forward. This issue is to surface the gaps below — not to prescribe the fix for each.
**1. State the `v` prefix as a normative rule, not just an example.** Folder names and every URL reference to a schema (`$ref`, `$id`, `@context`, `@vocab`, `schemaContext`, and documentation links) MUST use a `v`-prefixed version segment (`v2.0`, not `2.0`). Every schema repo already does this on disk 100% of the time — the guide should say so explicitly rather than leaving it implied by example, since that's exactly the gap that let un-prefixed references slip into `beckn/schemas`, `beckn/local-retail`, and `beckn/DEG` (fixed in [beckn/local-retail#66](https://github.com/beckn/local-retail/pull/66), [beckn/DEG#487](https://github.com/beckn/DEG/pull/487), [beckn/schemas#69](https://github.com/beckn/schemas/pull/69)).
**2. Reconcile the versioning scheme with actual practice.** [Versioning requirements](https://github.com/beckn/protocol-specifications-v2/blob/draft/docs/Schema_Design_Guide.md#versioning-requirements) mandates 3-part SemVer (`MAJOR.MINOR.PATCH`), but every Beckn-authored schema pack in every repo uses 2-part (`vMAJOR.MINOR`) — there is no PATCH segment anywhere in practice. The guide and reality can't keep disagreeing, especially once a static host takes the folder name as the literal, unresolvable URL path. (One possible resolution, not a decision made here: make PATCH optional — `vMAJOR.MINOR[.PATCH]` — which would also reconcile with point 5 below.)
**3. Extend "no floating references" to a schema's own internal references, not just production consumers.** [Version pinning in production](https://github.com/beckn/protocol-specifications-v2/blob/draft/docs/Schema_Design_Guide.md#version-pinning-in-production) already prohibits `latest`-style floating references for implementations *consuming* a schema. The same rule needs to apply to a schema authoring its own cross-references — `$ref`s to other schemas within `attributes.yaml`/`schema.json`, `@import`s in `context.jsonld`/`vocab.jsonld`, and documentation links in `README.md`. We found and fixed exactly this failure mode: version-less internal references (e.g. `Quantity/context.jsonld` instead of `Quantity/v2.0/context.jsonld`) that happened to keep working only because the current app falls back to "latest" — a static host has no such fallback ([beckn/DEG#490](https://github.com/beckn/DEG/pull/490), [beckn/schemas#72](https://github.com/beckn/schemas/pull/72)).
**4. Update the domain in the guide's own examples.** The guide's example context blocks still reference `schema.beckn.io` (e.g. `"beckn": "https://schema.beckn.io/LinkedData/v2.1/context.jsonld"`, `"groc": "https://schema.beckn.io/Grocery/v2.0/vocab#"`). If `schema.nfh.global` is now the canonical domain schema authors should point at, the guide's examples should say so — an author copying the guide's own sample `@context` block today would write a stale domain into a brand-new schema.
**5. Vendored external specs may legitimately break the 2-part convention.** `beckn/DEG`'s `specification/schema/openadr/v3.1.0/` vendors a subset of the external OpenADR standard, and is versioned `v3.1.0` (3-part) to mirror OpenADR's own real release number, not a Beckn-authored version. This sits in tension with point 2's 2-part convention — a strict 2-part rule would either force a mismatch with OpenADR's real version number or require inventing a Beckn-side version unrelated to what was actually vendored. The optional-PATCH resolution suggested in point 2 (`vMAJOR.MINOR[.PATCH]`) would accommodate this case, but as with point 2, that's one possible resolution, not a decision made here.
Contributor guide
Assessment
This issue has not been assessed yet.