Cara Versioning Schema Custom tanpa Merusak Output Lama

Jumat sore, developer deploy schema runtime baru.

Tujuannya sederhana: menambah hubungan antara Article, Person, dan Organization supaya graph lebih konsisten.

Lima menit kemudian validator masih hijau.

Tim lega.

Senin pagi baru ketahuan bahwa seluruh `@id` author berubah. Puluhan ribu Article sekarang menunjuk node Person versi baru, sementara halaman profile masih memakai ID lama. Tidak ada fatal error. Tidak ada layout rusak. Tidak ada alert dari user.

Graph pecah diam-diam.

Ini tipe incident yang membuat schema custom perlu diperlakukan seperti software, bukan snippet SEO.

Begitu structured data dibuat oleh runtime sendiri, kita punya codebase. Ada release. Ada dependency. Ada backward compatibility. Ada regression. Ada rollback. Dan kalau output lama sudah dipakai ratusan atau ribuan halaman, perubahan kecil pada naming atau ID bisa mengubah arti seluruh graph.

Versioning schema custom bukan berarti menambahkan `"version": "3.2"` ke JSON-LD lalu selesai.

Yang perlu di-version adalah contract output.

Node apa yang ada.

ID-nya apa.

Property mana yang wajib.

Relationship ke mana.

Data source dari mana.

Apa yang berubah dari versi sebelumnya.

Dan bagaimana sistem lama tetap bisa dibaca tanpa kita menciptakan dua realitas.

Mulai dari Pertanyaan yang Paling Membosankan: Apa yang Dianggap Stabil?

Setiap runtime schema perlu punya daftar hal yang tidak boleh berubah sembarangan.

Contoh:

Canonical Organization ID.

WebSite ID.

Format Person ID.

Format Article ID.

Publisher relationship.

Author relationship.

Breadcrumb identity.

Product IDs jika commerce.

Location IDs.

Brand IDs.

Hal-hal ini adalah API contract internal.

Kalau Organization selama dua tahun memakai:

`https://example.id/#organization`

jangan versi baru tiba-tiba mengubah menjadi:

`https://example.id/about/#org`

hanya karena terlihat lebih rapi.

Secara visual tidak ada bedanya.

Secara graph, kita baru menciptakan node baru.

Jika memang entity-nya sama, ID continuity lebih penting daripada estetika.

Versioning dimulai dari keputusan:

Stable IDs are stable.

Breaking change harus dianggap breaking change.

Schema Runtime Punya Dua Jenis Versi

Praktisnya, bedakan:

Code version.

Output schema version.

Code version:
runtime 3.4.1.

Output contract:
schema-contract 2.

Kenapa perlu dua?

Karena kita bisa memperbaiki bug PHP tanpa mengubah struktur JSON-LD.

Itu code patch.

Sebaliknya, kita bisa mengubah relationship penting dari:

Article → author → string

menjadi:

Article → author → Person node.

Itu perubahan output contract.

Dengan dua versi, audit lebih jelas.

“Runtime berubah” tidak otomatis berarti graph berubah.

Measurement juga lebih bersih.

Kalau AI visibility berubah setelah code patch yang hanya memperbaiki caching, jangan salah mengira entity model berubah.

Semantic Versioning Bisa Dipakai sebagai Inspirasi, Bukan Agama

Engineering team sudah familiar dengan:

major.minor.patch.

Bisa adaptasi.

Major:
Breaking semantic change.

Contoh:
Canonical ID policy berubah.
Node type berubah.
Relationship model berubah.

Minor:
Additive backward-compatible change.

Contoh:
Tambah optional ImageObject.
Tambah alternateName yang valid.
Tambah non-breaking property.

Patch:
Bug fix tanpa mengubah contract.

Contoh:
Escaping JSON.
Date formatting.
Wrong URL encoding.

Tidak harus mengikuti SemVer formal secara sempurna.

Yang penting team punya language.

Kalau developer bilang:
“Ini major.”

SEO dan editorial tahu perlu regression test luas.

Kalau patch:
risk lebih rendah.

Satu Changelog Kecil Bisa Menyelamatkan Banyak Jam

Schema changelog jangan seperti novel.

Contoh:

v3.4.0
– Added Person profile URL.
– Added reviewer relation.
– No change to Organization @id.

v4.0.0
– Migrated Organization canonical @id from legacy URI.
– Added compatibility alias mapping.
– Requires revalidation across Article, Product, Person templates.

