shard-wiki/research/260613-xwiki-deep-dive/findings.md

Findings — XWiki: implementation, extension interfaces, ecosystem

Date: 2026-06-13 · Status: research draft

Scope: XWiki as prior art for two shard-wiki concerns — (1) attaching a structured "wiki-as-application-platform" engine as a shard, and (2) how an engine exposes extension interfaces rich enough to host a federation adapter (INTENT composable integration). Sources are XWiki's own dev docs, the DeepWiki code analysis of xwiki/xwiki-platform, and the extensions repository.

Complements: research/260608-wikiengines-overview/ (landscape) and research/260608-federation-concepts/ §3.2 (XWiki ActivityPub).

---

1. What XWiki is

A programmable, component-based wiki platform (Java/Jakarta EE, Hibernate ORM) that blurs wiki and lightweight application platform. Pages are not just prose: they carry typed structured objects, so an XWiki page can be a form, a record, or a small application. This is the defining property the landscape scan flagged — and the reason XWiki is the hardest case for shard-wiki's Markdown-first page model.

2. Implementation architecture

2.1 Component system (the spine)

• Dependency-injection component model. Components are interfaces (roles) discovered via META-INF/components.txt and instantiated by a ComponentManager. Implementations declare @Component, an optional @Named role hint, and @Singleton. No interface→impl dependency — impls can ship in separate JARs and replace defaults at runtime.
• Core replaceable roles include XWikiStoreInterface (storage), ObservationManager (events), XWikiRightService (authorization), XWikiAuthService (authentication).

2.2 oldcore vs modular platform

• xwiki-platform-oldcore holds the foundational document model, persistence, and legacy APIs (com.xpn.xwiki.*). A bridge connects it to the newer component world to avoid circular dependencies.
• Newer modules layer on top: model (entity references), rendering, security, web (HTTP actions/templates), search-solr.

2.3 Data model — document-centric + class/object

• Central entity: XWikiDocument, addressed by DocumentReference (wiki / space / page). Content is parsed into an XDOM (rendering tree).
• Structured data via a class-object pattern (OOP-like):
  • BaseClass / XClass — schema (field definitions), like a class declaration
  • BaseObject / XObject — an instance conforming to a class, attached to a page
  • PropertyClass / BaseProperty — field definition / value
  • Property types: String, LargeString, Date, Number, List, …
• A single page can hold content plus N typed objects plus attachments. This is the structural fact shard-wiki must represent without flattening.

2.4 Storage & history

• Two-tier: XWikiCacheStore over XWikiHibernateStore (Hibernate, multi-DB).
• Tables: xwikidoc, xwikiobject, xwikiproperties, xwikiattachment, and xwikircs — internal RCS-style version history. History is real but engine-internal and non-portable (directly relevant to shard-wiki UC-36).

2.5 Events & rendering

• ObservationManager event bus: cancelable (DocumentCreatingEvent, DocumentUpdatingEvent, DocumentDeletingEvent) and post-facto (DocumentCreatedEvent, DocumentUpdatedEvent, …). Listeners are components — a natural change-notification source for incremental sync.
• Rendering pipeline: source syntax → parse → XDOM → transformations (macros) → serialize (HTML, PDF, …). Pluggable parsers/renderers; XWiki can parse Markdown as an input syntax even though its native syntax differs.

2.6 Multi-wiki

• One installation hosts many wikis (WikiReference), each with separate documents and configuration — XWiki's own multi-tenancy, conceptually adjacent to shard-wiki's root-entity/tenant boundary.

2.7 APIs & security

• Dual API surface: internal com.xpn.xwiki.* (full power) and script com.xpn.xwiki.api.* (wrapped, enforces programming rights and view rights). Privilege is enforced at the script boundary, not the storage boundary.

3. Interfaces to extend the core engine

XWiki's extensibility is unusually layered. From lowest/most-powerful to highest:

