Need a formal schema design methodology (schema reuse/precedence) to avoid inconsistent semantics

### Background
Beckn Protocol v2's stated goals include **global semantic interoperability** through **JSON-LD** and "deep alignment with schema.org" (see repo root `README.md`).

At the same time, the repository currently lacks any documented *method* for how schemas should be authored when a well-defined schema already exists (schema.org or other domain vocabularies). This shows up as inconsistency both in:
- **core schemas** (data model design), and
- **API request/response schemas** (action/request modeling).

---

### Problem statement / risk
Without a documented **schema design decision procedure** (order-of-precedence / flowchart), schema authoring can become ad-hoc:
- Partially reusing existing schemas without a clear rationale.
- Minting `beckn:` property names even when schema.org properties exist (or mixing both patterns).
- Selecting between competing standards without repeatable criteria.

This is risky because it can:
- Reduce predictability for implementers.
- Create divergence between bundles / verticals.
- Undermine the goal of semantic interoperability even if JSON-LD mappings exist, because the surface JSON keys still differ.

---

### Evidence in this repo (examples)

#### A) Missing or incomplete documentation
- `schema/core/v2/README.md` is currently empty.
- `governance/README.md`, `docs/README.md`, and `CONTRIBUTING.md` are all "TBD".

This makes it hard to understand the intended rules behind core schema design choices.

#### B) Data-layer: `Order` is schema.org-mapped but not schema.org-named
File: `schema/core/v2/attributes.yaml` → `components.schemas.Order`

`Order` is declared as:
- `@type: beckn:Order` and mapped to `schema:Order` via `x-jsonld`.

However, several properties that exist in `https://schema.org/Order` are represented with `beckn:*` names and then mapped back to schema.org using `x-jsonld`, e.g.:
- `beckn:orderNumber` → `schema:orderNumber`
- `beckn:seller` → `schema:seller`
- `beckn:buyer` → `schema:customer`
- `beckn:orderItems` → `schema:orderItem`
- `beckn:acceptedOffers` → `schema:acceptedOffer`
- `beckn:orderValue` → `schema:priceSpecification`

This is a concrete example of a "partially composed" pattern (schema.org semantics, Beckn naming).

#### C) Pattern appears in multiple core/v2 schemas
Similar `beckn:*` → `schema:*` mappings are present in core/v2 for:
- `Offer`, `Payment`, `Invoice`, `Buyer`, `OrderItem`, `Fulfillment`.

So this looks systemic rather than limited to one schema.

#### D) API-layer: `/beckn/discover` request vs schema.org `SearchAction`
File: `api/beckn.yaml`
- `/beckn/discover` uses `components.schemas.DiscoverRequest`.
- `DiscoverRequest.message` includes custom fields such as `text_search`, `filters`, `spatial`, and also a **useful** `media_search` (multi-modal search) structure.

schema.org also has a standard action model for search: **https://schema.org/SearchAction**.

**Key insight / opportunity (not a Beckn-vs-schema.org framing):**
- Beckn's current `DiscoverRequest` includes modern, agent-friendly ideas such as **multi-modal search** (`media_search`), which is valuable in an emerging "agentic" paradigm.
- schema.org's `SearchAction` offers a globally recognizable *Action* abstraction (`SearchAction`, `target` as an `EntryPoint`, etc.) that could improve semantic interoperability for "search intent" itself.

So rather than choosing one over the other, the open question is:
> Can Beckn adopt a **schema.org-first** approach for the *action semantics* (SearchAction), while retaining/standardizing Beckn's richer multimodal search inputs as extensions?

---

### Request
Can the core WG / maintainers please document a **formal schema design methodology** (preferably as a flowchart / decision tree) that defines:

1. **Schema discovery/selection precedence**
- When designing a schema for a concept (e.g. EV Charger / Charging Station), what is the order of precedence?

2. **Reuse vs extend vs mint**
- If a schema exists in schema.org:
- do we reference it "as-is" (including property names), or
- do we keep Beckn property names and map them to schema.org via JSON-LD?
- If only a partial match exists:
- what is the extension pattern (compose / allOf / attributes packs / additional context) and how do we name properties?

3. **Action & API modeling guidance**
- When an API operation represents an *action* that already exists in schema.org (e.g. `SearchAction`), should the request/response model be:
- schema.org Action-first (SearchAction / EntryPoint / query-input style), **plus**
- Beckn extensions for advanced capabilities (e.g. multimodal `media_search`, spatial constraints, JSONPath filtering)?

4. **Handling multiple competing standards**
- If multiple candidate schemas exist, what criteria should be applied?
- preference for existing JSON-LD context?
- level of adoption?
- clarity/maintenance/governance?
- backward compatibility impact?

5. **When to create new Beckn vocabulary terms**
- Only after exhausting schema.org and other domain vocabularies?
- When minting is required, what are the naming conventions and mapping expectations?

---

### Strawman decision flow (proposal)
A starting point for discussion:

1. **Check schema.org** for a matching schema/type.
2. **If there is a full match**:
- reference/reuse it **as-is** (both type and property names).
3. **If there is a partial match**:
- look for domain-specific schemas/vocabularies (ideally linked-data/native JSON-LD).
4. **If there are multiple competing schemas**:
- prefer the one with an existing JSON-LD representation and strong adoption/governance.
5. **Only when there is literally no suitable schema**:
- fall back to non-JSON-LD standards/specs;
- and only then create a Beckn JSON-LD schema (with a clear mapping story).

**For API actions**:
- Prefer schema.org Action types to express *intent semantics* (e.g. `SearchAction`).
- Extend to support Beckn's advanced search capabilities (e.g. multimodal `media_search`, spatial constraints, JSONPath filtering), but do so in a consistent way.

---

### Suggested next steps
- Add this methodology to a permanent doc location (e.g. `schema/core/v2/README.md` or a new `docs/schema-design-guidelines.md`).
- Optionally add an ADR template for schema design decisions.
- Consider a future refactor discussion: represent `/beckn/discover` as a `SearchAction` (schema.org-first) with standardized Beckn extensions that preserve today's multimodal/spatial/filtering capabilities.

---

### References
- schema.org Order: https://schema.org/Order
- schema.org SearchAction: https://schema.org/SearchAction
- Beckn core v2 schemas: `schema/core/v2/attributes.yaml`
- Beckn API spec: `api/beckn.yaml`