COMBINING ARCHITECTURAL COMPLEXITY WITH THE BOUNDED FREEDOM OF A SEMANTIC WIKI

Enterprise Architecture (EA) practitioners grapple with managing a complex, interconnected web of information encompassing applications, data, business processes, infrastructure, owners, suppliers and more. Traditional methods relying on static diagrams and spreadsheets often fall short, struggling to keep pace with constant change and making the analysis of intricate relationships a manual, error-prone task. Enterprise Architecture Repositories (EARs) aim to address this by providing a central, consistent “single source of truth”. However, many dedicated EA tools can be rigid or costly.

Having implemented this at a client, I have tried and experienced an alternative approach that leverages Semantic MediaWiki (SMW), an open-source extension to the familiar MediaWiki platform (the engine behind Wikipedia). SMW transforms a standard wiki into a powerful knowledge management system by adding a semantic layer. This layer allows users to embed structured, machine-readable data directly within wiki pages. The core mechanism involves semantic annotations, typically using the syntax [[Property::Value]]. This simple markup converts unstructured wiki text into structured data triples (subject-predicate-object), making the implicit relationships between architectural elements explicit and, crucially, queryable.

This approach shifts the paradigm from static EA documents, which quickly become outdated and require manual cross-referencing for analysis, to a dynamic, queryable knowledge base. By embedding structured data that can be queried dynamically, views and analyses reflect the current documented state of the architecture, moving beyond mere snapshots and blueprints. Furthermore, the familiar wiki interface potentially lowers the barrier to entry for accessing and even contributing to architectural knowledge, fostering the shared understanding EA strives for, compared to specialized tools with potentially limited licenses and steeper learning curves.

This article explores how SMW’s unique capability to model, manage, and query the relationships between architectural components makes it a compelling option for building a flexible and insightful EA repository. We will focus specifically on representing and leveraging connections such as ‘has owner’, ‘uses information’, ‘depends on application’, and ‘is supplied by’.

Laying the Foundation: EA Repositories, Meta-Models, and SMW

Before diving into implementation, let’s clarify the core concepts. An Enterprise Architecture Repository (EAR) serves as the central hub for storing and managing all architecture-related artifacts – including models, standards, principles, capabilities, and governance documents. Its purpose extends beyond simple storage; it aims to ensure consistency, support complex analyses (like impact analysis), improve decision-making, foster collaboration, promote reuse, and ultimately align IT investments and structure with business strategy.

The structure of the information within an EAR is defined by an EA Meta-Model. This meta-model acts as the blueprint, specifying the types of architectural elements the organization cares about (e.g., Application, Business Capability, Data Object, Technology Component, Owner, Supplier) and, critically, the permissible relationships between them (e.g., an Application is owned by an Owner, supports a Business Capability, uses a Data Object, runs on a Technology Component, is supplied by a Supplier). Common frameworks like TOGAF include content meta-models that often categorize elements into layers such as Business, Application, Data, and Technology. Defining these elements and their relationships clearly is paramount for maintaining consistency and enabling meaningful analysis.

Semantic MediaWiki (SMW) provides the building blocks to implement this structure:

• Semantic Annotations: The [[Property::Value]] syntax encodes instances of the meta-model within wiki pages.
• Properties & Types: Properties (e.g., Has Owner, Uses Information) represent attributes or relationships defined in the meta-model. Each property has a specific data type (e.g., Text, Number, Date, Page) that dictates the kind of value it can hold. The ‘Page’ type is fundamental for creating links between wiki pages representing different EA elements.
• Categories: Standard MediaWiki categories are used to classify pages according to their meta-model element type (e.g., [[Category:Application]], ]).
• Inline Queries (#ask): The #ask parser function allows users to retrieve and display data based on the semantic annotations (properties and categories) stored in the wiki.

Effectively, the EA meta-model serves as the direct blueprint for the semantic schema within SMW. Categories map to element types, properties map to attributes and relationships, and property types enforce the data structure. A well-defined EA meta-model is thus essential for a structured and useful SMW-based repository. While SMW offers significant flexibility in adding new properties or relationships, this very flexibility can lead to inconsistency if not governed properly. A poorly defined or overly rigid initial EA meta-model can hinder the repository’s effectiveness, regardless of the tool’s capabilities. Therefore, investing effort in defining a robust meta-model upfront is critical.

Building Your EA Repository in SMW

Translating an EA meta-model into a functioning SMW repository involves several steps:

1. Representing EA Elements as Pages: Each distinct architectural element – be it an application like “Global CRM”, a business owner like the “Marketing Department”, an information concept like “Customer Master Data”, or a supplier like “CloudServices Inc.” – is represented by its own dedicated wiki page. This leverages the natural page-centric structure of MediaWiki.
2. Appending free format information such as text and images, leveraging the freedom of the MediaWiki syntax.
   • Classifying Elements with Categories: Each element page is assigned to one or more categories corresponding to its type in the EA meta-model. For instance, the “Global CRM” page would include [[Category:Application]], while “Marketing Department” would have ]. This classification enables powerful type-based queries, such as retrieving all pages categorized as ‘Application’.
