# 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 |