ea-mdg-author

Logic: AI + AI Power Tools checks. The AI designs the metamodel and writes the file; deterministic tools emit, read back and validate it.

What it is for

Use it to write a small or one-off modeling language directly, or patch a shipped technology file. You end with an MDG Technology XML file that EA accepts, ready to deploy with ea-mdg-deploy.

ea-mdg-author writes the file of a Sparx EA MDG Technology: a modeling language made of stereotypes (each applied to a base type), the tagged values they carry, custom diagram types, and toolbox pages that put the stereotypes on a palette. It treats the file as the source of truth (see Three ways to get a technology). It covers:

• the file's skeleton, and the identifier and encoding rules that decide whether EA accepts it
• element and connector stereotypes, tagged value types, and the choice of base type
• custom diagram types and toolbox pages, including the exact-text match between them
• Quick Linker rules
• a companion validation rules file, written instead of scripts embedded in the technology
• migrating existing elements onto the stereotypes of an installed technology

It also covers the second way in: writing the file from a candidate metamodel that a census of an existing repository produced.

Capabilities it uses

When to use it, and when not

Before you edit, ask whether the MDG has a source model. Hand-editing the file of a technology that has a source model of profile packages causes permanent, silent divergence: the edit works today, and the next model-driven export regenerates the file from the packages and discards it. If you are not sure, ask before editing.

How it works

1. (AI, then you) Establish that the file is the source of truth. Ask whether a source model exists; if it does, stop and route to ea-mdg-model-build. If the technology is being generated from a census, record in the technology's notes that the file is the source of truth.
2. AI Write element stereotypes. One per concept, applied to a standard base type with its tagged values. The base type is chosen to be one the Project Browser renders natively (see below).
3. AI Write connector stereotypes, only if the technology needs its own relationship semantics. A technology need not define any. Plain UML connectors (Dependency, Realization, Association, Aggregation) work without a stereotype.
4. AI Write custom diagram types and toolbox pages. Each diagram type binds to a toolbox page by exact text match.
5. AI Add Quick Linker rules, optionally, and only when connector stereotypes exist.
6. AI Write the companion validation rules file. One "required tag" rule per mandatory tag, never scripts embedded in the technology.
7. AI Power Tools Emit and read back. When the file is generated, write_mdg_xml emits it and parse_mdg_xml reads it back; the AI compares counts, names, base types and tags with the design. For a hand-written file, reading it back is the syntax and structure check.
8. AI Hand off to deploy. ea-mdg-deploy installs and verifies. A success return from an install is not proof. A technology with toolbox pages belongs at Location: Model. A file reaches Location: Model only through EA's Import to Model dialog AI with computer use; otherwise you, whereas install_mdg with the embedded scope stores a file at Location: Project and drops the toolbox pages. A technology that will be maintained belongs in a source model (ea-mdg-model-build), from which one install call stores it at Location: Model.
9. (you, then AI + AI Power Tools checks) Decide whether to migrate existing elements. After a successful deploy the AI asks whether existing elements should be moved onto the technology's stereotypes. If you say yes: the AI finds candidates with a read-only query, you confirm the list, the AI updates the confirmed elements, and the validation rules run over the result.

The file's structure

An MDG file has one technology root and three parallel sections:

The technology's id appears in three places that must agree exactly: the root, the top-level documentation entry and the profile's own documentation entry. A mismatch in the last is the most common reason a toolbox fails to resolve.

Rules that apply to the whole file:

Stereotypes and tagged values. An element stereotype has a name (EA stores the bare name on the element and a qualified form for profile-aware tools, as in WBA::WBABusinessApplication), a display label, a note, colors, a default size, the base type it applies to, and a list of tagged values. The Westbrook WBABusinessApplication stereotype applies to Component and carries six base tags. Applying a stereotype to the wrong base type is the most consequential single error in an MDG. Tagged value types confirmed on EA 17 are String, enumeration (with a comma-separated list of values), Boolean, Date, memo, RefGUID, url, file and Integer.

Base type and Project Browser visibility. The base type decides the type EA stores. It must be a standard type the Project Browser renders natively, or the elements are invisible in the browser tree while still appearing on diagrams and in queries.

A standalone technology bases its stereotypes on a UML type and carries the ArchiMate or BPMN concept in the stereotype name and tags. If elements are already stored with the wrong base type, changing the type through the normal operation is silently ignored for ArchiMate-typed elements. The repair is a direct update to the repository's stored type, followed by closing and reopening the project. That write bypasses EA's own safeguards, so take a baseline first (ea-change-management).

