Published: 2026-04-18 Category: How To Offering relevance: Amplify
Direct Answer
Configuring MDG Technology in Sparx EA involves seven steps: understanding your governance requirements, reviewing existing MDGs already in your installation, designing your stereotype structure, building the MDG using the MDG Technology editor, defining validation rules, deploying to the repository, and training the team. The most common mistake is starting with the MDG editor before completing Steps 1–3 — the design decisions made in those steps determine whether the MDG delivers governed intelligence or just adds technical complexity. MDG configuration is the governance investment that makes your EA repository AI-queryable and BI-useful — it is worth doing carefully. Sparx Services delivers custom MDG design and implementation through the Amplify engagement, typically 4–8 weeks end to end.
Key Takeaways
- MDG configuration starts with requirements, not tooling — design before building.
- Review existing MDGs first: you are likely extending ArchiMate, not starting from scratch.
- Stereotype design is the key decision: which new element types do you need? Which are extensions of existing ArchiMate types?
- Tagged value enumeration design is the AI quality gate: controlled vocabularies enable precise AI queries.
- Validation rules are the enforcement mechanism: without them, governance is advisory, not enforced.
- Deployment to the repository (via Pro Cloud Server) makes the MDG active for all connecting Sparx EA clients.
- Version control the MDG XML file — treat it as code.
- Sparx Services builds custom MDGs as the core of the Amplify engagement.
Step 1: Understand What You Need to Govern
Before opening the Sparx EA MDG editor, complete a governance requirements analysis. This is a documentation and workshop step, not a tool step.
Questions to answer:
What modeling domains does your team use?
- ArchiMate (almost certainly — if not, activate it)
- BPMN (if process modeling is in scope)
- SysML (if systems engineering is in scope)
- Custom elements (what does your team model that does not fit neatly into ArchiMate or BPMN vocabulary?)
What element types do you need that do not exist in built-in MDGs? Example gaps in ArchiMate that organisations commonly address with custom stereotypes:
SaaS Application— an Application Component with cloud provider, subscription model, and vendor SLA attributesLegacy System— an Application Component with technical debt rating and migration priorityExternal Partner System— an Application Component with integration interface type and data classificationRegulatory Requirement— a Requirement element with regulation reference, jurisdiction, and compliance status
What governance attributes (tagged values) do you need on each element type? For every element type your team models, list the governance attributes that must be captured for the repository to be useful for portfolio analysis, executive reporting, and AI querying. Example for Application Component:
Lifecycle Status(enumeration: Active/Tolerate/Migrate/Eliminate/End-of-Life/Decommissioned)Business Owner(text: name of responsible business manager)Technical Owner(text: name of responsible IT team or manager)Business Domain(enumeration: your domain taxonomy)Annual Run Cost(currency)Business Criticality(enumeration: High/Medium/Low)Technical Health(enumeration: Good/Fair/Poor)Cloud Provider(for SaaS/cloud elements — enumeration: AWS/Azure/GCP/Other/On-Premises)
What validation rules need to be enforced?
- Which tagged values are mandatory? (Cannot save element without value)
- Are there naming conventions to enforce? (Naming pattern regex)
- Are there relationship constraints? (Application Components must have at least one Realisation to a Capability)
What custom diagram types do you need?
- Standard ArchiMate diagram types (Application Layer, Business Layer, etc.) are usually sufficient
- Custom diagram types are needed if you want to constrain which elements can appear in a specific diagram type
Document all of this before proceeding. The MDG build is the implementation of this design — not the place to make design decisions.
Step 2: Review Existing MDGs
Before building new stereotypes, thoroughly review what already exists in your Sparx EA installation. Many teams build custom stereotypes that duplicate built-in ArchiMate or TOGAF types they were not aware of.
In Sparx EA: Settings → MDG Technologies → View all active MDG packages
What to review:
- ArchiMate MDG: all element types in each layer (Strategy, Business, Application, Technology, Physical)
- TOGAF Content Metamodel MDG (if activated): Principle, Requirement, Gap, Work Package, Plateau
- Any previously installed custom MDGs from your organisation
Common discoveries at this step:
- ArchiMate’s
Capabilityelement (Strategy layer) already exists — teams sometimes create a custom “Capability” stereotype unnecessarily - ArchiMate’s
Principleelement exists in both ArchiMate and TOGAF MDGs — duplication confusion - A previous architect already created a partial custom MDG that needs extension rather than replacement
Decision output: For each governance requirement identified in Step 1, decide:
- Does an existing MDG element type cover this? (Use it — extend with tagged values only)
- Does an existing type need extension with custom tagged values? (Create a custom stereotype extending the existing type)
- Does an entirely new element type need to be created? (Create a new stereotype from a UML base metaclass)
Most governance requirements are satisfied by extending existing ArchiMate types with custom tagged values — not by creating new element types from scratch.
Step 3: Design Your Stereotype Structure
With the requirements analysed and existing MDGs reviewed, design the stereotype structure:
Stereotype hierarchy:
Create a hierarchy diagram (not in Sparx EA yet — draw this on paper or in a simple diagram tool first):
“ UML Component (base) └── ArchiMate Application Component (built-in MDG) ├── SaaS Application (custom — adds: CloudProvider, SubscriptionModel, VendorSLA) ├── Custom-Built Application (custom — adds: DevelopmentLanguage, CodeRepository) └── Legacy System (custom — adds: TechnicalDebtScore, MigrationPriority) “
For most organisations, 3–8 custom stereotypes covering the key element types (applications, capabilities, technology nodes, decisions) is the right scope for the initial MDG build. Avoid stereotype proliferation — more stereotypes means more modeling discipline required and more complexity to maintain.
Tagged value enumeration design:
For every enumeration tagged value, define the complete list of allowed values. This is the AI quality gate — the enumeration values become the controlled vocabulary that AI assistants use to filter and categorise:
Lifecycle Status enumerations:
- Active
- Invest
- Tolerate
- Migrate
- Eliminate
- End-of-Life
- Decommissioned
Business Domain enumerations:
- [Your specific domain taxonomy — derived from your Level 1 capability map domains]
- Customer Management
- Financial Management
- Supply Chain Management
- Technology Services
- Human Capital Management
- Risk and Compliance
Do not use free text where an enumeration is possible. Every field that will be used for filtering, grouping, or counting in BI dashboards or AI queries should be an enumeration with controlled values.
Step 4: Build the MDG Using the MDG Technology Editor
With design documentation complete, open Sparx EA to build the MDG.
Approach: UML Profile-based MDG construction
- Create a new package in the repository for MDG development (separate from operational architecture content — e.g., a “MDG Development” package at the root level, protected from read/write access by general team members)
- Within the MDG development package, create a UML Profile package for each stereotype domain:
– Application Architecture Profile – Business Architecture Profile – Decision Register Profile
- Within each Profile package, create Stereotype elements:
– Right-click the Profile package → Add Element → Profile → Stereotype – Name the Stereotype (e.g., “SaaS Application”) – Set the Base: the UML metaclass or ArchiMate element this extends (e.g., base = “Component” for a stereotype extending Application Component)
- Add Tagged Value definitions to each Stereotype:
– In the Stereotype element properties → Tags tab → Add tag definition – For each tag: name, type (string, integer, boolean, enumeration), allowed values (for enumerations), default value, notes
- Add Constraint elements for validation rules (attached to Stereotype elements):
– Constraint type: OCL (Object Constraint Language) for complex rules – Constraint type: simple property constraints for mandatory field checks
- Set display settings: icon (for custom element appearance in diagrams), shape (if custom shape is needed), colour defaults
MDG Technology wizard:
After building the Profile packages, use the MDG Technology wizard to package the profiles into a deployable MDG file:
Settings → MDG Technology → Generate MDG Technology File
The wizard prompts for:
- MDG Technology name and ID
- Version number
- Author
- Which Profile packages to include
- Output file location (save as
[OrganisationName]EAMDG.xml)
Step 5: Define Validation Rules
Validation rules are the enforcement mechanism — they surface governance violations when architects validate the model. Configure validation in two ways:
Within the MDG (constraint-based):
On each Stereotype element, add OCL constraints for mandatory fields: “ocl -- Constraint: BusinessOwner must be populated self.taggedValues->exists(tv | tv.tag = 'BusinessOwner' and tv.value <> '') “
On relationship constraints: “ocl -- Constraint: Application Component must have at least one Realisation to Capability self.supplier.oclIsKindOf(ArchiMate3::Strategy::Capability) or self.supplierDependencies->exists(d | d.oclIsKindOf(Realisation)) “
Validation script approach (more flexible):
For complex validation rules, write Sparx EA scripts (JavaScript in the scripting engine) that are run on demand or triggered on model changes. Scripts can:
- Check all elements in a package for mandatory tagged value completeness
- Generate a validation report listing violations by package and element
- Apply auto-fix for simple issues (set default values on empty fields)
Validation report integration: Configure the validation script to output results to a Results window report in Sparx EA. Architects can run the validation before saving for governance review or before an ARB submission. The report shows which elements have violations and what the violation is.
Step 6: Deploy to the Repository
With the MDG XML file generated, deploy it to the Sparx EA repository so all connecting clients receive it:
Method 1 — Per-project deployment:
- In Sparx EA client: Settings → MDG Technologies → Import
- Browse to the MDG XML file → Import
- The MDG is now active in this repository for this client session
Method 2 — Pro Cloud Server deployment (recommended for team repositories):
Deploy the MDG XML to the Pro Cloud Server configuration so all clients receive it automatically on connection:
- Copy the MDG XML file to the PCS shared MDG folder (configured in PCS settings)
- Configure PCS to serve this MDG to connecting clients
- All Sparx EA clients connecting to the repository via PCS automatically receive the MDG without individual import
Method 2 is required for team repositories — it ensures all architects use the same MDG version and removes the need for individual import steps.
Version control: Store the MDG XML file in your organisation’s version control system (Git repository). Tag each version. When the MDG is updated, commit the new version, increment the version number in the MDG metadata, and redeploy via PCS.
Step 7: Train the Team and Enforce Via Validation
An MDG without team adoption is wasted. Training and enforcement are the final and ongoing steps:
Training content:
- What stereotypes exist and when to use each one
- How to add tagged values when creating elements
- How to run validation and interpret results
- What the validation rules enforce and why
- Where to find the MDG reference documentation (publish the design documentation from Step 1 in the repository as architecture principles)
Enforcement approach:
Advisory enforcement (recommended to start): Run validation as a team review activity before ARB submissions. Architects are expected to resolve violations before submitting content for review. This is low-friction and builds the governance habit.
Gated enforcement (after governance culture is established): Configure the ARB workflow so that content with outstanding validation violations cannot be submitted for review — the validation must pass. This requires integration between the validation mechanism and the ARB process.
Automated enforcement (advanced): Use Sparx EA’s automation interface (scripted on-save validation) to check elements as they are saved and alert architects to violations immediately. This is the most immediate feedback loop but requires scripting effort.
Frequently Asked Questions
Q: How do we handle elements created before the MDG was established? Run a validation report on existing repository content against the new MDG rules. Violations will appear for elements that pre-date the governance standards. Remediation is typically prioritised: start with the most critical element types (Application Components, Capabilities) and the most critical tagged values (Lifecycle Status, Business Owner). Less critical violations can be addressed in a subsequent governance sprint. Do not attempt to fix all historical violations simultaneously — this is a common mistake that produces inconsistent partial remediation rather than systematic improvement.
Q: Can we have different MDG versions for different projects or teams? A single repository should use a single MDG version — this is the governance principle. Multiple MDG versions in the same repository produce inconsistent element types and make cross-domain analysis unreliable. If different teams have significantly different modeling needs, the MDG should be designed to accommodate both (with stereotype alternatives for different use cases) rather than split into separate versions. For truly separate programs with different governance requirements, separate repositories (each with their appropriate MDG version) may be the right answer.
Q: How long does it take for the team to adopt MDG governance? Based on Sparx Services’ implementation experience, meaningful adoption (most new elements created with correct stereotypes and key tagged values populated) typically takes 4–8 weeks after MDG deployment, with active training and enforcement. Full adoption (90%+ compliance across all element types and tagged values) takes 3–6 months, supported by regular validation reviews and a governance culture that treats MDG compliance as part of the architect’s quality standard. Without active management, adoption plateaus at a lower level and data quality degrades over time.
Q: Can we use the MDG to enforce naming conventions? Yes. OCL constraints or scripted validation rules can check element names against a naming pattern (using regex or simple string prefix/suffix checks). Example: “All Application Component names must not include abbreviations from the banned list” or “All Capability elements must use Title Case”. Naming constraint validation is advisory in practice — strict naming enforcement can frustrate architects for legitimate edge cases. A combination of published naming conventions (in the repository Principles package) and advisory validation (flagging violations without blocking) works well.
Q: Is it possible to map the custom MDG to ArchiMate specification elements for compliance? Yes. When custom stereotypes extend ArchiMate base types (e.g., SaaS Application extending Application Component), the custom elements are compatible with ArchiMate’s specification — they are specialisations of ArchiMate element types, not replacements. ArchiMate-compliant tools and interchange formats (ArchiMate Open Exchange Format) will treat the custom stereotype as the base ArchiMate type. The custom tagged values are not part of the ArchiMate spec but are proprietary extensions, which is standard and expected for enterprise implementations.
Q: Can the MDG be used to define relationship constraints (what can connect to what)? Yes. Sparx EA’s MDG can define relationship constraints on stereotypes — which relationship types are allowed from a given stereotype to other element types. Example: a SaaS Application stereotype can be constrained to allow Realisation relationships to Capability elements, Deployment relationships to Cloud Platform Node elements, and Association relationships to Business Owner role elements — but not arbitrary relationship types to arbitrary elements. Relationship constraints enforce modeling discipline and make validation meaningful. They require the MDG to define the relationship type constraints in the stereotype profile.
Q: How does the MDG integrate with Sparx EA’s Pattern feature? Patterns (Model Templates) in Sparx EA provide reusable package structures pre-populated with elements of specific types. Once the MDG defines the stereotypes and tagged values, Patterns use those types to create standard starting structures — a “New Business Domain” pattern creates a package with the standard sub-packages, a pre-populated Level 2 capability element template, and an Application Portfolio placeholder, all using the correct MDG stereotypes. Patterns and MDG work together: MDG provides the vocabulary; Patterns provide the structure. Sparx Services builds both in the Amplify engagement.
Q: What is the relationship between the MDG and EA GraphLink’s schema? EA GraphLink Interface A (GraphQL) and Interface B (MCP Server) both use the repository’s MDG configuration to build their semantic schema. When EA GraphLink generates its GraphQL schema or its MCP capability declaration, it includes the MDG-defined stereotypes as queryable element types and the tagged value enumerations as queryable dimensions. A custom stereotype SaaS Application becomes a distinct queryable type in the GraphQL schema and in the MCP capability declaration. This is why MDG design and EA GraphLink deployment are tightly coupled — the MDG is the semantic layer that makes EA GraphLink’s intelligence useful.
Q: Do we need to rebuild the MDG every time we want to add a new tagged value? Incremental MDG updates are straightforward: add the new tagged value definition to the appropriate stereotype in the MDG profile, regenerate the MDG XML file using the wizard, increment the version number, and redeploy via Pro Cloud Server. Existing elements are not affected immediately — they will have the new tagged value definition available from the next time they are edited, but historical elements will have empty values for the new field until manually populated or migrated via script. Sparx Services recommends versioning MDG updates and communicating changes to the team before deployment.
Ready to Build Your MDG Governance Framework?
Sparx Services’ Amplify engagement delivers your custom MDG Technology extension — from requirements analysis through stereotype design, build, validation rule configuration, and deployment.
We transfer MDG knowledge to your team during the engagement, so you can extend and maintain the governance framework independently after delivery.
