ea-validation

Logic: AI + AI Power Tools checks. The validator is deterministic; the AI authors rules and interprets results.

What it is for

Use it to check a model or a package against your modeling standard, after an import or a build and before a change is promoted. You end with every element and connector that breaks a rule, and the fixes you approve applied.

ea-validation teaches the AI to write and run conformance rules against a Sparx EA model through the ea_validate tool. A ruleset is a YAML file with a list of rules. Each rule selects elements or connectors by stereotype and applies one condition to them: a required tagged value, a value drawn from a closed list, a connector count, the stereotypes allowed at a connector's two ends, or a check that tagged value types were shipped in a built MDG. The engine reports each element or connector that breaks a rule.

ea_validate has one operation, audit. See ea_validate.

Capabilities it uses

When to use it, and when not

• After importing or building a model that uses a custom MDG, to confirm every element carries the required tagged values.
• Before exporting a model snapshot for downstream use, or as a gate in a model pipeline.
• To run a pre-built hosted ruleset, such as the ArchiMate 3.1 set (ArchiMate 3.1 ruleset), with no local file.

How it works

1. (AI, you) Decide what must hold. Mandatory tags, allowed values, connector cardinality, endpoint stereotypes. Which rules matter, and their severities, is your call.
2. (AI + AI Power Tools checks) Measure the stereotype names. The engine matches stereotype strings exactly against what EA stores for elements and connectors. The AI reads the names EA really stores (the stereotype usage summary, or a list of the distinct stereotypes) before writing a selector.
3. AI Write the rules. Each has an id, a severity, a selector, a condition and remediation text; the critical few are marked to run in demonstration mode.
4. AI Power Tools Run the audit. ea_validate audit with the rules (a file path, a web address or the rules written inline). A full scan runs every rule; demonstration mode runs only the rules marked as demonstration triggers; a package scope limits element rules to one package subtree.
5. (AI + AI Power Tools checks) Check the run actually matched something. Zero violations and zero matched elements produce the same output. The AI counts candidate elements with a read-only query for at least one rule before it reports a model as clean.
6. (AI, you) Report and remediate. The AI groups violations by rule, points at the remediation text, and offers fixes through the modeling skills. The validator never changes the model; you approve fixes.

What a rule contains

Only the list of rules is read by the engine. A header block recording the language, version and sources is for humans and is ignored at run time. Tags in a rule must be listed as named entries, not bare strings: a rule written with bare tag names is refused as malformed, pointing at the rule.

Selectors

Conditions. Which selector a condition works with is part of the grammar: the engine applies a condition only under its own selector type, and a mismatched pairing produces no violations and no error.

Outgoing means the element is the connector's source; incoming means it is the target. A reports-to relationship runs subordinate to manager, so an employee's reports-to count is outgoing from the subordinate. Tag values are read as text: an organizational level is stored as a string even when typed as an integer, so allowed values are "1", "2", "3" and so on.

Matching is exact, and it does not strip a prefix. The engine compares the stored stereotype name exactly: no normalization and no prefix stripping. Two consequences:

• Use the stored name. A technology's namespace is not in what EA stores for the element (the qualified form Tech::Name is held elsewhere), but a prefix that belongs to the stereotype's own name is. EA's built-in ArchiMate technology stores ArchiMate_Assignment, and Assignment matches nothing.
• A selector that is one character off selects nothing, the rule reports no violations, and the output reads exactly like a clean model.

The stored column also holds only an element's first stereotype, so an element carrying several stereotypes is selected by the first only.

Running the validator. The rules source is resolved in this order:

1. A web address starting with https://: fetched at call time (15-second timeout, response capped at 2 MB, no redirects followed, HTTPS only). An http:// address is refused. Failures return a deliberately generic message.
2. A file path, after expanding ~ and %VAR%. An unset variable is left as written, so the error shows which reference did not resolve.
3. A single line that looks like a path (contains / or \, or ends in .yaml or .yml) but is not a file: reported as not found, with the resolved path and a detail. If it is a directory, the detail says so.
4. Anything else is parsed as rules written inline. Inline rules that contain a / or \ need at least one newline, or they are taken for a path.

The path of a "tagged value type shipped" rule's built MDG file is expanded the same way, and an unreadable one is reported with the path it tried.

Running a hosted ruleset. The ArchiMate 3.1 set is hosted in the public skills repository. The AI can run it directly from its hosted location, with nothing installed. The server refuses redirects, so the address must be a direct link to the raw file. To run from disk instead, keep a copy of the YAML in the AI Power Tools rulesets folder, %USERPROFILE%\.claude\ai-power-tools\rulesets\<ruleset-name>\ (rulesets have no skill file, so they sit in the AI Power Tools data directory, not among the skills).

