| name | mps-aspect-structure-concepts |
| description | Define concepts, interface concepts, enumerations, and constrained data types in an MPS language's `structure` aspect. Covers smart-reference detection, alias rules, cardinality, INamedConcept usage, bulk creation, and the full `mps_mcp_alter_structure` / `mps_mcp_query_structure` reference. Use when authoring or modifying a language's structure model. |
| type | reference |
MPS Structure Aspect — Concepts
Concepts (ConceptDeclaration), interface concepts (InterfaceConceptDeclaration), enumerations (EnumerationDeclaration), and constrained data types (ConstrainedDataTypeDeclaration) are root nodes in a language's structure model. They use the language jetbrains.mps.lang.structure.
Critical Directives
- Implement
INamedConcept instead of declaring name directly. A name property declared directly on a concept is an antipattern in MPS — implement jetbrains.mps.lang.core.structure.INamedConcept instead.
- Smart reference check (CRITICAL): before setting a
conceptAlias, determine whether the concept is an "Implicit Smart Reference". If it has exactly one mandatory reference and no properties or children of its own, do NOT set a conceptAlias — the concept should be transparent in the editor and completion menu so the user types the target's name directly. Examples: variable references, method calls, routine calls.
- Leave alias empty on transparent collections too (e.g.
StatementList).
- Set alias on concepts that can be root — that's how the user reaches them through the new-root menu.
- Always rebuild the language with
mps_mcp_alter_nodes MAKE and rebuild="true" after structural changes, so the new concepts are discoverable by runtime tools.
Prerequisites
- Requires the target language and its
structure model.
- Uses the
jetbrains.mps.lang.structure language.
- Concepts, interface concepts, and enums are root nodes in the
structure model.
Workflow
- Locate language: use
mps_mcp_get_project_structure to find the language and its structure model.
- Module creation: if needed, create the module via
mps_mcp_create_module using an absolute path.
- Define elements:
- ConceptDeclaration: core entities.
- InterfaceConceptDeclaration: orthogonal functionality.
- EnumerationDeclaration: fixed values.
- ConstrainedDataTypeDeclaration: regex-restricted properties.
- Attributes (annotations): concepts extending
NodeAttribute / PropertyAttribute / ChildAttribute / LinkAttribute that graft extra children/data onto other concepts without editing them — see Attributes section below.
- Inheritance & interfaces:
- Use inheritance and abstract concepts for shared logic.
- Implement
jetbrains.mps.lang.core.structure.INamedConcept if the concept needs a name property.
- Smart reference assessment: see directives above.
- Set alias on concepts that can be root: helps the user instantiate the concept through a menu.
- Leave alias empty on smart references and transparent collections: e.g.
StatementList.
- Property definition:
- For enum properties: create the
EnumerationDeclaration first, then set the property dataType to reference it.
- Proper cardinality: make sure intended child collections have the cardinality of
0..n or 1..n.
- Bulk operations: use
mps_mcp_alter_structure for creating multiple concepts or enums efficiently.
- Local references within the same JSON blueprint can use names for resolution.
- Reload runtime: always rebuild the language (via
mps_mcp_alter_nodes with MAKE and rebuild="true") after structural changes to make concepts discoverable.
Attributes (Annotations)
Attributes let one language attach extra children, references, or property data to nodes of a concept it does not own — without editing or subclassing that concept. The host carries a universal smodelAttribute child slot (0..n, every BaseConcept has it); the attribute's own declaration says where it may attach. Used heavily for cross-cutting concerns: generator macros (NodeMacro/PropertyMacro/ReferenceMacro), documentation/description comments, requirement traces, error suppression.
- Declare an attribute = a
ConceptDeclaration that extends one of NodeAttribute (whole node), PropertyAttribute (one property), ChildAttribute (one child link), or LinkAttribute (one reference link), plus an AttributeInfo (alias @attribute info) in its smodelAttribute role specifying the extension point: role (the attach key), attributed (which concept(s) may receive it — BaseConcept = any), and multiple (one vs. many per node).
CREATE_CONCEPTS cannot express the AttributeInfo — create the concept extending the base attribute, then add the AttributeInfo with mps_mcp_update_node. Full walkthrough, concept reference, and the canonical RequirementTrace blueprint live in references/attributes-and-annotations.md.
Related Skills
mps-aspect-editor-menus-and-keymaps — once concepts exist, define their editors (often the next step).
mps-aspect-constraints — property validators, scopes, and canBe* rules layered on top of structure.
mps-aspect-behavior — virtual methods per concept.
mps-aspect-actions — node factories for newly created concepts.
mps-language-inheritance — for extendedLanguages and concept super/interface relationships.
Reference Index
- Open
references/structure-operation-api.md for exact mps_mcp_alter_structure and mps_mcp_query_structure operation names, JSON parameter formats, structure blueprint schemas, make flag handling, and makeStatus semantics (success / runtime_stale / failed / skipped).
- Open
references/attributes-and-annotations.md for attributes/annotations: the four attribute kinds (NodeAttribute / PropertyAttribute / ChildAttribute / LinkAttribute), the AttributeInfo extension-point spec, the two-step MCP creation flow, the smodelAttribute slot, and worked examples (RequirementTrace, generator macros, doc/comment annotations).