ArchiMate Model Quality

This skill provides guidance on creating high-quality, maintainable ArchiMate models.

Naming Conventions

Element Naming by Type

General Guidelines

• •Use Title Case for element names
• •Use compound terms for clarity ("Student Information System" not "System")
• •Avoid abbreviations unless domain-standard
• •Don't include element type in name when tool shows it visually
• •Use namespacing prefixes for large models: [Business Systems][Customer System]
• •Prefix views with state: ASIS_ApplicationLandscape, TOBE_Integration

EA Smells (Quality Issues)

Common Modeling Errors

1. •Mixing abstraction levels: Detailed processes alongside strategic capabilities
2. •Using Association as default: When specific relationship type applies
3. •Over-modeling: Every detail captured, creating maintenance burden
4. •Wrong element type: Using Process when Function is correct
5. •Missing services layer: Direct connections bypassing service abstraction
6. •View-centric thinking: Creating elements for single view, not reusing
7. •Inconsistent naming: Same concept with different names across views

Abstraction and Granularity

Abstraction Levels by Purpose

Granularity by Element Type

Key Principles

• •80/20 Rule: Only a subset of ArchiMate elements needed for most modeling
• •Match stakeholder needs: Detail viewpoints = one layer/one aspect
• •Limit view complexity: Target ~20 elements per view (40 max)

Viewpoint Selection

Stakeholder-to-Viewpoint Mapping

Pattern-to-Viewpoint Mapping

Model Quality Checklist

Before Creating

• • Define scope and purpose
• • Identify stakeholders and concerns
• • Select appropriate viewpoints
• • Establish naming conventions

During Modeling

• • Follow naming conventions consistently
• • Use correct element types
• • Model at appropriate abstraction level
• • Reuse existing elements (don't duplicate)
• • Add descriptions to elements

Model Review

• • Elements correctly typed
• • Names follow conventions
• • No orphaned elements
• • No strict layer violations
• • Relationships directionally correct
• • Views tell coherent stories

Model Organization

Folder Structure (By Layer)

Model
├── Strategy
├── Business
├── Application
├── Technology
├── Physical
├── Motivation
├── Implementation & Migration
├── Relations
└── Views

Folder Structure (By Domain)

Model
├── Customer Domain
│   ├── Business
│   ├── Application
│   └── Technology
├── Finance Domain
└── Shared Services

Additional Resources

Reference Files

For detailed viewpoint guidance and framework integration:

• •references/viewpoints.md - Complete ArchiMate viewpoints catalog
• •references/framework-integration.md - TOGAF, BPMN, IT4IT integration patterns

Automated Model Audit via the API

To audit a model in Archi, use the Archi Model API Server. Load the archi-server-api skill for full API workflow details. Use the /audit command for a guided audit workflow.

Querying for Quality Issues

Find Orphan Elements (Lonely Components)

Search for elements of each type and check for empty relationship arrays:

# Get all business actors
curl -s -X POST http://localhost:8765/model/search \
  -H "Content-Type: application/json" \
  -d '{"type": "business-actor", "limit": 200}'

# Get details for a specific element (includes relationships and views)
curl -s http://localhost:8765/model/element/ELEMENT_ID

Elements where the relationships array is empty are orphans.

Check Naming Conventions

Search elements and inspect names against the conventions table above:

# Find processes that might not follow Verb+Noun convention
curl -s -X POST http://localhost:8765/model/search \
  -H "Content-Type: application/json" \
  -d '{"type": "business-process", "limit": 200}'

Check each name:

• •Processes should start with a verb ("Handle", "Process", "Submit", "Validate")
• •Structural elements should be singular noun phrases in Title Case
• •Services should be noun/gerund phrases

Find Duplicate Elements

# Search with a common name fragment
curl -s -X POST http://localhost:8765/model/search \
  -H "Content-Type: application/json" \
  -d '{"namePattern": "Customer", "limit": 100}'

Compare results for same-type elements with identical or near-identical names.

Find Dead Elements (Not in Any View)

curl -s http://localhost:8765/model/element/ELEMENT_ID

If the views array in the response is empty, the element is not on any view.

Check for Missing Documentation

Search all elements — those with empty documentation field need attention:

curl -s -X POST http://localhost:8765/model/search \
  -H "Content-Type: application/json" \
  -d '{"limit": 500}'

Detect Association Overuse

Search for association relationships and check if a more specific type applies:

curl -s -X POST http://localhost:8765/model/search \
  -H "Content-Type: application/json" \
  -d '{"type": "association-relationship", "limit": 100}'

Applying Fixes

Rename Elements

curl -s -X POST http://localhost:8765/model/apply \
  -H "Content-Type: application/json" \
  -d '{"changes": [
    {"op": "updateElement", "id": "ELEMENT_ID", "name": "Corrected Name"}
  ]}'

Add Documentation

curl -s -X POST http://localhost:8765/model/apply \
  -H "Content-Type: application/json" \
  -d '{"changes": [
    {"op": "updateElement", "id": "ELEMENT_ID", "documentation": "Purpose and description of this element"}
  ]}'

Remove Orphan Elements

curl -s -X POST http://localhost:8765/model/apply \
  -H "Content-Type: application/json" \
  -d '{"changes": [
    {"op": "deleteElement", "id": "ORPHAN_ID", "cascade": true}
  ]}'

Always poll GET /ops/status?opId=OP_ID after applying changes, then POST /model/save to persist.