3. Structuring Data with Templates: To ensure consistency and simplify data entry, MediaWiki templates are indispensable. An “infobox-style” template should be created for each major element type (e.g., Template:Application, Template:Supplier).
   • These templates define parameters for the element’s key attributes (like description, version) and its relationships (like owner, data used, dependencies, supplier).
   • Crucially, within the template’s code, semantic annotations are used to automatically set the corresponding properties based on the parameter values provided by the user when calling the template (e.g., [[Has Owner::{{{owner}}}]], [[Uses Information::{{{information_used}}}]], ]).
   • This approach enforces the meta-model structure during data input, guiding users and improving data quality. Extensions like Page Forms can further enhance usability by generating user-friendly input forms based on these templates, hiding the underlying wiki markup.
4. Weaving the Web: Defining Relationships with Properties: The connections between architectural elements, as defined in the meta-model, are implemented using SMW properties, primarily those with the data type ‘Page’. This type allows a property’s value to be a link to another wiki page, thus creating an explicit semantic relationship.
   • For example, on the “Global CRM” page (likely via its template):
     • [[Has Owner::Marketing Department]] links to the “Marketing Department” page.
     • [[Uses Information::Customer Master Data]] links to the “Customer Master Data” page.
     • [[Uses Service:: Single SignOn Service]] links to the “Single SignOn Service” page.
     • [[Is Hosted By:: CloudServices Inc]] links to the “CloudServices Inc” page.
   • These ‘Page’ type properties form the relational backbone of the EA repository, creating a navigable graph of interconnected elements. This structure is fundamental for understanding dependencies and performing impact analysis. Without extensive use of ‘Page’ properties, the repository risks becoming merely a collection of isolated descriptions rather than an integrated model. Inverse properties can also be defined to allow querying relationships in both directions (e.g., finding all applications owned by a specific department).

Example: Linking Applications to Owners and Vice Versa

Let’s illustrate how templates and queries work together for the ‘Has Owner’ relationship:

• Application Page Setup: Assume we have a template Template:Application. Inside this template’s code, we include the semantic annotation: [[Has Owner::{{{owner}}}]]. When creating the page for “Global CRM”, a user would call this template like: {{Application | Name=Global CRM | owner=Marketing Department |… }}. This action sets the ‘Has Owner’ property on the “Global CRM” page, pointing to the “Marketing Department” page.
• Owner Page Setup: Now, consider the page for “Marketing Department”, which uses Template:Owner. To automatically display all applications owned by this department, we embed an #ask query within Template:Owner:

Code snippet

'''Applications Owned:'''

{{#ask:

  [[Category:Application]]

  [[Has Owner::{{PAGENAME}}]]

| format=ul

}}

This query searches for all pages within the [[Category:Application]] that have the Has Owner property pointing specifically to the current page ({{PAGENAME}} automatically inserts the title of the page where the template is used, i.e., “Marketing Department”). The result is displayed as an unordered list (format=ul).

This two-way setup, enabled by templates and inline queries, ensures that relationship information is entered consistently on the application page and automatically reflected (queried) on the related owner page, keeping the information synchronized and easily accessible from both ends.

The following table summarizes how common EA repository needs map to SMW features:

Unlocking Insights: Querying Your Semantic EA Repository

Once the architectural data and relationships are captured using semantic annotations, SMW’s query capabilities unlock powerful analysis. The primary tool for this is the #ask inline query parser function. Its basic structure allows specifying conditions to select pages and defining which properties of those pages to display:

