Requirements:- Stable, backward-compatible contract so training code and feature store can evolve independently- Machine-readable metadata, schema validation, explicit versioning, and compatibility rules- Simple API for feature retrieval with clear semantics (freshness, join keys, types, null handling)High-level approach:- Define a Feature Contract artifact per feature group containing metadata, protobuf/JSON schema, and a semantic version.- Provide a contract registry (Git + CI or a feature-metadata service) that enforces schema checks and compatibility on updates.- Training code depends on the contract (not implementation).Required metadata (per feature group):- name, namespace, id_keys (join keys), description- schema: field name, type, nullable, default, semantic dtype (e.g., categorical/continuous)- freshness: max_age, ingestion_schedule- lineage: data source, transformations, owner, last_updated- version: semantic (MAJOR.MINOR.PATCH)- compatibility policy: breaking fields allowed? deprecation windowsSchema checks:- Machine-validate incoming/upstream feature writes against the schema- CI checks when updating contract: allowed changes (MINOR/PATCH = additive/non-breaking; MAJOR = breaking)- Runtime validation in training: assert returned schema matches contract; fail-fast with clear errors- Provide lightweight adapter utilities to rename or cast fields when safeVersioning & compatibility rules:- Semantic versioning: MAJOR = incompatible change (remove/rename type), MINOR = additive (new fields), PATCH = metadata only- Training code should pin to a contract version range (e.g., "feature_x>=1.2.0,<2.0.0") and test against HEAD in CI- Deprecation: mark fields deprecated with sunset date, maintain shims for one MAJOR cycleExample API signature (Python):python
from typing import List, Dict
def get_features(
feature_refs: List[str], # ["users:age:1.2.0", "users:country:1.0.0"]
entity_keys: List[Dict], # [{"user_id": 123}, ...] or a dataframe
as_of: str = None, # ISO timestamp for training-time joins
validate_schema: bool = True
) -> List[Dict]:
"""
Returns rows aligned with entity_keys. Each feature_ref includes contract version.
If validate_schema, assert returned schema matches contract and raise informative errors.
"""
Operational practices:- Keep contracts in versioned repo; run schema compatibility checks in PRs- CI builds lightweight contract clients used by training tests- Provide migration tooling (adapters) for safe renames and type casts- Monitor runtime schema drift and alert on contract violationsThis design lets engineers upgrade feature store implementation or model training independently while ensuring stability via explicit, versioned, machine-checked contracts.