diff --git a/api/core/v1beta1/featureflag_types.go b/api/core/v1beta1/featureflag_types.go
index 3c6f332e2..e8daecb2c 100644
--- a/api/core/v1beta1/featureflag_types.go
+++ b/api/core/v1beta1/featureflag_types.go
@@ -36,6 +36,13 @@ type FlagSpec struct {
 	// +kubebuilder:validation:Schemaless
 	// +kubebuilder:pruning:PreserveUnknownFields
 	// +kubebuilder:validation:Type=object
+	// Metadata holds optional flag-set level metadata.
+	// Additional metadata keys are preserved to support flagd metadata inheritance.
+	Metadata json.RawMessage `json:"metadata,omitempty"`
+	// +optional
+	// +kubebuilder:validation:Schemaless
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Type=object
 	Evaluators json.RawMessage `json:"$evaluators,omitempty"`
 }
 
@@ -50,14 +57,21 @@ type Flag struct {
 	// +kubebuilder:validation:Schemaless
 	// +kubebuilder:pruning:PreserveUnknownFields
 	// +kubebuilder:validation:Type=object
-	Variants       json.RawMessage `json:"variants"`
-	DefaultVariant string          `json:"defaultVariant"`
+	Variants json.RawMessage `json:"variants"`
+	DefaultVariant string `json:"defaultVariant"`
 	// +optional
 	// +kubebuilder:validation:Schemaless
 	// +kubebuilder:pruning:PreserveUnknownFields
 	// +kubebuilder:validation:Type=object
 	// Targeting is the json targeting rule
 	Targeting json.RawMessage `json:"targeting,omitempty"`
+	// +optional
+	// +kubebuilder:validation:Schemaless
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Type=object
+	// Metadata holds optional per-flag metadata.
+	// Additional metadata keys are preserved to support flagd metadata inheritance.
+	Metadata json.RawMessage `json:"metadata,omitempty"`
 }
 
 // FeatureFlagStatus defines the observed state of FeatureFlag
@@ -119,4 +133,4 @@ func (ff *FeatureFlag) GenerateConfigMap(name string, namespace string, referenc
 			common.FeatureFlagConfigMapKey(namespace, name): string(b),
 		},
 	}, nil
-}
+}
\ No newline at end of file
diff --git a/api/core/v1beta1/zz_generated.deepcopy.go b/api/core/v1beta1/zz_generated.deepcopy.go
index f1e132bbe..1a48d3a54 100644
--- a/api/core/v1beta1/zz_generated.deepcopy.go
+++ b/api/core/v1beta1/zz_generated.deepcopy.go
@@ -253,6 +253,11 @@ func (in *Flag) DeepCopyInto(out *Flag) {
 		*out = make(json.RawMessage, len(*in))
 		copy(*out, *in)
 	}
+	if in.Metadata != nil {
+		in, out := &in.Metadata, &out.Metadata
+		*out = make(json.RawMessage, len(*in))
+		copy(*out, *in)
+	}
 }
 
 // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Flag.
@@ -269,6 +274,11 @@ func (in *Flag) DeepCopy() *Flag {
 func (in *FlagSpec) DeepCopyInto(out *FlagSpec) {
 	*out = *in
 	in.Flags.DeepCopyInto(&out.Flags)
+	if in.Metadata != nil {
+		in, out := &in.Metadata, &out.Metadata
+		*out = make(json.RawMessage, len(*in))
+		copy(*out, *in)
+	}
 	if in.Evaluators != nil {
 		in, out := &in.Evaluators, &out.Evaluators
 		*out = make(json.RawMessage, len(*in))
diff --git a/config/crd/bases/core.openfeature.dev_featureflags.yaml b/config/crd/bases/core.openfeature.dev_featureflags.yaml
index 02566fd07..87527d9ce 100644
--- a/config/crd/bases/core.openfeature.dev_featureflags.yaml
+++ b/config/crd/bases/core.openfeature.dev_featureflags.yaml
@@ -53,6 +53,12 @@ spec:
                       properties:
                         defaultVariant:
                           type: string
+                        metadata:
+                          description: |-
+                            Metadata holds optional per-flag metadata.
+                            Additional metadata keys are preserved to support flagd metadata inheritance.
+                          type: object
+                          x-kubernetes-preserve-unknown-fields: true
                         state:
                           enum:
                           - ENABLED
@@ -71,6 +77,12 @@ spec:
                       - variants
                       type: object
                     type: object
+                  metadata:
+                    description: |-
+                      Metadata holds optional flag-set level metadata.
+                      Additional metadata keys are preserved to support flagd metadata inheritance.
+                    type: object
+                    x-kubernetes-preserve-unknown-fields: true
                 required:
                 - flags
                 type: object