Add support for JSON snippets

[ako]

Create a JSON snippet with option to overrule property names.

[github-actions]

Issue Triage

Summary:
The issue requests adding support for JSON snippets that allow overriding property names.

Checklist for feature request:

• ✅ Use case – missing (why the feature is needed, what problem it solves)
• ✅ Proposed syntax or behavior – missing (how the option would look or work)
• ⚪ Mendix version relevance – not provided (only needed if the feature depends on a specific Mendix version)

Request for more information:
Could you please add a brief description of the use case (e.g., what scenario motivates this feature) and outline the proposed syntax or behavior you have in mind? If the feature is only relevant for certain Mendix versions, mentioning that would also be helpful. Thanks!

---

Automated triage via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Completeness Assessment

The enhancement request lacks critical details needed for implementation. Please provide:

1. Mendix version - Is this for a specific Mendix version (e.g., 10.6+, where JSON snippets might have been introduced)?
2. Exact meaning of "JSON snippet" - Does this refer to:
   • A snippet containing JSON data/widgets?
   • A JSON structure document used in import/export mappings?
   • A snippet specifically designed for JSON processing (like a JSON viewer/editor widget)?
3. Concrete examples of desired syntax - Show 2-3 examples of what the MDL should look like for:
   • Creating a JSON snippet
   • Using the "overrule property names" option
   • How this differs from existing snippet/JSON functionality
4. Which Mendix concepts are involved - Is this primarily about:
   • Snippets (reusable UI components)?
   • JSON structures/schemas?
   • Import/export mappings?
   • Specific widgets (like DataGrid2, JSON viewer)?

Without this information, it's impossible to determine if this overlaps with existing features or design appropriate syntax.

Overlap Check

Based on current documentation, the following existing features may partially cover this request:

• SNIPPET support: Already implemented via MOVE SNIPPET, ALTER SNIPPET, and CREATE SNIPPET (implied by MOVE supporting SNIPPET)
• Property overriding: Existing SET syntax in ALTER PAGE/SNIPPET allows changing widget properties
• Mapping syntax: Layout mapping uses MAP (Old AS New) for placeholder remapping
• JSON structures: Implied by OData/REST client support and import mappings in External SQL section

However, there's no explicit mention of:

• JSON-specific snippet types
• Property name overriding for JSON mappings
• Dedicated JSON snippet creation syntax

If this refers to JSON import/export mapping functionality, there may be overlap with the existing IMPORT FROM ... MAP (...) syntax, but snippets add a reusable layer not currently present.

Proposed MDL Syntax

Assuming "JSON snippet" refers to a reusable snippet containing JSON structure definitions (for use in import/export mappings) with property name override capability:

-- Basic JSON snippet creation
CREATE JSON SNIPPET Module.MyJsonSnippet (
    PropertyMappings: (
        "jsonProperty1" -> MendixAttribute1,
        "jsonProperty2" -> MendixAttribute2
    )
);

-- With explicit property name overriding
CREATE JSON SNIPPET Module.ApiResponse (
    PropertyMappings: (
        "user_id" -> User.ID AS "Identifier",
        "createdAt" -> User.CreatedDate AS "Timestamp"
    )
);

-- Using in an import mapping (hypothetical)
IMPORT FROM source QUERY 'SELECT * FROM api_response'
  INTO MyModule.ApiLog
  MAP (data AS JsonData USING SNIPPET Module.ApiResponse);

Note: This syntax assumes JSON snippets define property mappings similar to import mappings, with optional AS clauses to override how property names are interpreted.

Implementation Roadmap

1. Grammar (mdl/grammar/MDLParser.g4):

   • Add JSON and SNIPPET tokens if not present
   • Add rule for jsonSnippetCreation following createStatement pattern
   • Add propertyMappingList and propertyMapping rules with AS override syntax

2. AST (mdl/ast/ast_snippet.go):

   • Add JsonSnippetStmt struct with PropertyMappings []*PropertyMapping
   • Add PropertyMapping struct with JsonName, MendixAttribute, OverruledName

3. Visitor (mdl/visitor/visitor_snippet.go):

   • Implement buildJsonSnippetStatement to parse property mappings and overrides

4. SDK Types (sdk/snippets/ or sdk/pages/):

   • Add JsonSnippet type with mapping properties
   • Update snippet writer/parser to handle JSON-specific BSON structure

5. BSON Handling (sdk/mpr/parser_snippet.go, writer_snippet.go):

   • Add parsing/serialization for JSON snippet BSON structure
   • Verify storage name for JSON snippet type via reflection data

