Page MenuHomePhabricator

[Federated Items] Architecture for Federated Items
Open, HighPublicSpike

Description

Context

Federated Items is currently released as an Alpha version with the Wikibase Suite stack. It incorporates learnings from previously developed Federated Properties. Our goal for the Alpha is to validate the manual editing UX and collect feedback for extended functionality (storage/caching, API representation, query service).

First demo sessions with WMDE and Wikibase users received positive feedback on ease of use.

Engineers and Wikibase/Wikidata users have raised a recurring architectural question:
Should we introduce a new data type for Federated Items?

The current implementation uses 'wikibase-item' as the default data type. An alternative approach would be a new dedicated data type (e.g. 'federated-item').

Both paths come with caveats (pros and cons) that are not yet clarified. This spike should produce a recommendation with sufficient evidence to make a confident architectural decision.

Requirements from the user perspective: The user flow must stay the same.

  • Remote items appear in the value dropdown for any property of a data type item
  • Users do not need to create a different property for remote items
  • Users do not see an extra step to choose between local/remote

Goal of the Spike

Provide an evidence-based recommendation on whether to:

  1. Keep current approach: Source-aware wikibase-item
  2. New data type with auto-assignment: federated-item, automatically assigned when saving an item that is remote
  3. Alternative: Any combination discovered during the spike

Questions to be addressed:

  • Can a single property support a mix of wikibase-item and federated-item values?
  • What happens when an existing statement is edited or re-saved (from wikibase-item to federated-item and vice versa)
  • How do imports (e.g. QuickStatements) handle each data type?
  • How is site search affected by each option?
  • What is the impact on Action API, REST API, and dumps per option?
  • Which option is more robust to future Wikibase Core changes?
  • Can users distinguish federated vs. local values in SPARQL per option?
  • Does any option exclude federation from other sources than Wikidata?
  • What is the rough engineering effort per option?
  • What are the top 3-5 risks per option?

Event Timeline

Leif_WMDE renamed this task from [Federation] Do we need to incorporate a new data type for federated items? to [Federated Items] Do we need to incorporate a new data type for federated items?.May 12 2026, 1:01 PM
Leif_WMDE updated the task description. (Show Details)
Leif_WMDE changed the subtype of this task from "Task" to "Spike".May 13 2026, 10:11 AM

I’ll leave a few thoughts here to elaborate on the comments I’ve left in other places before. I’m looking at this mainly from a software architecture perspective, but as far as I know these suggestions are fully compatible with the product requirements.

Use data type registration (not necessarily a new data type!)
Since this feature changes how item statement values behave, the existing data type registration mechanism seems like the right extension point to build this on. It was created to add new data types to a Wikibase instance, but it can also be used to override existing ones. From a technical perspective, I don’t think it makes a big difference whether we create a new data type, or override the existing wikibase-item type.

In either case, I think the result should be one data type that supports both local and remote items. Making properties support a mix of multiple data types as the question in the task description suggests sounds like a dangerous change.

Consider creating a separate extension
The biggest advantage I see in using data type registration is that it requires (almost?) no changes to existing Wikibase code. The whole feature can be implemented in a completely separate MediaWiki extension. I think that’s worth considering because it means:

  • Lower risk to break Wikibases that don’t (yet) need this feature like Wikidata
  • More freedom for the team working on the feature (separate repo, faster CI)
  • A clear boundary between “core” Wikibase and this feature
  • No need for a config-based feature toggle

Don’t use entity sources
Entity sources were initially created to enable structured data on Wikimedia Commons. I was part of the team that then built federated properties on top of entity sources, and we regretted that after a while, because it had a massive ripple effect throughout the code base.

Some kind of configuration will of course be needed for remote Wikibases, but that could go into a separate setting.

Don’t extend wbsearchentities unless necessary
The UI component suggesting a mix of local and remote items doesn’t have to use wbsearchentities. It’s probably cleaner to just create a dedicated (REST?) endpoint instead of modifying the existing search behavior.

Keep storage simple
As long as data storage of remote items is only needed to avoid repeated requests to fetch labels and descriptions, we can probably get away with a simple cache instead of storing that data in a dedicated db table.

Leif_WMDE renamed this task from [Federated Items] Do we need to incorporate a new data type for federated items? to [Federated Items] Architecture for Federated Items.Jun 23 2026, 4:53 PM
Lucyfediachambers subscribed.

Due to size converted from a Spike to an Epic of Spikes :) This will be split into sub-tickets which can be added to sprints individually.