Metadata to allow nullable values

[askpt]

Summary

The current ImmutableMetadata implementation in the .NET SDK uses Dictionary<string, object> for storing metadata values. This means there's no way to distinguish between a metadata key that doesn't exist and a metadata key that explicitly has a null value.

This issue was identified during the review of open-feature/dotnet-sdk-contrib#524, where JsonElement values with JsonValueKind.Null are being converted to empty strings:

JsonValueKind.Null => string.Empty,

As noted by @chrfwow: "Shouldn't there be a difference between an empty string and a null value?"

Current Behavior

The ImmutableMetadata class stores values in an ImmutableDictionary<string, object>:

private readonly ImmutableDictionary<string, object> _metadata;

When retrieving values, there's no distinction between:

1. A key that doesn't exist in the metadata
2. A key that exists but has an explicit null value
3. A key that exists with an empty string value

For example, GetString("key") returns null for both missing keys and keys with null values.

OpenFeature Specification Consideration

Per Requirement 2.2.10 in the OpenFeature specification:

flag metadata MUST be a structure supporting the definition of arbitrary properties, with keys of type string, and values of type boolean | string | number.

The current spec does not include null as a valid metadata value type. This raises the question of whether this change should:

• Be accompanied by a spec change proposal in open-feature/spec
• Be implemented as a .NET SDK-specific extension
• Only affect internal storage while maintaining spec-compliant external behavior

Proposed Changes

1. Update the internal dictionary type to support nullable values:

   private readonly ImmutableDictionary<string, object?> _metadata;

2. Add a ContainsKey method to allow consumers to check if a key exists:

   public bool ContainsKey(string key) => _metadata.ContainsKey(key);

3. Consider adding TryGetValue methods for more explicit value retrieval:

   public bool TryGetString(string key, out string? value);
   public bool TryGetBool(string key, out bool?  value);
   public bool TryGetInt(string key, out int? value);
   public bool TryGetDouble(string key, out double? value);

4. Update the constructor to accept nullable values:

   public ImmutableMetadata(Dictionary<string, object?> metadata)

Breaking Changes

This is a breaking change because:

• The constructor signature changes from Dictionary<string, object> to Dictionary<string, object?>
• Existing code that relies on the current behavior (null meaning "not found") may need updates

Questions for Discussion

1. Should this change be accompanied by a spec change proposal in open-feature/spec to include null as a valid metadata value type?
2. What API design best serves consumers who need to distinguish between "key not found", "key with null value", and "key with empty string"?
3. Should migration guidance be included for users upgrading to 3.0.0?

Related

• open-feature/dotnet-sdk-contrib#524 - PR where this issue was identified
• Review comment by @chrfwow

[kylejuliandev]

A possible alternative solution could be to utilise the Value type as in the ImmutableMetadata. For example:

private readonly ImmutableDictionary<string, Value> _metadata;

Rationale

• Consistent abstraction: Value already supports strings, booleans, and numbers (integer/double/float), and can represent null via the IsNull property. It’s also the SDK’s familiar container for structured data, including Structure and arrays.
• Clear null semantics: With Value, an explicit null is representable (Value.IsNull), which helps address the ambiguity between “not present” and “present but null” at the value level.

Proposed Changes

1. Remove the GetBool, GetInt, GetDouble, and GetString accessor methods.

- public bool? GetBool(string key)
- public int? GetInt(string key)
- public double? GetDouble(string key)
- public string? GetString(string key)

2. Add a TryGetValue accessor method for retrieving the Value.

+ public Value? TryGetValue(string key, out Value value)

3. Change the constructor to pass Dictionary of Value instead.

- public ImmutableMetadata(Dictionary<string, object> metadata)
+ public ImmutableMetadata(Dictionary<string, Value> metadata)

Breaking Changes

This would drastically change how ImmutableMetadata is initialised and accessed. The following changes would result in breaking changes:

• Removal of existing accessor methods (GetBool, GetInt, GetDouble, and GetString).
• Changing constructor signature from Dictionary<string, object> to Dictionary<string, Value>.

Example Usage

With the proposed change you can access metadata with the following pattern:

if (_metadata.TryGetValue("notes", out var v))
{
    if (v.IsNull)
    {
        // present and explicitly null
    }
    else
    {
        // present with a concrete value
    }
}
else
{
    // key not found
}

Migration and compatibility

Instead of removing the existing accessor methods (GetBool, GetInt, GetDouble, and GetString) these could be wired to access the underlying Dictionary<string, Value> and behave in the same manner as they did before.

public bool? GetBool(string key)
{
	var value = GetValue(key);
	
	return value.IsBoolean ? value.AsBoolean : null;
}

private Value GetValue(string key)
{
	if (!this._metadata.ContainsKey(key))
	{
		return new Value();
	}

	return this._metadata[key];
}

Additionally, we could keep the existing constructor and chain constructors together as Value has a constructor which accepts object.

public ImmutableMetadata(Dictionary<string, Value> metadata)
{
}

public ImmutableMetadata(Dictionary<string, object> metadata)
	: this(metadata.ToDictionary(kvp => kvp.Key, kvp => new Value(kvp.Value)))
{
}

[askpt]

Thanks for the suggestion. I don't like this that much. Using a custom Value.IsNull pattern would be a step backwards from idiomatic C# and would break the expected nullability semantics that . NET developers rely on.

I would prefer a native C# nullable type.