Upgrade `beckn/mobility` to Beckn Protocol v2.0 Compatibility

[ravi-prakash-v]

Background

Beckn Protocol v2.0.0 (Release Candidate) introduces a JSON-LD + schema.org-aligned core schema, updated APIs, and refreshed reference flows intended for next-gen Beckn networks. ([GitHub][1])
The current beckn/mobility repository is based on earlier protocol generations and must be updated to remain interoperable with the v2 core specification and tooling. ([GitHub][2])

This issue tracks the work needed to make the mobility domain spec structurally compatible with v2.0 (schemas, examples, docs, and validation).

---

Goals

1. Align mobility domain models and flows with Beckn Protocol v2.0 core schemas and semantics. ([GitHub][1])
2. Adopt v2-style JSON-LD modeling (contexts, vocab strategy, schema compatibility). ([GitHub][1])
3. Update mobility docs, examples, and validations so implementers can confidently build against v2.
4. Preserve domain intent while making breaking changes explicit and well-migrated.

---

Non-goals (for this issue)

• Creating brand-new mobility subdomains/features beyond parity migration.
• Refactoring unrelated repo infrastructure unless required for v2 validation/tooling.

---

Scope of Work (Deliverables)

A) Audit + Gap Analysis

• Inventory current mobility spec artifacts (schemas, examples, flows, glossary) and versions.

• Identify what is core-inherited vs mobility-specific.

• Create a “v1/v0.x → v2 mapping” doc:

  • message structure deltas
  • entity/property renames
  • deprecated/removed fields
  • semantic shifts needed for schema.org alignment ([GitHub][1])

Output: docs/migration/v2-gap-analysis.md

---

B) Schema & JSON-LD Alignment

• Rebase mobility schema definitions onto v2 core schema conventions.

• Introduce/refresh JSON-LD assets as required by v2 approach (context/vocab strategy consistent with v2 repo patterns). ([GitHub][1])

• Ensure mobility-specific extensions are:

  • cleanly namespaced
  • consistent with schema.org-aligned modeling
  • documented with rationale and examples ([GitHub][1])

Output: Updated schema folder(s) and JSON-LD artifacts aligned to v2.

---

C) API & Flow Updates

• Update mobility flows to match v2 API behavior and sequencing assumptions.
• Update endpoint naming/paths only as required by v2 (avoid gratuitous churn).
• Ensure example payloads validate against v2-aligned schemas.

Output: Updated docs/ flows + examples/ payloads.

---

D) Validation, Tooling, and CI

• Add automated schema validation to CI (JSON Schema + JSON-LD sanity checks where applicable).
• Provide a minimal “how to validate locally” script or documented workflow.
• Ensure repo remains easy to consume (clear README, versioning notes).

Output: CI checks + docs/validation.md

---

E) Migration Guide for Implementers

• Publish MIGRATION_GUIDE_V2.md including:

  • what breaks (and why)
  • mapping tables for key objects/fields
  • sample “before/after” payloads
  • recommended rollout strategy for networks/apps (dual-stack, adapters, etc.)

Output: Implementer-facing migration doc.

---

Acceptance Criteria (Definition of Done)

• Mobility spec compiles/validates against Beckn Protocol v2.0 assumptions and schema structure. ([GitHub][1])
• All example payloads validate under the updated schema checks in CI.
• Clear versioning is published (tag/release) and README explicitly states compatibility.
• Migration guide is actionable and covers the top 80% implementer pain points.

---

Risks / Notes

• v2 is a release candidate and may still evolve; design should anticipate minor churn (keep adapters/mappings modular). ([GitHub][1])
• JSON-LD + schema.org alignment can surface modeling ambiguities; document decisions to avoid “spec drift by vibes.” ([GitHub][3])

---

References

• Beckn Protocol v2.0 repository (RC): beckn/protocol-specifications-v2 ([GitHub][1])
• Beckn Protocol core repo (historic context): beckn/protocol-specifications ([GitHub][4])
• Mobility spec repo overview/history: beckn/mobility ([GitHub][2])
• MaaS standards landscape reference (context for mobility interoperability expectations):

---

Suggested Breakdown into Child Issues

1. [Mobility→v2 Gap Analysis + Mapping]
2. [Schema/JSON-LD Rebase for Mobility]
3. [Flow & Example Payload Updates]
4. [Validation + CI Integration]
5. [Migration Guide + Release Notes]