[API Proposal]: ExampleValueAttribute

The proposal names the System.ComponentModel namespace and ExampleValueAttribute, but no repository files, tests, or entry points. Start by comparing the proposed API with DefaultValueAttribute and reviewing the surrounding System.ComponentModel APIs. Done means the API design is resolved and the proposed attribute is implemented with its documented usage supported.

Background and motivation

Introduction

This proposal introduces a new attribute, ExampleValueAttribute, to the System.ComponentModel namespace. It is designed to mirror the API surface of DefaultValueAttribute, but with the purpose of specifying example values for documentation and tooling scenarios.

Motivation

While DefaultValueAttribute is commonly used to indicate the default value of a property or parameter, there is currently no built-in attribute to indicate an example value. Example values are useful for:

• API documentation generation
• Design-time tooling
• Testing and validation scenarios
• Enhancing developer understanding of expected inputs

Adding ExampleValueAttribute provides a standardized way to annotate members with example values without overloading the semantics of DefaultValueAttribute.

Remarks

• This attribute is intended for use in documentation and tooling contexts.
• It does not affect runtime behavior or serialization.
• Consumers of this attribute (e.g., OpenAPI generators, UI scaffolding tools) can use the Value property to display or infer example inputs.

API Proposal

namespace System.ComponentModel
{
    [AttributeUsage(AttributeTargets.Property | AttributeTargets.Parameter)]
    public sealed class ExampleValueAttribute : Attribute
    {
        public ExampleValueAttribute(object value)
        {
            Value = value;
        }

        public object Value { get; }
    }
}

API Usage

Example 1: Property

public class Product
{
    [ExampleValue("Widget-123")]
    public string SKU { get; set; }
}

Example 2: Parameter

public void Configure([ExampleValue(true)] bool enableFeature)
{
    // ...
}

Alternative Designs

Examples can be provided using XML documentation, but providing an attribute gives users that are already familiar with similar attributes like DefaultValueAttribute an alternative that does not require enabling XML doc comments, which is an opt-in feature.

Risks

• Minimal risk, as this is a non-breaking addition.
• Tooling must opt-in to support this attribute.