fix: Reject reserved chars in FV names and make version parser resilient

franciscojavierarceo · claude · franciscojavierarceo · commit bc986ef43f74 · 2026-03-24T10:48:13.000-04:00
Block `@` and `:` in feature view names via ensure_valid() to prevent
ambiguous version-qualified reference parsing. Make _parse_feature_ref()
fall back gracefully for legacy FV names containing `@` instead of
raising, and update Go's ParseFeatureReference to only strip `@` suffixes
matching `v&lt;N&gt;`.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/reference/alpha-feature-view-versioning.md b/docs/reference/alpha-feature-view-versioning.md
@@ -208,6 +208,18 @@ Version history tracking in the registry (listing versions, pinning, `--no-promo
 
 For the complete design, concurrency semantics, and feature service interactions, see the [Feature View Versioning RFC](../rfcs/feature-view-versioning.md).
 
+## Naming Restrictions
+
+Feature references use a structured format: `feature_view_name@v<N>:feature_name`. To avoid
+ambiguity, the following characters are reserved and must not appear in feature view or feature names:
+
+- **`@`** — Reserved as the version delimiter (e.g., `driver_stats@v2:trips_today`). `feast apply`
+  will reject feature views with `@` in their name. If you have existing feature views with `@` in
+  their names, they will continue to work for unversioned reads, but we recommend renaming them to
+  avoid ambiguity with the `@v<N>` syntax.
+- **`:`** — Reserved as the separator between feature view name and feature name in fully qualified
+  feature references (e.g., `driver_stats:trips_today`).
+
 ## Known Limitations
 
 - **Online store coverage** — Version-qualified reads (`@v<N>`) are SQLite-only today. Other online stores are follow-up work.
diff --git a/docs/rfcs/feature-view-versioning.md b/docs/rfcs/feature-view-versioning.md
@@ -437,6 +437,7 @@ Feature services work with versioned feature views when the online versioning fl
 - **Offline store versioning.** This RFC covers online reads only. Versioned historical retrieval is out of scope.
 - **Version deletion.** There is no mechanism to prune old versions. This could be added later if registries grow large.
 - **Cross-version joins.** Joining features from different versions of the same feature view in `get_historical_features` is not supported.
+- **Naming restrictions.** Feature view names must not contain `@` or `:` since these characters are reserved for version-qualified references (`fv@v2:feature`). `feast apply` rejects new feature views with these characters. The parser falls back gracefully for legacy feature views that already contain `@` in their names — unrecognized `@` suffixes are treated as part of the name rather than raising errors.
 
 ## Open Questions
 
diff --git a/go/internal/feast/onlineserving/serving.go b/go/internal/feast/onlineserving/serving.go
@@ -4,6 +4,7 @@ import (
 	"crypto/sha256"
 	"errors"
 	"fmt"
+	"regexp"
 	"sort"
 	"strings"
 
@@ -495,7 +496,11 @@ func ParseFeatureReference(featureRef string) (featureViewName, featureName stri
 
 	// Strip @v<N> version qualifier from feature view name
 	if atIdx := strings.Index(featureViewName, "@"); atIdx >= 0 {
-		featureViewName = featureViewName[:atIdx]
+		suffix := featureViewName[atIdx+1:]
+		matched, _ := regexp.MatchString(`^[vV]\d+$`, suffix)
+		if matched {
+			featureViewName = featureViewName[:atIdx]
+		}
 	}
 	return
 }
diff --git a/sdk/python/feast/base_feature_view.py b/sdk/python/feast/base_feature_view.py
@@ -195,6 +195,18 @@ def ensure_valid(self):
         """
         if not self.name:
             raise ValueError("Feature view needs a name.")
+        if "@" in self.name:
+            raise ValueError(
+                f"Feature view name '{self.name}' must not contain '@'. "
+                f"The '@' character is reserved for version-qualified references "
+                f"(e.g., 'fv@v2:feature')."
+            )
+        if ":" in self.name:
+            raise ValueError(
+                f"Feature view name '{self.name}' must not contain ':'. "
+                f"The ':' character is reserved as the separator in fully qualified "
+                f"feature references (e.g., 'feature_view:feature_name')."
+            )
 
     def with_name(self, name: str):
         """
diff --git a/sdk/python/feast/infra/registry/sql.py b/sdk/python/feast/infra/registry/sql.py
@@ -627,6 +627,7 @@ def apply_feature_view(
         commit: bool = True,
         no_promote: bool = False,
     ):
+        feature_view.ensure_valid()
         self._ensure_feature_view_name_is_unique(feature_view, project)
         fv_table = self._infer_fv_table(feature_view)
         fv_type_str = self._infer_fv_type_string(feature_view)
diff --git a/sdk/python/feast/utils.py b/sdk/python/feast/utils.py
@@ -94,10 +94,8 @@ def _parse_feature_ref(ref: str) -> Tuple[str, Optional[int], str]:
     # Parse version number from formats like "v2", "V2"
     match = re.match(r"^[vV](\d+)$", version_str)
     if not match:
-        raise ValueError(
-            f"Invalid version '{version_str}' in feature reference '{ref}'. "
-            f"Expected format: 'v<number>' or 'latest'"
-        )
+        # Not a recognized version format — treat entire fv_part as the name
+        return (fv_part, None, feature_name)
 
     return (fv_name, int(match.group(1)), feature_name)
 
diff --git a/sdk/python/tests/integration/registration/test_versioning.py b/sdk/python/tests/integration/registration/test_versioning.py
@@ -1384,3 +1384,35 @@ def test_no_promote_version_accessible_by_explicit_ref(
         assert v0_fv.current_version_number == 0
         feature_names_v0 = {f.name for f in v0_fv.schema}
         assert "explicit_feature" not in feature_names_v0
+
+
+class TestFeatureViewNameValidation:
+    """Tests that feature view names with reserved characters are rejected on apply."""
+
+    def test_apply_feature_view_with_at_sign_raises(self, registry, entity):
+        """Applying a feature view with '@' in its name should raise ValueError."""
+        fv = FeatureView(
+            name="my_weirdly_@_named_fv",
+            entities=[entity],
+            ttl=timedelta(days=1),
+            schema=[
+                Field(name="driver_id", dtype=Int64),
+                Field(name="trips_today", dtype=Int64),
+            ],
+        )
+        with pytest.raises(ValueError, match="must not contain '@'"):
+            registry.apply_feature_view(fv, "test_project", commit=True)
+
+    def test_apply_feature_view_with_colon_raises(self, registry, entity):
+        """Applying a feature view with ':' in its name should raise ValueError."""
+        fv = FeatureView(
+            name="my:weird:fv",
+            entities=[entity],
+            ttl=timedelta(days=1),
+            schema=[
+                Field(name="driver_id", dtype=Int64),
+                Field(name="trips_today", dtype=Int64),
+            ],
+        )
+        with pytest.raises(ValueError, match="must not contain ':'"):
+            registry.apply_feature_view(fv, "test_project", commit=True)
diff --git a/sdk/python/tests/unit/test_feature_view_versioning.py b/sdk/python/tests/unit/test_feature_view_versioning.py
@@ -370,16 +370,79 @@ def test_invalid_no_colon(self):
         with pytest.raises(ValueError, match="Invalid feature reference"):
             _parse_feature_ref("driver_stats_trips")
 
-    def test_invalid_version_format(self):
-        with pytest.raises(ValueError, match="Invalid version"):
-            _parse_feature_ref("driver_stats@abc:trips")
+    def test_unrecognized_version_falls_back(self):
+        """Unrecognized version format falls back to treating full fv_part as the name."""
+        fv, version, feat = _parse_feature_ref("driver_stats@abc:trips")
+        assert fv == "driver_stats@abc"
+        assert version is None
+        assert feat == "trips"
 
     def test_empty_version(self):
         fv, version, feat = _parse_feature_ref("driver_stats@:trips")
         assert fv == "driver_stats"
         assert version is None
         assert feat == "trips"
 
+    def test_at_sign_in_fv_name_falls_back_gracefully(self):
+        """Legacy FV name with @ falls back to treating whole pre-colon string as name."""
+        fv, version, feat = _parse_feature_ref("my@weird:feature")
+        assert fv == "my@weird"
+        assert version is None
+        assert feat == "feature"
+
+    def test_at_sign_with_valid_version_still_parses(self):
+        """A valid @v<N> suffix still parses as a version."""
+        fv, version, feat = _parse_feature_ref("stats@v2:trips")
+        assert fv == "stats"
+        assert version == 2
+        assert feat == "trips"
+
+
+class TestEnsureValidRejectsReservedChars:
+    def test_at_sign_in_name_raises(self):
+        from datetime import timedelta
+
+        from feast.entity import Entity
+        from feast.feature_view import FeatureView
+
+        entity = Entity(name="entity_id", join_keys=["entity_id"])
+        fv = FeatureView(
+            name="my@weird_fv",
+            entities=[entity],
+            ttl=timedelta(days=1),
+        )
+        with pytest.raises(ValueError, match="must not contain '@'"):
+            fv.ensure_valid()
+
+    def test_colon_in_name_raises(self):
+        from datetime import timedelta
+
+        from feast.entity import Entity
+        from feast.feature_view import FeatureView
+
+        entity = Entity(name="entity_id", join_keys=["entity_id"])
+        fv = FeatureView(
+            name="my:weird_fv",
+            entities=[entity],
+            ttl=timedelta(days=1),
+        )
+        with pytest.raises(ValueError, match="must not contain ':'"):
+            fv.ensure_valid()
+
+    def test_valid_name_passes(self):
+        from datetime import timedelta
+
+        from feast.entity import Entity
+        from feast.feature_view import FeatureView
+
+        entity = Entity(name="entity_id", join_keys=["entity_id"])
+        fv = FeatureView(
+            name="driver_stats",
+            entities=[entity],
+            ttl=timedelta(days=1),
+        )
+        fv.ensure_valid()  # Should not raise
+
 
 class TestStripVersionFromRef:
     def test_bare_ref(self):
