beckn / beckn/protocol-specifications-v2

Review schema design guide for references to version

Open
#195 0 comments 0 reactions 1 assignee Claimed by @nirmalnr View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.