[Mpdreamz]

Adds tests that an older reader of links.json ignores properties it does not know and reads everything else as before. They guard the link index against a newer build adding data, such as the pages of an API.

Affects: Links & redirects

Prompt summary: Validate that the current main can read the new link index, and add a dedicated PR against main so backwards compatibility stays covered. The link index is read by every build, including builds of older docs-builder versions.

Why

#4731 adds a floating property to the links.json of a docset that declares APIs. Every consumer of the link index reads that file with RepositoryLinks, so it keeps working only while the reader ignores unknown properties. Nothing tests that today. A change such as strict unmapped-member handling would break every build that fetches a repository with an API, and it would break them at once.

What

Unknown properties are ignored

LinksJsonForwardCompatibilityTests deserializes a links.json that has the floating section a later build writes, and several arbitrary shapes under the same name and under another unknown name: a string, a number, an array, and nested unknown fields. In each case links, cross_links, redirects, origin and url_path_prefix read exactly as they do without the property.

Cross-links resolve as before

A file with and without the floating section resolves the same cross-links through CrossLinkResolver: a page, a page with an existing anchor, a missing anchor and a missing page.

Verify

dotnet test --project tests/Elastic.Markdown.Tests --treenode-filter "/*/*/LinksJsonForwardCompatibilityTests/*"

With [JsonUnmappedMemberHandling(JsonUnmappedMemberHandling.Disallow)] added to RepositoryLinks, all 12 tests fail.

I also read the real links.json of docs-content built with the new floating section (1.45 MB, ten APIs) with this code. It reads exactly like the real file built without it: 2,775 links, 1,884 cross-links and 909 redirects are equal, and 60 real cross-links resolve identically.

🤖 Generated with Claude Code

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4752/