{{#ask: [[Condition1]][[Condition2]] |?PropertyToDisplay1 |?PropertyToDisplay2 |format=table/list/etc. }}

Focusing on the relationships emphasized earlier, here are practical query examples:

• Find all Applications owned by the Marketing Department:

{{#ask: [[Category:Application]][[Has Owner::Marketing Department]] }}

(Selects pages in Category:Application that have the property ‘Has Owner’ pointing to the ‘Marketing Department’ page)

• List Applications and the Information concepts they use:

{{#ask: [[Category:Application]] |?Uses Information }}

(Selects pages in Category:Application and displays the value(s) of their ‘Uses Information’ property)

• Identify Applications dependent on the ‘Single SignOn Service’:

{{#ask: [[Category:Application]]] }}

(Selects pages in Category:Application linked via the ‘Depends On Application’ property to ‘Single SignOn Service’)

• Show all Applications provided by ‘CloudServices Inc.’:

{{#ask: [[Category:Application]]] }}

(Selects pages in Category:Application linked via the ‘Is Supplied By’ property to ‘CloudServices Inc.’)

• Find Applications using ‘Customer Master Data’:

{{#ask: [[Uses Information::Customer Master Data]] }}

(Selects any page (implicitly Applications if well-modeled) that uses ‘Customer Master Data’)

• Find pages linking to the current page: A common requirement is to find all elements that have a relationship pointing to the current page (incoming links). This is achieved by using the {{PAGENAME}} or {{FULLPAGENAME}} magic word within the query condition. For example, to find all Application pages that depend on the current application page, you could place the following query on the application’s page (likely within its template):
  {{#ask: [[Category:Application]]] }}

This query selects pages categorized as ‘Application’ where the ‘Depends On Application’ property is set to the title of the page where the query is placed. Using this pattern within templates makes it highly reusable and efficient for displaying incoming relationships, such as dependencies or components used by the current element.

Traversing multiple relationship steps within a single query (e.g., finding applications using data owned by a specific department) can be more complex in SMW and may require helper templates, subqueries, or extensions, though the underlying principle of following semantic links remains.

These queries allow for the dynamic generation of architectural views and facilitate impact analysis far more effectively than static documentation. For example, identifying all business processes supported by a specific application before decommissioning it becomes a straightforward query, dynamically reflecting the current state of the documented relationships

Advantages of Using SMW for EA

Leveraging Semantic MediaWiki as an EA repository offers several compelling advantages:

• Flexibility and Agility: SMW makes it relatively easy to adapt the meta-model over time. Adding new properties or relationship types doesn’t typically require complex schema migrations, allowing the repository to evolve alongside the enterprise’s needs. This contrasts with the potential rigidity or vendor lock-in associated with some proprietary tools.
• Collaboration and Knowledge Sharing: The platform inherits MediaWiki’s strong collaborative features, enabling multiple stakeholders to contribute to, refine, and discuss architectural knowledge within a shared space. The familiarity of the wiki interface (due to Wikipedia) can significantly aid user adoption. It fosters the creation of a “shared commons” for architecture information.
• Built-in Versioning: MediaWiki inherently tracks the complete history of changes for every page, providing a robust, automatic audit trail for all architectural artifacts and decisions captured within the wiki.
• Powerful Querying for Analysis: As demonstrated, SMW’s semantic query capabilities enable dynamic reporting, gap analysis, and impact analysis based on the explicitly defined relationships, moving beyond static views. Custom architectural views can be generated on-the-fly to address specific stakeholder concerns.
• Open Source Ecosystem: The core SMW software and many powerful extensions are free of license fees. It benefits from a large community and offers significant extensibility through add-ons for forms, visualization, data import/export, and more. This avoids vendor lock-in, and data can typically be exported in standard formats like RDF or CSV.
• Integration Potential: SMW is designed to be extensible and can be integrated with other enterprise systems, data sources, or external vocabularies, allowing the architectural repository to become a true knowledge hub.

By combining these features, SMW can facilitate a ‘living architecture’ repository. It allows blending the formal ‘design time’ models with collaborative context (discussions, rationale captured on wiki pages). Queries can then present views that merge design intent with operational reality and human insights, creating a richer picture than static documentation alone. However, while the open-source nature eliminates license fees, successful enterprise adoption often requires investment in setup, customization, training, and ongoing support, necessitating either strong internal skills or partnerships with specialized consultants.

Challenges and Considerations

Despite its strengths, implementing SMW as an EA repository presents challenges:

• Initial Setup and Meta-Model Definition: Installing and configuring MediaWiki, SMW, and necessary extensions requires technical effort. More significantly, substantial upfront work is needed to define a robust, appropriate, and agreed-upon EA meta-model – the quality of the repository fundamentally depends on this initial design phase.
• User Training and Adoption: While viewing information may be intuitive for those familiar with wikis, contributors need training on the specific templates, forms (if used), and the underlying semantic concepts to ensure data quality and consistency. Driving adoption requires clear communication, governance processes, and potentially dedicated “wiki gardening” roles to maintain quality. Making the interface truly user-friendly often relies on extensions like Page Forms or custom development.
• Performance and Scalability: For repositories with very large datasets (millions of semantic facts) or highly complex, multi-step queries, performance can become a concern. Addressing this may require careful query optimization, implementing caching strategies (PHP opcode caching, Memcached), tuning database parameters, and potentially deploying SMW with a dedicated RDF triple store backend for demanding query loads. SMW may not scale to Wikimedia’s level for complex semantic operations without significant architectural considerations for the repository itself.
• Query Language Learning Curve: While basic #ask queries are straightforward, mastering advanced features like subqueries, complex result formatting, or navigating intricate property chains requires a deeper understanding of SMW’s query syntax and capabilities.
• Semantic Fidelity: Ensuring users consistently apply properties according to the defined meta-model requires ongoing governance, clear documentation, and the use of templates/forms to guide input. Without this, the repository risks “semantic drift,” where inconsistent annotations degrade data quality and query reliability.
• Content Maintenance and Governance: Crucially, the value of the repository hinges on the quality and timeliness of its content. This is not a “set it and forget it” system. The organization must commit resources to continuously administer, maintain, and update the architectural information as the enterprise evolves. This involves establishing clear ownership for different architectural domains, implementing standardized processes for data entry and updates, conducting regular reviews for accuracy and relevance, and potentially assigning dedicated roles (like “wiki gardeners”) to oversee content quality and user support. Without this sustained organizational effort, even the best-designed repository will quickly become outdated and lose credibility.

Success with SMW for EA is therefore not purely a technical exercise. It demands organizational commitment to define the meta-model, establish governance, train users, and potentially dedicate resources for maintenance and support. Furthermore, architects must consider the architecture of the repository itself, planning for data volume, query complexity, and potential scaling needs, which requires a deeper technical engagement than using some pre-packaged commercial tools.

Conclusion: Is SMW the right fit for your EA repository?

Semantic MediaWiki presents a compelling alternative to traditional EA repositories, offering unmatched flexibility in modeling architectural elements and their intricate relationships. Its powerful, relationship-aware query engine enables dynamic analysis and tailored views that are difficult to achieve with static documentation. Coupled with the inherent collaborative strengths of the MediaWiki platform and the benefits of an open-source ecosystem, SMW can become a vibrant hub for architectural knowledge.

However, realizing these benefits demands a significant investment beyond just installing the software. Success hinges on meticulous upfront meta-model design, technical expertise for setup and potential performance tuning, dedicated user training and adoption efforts, and robust governance processes to maintain data quality.

SMW is likely a particularly good fit for organizations that:

• Prioritize flexibility and adaptability in their EA practice over extensive out-of-the-box features.
• Already utilize MediaWiki internally, leveraging existing infrastructure and user familiarity.
• Possess or are willing to develop the technical skills to manage an open-source platform.
• Place a high value on broad collaboration and discussion around architectural knowledge.

Ultimately, Semantic MediaWiki offers the potential to build a dynamic, deeply interconnected, and collaborative EA knowledge repository. It moves beyond static documentation to create a living representation of the enterprise architecture, enriched by structured data and human context. For organizations prepared to invest in its setup and cultivation, and as evidenced by successful implementations in demanding specialized consultancies, SMW can be a powerful and adaptable foundation for modern Enterprise Architecture management.

Interesting references:

• https://www.semantic-mediawiki.org/wiki/Semantic_MediaWiki
• https://www.archixl.nl/nl/producten/archimedes-architectuurpublicatieplatform
• https://pubs.opengroup.org/architecture/togaf91-doc/arch/chap41.html
• https://www.semantic-mediawiki.org/wiki/Professional_support
• https://www.pro.wiki/semantic-mediawiki-hosting