# Migration Guide: October 2025 Schema ID Normalization

This document describes the breaking / notable changes introduced during the October 2025 registry expansion & hygiene pass.

## Summary

We performed a comprehensive normalization of schema identifiers, added a large new family of governance / lineage / valuation / analytics schemas, and enforced consistent metadata for UI prefills.

### Key Themes

- Canonical `$id` host alignment: `https://semanticord.org/schema/` (previously some schemas used `https://semanticord.org/schema/`).
- Removal of legacy "Payload" suffix in `$id` and filenames (e.g. `omniRFQPayload` -> `omniRFQ`).
- Introduction of explicit `x-prefill.domainPayloadExample` for every schema to ensure rich UI prefills instead of synthetic fallbacks.
- Extended schema catalog (16 new schemas) to cover governance, lineage, risk, analytics, impact, valuation.
- Added (or reserved) `x-relations` for richer graph semantics (some enrichment still pending—see Roadmap).

## Affected Existing Schemas

| Old Filename / $id (illustrative)                       | New Filename / $id                                                   | Notes                     |
| ------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
| `omniRFQPayload.v1.json` / `.../omniRFQPayload.v1.json` | `omniRFQ.v1.json` / `https://semanticord.org/schema/omniRFQ.v1.json` | Dropped `Payload` suffix. |
| `geoBidAuctionPayload.v1.json`                          | `geoBidAuction.v1.json`                                              | Dropped `Payload` suffix. |
| `predictAIForecastPayload.v1.json`                      | `predictAIForecast.v1.json`                                          | Dropped `Payload` suffix. |
| Mixed host `https://semanticord.org/...`                 | `https://semanticord.org/...`                                        | Unified host.             |

(If you reference any of the old `$id` values you must update them.)

## New Schemas Added

```
policy.v1.json
accessRevocation.v1.json
dataLineage.v1.json
riskAssessment.v1.json
revisionLog.v1.json
capabilityStatement.v1.json
externalAnchorBatch.v1.json
organizationProfile.v1.json
consentRecord.v1.json
deprecationNotice.v1.json
rollingMetric.v1.json
cohortAnalysis.v1.json
qualityException.v1.json
impactMethodology.v1.json
valuationModel.v1.json
eventTypeCatalog.v1.json
```

Each ships with:

- Draft 2020-12 base
- Canonical `$id` under unified host
- `x-prefill.memoryUnit` block (with `event.type` / `kind` / `schemaRef`)
- `x-prefill.domainPayloadExample`

## Consumer Action Items

1. Update all hard-coded `$id` references to the new canonical host & names.
2. If you validated on previous `*Payload` IDs, add aliases (optionally maintain a compatibility map) or migrate stored documents.
3. Ensure your Memory Unit generator reads `event.type` (preferred) with fallback to `eventType` if you still handle older envelopes.
4. Rebuild any local caches of schema hashes; the hash values changed for normalized schemas.
5. If you ingest by schema filename, adjust for renamed files (remove `Payload`).

## Compatibility Strategy

No runtime aliasing layer is currently provided in the registry. If you require backwards compatibility:

- Maintain a local map from old -> new `$id`.
- During ingestion, rewrite old `$id` to new before validation.
- Reject (or log) documents using deprecated IDs after a grace period.

Example mapping snippet:

```json
{
  "https://semanticord.org/schema/omniRFQPayload.v1.json": "https://semanticord.org/schema/omniRFQ.v1.json",
  "https://semanticord.org/schema/geoBidAuctionPayload.v1.json": "https://semanticord.org/schema/geoBidAuction.v1.json"
}
```

## Prefill Metadata Changes

Every schema now exposes a curated `x-prefill.domainPayloadExample` object. If your UI previously depended on synthesized payloads, you can prefer the curated example when present:

Pseudo-logic:

```js
const example =
  schema?.["x-prefill"]?.domainPayloadExample || synthesize(schema);
```

## Hashes

All schema hashes were recomputed after changes. See `registry/schemas.v1.json` or run:

```
node scripts/compute-schema-hashes.mjs
```

## Roadmap / Pending Follow-ups

- Lint script enforcement (naming, presence of examples, relations) – In Progress.
- Expanded `x-relations` graph enrichment (impact ↔ methodology, valuation ↔ price index, etc.).
- Potential alias file for deprecated `$id` (if demand justifies).

## FAQ

Q: Why change the host?
A: Unifying under a single neutral umbrella reduces fragmentation and future-proofs multi-project adoption.

Q: Why remove `Payload` suffix?
A: It was redundant; each file already represents a schema for a document payload. Shorter IDs improve readability and reduce integration friction.

Q: How do I detect old IDs?
A: Regex: `/semanticord\.si\/schema\/(.+?Payload\.v1\.json)/`

Q: Will versions increment?
A: Not for this normalization; semantic content unchanged for renamed schemas. Future schema evolution will bump `v1` -> `v1.x` or `v2` per governance rules.

## Support

Open an issue or reach out to the registry maintainers if you encounter migration edge cases.

---

Migration authored: 2025-10