feat: normalize relative paths and enforce ServiceUrl as constant

Two improvements for Studio Pro compatibility:

1. **Normalize relative paths to absolute file:// URLs**
   - Relative paths (./path or path/file.xml) are automatically converted
     to absolute file:// URLs in the Mendix model
   - Ensures Studio Pro can detect local file vs HTTP metadata sources
   - Example: './metadata.xml' → 'file:///absolute/path/to/project/metadata.xml'

2. **Enforce ServiceUrl as constant reference**
   - ServiceUrl must always start with '@' (e.g., '@Module.ConstantName')
   - Direct URLs are rejected with clear error message
   - Enforces Mendix best practice of externalizing configuration

Implementation:
- Added normalizeMetadataUrl() function with path resolution logic
- Added validation in createODataClient() for ServiceUrl format
- Updated all documentation and examples
- Added comprehensive test coverage
- Added test MPK file with real Studio Pro-created services

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: dionesiusap

.claude/skills/mendix/odata-data-sharing.md

@@ -16,13 +16,18 @@ This skill covers how to use OData services to share data between Mendix applica
 
 `CREATE ODATA CLIENT` supports three formats for the `MetadataUrl` parameter:
 
-| Format | Example | Use Case |
-|--------|---------|----------|
-| **HTTP(S) URL** | `https://api.example.com/odata/v4/$metadata` | Production, fetches from live service |
-| **Absolute file:// URI** | `file:///Users/team/contracts/service.xml` | Local metadata at fixed path |
-| **Relative path** | `./metadata/service.xml` or `metadata/service.xml` | Metadata alongside project (offline, testing, CI/CD) |
-
-**Path Resolution:**
+| Format | Example | Stored In Model |
+|--------|---------|-----------------|
+| **HTTP(S) URL** | `https://api.example.com/odata/v4/$metadata` | Unchanged |
+| **Absolute file:// URI** | `file:///Users/team/contracts/service.xml` | Unchanged |
+| **Relative path** | `./metadata/service.xml` or `metadata/service.xml` | **Normalized to absolute `file://`** |
+
+**Path Normalization:**
+- Relative paths (with or without `./`) are **automatically converted** to absolute `file://` URLs in the Mendix model
+- This ensures Studio Pro can properly detect local file vs HTTP metadata sources (radio button in UI)
+- Example: `./metadata/service.xml` → `file:///absolute/path/to/project/metadata/service.xml`
+
+**Path Resolution (before normalization):**
 - With project loaded (`-p` flag or REPL): relative paths are resolved against the `.mpr` file's directory
 - Without project: relative paths are resolved against the current working directory
 
@@ -33,6 +38,34 @@ This skill covers how to use OData services to share data between Mendix applica
 - **Pre-production** — test against upcoming API changes before deployment
 - **Firewall-friendly** — works in locked-down corporate environments
 
+## ServiceUrl Must Be a Constant
+
+**IMPORTANT:** The `ServiceUrl` parameter **must always be a constant reference** (prefixed with `@`). Direct URLs are not allowed.
+
+**Correct:**
+```sql
+CREATE CONSTANT ProductClient.ProductDataApiLocation
+  TYPE String
+  DEFAULT 'http://localhost:8080/odata/productdataapi/v1/';
+
+CREATE ODATA CLIENT ProductClient.ProductDataApiClient (
+  ODataVersion: OData4,
+  MetadataUrl: 'https://api.example.com/$metadata',
+  ServiceUrl: '@ProductClient.ProductDataApiLocation'  -- ✅ Constant reference
+);
+```
+
+**Incorrect:**
+```sql
+CREATE ODATA CLIENT ProductClient.ProductDataApiClient (
+  ODataVersion: OData4,
+  MetadataUrl: 'https://api.example.com/$metadata',
+  ServiceUrl: 'https://api.example.com/odata'  -- ❌ Direct URL not allowed
+);
+```
+
+This enforces Mendix best practice of externalizing configuration values for different environments.
+
 ## Architecture Overview
 
 OData data sharing follows a **producer/consumer** pattern with three layers:

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -149,19 +149,25 @@ CREATE ODATA CLIENT MyModule.LocalService (
   Timeout: 300
 );
 