Connector stereotypes apply to a connector type (Dependency, Association, Realization, Aggregation, Composition, InformationFlow, Sequence). The Westbrook illustration defines three: Uses on an Association, Flows on an InformationFlow and realizes on a Realization, each carrying the same three closed-list tags (data flow classification, integration pattern and SLA tier). For a relationship between Westbrook elements, one of them is used where it fits, and a plain UML connector otherwise. The skill's worked example of adding another, a "runs on" connector between a business application and a vendor system, is a proposed extension shown only to teach the pattern.

Diagram types and toolbox pages. A diagram type has a display label shown in the New Diagram dialog (EA 17.0 shows the stereotype name instead of the label), an identifier, and a toolbox it uses. A toolbox page is one stereotype of its own kind; each palette item on it names the stereotype in qualified form, <TechID>::StereotypeName in the skill's pattern, where the prefix is the technology id that the profile's own documentation entry declares (for Westbrook, WBA::WBABusinessApplication). One page per stereotype; several pages can sit in one toolbox section.

How a diagram type finds its toolbox depends on exact text, and a mismatch leaves the diagram type without its toolbox. The diagram profile names the toolbox by text. Two forms are in use: the toolbox page's own name, which the skill's pattern uses, and the technology id followed by two colons and the name of the toolbox's UML profile, which the Westbrook technology uses and which resolves there. Whether the text resolves also depends on how the diagram profile is named (the Westbrook technology names its diagram profile with its technology id), so the skill recommends trying your form on a scratch diagram before relying on it. A stereotype on no toolbox page ships invisible: it validates, and nobody can place it. The skill also gives the identifier pattern for names over 12 characters and a short palette of integer colors (light blue, light grey, light green, light amber).

Quick Linker is the hover menu EA shows on a diagram element for creating connectors. Rules live on the source stereotype and name a target stereotype, in the <TechID>::Name form.

• Add rules only when connector stereotypes exist. A plain relationship already appears in EA's default menu.
• Hide EA's default UML links only when at least one rule exists; otherwise the menu is empty and looks broken.
• A target written without the technology prefix does not resolve and fails silently.
• When the file is generated, declare the rules on the source stereotype in the metamodel and the writer emits them.
• The Westbrook technology's own rules use its connector stereotypes: a vendor system element offers a Uses connector to a technology node element.
• For a technology expressed as a model, the equivalent is a connector tagged value on a connector stereotyped "stereotyped relationship". That belongs to ea-mdg-model-build.
• AI with computer use; otherwise you To check it in EA: deploy, restart EA, drop a source element on a diagram and hover for one to two seconds. The overlay disappears when focus changes, so capture it immediately.

The validation rules file. Do not embed validation scripts in the technology: that mechanism runs inside EA's own scripting engine, which ea_validate does not run. Ship a companion rules file named for the technology and run it with ea_validate: one "tagged value required" rule per mandatory tag (for example, every WBADataAsset must have a non-empty dataClassification). Run it after every install, and confirm it evaluated more than zero elements before treating zero violations as a clean model; see ea-validation.

Authoring from a generated candidate. The other way into this skill is a repository that already contains an undeclared language. The sequence is: census, candidate metamodel, write the file, read it back and compare, install, verify.

1. Engine Census, profile-aware, not the stereotype usage summary alone (its bare-name table cannot separate governed from ad hoc use of one name).
2. Shape the candidate: technology id, name, version, notes (record the provenance here: generated, from which repository, on what date), stereotypes (name, label, base type, notes, tagged values) and diagram types.
3. Emit with write_mdg_xml.
4. Read it back before installing: parse_mdg_xml the output and compare stereotype count, names, base types and tags with what you passed in. Install and deploy both report success on a file that is missing content.
5. Install and verify through ea-mdg-deploy. Its checks on screen are AI with computer use; otherwise you.

Points specific to authoring from a generated candidate:

• Naming. A census gives names, not display labels. Strip the known technology prefix first, then split; do not split mechanically (WBABusinessApplication becomes wbabusiness_application). Where a technology is loaded, get_mdg_from_runtime supplies real labels and they win. Otherwise the AI puts the derived labels in front of you before shipping them.
• The effective id limit is 7 characters. The writer generates the diagram and toolbox identifiers by adding a suffix, so an 8-character id yields a 13-character derived id. The writer checks every id before writing and refuses, naming the field, the value, its length and the limit. A hand-written file has no such check. Shorten a census-derived id deliberately rather than truncating it.
• Connector stereotypes. A census finds connector stereotypes as readily as element ones, and counts them by stereotype and connector type. An observed connector stereotype is often a shipped language's relationship (for example from the BMM, UML standard-profile or BPMN technologies); adopting it makes an accident permanent. Check the profile binding before promoting one. A qualified name typed into a free-text stereotype field with no binding behind it is a data defect to fix in the repository, not a stereotype to adopt.
• Enumeration tags stay free text. The writer emits no reference data. A technology installed from the writer's output alone gives free-text fields where a closed list was intended. Say so when handing it over. Reference data is covered by ea-mdg-model-build, Phase 3.
• The writer fixes geometry and colors. Every element stereotype is written at one default size and the theme-default color. Sizes and colors need a hand edit afterwards, which commits you to the file as the source.

