feat: Support file:// URLs for OData metadata in CREATE ODATA CLIENT

[dionesiusap]

Problem

When creating consumed OData services with CREATE ODATA CLIENT, the MetadataUrl parameter currently only supports HTTP/HTTPS URLs. This creates friction in several scenarios:

• Offline development — developers working without network access cannot create OData clients
• Testing and CI/CD — test environments often use local metadata snapshots to ensure reproducibility
• Version-pinned metadata — teams want to lock to a specific metadata version rather than fetching from a live service
• Pre-production services — metadata for services under development may only exist as files, not deployed endpoints

Proposed Solution

Allow MetadataUrl to accept file:// URLs pointing to local XML metadata files:

```mdl
-- Absolute path
CREATE ODATA CLIENT MyModule.ExternalAPI (
MetadataUrl: 'file:///Users/username/projects/metadata/service.xml'
);

-- Relative path (relative to project .mpr directory)
CREATE ODATA CLIENT MyModule.LocalService (
MetadataUrl: 'file://./metadata/local-service.xml'
);
```

Key Behavior

1. Protocol detection — If MetadataUrl starts with file://, read from local filesystem instead of HTTP
2. Path resolution:
   • file:///absolute/path → absolute path
   • file://./relative/path → relative to .mpr file directory
3. Hash calculation — SHA256 hash computed identically to HTTP-fetched metadata (for change detection)
4. Backwards compatible — existing HTTP/HTTPS URLs work unchanged

Benefits

• Offline development — no network required to set up OData clients
• Reproducibility — metadata snapshots ensure consistent test/CI behavior
• Team collaboration — commit metadata files alongside code in version control
• Pre-production integration — test against upcoming API changes before deployment
• Firewall-friendly — works in locked-down corporate environments

Implementation Details

See full proposal: `docs/11-proposals/PROPOSAL_odata_local_metadata.md`

Estimated effort: 2-3 hours

[github-actions]

Issue Triage

Summary:
The issue requests adding support for file:// URLs in the MetadataUrl parameter of CREATE ODATA CLIENT so developers can point to local OData metadata files for offline work, testing, and CI/CD scenarios.

Checklist for feature request

Required info	Present?	Details
Use case – why the feature is needed	✅	Lists offline development, firewall restrictions, reproducibility, version‑pinned metadata, and pre‑production services.
Proposed syntax or behavior	✅	Shows absolute and relative file:// examples, protocol detection, path resolution, hash calculation, and backward compatibility.
Mendix version relevance (if version‑specific)	❌	No mention of which Mendix versions this applies to or any version‑specific considerations.

Next steps
Could you please clarify whether this feature is intended for all Mendix versions or if there are any version‑specific constraints (e.g., only works with Mendix 10.x and above)? Adding that information will help reviewers assess the request more easily. Thank you!

---

Automated triage via OpenRouter — workflow source

[ako]

Reviewed. Sound proposal, narrow scope — worth doing. A few design points worth resolving before implementation:

Scope check. Only one fetch site exists: fetchODataMetadata() at mdl/executor/cmd_odata.go:1409. AsyncAPI contracts are stored as Document on the service (no URL fetch), so OData is the only consumer of this pattern today. Good, contained change.

Design points

1. file://./relative/path is non-standard. Per RFC 8089 a file:// URI has either an empty host (file:///abs/path) or a real host component. file://./path parses as host="." — unusual and will trip up net/url. Two cleaner options:

   • Accept a bare path alongside file:///abs/path (./metadata/x.xml, metadata/x.xml).
   • Support only file:///… absolute and require pre-resolution.

   I'd lean toward the first — MDL is a pragmatic DSL and bare relative paths are unambiguous. Suggest dropping file://./… from the spec.

2. "Relative to project directory" needs a precise definition. The executor doesn't always have a loaded .mpr in scope (e.g., mxcli check with no -p). What's the base directory when no project is loaded — cwd? The MDL script's directory? Please state explicitly and cover with a test.

3. Reuse the existing helper. cmd/mxcli/lsp_helpers.go:33 already has uriToPath() using net/url. Prefer it over ad-hoc strings.HasPrefix("file://") parsing — handles URL-encoded paths and (eventually) Windows drives correctly.

4. Referenced proposal isn't in the repo. The issue cites docs/11-proposals/PROPOSAL_odata_local_metadata.md; no such file exists on main. Either it's in an unshipped branch or aspirational — could you either push it or drop the reference?

5. Hash-on-file semantics. Worth documenting that editing the local file invalidates the cached metadata just like a live service change would. Desired behavior, but users should know.