--- Local file with relative path (resolved against .mpr directory)
+-- Local file with relative path (normalized to absolute file:// in model)
 CREATE ODATA CLIENT MyModule.LocalService2 (
   Version: '1.0',
   ODataVersion: OData4,
   MetadataUrl: './metadata/service.xml',
-  Timeout: 300
+  Timeout: 300,
+  ServiceUrl: '@MyModule.ServiceLocation'  -- Must be a constant reference
 );
 ```
 
 **Note:** `MetadataUrl` supports three formats:
 - `https://...` or `http://...` — fetches from HTTP(S) endpoint
 - `file:///abs/path` — reads from local absolute path
-- `./path` or `path/file.xml` — reads from local relative path (resolved against `.mpr` directory when project is loaded, or `cwd` otherwise)
+- `./path` or `path/file.xml` — reads from local relative path, **normalized to absolute `file://` in the model** for Studio Pro compatibility
+
+**Important:** `ServiceUrl` must always be a constant reference starting with `@` (e.g., `@Module.ConstantName`). Create a constant first:
+```sql
+CREATE CONSTANT MyModule.ServiceLocation TYPE String DEFAULT 'https://api.example.com/odata/v4/';
+```
 
 **OData Service Example:**
 ```sql

mdl-examples/odata-local-metadata/README.md

@@ -9,6 +9,11 @@ This example demonstrates how to create consumed OData services using local meta
 - **Version-pinned metadata** — lock to a specific metadata version
 - **Pre-production services** — test against metadata files before deployment
 
+## Important Notes
+
+1. **Relative paths are normalized** — Any relative path is automatically converted to an absolute `file://` URL in the Mendix model for Studio Pro compatibility
+2. **ServiceUrl must be a constant** — Always use `@Module.ConstantName` format, not direct URLs
+
 ## Supported Formats
 
 ### 1. Absolute `file://` URI
@@ -20,13 +25,16 @@ CREATE ODATA CLIENT MyModule.Service (
 
 ### 2. Relative path (with or without `./`)
 ```mdl
--- Resolved relative to the .mpr file's directory when project is loaded
+-- Resolved relative to the .mpr file's directory, then normalized to absolute file://
+-- Example: './metadata/service.xml' → 'file:///absolute/path/to/project/metadata/service.xml'
 CREATE ODATA CLIENT MyModule.Service (
-  MetadataUrl: './metadata/service.xml'
+  MetadataUrl: './metadata/service.xml',
+  ServiceUrl: '@MyModule.ServiceLocation'
 );
 
 CREATE ODATA CLIENT MyModule.Service2 (
-  MetadataUrl: 'metadata/service.xml'
+  MetadataUrl: 'metadata/service.xml',
+  ServiceUrl: '@MyModule.ServiceLocation'
 );
 ```
 

mdl-examples/odata-local-metadata/example.mdl

@@ -1,31 +1,43 @@
 -- Example: Using local OData metadata files
 --
 -- This demonstrates three ways to specify local metadata files for OData clients:
--- 1. Absolute file:// URI
--- 2. Relative path with ./
--- 3. Relative path without ./
+-- 1. Absolute file:// URI (stored as-is)
+-- 2. Relative path with ./ (normalized to absolute file://)
+-- 3. Relative path without ./ (normalized to absolute file://)
+--
+-- IMPORTANT: ServiceUrl must be a constant reference (prefixed with @)
+
+-- First, create constants for service locations (required for ServiceUrl)
+CREATE CONSTANT TestModule.NorthwindLocation
+  TYPE String
+  DEFAULT 'https://services.odata.org/V4/Northwind/Northwind.svc/';
 
--- Method 1: Absolute file:// URI (works anywhere)
+-- Method 1: Absolute file:// URI (stored as-is in model)
 -- Useful when the metadata file is in a fixed location
 CREATE ODATA CLIENT TestModule.NorthwindAbsolute (
-  MetadataUrl: 'file:///tmp/northwind-metadata.xml'
+  MetadataUrl: 'file:///tmp/northwind-metadata.xml',
+  ServiceUrl: '@TestModule.NorthwindLocation'
 );
 
--- Method 2: Relative path with ./ (resolved against .mpr directory)
+-- Method 2: Relative path with ./ (normalized to absolute file:// in model)
 -- Best for metadata files stored alongside the project
+-- Example: './metadata/file.xml' → 'file:///absolute/path/to/project/metadata/file.xml'
 CREATE ODATA CLIENT TestModule.NorthwindRelative (
-  MetadataUrl: './mdl-examples/odata-local-metadata/sample-metadata.xml'
+  MetadataUrl: './mdl-examples/odata-local-metadata/sample-metadata.xml',
+  ServiceUrl: '@TestModule.NorthwindLocation'
 );
 
--- Method 3: Relative path without ./ (also resolved against .mpr directory)
+-- Method 3: Relative path without ./ (normalized to absolute file:// in model)
 CREATE ODATA CLIENT TestModule.NorthwindSimple (
-  MetadataUrl: 'mdl-examples/odata-local-metadata/sample-metadata.xml'
+  MetadataUrl: 'mdl-examples/odata-local-metadata/sample-metadata.xml',
+  ServiceUrl: '@TestModule.NorthwindLocation'
 );
 
--- HTTP(S) URLs still work as before
+-- HTTP(S) URLs still work as before (stored as-is in model)
 CREATE ODATA CLIENT TestModule.NorthwindRemote (
-  MetadataUrl: 'https://services.odata.org/V4/Northwind/Northwind.svc/$metadata'
+  MetadataUrl: 'https://services.odata.org/V4/Northwind/Northwind.svc/$metadata',
+  ServiceUrl: '@TestModule.NorthwindLocation'
 );
 
--- Show the created clients
+-- Show the created clients (note: relative paths appear as file:// URLs)
 SHOW ODATA CLIENTS IN TestModule;

mdl/executor/cmd_odata.go

@@ -991,6 +991,10 @@ func (e *Executor) createODataClient(stmt *ast.CreateODataClientStmt) error {
 			ClientCertificate: stmt.ClientCertificate,
 		}
 		if stmt.ServiceUrl != "" {
+			// ServiceUrl must be a constant reference (e.g., @Module.ConstantName)
+			if !strings.HasPrefix(stmt.ServiceUrl, "@") {
+				return fmt.Errorf("ServiceUrl must be a constant reference starting with '@' (e.g., '@Module.LocationConstant'), got: %s", stmt.ServiceUrl)
+			}
 			cfg.OverrideLocation = true
 			cfg.CustomLocation = stmt.ServiceUrl
 		}
@@ -1004,12 +1008,21 @@ func (e *Executor) createODataClient(stmt *ast.CreateODataClientStmt) error {
 	}
 
 	// Fetch and cache $metadata from the service URL
+	// Normalize local file paths to absolute file:// URLs for Studio Pro compatibility
 	if newSvc.MetadataUrl != "" {
 		mprDir := ""
 		if e.mprPath != "" {
 			mprDir = filepath.Dir(e.mprPath)
 		}
-		metadata, hash, err := fetchODataMetadata(newSvc.MetadataUrl, mprDir)
+
+		// Normalize MetadataUrl: convert relative paths to absolute file:// URLs
+		normalizedUrl, err := normalizeMetadataUrl(newSvc.MetadataUrl, mprDir)
+		if err != nil {
+			return fmt.Errorf("failed to normalize MetadataUrl: %w", err)
+		}
+		newSvc.MetadataUrl = normalizedUrl
+
+		metadata, hash, err := fetchODataMetadata(normalizedUrl, mprDir)
 		if err != nil {
 			fmt.Fprintf(e.output, "Warning: could not fetch $metadata: %v\n", err)
 		} else if metadata != "" {
@@ -1411,6 +1424,59 @@ func astEntityDefToModel(def *ast.PublishedEntityDef) (*model.PublishedEntityTyp
 	return entityType, entitySet
 }
 
+// normalizeMetadataUrl converts relative paths to absolute file:// URLs.
+// This ensures Studio Pro can properly detect local file vs HTTP metadata sources.
+//
+// Input formats:
+//   - https://... or http://... → returned as-is
+//   - file:///abs/path → returned as-is
+//   - ./path or path/file.xml → converted to file:///absolute/path
+//
+// If mprDir is provided, relative paths are resolved against it.
+// Otherwise, they're resolved against the current working directory.
+func normalizeMetadataUrl(metadataUrl string, mprDir string) (string, error) {
+	if metadataUrl == "" {
+		return "", nil
+	}
+
+	// HTTP(S) URLs are already normalized
+	if strings.HasPrefix(metadataUrl, "http://") || strings.HasPrefix(metadataUrl, "https://") {
+		return metadataUrl, nil
+	}
+
+	// Extract file path
+	filePath := metadataUrl
+	if strings.HasPrefix(metadataUrl, "file://") {
+		filePath = pathutil.URIToPath(metadataUrl)
+		if filePath == "" {
+			return "", fmt.Errorf("invalid file:// URI: %s", metadataUrl)
+		}
+	}
+
+	// Convert relative paths to absolute
+	if !filepath.IsAbs(filePath) {
+		if mprDir != "" {
+			filePath = filepath.Join(mprDir, filePath)
+		} else {
+			// No project loaded - use cwd
+			cwd, err := os.Getwd()
+			if err != nil {
+				return "", fmt.Errorf("failed to resolve relative path: %w", err)
+			}
+			filePath = filepath.Join(cwd, filePath)
+		}
+	}
+
+	// Convert to absolute path (clean up ./ and ../)
+	absPath, err := filepath.Abs(filePath)
+	if err != nil {
+		return "", fmt.Errorf("failed to get absolute path: %w", err)
+	}
+
+	// Return as file:// URL
+	return "file://" + filepath.ToSlash(absPath), nil
+}
+
 // fetchODataMetadata downloads or reads the $metadata document.
 // Supports:
 //   - https://... or http://... (HTTP fetch)

mdl/executor/cmd_odata_test.go

@@ -93,6 +93,91 @@ func TestFetchODataMetadata_LocalFile(t *testing.T) {
 	}
 }
 
+func TestNormalizeMetadataUrl(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	tests := []struct {
+		name       string
+		input      string
+		mprDir     string
+		wantPrefix string
+		wantErr    bool
+	}{
+		{
+			name:       "HTTP URL unchanged",
+			input:      "https://api.example.com/$metadata",
+			mprDir:     "",
+			wantPrefix: "https://",
+			wantErr:    false,
+		},
+		{
+			name:       "HTTPS URL unchanged",
+			input:      "http://localhost:8080/odata/$metadata",
+			mprDir:     "",
+			wantPrefix: "http://",
+			wantErr:    false,
+		},
+		{
+			name:       "Absolute file:// unchanged",
+			input:      "file:///tmp/metadata.xml",
+			mprDir:     "",
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+		{
+			name:       "Relative path normalized to file://",
+			input:      "./metadata.xml",
+			mprDir:     tmpDir,
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+		{
+			name:       "Bare relative path normalized to file://",
+			input:      "metadata.xml",
+			mprDir:     tmpDir,
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+		{
+			name:       "Absolute path normalized to file://",
+			input:      "/tmp/metadata.xml",
+			mprDir:     "",
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := normalizeMetadataUrl(tt.input, tt.mprDir)
+
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("Expected error but got none")
+				}
+				return
+			}
+
+			if err != nil {
+				t.Errorf("Unexpected error: %v", err)
+				return
+			}
+
+			if !strings.HasPrefix(result, tt.wantPrefix) {
+				t.Errorf("Result %q does not start with %q", result, tt.wantPrefix)
+			}
+
+			// Verify file:// URLs are absolute
+			if strings.HasPrefix(result, "file://") {
+				path := strings.TrimPrefix(result, "file://")
+				if !filepath.IsAbs(path) {
+					t.Errorf("file:// URL contains relative path: %q", result)
+				}
+			}
+		})
+	}
+}
+
 func TestFetchODataMetadata_RelativePathWithoutProject(t *testing.T) {
 	// Create metadata file in current directory
 	tmpDir := t.TempDir()