Mps Aspect Structure Concepts

Multi-valued references ([0..n])

An MPS reference link is always single-valued: 0..1 (optional) or 1 (mandatory). Cardinality on references does not exist, so multiple: true is rejected on both write paths — UPDATE_CONCEPT_REFERENCE and a references entry of a CREATE_CONCEPTS blueprint. Only a children entry takes multiple.

Model a [0..n] reference as a thin smart-reference wrapper concept held in a 0..n child role on the owner. The wrapper is a non-rootable BaseConcept subconcept with exactly one mandatory reference, no alias, and no own properties or children — so the editor shows it transparently and the user just types the target's name. This is what MPS itself does: ConceptDeclaration.implements is a 0..n child list of InterfaceConceptReference, each holding one intfc reference.

[
  {
    "name": "CourseRef",
    "shortDescription": "Reference to a Course",
    "references": [
      { "role": "course", "target": "Course", "optional": false }
    ]
  },
  {
    "name": "Curriculum",
    "rootable": true,
    "conceptAlias": "curriculum",
    "implements": ["jetbrains.mps.lang.core.structure.INamedConcept"],
    "children": [
      { "role": "courses", "target": "CourseRef", "multiple": true, "optional": true }
    ]
  }
]

Keep the wrapper bare: give it an own property, an own containment link, or a plain conceptAlias and it stops qualifying implicitly, so the user has to instantiate it explicitly instead of typing the target's name. Two things do still make a non-bare concept smart, but neither is worth the trouble here: an explicit SmartReferenceAttribute, which short-circuits every structural check, and a smart alias of the form pre<{role}>post, which MPS's editor honours (though IS_SMART_REFERENCE reports it as not smart). Confirm with mps_mcp_query_structure IS_SMART_REFERENCE on the wrapper: expect isSmartReference: true and characteristicReferenceName naming its single reference role.

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

Start here — most common case: creating or changing concepts, enumerations, or data types → read the file(s) in the matching Section index row above. Attributes/annotations → only references/attributes-and-annotations.md.

• Open the Section index row (files under references/structure-operation-api/, listed in the index at references/structure-operation-api.md) for the exact mps_mcp_alter_structure or mps_mcp_query_structure operation you are about to call — JSON parameter formats, structure blueprint schemas, make flag handling, and makeStatus semantics.
• Open references/attributes-and-annotations.md for attributes/annotations: the four attribute kinds (NodeAttribute / PropertyAttribute / ChildAttribute / LinkAttribute), how to choose between them (feature-pinned kinds need a visible feature cell — whole-role markers should be a NodeAttribute + LinkDeclaration reference, converted at runtime via MetaAdapterByDeclaration), the AttributeInfo extension-point spec (role, attributed, multiple), the two-step MCP creation flow, the smodelAttribute slot, and worked examples (RequirementTrace, generator macros, doc/comment annotations).