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

### 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](https://github.com/beckn/protocol-specifications-v2)][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](https://github.com/beckn/mobility)][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](https://github.com/beckn/protocol-specifications-v2)][1])
2. Adopt **v2-style JSON-LD modeling** (contexts, vocab strategy, schema compatibility). ([[GitHub](https://github.com/beckn/protocol-specifications-v2)][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](https://github.com/beckn/protocol-specifications-v2)][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](https://github.com/beckn/protocol-specifications-v2)][1])
* [ ] Ensure mobility-specific extensions are:

* cleanly namespaced
* consistent with schema.org-aligned modeling
* documented with rationale and examples ([[GitHub](https://github.com/beckn/protocol-specifications-v2)][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](https://github.com/beckn/protocol-specifications-v2)][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](https://github.com/beckn/protocol-specifications-v2)][1])
* JSON-LD + schema.org alignment can surface modeling ambiguities; document decisions to avoid “spec drift by vibes.” ([[GitHub](https://github.com/beckn/protocol-specifications-v2/issues/63)][3])

---

### References

* Beckn Protocol v2.0 repository (RC): `beckn/protocol-specifications-v2` ([[GitHub](https://github.com/beckn/protocol-specifications-v2)][1])
* Beckn Protocol core repo (historic context): `beckn/protocol-specifications` ([[GitHub](https://github.com/beckn/protocol-specifications)][4])
* Mobility spec repo overview/history: `beckn/mobility` ([[GitHub](https://github.com/beckn/mobility)][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]**