#	Mechanism	What it extends	How
1	Components	anything	implement a role interface, @Component + @Named hint; ship in a JAR with components.txt; can override defaults (store, auth, rights)
2	Rendering macros (Java)	content processing	register Macro.class role + hint; participates in the XDOM transformation pipeline
3	Wiki macros	content processing	a wiki page following a spec — no Java, no compile; in-wiki authoring
4	Script services	scripting API	implement org.xwiki.script.service.ScriptService; exposed to Velocity/Groovy as $services.<hint>
5	UI Extensions (UIX) at UI Extension Points (UIXP)	the interface, no skin edit	UIX stored as XObjects of XWiki.UIExtensionClass (label/target/icon); injected at named hooks (since v4.2), e.g. org.xwiki.platform.panels.Applications
6	REST API (JAX-RS)	remote integration	resources for pages, spaces, objects, classes, attachments, comments, tags, annotations, users/groups, history; custom JAX-RS resources can be added
7	Event listeners	reactive behavior	register a component on ObservationManager to react to document lifecycle events
8	Resource reference handlers	new URL/resource types	implement ResourceReferenceHandler on the root component manager
9	Skins / templates / Velocity	presentation	Flamingo skin macros, templates

Two things stand out for shard-wiki: (a) the component model lets an extension replace authentication, authorization, and storage — i.e. an XWiki instance could delegate auth exactly as shard-wiki's blueprint prescribes; (b) the REST API plus event bus give a federation adapter both a transport (read/write pages+objects+ history) and a push-based freshness signal.

4. Extension ecosystem

• extensions.xwiki.org repository: 900+ extensions (applications, macros, skins, panels, themes, legacy plugins). Browsed/installed/upgraded at runtime via the Extension Manager Application from the admin UI.
• Extension types:
  • XAR — a package of wiki pages (an application, a wiki macro, or a snippet)
  • JAR — server-side Java: components and script services
  • WebJar — JAR of web resources (JS/CSS/Less)