Migrating existing elements after install. EA does not update existing elements when a technology is installed. After a successful deploy:

1. Ask. "The MDG is installed. Would you like to apply it to existing elements?" If no, stop.
2. Find candidates with a read-only query: elements whose stored type matches the stereotype's base type and whose stereotype is not already one of the technology's. Present the list and confirm which to change.
3. Update each confirmed element with update_element (stereotype and initial tagged values). Do not set stereotypes by writing to the database directly: EA's cache will not see it.
4. Validate with the rules file and ask you to fill required tags before saving.

EA may reject a stereotype whose base type does not match the element's current type. The update then reports a stereotype warning and lists the properties that did not apply. The AI reads both.

What you get

• A technology file (stereotypes, tags, diagram types, toolbox pages, optional Quick Linker rules) that reads back to match the design.
• A companion validation rules file.
• For a generated technology, a candidate you reviewed before anything was written, and provenance in the technology's notes.
• After deployment and your agreement, existing elements migrated onto the technology's stereotypes.

Tools it relies on

• write_mdg_xml, parse_mdg_xml, get_mdg_from_runtime, install_mdg: Authoring, Managing technologies, Discovering technologies
• update_element: Elements
• set_connector_tagged_value and its get, list and delete siblings: Tagged values
• execute_sql (read-only use): Direct queries
• ea_validate audit: ea_validate
• The census helper (an engine: needs local code execution), and the file-encoding and latency references: Shared references

Sample prompts

1. "I need a small MDG for Westbrook Bank with a Business Application and a Vendor System stereotype, both Components, with criticality and lifecycle tags. Write the file."
2. "Add a toolbox page and a custom Application View diagram type to the WBA technology."
3. "Generate an MDG from the stereotypes people actually use in this repository. Show me the candidate before you write anything."
4. "Add a validation rules file for WBA that requires dataClassification on every data asset, then run it."
5. "WBA is installed. Move the existing data classes onto WBADataAsset and give them empty governance tags, after showing me the list."

Recommended models

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

Checking accuracy and completeness

1. Read the file back. Read the written file with parse_mdg_xml. Correct: stereotype count, names, base types and tags equal the design; diagram type count equals the design. Red flag: any difference, or a parse failure.
2. Check every identifier. Correct: every id is 12 characters or fewer, the three technology-id occurrences are identical, and for a generated technology the derived diagram and toolbox ids fit. Red flag: a rejected import with no other cause.
3. Check the text bindings. Correct: a scratch diagram of each custom type shows its toolbox, whichever text form your file uses (the toolbox page's name, or the technology id and the toolbox profile's name); each palette item names a qualified stereotype that exists, and every stereotype appears on a page. Red flag: a diagram type whose toolbox is empty, or a stereotype on no page.
4. Verify the loaded result against the file. After deploy, get_mdg_from_runtime with the technology id. Correct: the answer is live (not "registered, not enabled"), comes from the Location you installed to with no second copy named, and carries the same stereotypes, tags and diagram types as the file. Red flag: any other label, a second copy, or a version mismatch.
5. Prove the validation rules can fire. Run them in demonstration mode on data that violates a rule. Correct: more than zero rules evaluated and the violation appears. Red flag: zero violations with no check that any element matched (a rule whose stereotype name is one character off selects nothing and reads as a clean model).
6. Check migration writes. After an update, re-read the element. Correct: stereotype set, no rejected properties, no stereotype warning. Red flag: a success response with a non-empty list of rejected properties.
7. Check enumeration tags in the UI when the technology is generated: expect free text unless reference data was added separately.

Limitations

• A hand-authored file and a source model diverge permanently. The skill cannot detect that someone else maintains a model for the technology, so it asks before editing.
• Generated files ship no reference data, so enumeration tags are free text unless reference data is created separately.
• The writer fixes sizes and colors (see above).
• A file reaches Location: Model only through an EA dialog. The AI drives Import to Model with computer use and otherwise you do it. install_mdg with the embedded scope stores a file at Location: Project and drops its toolbox pages.
• The skill's examples were verified on EA 17.0 build 1704. The in-model Locations were measured on EA 17.1 build 1716.
• Quick Linker can only be verified in the UI, and the overlay cannot be captured reliably. With computer use the AI makes the attempt; without it the check is yours.