6. Executor:

   • Builder: cmd_snippets_builder.go to convert AST to BSON
   • Show: cmd_snippets_show.go to generate MDL from BSON (including override syntax)

7. Documentation:

   • Update MDL Quick Reference with JSON snippet syntax
   • Add examples to mdl-examples/doctype-tests/
   • Update help topics and skills

BSON Investigation

1. Create reference in Studio Pro:

   • Create a JSON snippet (if the concept exists in your Mendix version)
   • Save and note the qualified name

2. Find document ID:

   ./bin/mxcli -p test.mpr -c "SELECT Id, QualifiedName FROM CATALOG.SNIPPETS WHERE QualifiedName = 'Module.MyJsonSnippet'"

3. Dump raw BSON:

   go run ./cmd/debug/main.go test.mpr <document-id>

4. Analyze structure for:

   • $Type value (storage name for JSON snippet)
   • Property mapping structure (likely in an ObjectCollection)
   • How property name overrides are stored (if supported)
   • Compare with existing snippet BSON structure

5. Check reflection data:

   • Examine reference/mendixmodellib/reflection-data/ for JSON snippet definition
   • Look for properties related to mappings or property overrides

Testing Strategy

1. Doctest script (`mdl0

---

Automated guide via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Completeness Assessment

The enhancement request lacks critical details needed for proper implementation. I need to ask clarifying questions before proceeding:

Specific questions to ask the reporter:

1. What exactly is meant by "JSON snippet" in this context? Is this referring to:

   • JSON structure documents (used for import/export mappings)
   • Snippets containing JSON data or JSON-related widgets
   • Standalone JSON definition documents
   • Something else entirely?

2. Which Mendix concepts are involved? Based on the "option to overrule property names" phrase, this seems related to property mapping in JSON structures, but I need confirmation.

3. What is the expected Mendix version compatibility? JSON structure handling may vary between versions.

4. Can you provide an example of the desired MDL syntax? The request mentions "option to overrule property names" but doesn't show what this looks like.

5. Is this for defining new JSON structures, modifying existing ones, or both?

Without these details, I cannot accurately design the MDL syntax or implementation approach.

Overlap Check

Based on current implementation status:

• JSON structure definitions are listed as "Not Yet Implemented" in the Feature Matrix
• Import mappings (JSON/XML) and Export mappings (JSON/XML) are also not implemented
• No existing MDL support for JSON structures, property mapping, or related functionality
• Some related work exists in widget templates for pluggable widgets, but this is different

Conclusion: This would be a new feature with minimal overlap. The closest existing functionality might be:

• OData client/entity definitions that use AS for naming (PUBLISH ENTITY MyModule.Customer AS 'Customers')
• DataGrid column properties that allow overriding captions
• But these don't cover JSON structure definition

Proposed MDL Syntax

Note: Since the request is unclear, this is a speculative proposal based on common JSON structure patterns in Mendix and existing MDL conventions. Actual syntax should be confirmed with the reporter.

Following MDL design guidelines (reads as English, standard CRUD verbs, qualified names, property format):

-- Basic JSON structure definition
CREATE JSON STRUCTURE Module.Name (
    PropertyName: Type,
    AnotherProperty: AnotherType
);

-- JSON structure with property name overruling (mapping JSON property to Mendix attribute)
CREATE JSON STRUCTURE Module.Name (
    JsonPropertyName AS MendixAttribute: Type,
    AnotherJsonProperty AS AnotherMendixAttribute: AnotherType
);

-- With optionality specification
CREATE JSON STRUCTURE Module.Name (
    RequiredProperty: String,
    OptionalProperty: String (optional: true)
);

Examples:

CREATE JSON STRUCTURE MyModule.Person (
    firstName AS FirstName: String,
    lastName AS LastName: String,
    age AS Age: Integer
);

CREATE JSON STRUCTURE MyModule.Address (
    street AS Street: String(100),
    city AS City: String(50),
    postalCode AS PostalCode: String(10),
    country AS Country: String(50)
);

Evaluation against guidelines:

• ✅ Reads as English: "CREATE JSON STRUCTURE MyModule.Person"
• ✅ Standard CRUD verb: CREATE
• ✅ Qualified names: Module.Name format
• ✅ Property format: ( Key: value, ... ) with colon separators
• ✅ LLM-friendly: One example shows the pattern
• ✅ Diff-friendly: Adding one property is one-line change

Implementation Roadmap

Note: Implementation steps assume JSON structures are a new document type. Adjustments may be needed based on actual Mendix BSON structure.

1. Grammar (mdl/grammar/MDLLexer.g4 + MDLParser.g4):

   • Add tokens: JSON, STRUCTURE, AS, OPTIONAL (if not existing)
   • Add parser rule: jsonStructureStatement to microflowStatement/pageStatement alternatives or as top-level statement
   • Regenerate: make grammar

2. AST (mdl/ast/):

   • Create ast_json.go with JsonStructureStmt struct:

     type JsonStructureStmt struct {
         Name          model.QualifiedName
         Properties    []JsonStructureProperty
     }
     
     type JsonStructureProperty struct {
         JsonName      string
         MendixName    string
         Type          ast.Type
         Optional      bool
     }

3. Visitor (mdl/visitor/):

   • Create visitor_json.go with buildJsonStructureStatement function
   • Add to statement switch in visitor

4. SDK Types (sdk/):

   • Create sdk/json/json.go with JsonStructure type matching BSON structure
   • Implement isElement() interface

5. BSON Parser (sdk/mpr/parser_json.go):

   • Add parseJsonStructure function
   • Handle $Type field (storage name to be determined)
   • Parse properties and mappings

6. BSON Writer (sdk/mpr/writer_json.go):

   • Add serializeJsonStructure function
   • Convert Go struct to BSON document with correct $Type

7. Executor:

   • Builder: mdl/executor/cmd_json_builder.go (AST → BSON)
   • Show: mdl/executor/cmd_json_show.go (BSON → MDL)
   • Add handlers to executor switches

8. Catalog (mdl/catalog/):

   • Add JSON structures table in tables.go
   • Add builder in builder_modules.go

BSON Investigation

To understand how JSON structures are stored in MPR files:

1. Create reference example:

   • In Mendix Studio Pro, create a JSON structure with property mappings
   • Save project as .mpr

2. Examine BSON structure:

   • Use mx tool: ~/.mxcli/mxbuild/*/modeler/mx check /path/to/project.mpr --verbose
   • Or use SQLite browser on MPR v1 or examine mprcontents/ folder for v2
   • Look for documents with JSON structure characteristics

3. Key investigation points:

   • What is the $Type value for JSON structures? (Check reflection data)
   • How are properties stored? As array or object?
   • How is property mapping represented? (Separate fields or combined?)
   • What are the required default properties?
   • Check reference/mendixmodellib/reflection-data/ for JSON structure definition

4. Specific files to check:

   • reference/mendixmodellib/reflection-data/v10.0.0/ (adjust version)
   • Look for JSON-related type definitions
   • Examine existing parser/writer files for similar structures (sdk/mpr/parser_*.go)

Testing Strategy

1. Doctest test script:

   • Add mdl-examples/doctype-tests/20-json-structure-examples.mdl
   • Include CREATE, DESCRIBE, and validation examples

2. mx check validations:

   • Verify syntax checking catches invalid property formats
   • Ensure qualified names are required
   • Check for duplicate property names

3. Integration tests:

   • Add mdl/executor/json_test.go
   • Test CREATE → DESCRIBE roundtrip
   • Test opening created JSON structures in Studio Pro (no CE errors)
   • Test property mapping preservation

4. Validation scenarios:

   • Basic JSON structure without mapping
   • JSON structure with property name overruling
   • Mixed required/optional properties
   • Edge cases (special characters in names, etc.)

Gotchas & Risks

1. Storage name vs qualified name:

   • Critical risk: Using wrong BSON $Type causes TypeCacheUnknownTypeException
   • Must verify exact storage name from MPR reflection data, not assume from SDK docs

2. BSON defaults and required fields:

   • JSON structures may require specific default properties
   • Missing defaults could cause Studio Pro to reject the document
   • Need to examine existing JSON structures in MPR for required fields

3. Property mapping complexity:

   • Bidirectional mapping (JSON↔Mendix) needs clear representation
   • Must handle cases where JSON and Mendix names are identical (no AS needed)
   • Optional property specification must be correctly serialized

4. Version compatibility:

   • JSON structure format may vary between Mendix versions
   • Implementation should target specific version or include version checks

5. Potential CE error codes:

   • Similar to widget templates: CE0463 if property structure mismatch
   • Possible CE0066 if entity access rules misapplied (less likely for JSON)
   • General BSON parsing errors if structure incorrect

6. LSP and autocomplete:

   • Need to add JSON structure name completion in REPL
   • Property name suggestions based on context
   • Hover documentation for "

---

Automated guide via OpenRouter — workflow source