Sekarang incident investigation mudah.

Tanpa changelog:

“Kenapa publisher ID berubah?”

“Kayaknya pas update theme.”

“Kapan?”

“Nggak tahu.”

This is avoidable.

Schema invisible.

Changelog creates memory.

Jangan Versioning dengan Mengganti Semua `@id`

Kesalahan paling umum:

Runtime v1:
`#organization-v1`.

Runtime v2:
`#organization-v2`.

Runtime v3:
`#organization-v3`.

Looks organized.

Semantically terrible jika semuanya tetap entity yang sama.

Version number belongs to generator metadata, deployment log, or internal diagnostics.

Not entity identity.

Organization doesn't become new company because runtime updated.

Person doesn't become new person because schema code changed.

Product doesn't become new product because plugin version increased.

Stable entity IDs should survive software releases.

Version software, not reality.

Kalau Entity Benar-Benar Berubah, Baru Pikirkan New Identity

Rebrand tidak selalu new entity.

CEO change definitely not new Organization.

Address change not new Organization.

New product variant may be new Product node.

Merger can create new legal entity.

Spin-off could.

Versioning policy needs business truth.

Don't let deployment architecture decide ontology.

Example:

Brand rename.

Same legal organization.

Organization ID stable.

`name` changes.

`alternateName` captures old label if appropriate.

Visible page explains.

Graph continuity preserved.

If company legally replaced by a new company:
maybe new Organization node.

That's entity event.

Not code event.

Backward Compatibility Itu Apa dalam Schema?

Suppose old Article graph had:

Article.author:
Person A.

New runtime adds:

Person A.worksFor:
Organization X.

Backward-compatible.

Old consumer that only cares author still fine.

Now suppose runtime changes Article ID from:

URL#article

to:
URL#creativework

Any external/internal system storing old `@id` references may no longer connect.

Breaking.

Or runtime changes Brand object into Organization because plugin requires.

Breaking semantics.

Backward compatibility means existing stable relationships remain meaningful.

Additive properties are usually safer.

Identity and type changes need migration plan.

Shadow Output Sebelum Full Release

For site besar, don't deploy straight to all pages.

Generate new schema in shadow mode.

Not necessarily public.

On staging or diagnostic endpoint.

Take sample URLs:

Homepage.

Article.

Author.

Report.

Dataset.

Location.

Product.

Variant.

Category.

Compare old vs new.

Node diff.

Property diff.

ID diff.

Relationship diff.

Unexpected changes.

This is schema diff testing.

If 90% output changed but ticket only asked “add reviewer”, red flag.

Diff should match intent.

Schema rollout without diff is flying blind.

Golden Fixtures

Keep representative pages as test fixtures.

Fixture:
Article single author.

Expected:
WebPage.
Article.
Person.
Organization.
Breadcrumb.

Fixture:
Article multi-author.

Fixture:
Report with Dataset.

Fixture:
Closed LocalBusiness.

Fixture:
Product variant.

When runtime changes:
render.
compare expected.

Automated test catches:

missing publisher.

ID changed.

duplicate Organization.

wrong canonical.

date malformed.

This is standard software testing mindset applied to schema.

No need exotic tool.

Even JSON snapshots in repository work.

Stable Property Names vs Consumer Changes

Schema.org evolves.

Google Search documentation evolves.

Your output may need adjustment.

Example:
a property becomes newly recommended.

Search feature retired.

Consumer requirement changes.

Do not rewrite entire graph every time.

Separate:

Core semantic model.

Consumer projection.

Core:
Organization, Person, Product relationships.

Consumer layer:
Google-specific required/recommended fields for supported Search feature.

If Google feature changes, consumer projection can update.

Entity identity remains.

This architecture reduces churn.

Schema as ontology + schema as Search feature are related but not identical.

Migration Layer untuk Old Output

Sometimes old IDs are already everywhere.

You cannot clean instantly.

Create mapping.

Legacy Person ID → canonical Person ID.

Legacy Organization label → current Organization.

Internal registry stores aliases.

During transition, generator can recognize old reference and output canonical node.

Don't publish two sameAs relationships blindly just to stitch.

Use semantics appropriate.

For internal migration, alias mapping can stay internal.

Public graph should present clean current identity.

The goal is not expose migration mechanics.

It is prevent fragmentation.

Do Not Delete Old Properties without Dependency Audit

Custom applications may consume JSON-LD.

Partner.

Internal crawler.