• "Plugin" (legacy) vs Component (modern): the old plugin API is superseded by the component system; new code is components.
• Notable extensions (relevance to shard-wiki in parentheses):
  • AppWithinMinutes — build structured apps (XClass+XObjects) from the UI (→ pages-as-records, the UC-39 case)
  • LDAP / Active Directory and Entra ID (Azure AD) authentication (→ confirms pluggable XWikiAuthService; mirrors shard-wiki's delegated authn)
  • ActivityPub — fediverse federation (→ adapter transport, cf. UC-31)
  • LiveData / LiveTable — queryable tabular views over XObjects
  • draw.io diagrams, PDF viewer, Task Manager, Blog — content/app breadth

5. XWiki as a shard — capability profile

Read through shard-wiki's capability-aware adapter lens:

Capability	XWiki	Note
Read	✓	REST + render to HTML/Markdown
Write	✓	REST PUT page/object; per-document granularity (page + its objects)
Structured payload	✓✓	XObjects/XClass — richer than Markdown; must not be flattened (UC-34/UC-39)
Version/diff	✓ (internal)	xwikircs; not git-portable → coordination journal supplies that (UC-36)
Merge	partial	no native git-style 3-way merge
Change events	✓	ObservationManager → push-based sync/freshness (enriches UC-31)
Auth model	pluggable	XWikiAuthService/XWikiRightService replaceable — authorize through shard-wiki core, don't trust engine ACLs
Federation hooks	✓✓	component + REST + UIX make XWiki able to host a shard-wiki adapter (UC-38)
Multi-tenancy	✓	WikiReference farm → multiple shards / root entities

6. Mapping to shard-wiki INTENT (compare, do not equate)

6.1 Reinforcements

Observation	INTENT principle
Pages = content + typed XObjects	Markdown-first, backend-neutral must carry structure, not flatten (UC-34/39)
xwikircs internal-only history	Git-addressable coordination adds the portable layer (UC-36)
Pluggable XWikiAuthService	authorization in core, authentication delegated — XWiki already does exactly this
Component + REST + UIX extension surface	composable integration — engine becomes federation-capable via its own API (UC-38)
ObservationManager events	explicit provenance/freshness via push, not poll (UC-31, UC-24)
WikiReference multi-wiki	root-entity / tenant boundary has prior art

6.2 Deliberate divergences (design bugs if conflated)

XWiki assumption	shard-wiki correction
Native XWiki syntax + macro render is the page	shard-wiki keeps Markdown-first; engine render stays out of core, structure travels as metadata
ACLs/rights live in the engine DB	authorize in core; engine rights are advisory, not trusted
History is the engine's RCS table	coordination journal is space-level and git-backed
Federation = an XWiki extension talking to other XWikis	shard-wiki federates heterogeneous backends; XWiki is one shard among many
App = XObjects rendered by XWiki	shard-wiki must represent records without depending on XWiki to render them

6.3 What XWiki teaches that shard-wiki should not lose

1. A clean role/hint component model is what makes auth/store/rights swappable — shard-wiki's adapter contract should be similarly role-based and override-friendly.
2. Structured objects are first-class, not an afterthought — the page model needs a typed-metadata escape hatch from day one.
3. An engine with a real extension API can host the adapter itself — the cheapest path to a high-fidelity shard is engine-side, not screen-scraping.

7. Use-case seeds → catalog (promoted 2026-06-13)

Seed	Catalog UC	Disposition
Engine hosts a federation adapter via its native extension API	UC-38 (new)	composable integration — first UC for the engine-side direction
Attach a wiki-as-application-platform shard (pages are typed records/forms)	UC-39 (new)	extends UC-34 toward bodiless structured pages
Structured page carries semantic data	UC-34	enriched with XObject/XClass concretes
Internal-only revision history	UC-36	enriched with xwikircs example
Subscribe to remote shard changes	UC-31	enriched with ObservationManager event-driven transport

8. Open questions (for spec / workplans)

1. Page-model representation of XObjects — typed frontmatter, sidecar file, or opaque provenance blob? (shared with wikiengines §6 Q1; XWiki makes it urgent)
2. Bodiless record pages — does shard-wiki's page model require a Markdown body, or can a page be purely structured (AppWithinMinutes apps)?
3. Adapter placement — engine-side extension (high fidelity, needs deploy access) vs external REST adapter (zero engine change, lower fidelity). Both? Capability-gated?
4. Event transport — consume ObservationManager via a JAR listener, or poll REST history? Affects freshness guarantees (UC-31/UC-24).
5. Rights mapping — translate XWiki XWikiRightService rights into shard-wiki actions (read/write/patch/merge/administer), or ignore and authorize purely in core?

9. Sources

Source	URL
XWiki — Developer Guide	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/
XWiki — Creating XWiki Components	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingComponents/
XWiki — Available Extension Points	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ExtensionPoint/
XWiki — UI Extension Point Tutorial	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/UIXTutorial/
XWiki — Wiki Macro Tutorial	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/
XWiki — RESTful API	https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI
XWiki Rendering — Writing a Macro	https://rendering.xwiki.org/xwiki/bin/view/Main/ExtendingMacro
Extension Manager Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Manager%20Application
Extension Module — Extensions/types	https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/Extensions/
DeepWiki — xwiki/xwiki-platform (code analysis)	https://deepwiki.com/xwiki/xwiki-platform
Mancinelli — Overview of XWiki's RESTful API	http://blog.fabio.mancinelli.me/2011/03/07/XWikis_RESTful_API.html
shard-wiki — wiki engines overview	research/260608-wikiengines-overview/findings.md
shard-wiki — federation concepts	research/260608-federation-concepts/findings.md

---

10. Traceability

This document section	Informs (future)
§2 architecture	adapter design for app-platform engines
§3 extension interfaces	UC-38 engine-side adapter; composable-integration API shape
§5 capability profile	adapter capability-profile vocabulary (SHARD-WP-0002)
§6 INTENT mapping	architecture-blueprint guardrails
§7 UC seeds	spec/UseCaseCatalog.md (UC-38, UC-39; UC-31/34/36 enrichment)
§8 open questions	spec — page model for structured/bodiless pages