ea_validate

ea_validate checks a model against a validation ruleset: a file of rules that say what a conforming model must look like. One operation exists, audit. It runs a ruleset against the whole model or one package subtree and returns every violation found.

Operation	What it does	When you would use it	Changes the model	Logic
`audit`	Runs a ruleset against the model and returns every violation, each with the rule, severity, the element or connector, a message and the rule's short fix text	A conformance check after a model build or import; before exporting a snapshot; as a gate in a model pipeline; confirming that a repository meets its required tagged values, connector counts and endpoint constraints	No	Deterministic

A ruleset is referenced by path, URL or inline text. Authoring a ruleset is done by a skill, not an operation, and audit returns its result directly and stores no report.

Who decides. The engine is deterministic: it reads the model, applies each rule and returns the violations, and the same rules on the same model give the same result. It does not reason about the model. The AI chooses the ruleset, runs it and interprets the result. See ea-validation for running and reading a ruleset, ea-ruleset-author for building one, and ArchiMate 3.1 ruleset for the hosted ArchiMate ruleset, which can flag items that are in fact acceptable; read its limitations before relying on it.

What a ruleset is

A ruleset is a YAML file with a list of rules. Each rule has:

an identifier, reported with each violation
a severity, reported as given. It defaults to error, and the value is not checked, so error, warning and info are conventions
a selector, saying which things the rule tests
a condition, saying what each selected thing must satisfy
a short fix text, reported with each violation
optionally, a demonstration marker, so a rule can be run alone in a demonstration mode

Everything else in the file (a descriptive header, comments, extra keys on a rule) is ignored by the engine and exists for people.

What a ruleset can express

A rule selects either elements or connectors.

An element rule selects elements by stereotype, optionally narrowed to those whose tagged values are in a given list. An element with no value for that tag is dropped from the selection.
A connector rule selects connectors by connector stereotype.

The conditions it can test:

Rule kind	Applies to	What it checks
Required tagged value (`tagged_value_required`)	Elements	A listed tag is filled in. A missing or blank value is a violation
Allowed tagged values (`tagged_value_constraint`)	Elements	A listed tag that has a value has one of the allowed values. An empty value is not flagged, so pair it with a required-tag rule
Connector count (`connector_count`)	Elements	The element has between a minimum and a maximum number of connectors of a given stereotype, counted outgoing (the default) or incoming
Connector endpoints (`connector_endpoint_stereotype`)	Connectors	The connector's source and target elements have stereotypes from allowed lists. An omitted list counts as empty, so every connector of that stereotype fails
Tagged value types shipped (`tagged_value_type_shipped`)	Elements (the profile's stereotype-defining classes)	Tagged value types defined in the model's reference data and used by the profile were actually included in the built technology, meaning they were selected on the MDG Technology Wizard's Tagged Value Types page

For the last rule kind, the server reads any entry in the built file's tagged-value-type section as a shipped type.

In plain terms, a ruleset can enforce: "every Business Application has a criticality", "criticality is one of these four values", "every Business Application is realized by at least one component", and "a Realization connector joins only these kinds of element". It cannot express anything outside these rule kinds: no cross-element comparisons, no checks on attributes or operations, no tags held on connectors, and no free-form logic.

How to supply the ruleset

The ruleset is supplied as a file path, an https:// address, or the YAML text itself. The server reads the argument in this order:

A web address. A value starting https:// is fetched when audit runs, so a caller can always run the current published ruleset. The fetch is bounded: secure connections only, no redirects, a 15-second timeout and a 2 MB size cap. A plain http:// address is refused. A link that redirects, such as a typical release-download link, is therefore refused. Point at the final link (a raw-content link), or save the file and pass its path.
A file path. A single-line value that names an existing file is read as UTF-8. A leading ~ and Windows-style environment references are expanded first. An unset reference is left as written, so the error shows which one did not resolve.
A path that is not a file. A single line with a path separator, or ending in .yaml or .yml, is treated as a path. If no file exists, the call reports the path it tried and does not fall through to reading it as YAML.
The YAML text itself. Anything else. Inline YAML that contains a slash must include at least one line break, or it is read as a path.

There are two modes: a full scan that evaluates every rule, and a demonstration mode that evaluates only rules carrying the demonstration marker. Optionally the audit can be limited to one package subtree.

What you get back

the mode, the number of rules evaluated, and the number of violations
for each violation: the rule id, severity, the element (or connector) id and name, a generated message such as "required tag 'criticality' is empty", and the rule's fix text. For a connector rule, the id is the connector's and the name reads connector#<id>

Problems with the ruleset itself are reported as errors that say what is wrong: unreadable or invalid YAML, a path that does not exist, a rule with the wrong shape (the commonest being a tag list written as a list of names where the server needs a list of entries), a built technology file that cannot be read, a fetch that was refused or failed, or an unrecognized mode. Rule shapes are checked before any rule is evaluated, so a malformed ruleset fails fast and points at the offending rule. A failed fetch gives a deliberately generic reason, so the call cannot be used to probe a network.

Limits that matter

A clean result does not prove a rule worked. A ruleset that matches nothing returns zero violations, the same output as a clean model, and the response does not say how many elements each rule matched. Confirm that each rule matched something, ideally by making it fail on a known bad element, before reporting a model as clean.
Unknown rule conditions are ignored. A rule is counted as evaluated but produces nothing when its selector type is unrecognized, when an element rule has an empty stereotype list, when a connector rule names no connector stereotype, or when its condition type is unknown or does not belong to its selector (for example an endpoint condition on an element rule). A typo therefore yields a clean result, not an error.
Connector rules are not scoped to a package. The package option limits element rules to that package and its whole subtree at any depth. Connector rules ignore it and always run over the whole model. A package id that does not exist is not an error: it scopes to nothing and returns a clean pass with zero violations.
Stereotype matching is exact. Element rules compare the stereotype as stored on the element, with no normalizing and no prefix stripping. Write it as EA stores it (the plain name, WBABusinessApplication, not WBA::WBABusinessApplication) and confirm the spelling in the model with summarize_stereotype_usage in Summaries. A name one character off selects nothing and the rule reports no violations. If an element carries more than one stereotype, a rule whose stereotype is not that element's first may not select it; check such elements.
Tags are read from element tagged values only. Tags held in other places, such as on connectors, are not read.
Cost and size. Each rule runs one query to find candidates, then more queries per candidate (one per tag, one per connector count, and so on). A broad rule over a large model issues many queries through EA, so scope with the package option. There is no cap or paging on the violation list, so a noisy ruleset returns a large response. Scope the call or run one rule group at a time.
Network use is limited to the ruleset address. Nothing else is fetched.
audit does not change the model and is not affected by read-only mode.

set_active_mdg in Managing technologies records a preference only and enforces nothing. audit is how conformance is checked.