Search pipeline.

Data warehouse.

Browser extension.

Maybe nobody.

But check.

If property being removed:
search codebase.

Search analytics.

Search API dependencies.

Document.

Example:
custom `identifier` field used by internal entity extractor.

SEO developer removes because “Google doesn't need it.”

Internal system breaks.

Schema can have consumers beyond Search.

Governance needs consumer inventory.

Feature Flags

For risky changes:

schema_v4_enabled:
false.

Enable 5%.

10%.

50%.

100%.

Or page-type-specific rollout.

Articles first.

Products later.

Why?

Product/Offer errors have higher business consequence.

Organization ID changes affect sitewide graph.

Controlled rollout reduces blast radius.

WordPress custom runtime can use config.

Enterprise service can use deployment flag.

No need expose to user.

Rollback should be one switch.

Versioning without rollback is half a plan.

Rollback Harus Mengembalikan Output, Bukan Cuma Code

Imagine code rollback succeeds.

But cache still serves new JSON-LD.

CDN.

Page cache.

Object cache.

Static HTML.

Need cache invalidation.

Test.

A rollback playbook:

disable v4.

restore v3.

purge caches.

fetch representative pages.

validate IDs.

record time.

Search consumers will recrawl at their own pace.

You cannot instantly erase external copies.

But public source becomes correct again.

Operational clarity matters.

Schema Version Jangan Menjadi Visible Marketing Date

Some teams output:

“schemaVersion: 2026.08.1”

inside custom JSON-LD.

If property isn't in vocabulary:
consumer may ignore.

If custom namespace:
fine for internal use if intentional.

But don't invent property and present as official.

Better keep version in:

HTML comment.

HTTP diagnostic.

Internal endpoint.

Deployment metadata.

Log.

Repository.

If public custom metadata needed, namespace clearly.

No pretending Schema.org supports it.

Schema contracts can be versioned without polluting semantics.

Data Migration vs Code Migration

Code migration:
generator changed.

Data migration:
source fields changed.

Example author:

Old:
free-text author_name.

New:
person_id.

Code can handle both during transition.

If person_id exists:
use Person registry.

Else:
fallback to legacy author_name until migrated.

Then migration job fills IDs.

After coverage reaches 100%, remove fallback in major version.

This pattern prevents breaking old content.

Don't require 10,000 historical posts be manually edited before runtime works.

Compatibility layer.

Measure migration coverage.

No silent guessing.

Versioning juga Membantu Factual Audit

Suppose Organization legalName wrong.

Was it wrong in data source?

Or runtime?

Check:

v3.3 output.

v3.4 output.

Entity registry history.

If wrong begins at one version:
code regression.

If all versions:
data issue.

Without version:
no forensic trail.

Schema can become evidence of what site claimed at a point in time.

This matters for rebrand, leadership, product changes.

Keep deployment snapshots for critical entity graph.

Not necessarily every page.

Representative snapshots enough.

AI Citation Bukan Release Acceptance Test

New schema version deploys.

ChatGPT citation doesn't change.

Does that mean release failed?

No.

Acceptance tests should be controlled:

valid JSON-LD.

correct entities.

stable IDs.

visible-content alignment.

consumer eligibility where relevant.

no duplicates.

no conflicting canonical.

AI citation is downstream observation.

Measure later.

Do not rollback a semantically correct runtime because one volatile AI query dropped.

Conversely, don't keep wrong schema because citation increased.

Truth first.

A Good Release Note Is Boring

“Changed Person URL field to canonical profile URL. No change to Person @id. No change to Article IDs. Added reviewedBy only where CMS review record exists. Passed 20 template fixtures.”

That is excellent.

No:
“AI entity boost v5.”

No:
“LLM optimization engine.”

Unless actual evidence and product context.

Schema custom should be governed like infrastructure.

Clear.

Testable.

Rollbackable.

Versioning Is Mostly About Saying “This Must Not Change”

The glamorous part is new property.

The mature part is stable contract.

Organization ID stays.

Product IDs stay.

Old pages remain valid.

Fallback exists.

Changes are documented.

Tests run.

Rollout controlled.

If schema custom has been live for years, every new release inherits responsibility for the graph that already exists.

You are not generating JSON-LD from scratch anymore.

You are maintaining history.

And the easiest way to avoid breaking that history is to treat each schema release the way a serious engineering team treats an API release:

Know what is stable.

Know what changes.

Know who depends on it.

And always know how to go back.