The response. The audit returns whether it succeeded, the mode, the number of rules evaluated, the violation count, and a list of violations. Each violation carries the rule id, the severity, the element's id and name, a message (for example "required tag 'dataClassification' is empty") and the rule's remediation text. For a connector violation, the identifier is the connector's id and the name is connector#<id>. The number of rules evaluated is the number of rules run (after the demonstration filter); it does not say how many elements any rule matched.

Failures are reported without a violation list: an invalid mode (the valid ones are full scan and demonstration), malformed rules, a rule with the wrong shape (naming the rule and the problem), a fetch refused or failed, a path not found, an unreadable rules file or built MDG, or a missing dependency (the YAML library not installed). An unknown operation name returns the list of valid names.

What you get

• A list of rules, written from your requirements and the stored stereotype names, that you reviewed.
• A violation report grouped by rule, with remediation text and a plain statement of how many elements each rule matched.
• An honest statement of whether a clean result is clean or just empty, backed by candidate counts.

Tools it relies on

• ea_validate audit: ea_validate
• summarize_stereotype_usage, for the stored stereotype names: Summaries
• execute_sql, to count what a selector will match (use read-only): Direct queries
• update_element, set_tagged_value, for remediation with your agreement: Elements, Tagged values
• The validation engine module that resolves the rules source, parses it, checks rule shape and replays the selection (Inside the server)
• ea-ruleset-author and the ArchiMate 3.1 ruleset, for whole-language rulesets

Sample prompts

1. "Does every Westbrook data asset have a dataClassification? Write a rule and run it."
2. "Validate the WBA technology: every stereotype's mandatory tags, and criticality must be one of the four allowed values. Only the Applications package."
3. "Run the ArchiMate 3.1 conformance set against this model and summarize what you find."
4. "Every WBABusinessApplication must have at least one outgoing dependency, and none may depend on a WBAVendorSystem that is Retired. What can the validator check?"
5. "My rule says 0 violations but I know there are bad elements. Why?"

Recommended models

Ratings are guidance based on the kind of reasoning the skill needs, not measured benchmarks.

Checking accuracy and completeness

1. The selector matches something. For each rule, count candidates with a read-only query on the stored stereotype (elements, or connectors for a connector rule). Correct: a nonzero count where the model has such elements. Red flag: a rule with zero candidates in a model that has the stereotype, which means a name is one character off.
2. A violation count that an independent query reproduces. For a "tagged value required" rule, count elements with the tag blank or absent and compare. Correct: equal. Red flag: a difference.
3. A planted violation is reported. Create or pick an element that breaks a rule and confirm it appears with the right rule id. This proves the rule can fire.
4. Rules evaluated equals the rules run. The count of rules in the file, or the demonstration subset in demonstration mode. Red flag: a smaller number, which suggests a YAML structure problem.
5. Scope behaves as intended. With a package scope, element rules report only elements inside the subtree. Connector rules are not limited to the package: a connector violation outside the package is expected, not a defect.
6. Endpoint lists name stereotypes that exist. A wrong name in an allowed-source or allowed-target list does not silence a rule; every connector of that type is reported as a violation.
7. The right resolution path ran. A not-found or fetch-failed result is a path or network problem, not a ruleset problem.

Limitations

• No matched-count in the response. The output cannot distinguish "nothing violated" from "nothing selected". Count candidates yourself.
• Exact-match stereotype comparison, first stereotype only. The selector uses the stored stereotype, which holds a single value per element.
• The grammar has five condition types, each bound to one selector type. Rules that depend on the target's properties, on a connector's tags, or on a conditional ("if the source is X then the target must be Y") cannot be expressed. In particular, an endpoint rule applies both lists to every connector it selects. See ArchiMate 3.1 ruleset for how this affects a shipped ruleset.
• Connector rules and connector counts are not scoped by a package.
• Unrecognized condition types, and mismatched selector and condition pairings, produce nothing, without an error.
• Hosted rulesets need network access and HTTPS, with a 2 MB cap, and the error detail is generic by design.
• The "tagged value type shipped" check accepts any child of the file's tagged-value-type list that has a name. Check it against a real built file before using it as a high-stakes gate.
• Every violation is returned in one list, with no cap or pagination setting.
• EA can block on a dialog. EA reports many failures as a modal dialog that waits for a person and blocks every later call, so a call that seems to hang is usually waiting on one (see Shared references). With computer use the AI sees the dialog in EA's window, reads it, uses the message to correct the call, dismisses it and carries on. Without computer use you screenshot the dialog and paste it into the conversation so the AI can analyze it, then dismiss it so processing can continue.