Security: MDL scripts are already trusted input (they mutate the project on the user's behalf), so reading a user-chosen local file isn't new exposure.

Suggested minimal spec

MetadataUrl accepts:
  https://…            HTTP(S) fetch (existing)
  http://…             HTTP(S) fetch (existing)
  file:///abs/path     Local absolute path
  ./path, path/x.xml   Local path relative to the .mpr project dir
                       (or cwd if no project loaded)

Happy to pair on the implementation once the relative-path resolution rule is nailed down.

[dionesiusap]

Thanks for the detailed review. All points are well taken. Here's how I'll address them:

1. Relative path syntax — Agreed, will use the minimal spec you suggested:

MetadataUrl accepts:
  https://…            HTTP(S) fetch (existing)
  http://…             HTTP(S) fetch (existing)
  file:///abs/path     Local absolute path
  ./path, path/x.xml   Local path relative to the .mpr project dir
                       (or cwd if no project loaded)

2. Base directory resolution — Proposed rule:

• With project loaded (-p flag or REPL): relative to the .mpr file's directory
• No project loaded (mxcli check without -p): relative to cwd
• Will add test coverage for both scenarios

3. Using uriToPath() — Will reuse the existing helper from lsp_helpers.go instead of ad-hoc string parsing.

4. Proposal document — Will inline the full spec in the PR description instead of a separate proposal file.

5. Hash invalidation — Will document that editing the local XML file invalidates cached metadata (same behavior as remote service changes).

Let me know if the base directory rule needs adjustment before I start implementation. Happy to pair if you'd like to work through it together.

[dionesiusap]

Implementation Question: Path Utility Reuse

During implementation, I've identified that we need a uriToPath() helper to handle file:// URL parsing. This function already exists in cmd/mxcli/lsp_helpers.go (5 lines, using net/url.Parse).

Two viable approaches:

Option 1: Reimplement in executor package

Copy the function into mdl/executor/ (likely in helpers.go or cmd_odata.go).

Pros:

• Self-contained, no new packages
• Fast to implement and review
• Zero dependency changes

Cons:

• Code duplication (two copies of the same 5-line function)
• Must maintain both if bugs are found

Option 2: Extract to shared utility package

Create internal/pathutil package, move the function there, update both call sites.

Pros:

• Single source of truth
• Reusable for future path utilities
• Follows Go's internal/ pattern for shared code

Cons:

• Broader PR scope (refactors existing LSP code)
• More files to review

Note: Importing directly from cmd/mxcli is technically possible but architecturally unclean (executor shouldn't depend on CLI layer, and the function is unexported anyway).

I'm leaning toward Option 2 for better long-term maintainability, but wanted to check if there's a preference or existing pattern I should follow. Thoughts?

[github-actions]

Enhancement Implementation Guide

Completeness Assessment

The issue provides a clear problem statement and proposed solution with examples. However, to implement this correctly, we need clarification on:

1. Mendix version target: What is the minimum Mendix version that should support file:// URLs for OData metadata? (OData client implementation may vary across versions)
2. Error handling expectations: What specific behavior is expected for:
   • Non-existent files
   • Invalid XML content
   • Files outside project directory (security considerations)
   • Network-like timeouts for file reads (should we apply the existing Timeout property?)
3. Hash calculation details: The issue mentions SHA256 hash identical to HTTP-fetched metadata. We need to confirm:
   • Is the hash computed on the raw XML bytes or after some normalization?
   • Where is this hash stored in the BSON (to verify change detection works correctly)

The issue references a full proposal (docs/11-proposals/PROPOSAL_odata_local_metadata.md) which may contain these details. If unavailable, we should ask for clarification before proceeding.

Overlap Check

This functionality cannot be achieved with existing syntax. Currently:

• MetadataUrl only accepts HTTP/HTTPS strings
• No alternative mechanism exists to specify local metadata files
• Workarounds would require:
  • Running a local HTTP server to serve the file (adds complexity)
  • Manually modifying the MPR file (not via MDL)
  • Using placeholder URLs and post-processing (not idempotent)

The proposed solution extends an existing property rather than creating new syntax, minimizing overlap risk.

Proposed MDL Syntax

The issue's proposed syntax follows MDL design guidelines well:

-- Absolute path
CREATE ODATA CLIENT MyModule.ExternalAPI (
  MetadataUrl: 'file:///Users/username/projects/metadata/service.xml'
);

-- Relative path (relative to project .mpr directory)
CREATE ODATA CLIENT MyModule.LocalService (
  MetadataUrl: 'file://./metadata/local-service.xml'
);

Evaluation against guidelines:

• ✅ Reads as English: Natural language flow
• ✅ Qualified names: Uses Module.ODataClientName format
• ✅ Property format: Standard ( Key: value, ... ) with colons
• ✅ LLM-friendly: One example clearly shows both absolute/relative patterns
• ✅ Diff-friendly: Adding/Modifying MetadataUrl is a one-line change
• ✅ Backwards compatible: Existing HTTP/HTTPS URLs require no changes
• ✅ No new keywords: Leverages existing MetadataUrl property
• ✅ Deterministic DESCRIBE: Output will show the exact file:// URL used

No changes needed to the proposed syntax.

Implementation Roadmap

This extends an existing statement (CREATE ODATA CLIENT), so we focus on the executor layer. No grammar/AST changes needed since we're only modifying interpretation of an existing string property.

Files to Modify

1. Executor Handler (mdl/executor/cmd_odata_client.go):

   • Locate the OData client creation/update logic
   • Add protocol detection for file:// in MetadataUrl processing
   • Implement path resolution:
     • Absolute: file:///path/to/file.xml → /path/to/file.xml
     • Relative: file://./relative/path.xml → <mpr_dir>/relative/path.xml
   • Read file content and compute SHA256 hash (matching HTTP implementation)
   • Handle errors (file not found, invalid XML, permissions) with meaningful MDL errors

2. BSON Writer (sdk/mpr/writer_odata_client.go or similar):

   • Verify current storage of metadata/hash for OData clients
   • Ensure local-file-derived metadata is stored identically to HTTP-fetched metadata
   • Confirm hash storage location matches expectations

3. Helper Function (new or existing):

   • Create resolveFileURL(url string, mprDir string) (string, error) in mdl/executor/util.go
   • Handles file:// URL parsing and path resolution
   • Returns absolute filesystem path or error

Implementation Steps

1. Locate OData client executor:

   • Search for CREATE ODATA CLIENT in mdl/executor/
   • Expected file: mdl/executor/cmd_odata_client.go or cmd_odata.go

2. Modify metadata processing:

   // In OData client property handling
   if strings.HasPrefix(metadataURL, "file://") {
       filePath, err := resolveFileURL(metadataURL, projectDir)
       if err != nil {
           return fmt.Errorf("invalid file URL %q: %w", metadataURL, err)
       }
       metadataContent, err := os.ReadFile(filePath)
       if err != nil {
           return fmt.Errorf("failed to read metadata file %q: %w", filePath, err)
       }
       // Validate XML? (Optional - Mendix may do this later)
       metadataHash = sha256.Sum256(metadataContent)
       // Use metadataContent instead of HTTP response
   } else {
       // Existing HTTP logic
   }

3. Update BSON storage:

   • Confirm where metadata content and hash are stored in OData client BSON
   • Ensure local-file metadata follows same structure as HTTP metadata

4. Update DESCRIBE logic:

   • No changes needed - DESCRIBE should output the original file:// URL string

Pattern to Follow

• Similar to how IMPORT statement handles file paths (see mdl/executor/cmd_import.go)
• Follow error handling patterns in mdl/executor/cmd_http.go for HTTP calls
• Use existing path resolution utilities if available (check mdl/executor/)

BSON Investigation

Key Structures to Verify

1. OData Client BSON Structure:

   • Create test OData client with HTTP metadata in Studio Pro
   • Dump BSON using:

     mxcli bson dump -p test.mpr --type "ExternalODataClient" --object "MyModule.MyClient"

   • Look for:
     • Metadata storage location (likely a $Type like InternalODataClientMetadata)
     • Hash storage field (probably MetadataHash or similar)
     • Any version/checksum fields

2. Reflection Data Check:

   • Examine reference/mendixmodellib/reflection-data/ for:
     • ExternalODataClient entity definition
     • Associated metadata entity type
     • Default values and required fields

3. Change Detection Mechanism:

   • Verify how Mendix uses the hash for change detection (likely compares stored hash vs recomputed hash on load)
   • Ensure our local-file hash calculation matches exactly what HTTP path produces

Investigation Steps

# 1. Create reference project
mxcli new test_odata --version 10.0.0
cd test_odata
# Create OData client with HTTP URL via MDL or manually in Studio Pro

# 2. Dump BSON
mxcli bson dump -p test_odata

---
*Automated guide via OpenRouter — [workflow source](https://github.com/mendixlabs/mxcli/blob/main/.github/workflows/ai-enhancement-guide.yml)*