feat(generator): expand CRD schema metadata support (#1201)

Adds attributes for defaults, examples, formats, and enum values in
generated CRD schemas, including structured JSON and class-level
defaults.Includes focused attribute validation and explicitly configures
the CRD conversion strategy based on registered conversion webhooks.

closes #1200

Author: kimpenhaus

docs/docs/operator/building-blocks/entities.mdx

@@ -140,12 +140,22 @@ public class EntitySpec
 - `[UniqueItems]`: **Rejected by the transpiler.** Kubernetes CRD schemas do not allow `uniqueItems: true`, so applying this attribute now fails transpilation. Use `[XListType(XListType.Set)]` for Kubernetes set semantics instead
 - `[PropertyLimits]`: Specifies minimum and maximum number of properties for an object
 - `[ValidationRule]`: Defines custom validation rules using CEL expressions. Can be applied to properties and to class types — in both cases it emits `x-kubernetes-validations` on the corresponding schema node. When applied to both a class and a property of that type, the rules are merged (class rules first, then property rules). Class-level rules are also collected across the **class inheritance chain**: a rule placed on a base class is inherited by every derived entity or nested type, and all rules found along the chain are merged onto the schema node
+- `[EnumValues]`: Overrides the allowed string, integer, or floating-point values emitted as the OpenAPI `enum`.
+  Values must be non-empty, unique, and compatible with the generated string, integer, number, or
+  `IntOrString` schema
 
 ### Documentation Attributes
 
 - `[Description]`: Adds a description to a property or entity
 - `[Title]`: Adds a title to a property or entity
 - `[ExternalDocs]`: Links to external documentation
+- `[DefaultValue]`: Adds an OpenAPI default value to a property or class. Set `Json = true` on a string argument to
+  represent structured values such as objects or arrays instead of a literal string. A class-level default applies
+  wherever that type is used in the schema, including the `spec` or `status` subresource. Class-level defaults are
+  inherited
+- `[Example]`: Adds an OpenAPI example. Set `Json = true` for structured JSON examples
+- `[Format]`: Overrides the inferred OpenAPI format, for example `[Format("uri")]` or `[Format("email")]`.
+  Use `[Format(null)]` to suppress an inferred format such as `int32`; empty or whitespace-only formats are rejected
 
 ### Display Attributes
 
@@ -182,17 +192,30 @@ public class V1DemoEntity : CustomKubernetesEntity<V1DemoEntity.V1DemoEntitySpec
         public string Username { get; set; } = string.Empty;
 
         [Description("Number of replicas to run")]
+        [DefaultValue(1)]
         [RangeMinimum(1)]
         [RangeMaximum(10)]
         public int Replicas { get; set; } = 1;
 
         [Pattern(@"^[a-z0-9-]+$")]
         [Description("The namespace where resources should be created")]
         public string? TargetNamespace { get; set; }
+
+        [Format("uri")]
+        [Example("https://example.com/events")]
+        public string? CallbackUrl { get; set; }
+
+        [DefaultValue("{}", Json = true)]
+        public Dictionary<string, object> Labels { get; set; } = [];
     }
 
+    [DefaultValue("{}", Json = true)]
     public class V1DemoEntityStatus
     {
+        [DefaultValue(0)]
+        [Description("Last reconciled resource generation")]
+        public long ObservedGeneration { get; set; }
+
         [Description("Current state of the entity")]
         public string CurrentState { get; set; } = string.Empty;
 
@@ -293,4 +316,4 @@ subresources:
 
 :::note
 `[ScaleSubresource]` and the status subresource are controlled independently. A `Status` property activates `status: {}` regardless of `[ScaleSubresource]`, and `[ScaleSubresource]` adds `scale:` regardless of whether a `Status` property exists.
-:::
+:::

docs/docs/operator/cli.mdx

@@ -105,6 +105,9 @@ Common options:
 - `--docker-image-tag`: Specify Docker image tag
 - `--no-ansi`: Disable ANSI colored output (useful for CI/CD pipelines)
 
+Generated CRDs explicitly use `conversion.strategy: None` unless a conversion webhook is registered for the CRD.
+For registered conversion webhooks, the strategy is `Webhook` and includes the webhook client configuration.
+
 ## Cluster Information
 
 The `version` command shows information about your current Kubernetes cluster:
@@ -162,4 +165,4 @@ All commands support these options:
    ```bash
    # Generate resources with custom output
    kubeops generate operator MyOperator ./MyOperator.csproj --out ./k8s --format yaml
-   ```
+   ```

src/KubeOps.Abstractions/Entities/Attributes/DefaultValueAttribute.cs

@@ -0,0 +1,46 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+namespace KubeOps.Abstractions.Entities.Attributes;
+
+/// <summary>
+/// Defines the default value of a property or type in the generated OpenAPI schema.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property | AttributeTargets.Class, Inherited = true)]
+public sealed class DefaultValueAttribute : Attribute
+{
+    /// <summary>
+    /// Initializes the attribute with a boolean value.
+    /// </summary>
+    /// <param name="value">The default value.</param>
+    public DefaultValueAttribute(bool value) => Value = value;
+
+    /// <summary>
+    /// Initializes the attribute with an integer value.
+    /// </summary>
+    /// <param name="value">The default value.</param>
+    public DefaultValueAttribute(long value) => Value = value;
+
+    /// <summary>
+    /// Initializes the attribute with a floating-point value.
+    /// </summary>
+    /// <param name="value">The default value.</param>
+    public DefaultValueAttribute(double value) => Value = value;
+
+    /// <summary>
+    /// Initializes the attribute with a string value.
+    /// </summary>
+    /// <param name="value">The default value or its JSON representation when <see cref="Json"/> is set.</param>
+    public DefaultValueAttribute(string value) => Value = value;
+
+    /// <summary>
+    /// Gets or sets whether the string value contains JSON that should be emitted as a structured value.
+    /// </summary>
+    public bool Json { get; init; }
+
+    /// <summary>
+    /// Gets the configured default value.
+    /// </summary>
+    public object Value { get; }
+}

src/KubeOps.Abstractions/Entities/Attributes/EnumValuesAttribute.cs

@@ -0,0 +1,35 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+namespace KubeOps.Abstractions.Entities.Attributes;
+
+/// <summary>
+/// Overrides the allowed values generated for a property in the OpenAPI schema.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public sealed class EnumValuesAttribute : Attribute
+{
+    /// <summary>
+    /// Initializes the attribute with string values.
+    /// </summary>
+    /// <param name="values">The allowed values.</param>
+    public EnumValuesAttribute(params string[] values) => Values = values;
+
+    /// <summary>
+    /// Initializes the attribute with integer values.
+    /// </summary>
+    /// <param name="values">The allowed values.</param>
+    public EnumValuesAttribute(params long[] values) => Values = values.Cast<object>().ToArray();
+
+    /// <summary>
+    /// Initializes the attribute with floating-point values.
+    /// </summary>
+    /// <param name="values">The allowed values.</param>
+    public EnumValuesAttribute(params double[] values) => Values = values.Cast<object>().ToArray();
+
+    /// <summary>
+    /// Gets the configured allowed values.
+    /// </summary>
+    public IReadOnlyList<object> Values { get; }
+}

src/KubeOps.Abstractions/Entities/Attributes/ExampleAttribute.cs

@@ -0,0 +1,46 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+namespace KubeOps.Abstractions.Entities.Attributes;
+
+/// <summary>
+/// Defines an example value for a property in the generated OpenAPI schema.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public sealed class ExampleAttribute : Attribute
+{
+    /// <summary>
+    /// Initializes the attribute with a boolean value.
+    /// </summary>
+    /// <param name="value">The example value.</param>
+    public ExampleAttribute(bool value) => Value = value;
+
+    /// <summary>
+    /// Initializes the attribute with an integer value.
+    /// </summary>
+    /// <param name="value">The example value.</param>
+    public ExampleAttribute(long value) => Value = value;
+
+    /// <summary>
+    /// Initializes the attribute with a floating-point value.
+    /// </summary>
+    /// <param name="value">The example value.</param>
+    public ExampleAttribute(double value) => Value = value;
+
+    /// <summary>
+    /// Initializes the attribute with a string value.
+    /// </summary>
+    /// <param name="value">The example value or its JSON representation when <see cref="Json"/> is set.</param>
+    public ExampleAttribute(string value) => Value = value;
+
+    /// <summary>
+    /// Gets or sets whether the string value contains JSON that should be emitted as a structured value.
+    /// </summary>
+    public bool Json { get; init; }
+
+    /// <summary>
+    /// Gets the configured example value.
+    /// </summary>
+    public object Value { get; }
+}

src/KubeOps.Abstractions/Entities/Attributes/FormatAttribute.cs

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+namespace KubeOps.Abstractions.Entities.Attributes;
+
+/// <summary>
+/// Overrides the OpenAPI format generated for a property.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public sealed class FormatAttribute(string? format) : Attribute
+{
+    /// <summary>
+    /// Gets the OpenAPI format.
+    /// </summary>
+    public string? Format => format;
+}

src/KubeOps.Abstractions/README.md

@@ -19,3 +19,10 @@ By depending only on this package, you can define your entities and interfaces w
 
 - Define your CRD entity classes in a separate library, shared between your operator and potentially other applications.
 - Build tools that need to understand KubeOps entity definitions without needing the operator runtime.
+
+## CRD schema metadata
+
+Entity properties can describe OpenAPI schema metadata with attributes such as `[DefaultValue]`, `[Example]`,
+`[Format]`, and `[EnumValues]`. String defaults and examples can set `Json = true` to represent structured JSON
+objects or arrays. `[DefaultValue]` can also be applied to a class to set the default wherever that type occurs in
+the generated schema, including the `spec` or `status` subresource.

src/KubeOps.Cli/Generators/CrdGenerator.cs

@@ -4,6 +4,8 @@
 
 using System.Reflection;
 
+using k8s.Models;
+
 using KubeOps.Cli.Output;
 using KubeOps.Cli.Transpilation;
 using KubeOps.Transpiler;
@@ -20,29 +22,38 @@ public void Generate(ResultOutput output)
 
         foreach (var crd in crds)
         {
-            if (conversionWebhooks
-                    .Find(wh => crd.Spec.Group == wh.Group && crd.Spec.Names.Kind == wh.Kind) is not null)
+            var hasConversionWebhook = conversionWebhooks
+                .Find(wh => crd.Spec.Group == wh.Group && crd.Spec.Names.Kind == wh.Kind) is not null;
+
+            ConfigureConversion(crd, hasConversionWebhook, caBundle);
+
+            output.Add($"{crd.Metadata.Name.Replace('.', '_')}.{outputFormat.GetFileExtension()}", crd);
+        }
+    }
+
+    internal static void ConfigureConversion(
+        V1CustomResourceDefinition crd,
+        bool hasConversionWebhook,
+        byte[] caBundle)
+    {
+        crd.Spec.Conversion = hasConversionWebhook
+            ? new()
             {
-                crd.Spec.Conversion = new()
+                Strategy = "Webhook",
+                Webhook = new()
                 {
-                    Strategy = "Webhook",
-                    Webhook = new()
+                    ConversionReviewVersions = ["v1"],
+                    ClientConfig = new()
                     {
-                        ConversionReviewVersions = new[] { "v1" },
-                        ClientConfig = new()
+                        CaBundle = caBundle,
+                        Service = new()
                         {
-                            CaBundle = caBundle,
-                            Service = new()
-                            {
-                                Path = $"/convert/{crd.Spec.Group}/{crd.Spec.Names.Plural}",
-                                Name = "service",
-                            },
+                            Path = $"/convert/{crd.Spec.Group}/{crd.Spec.Names.Plural}",
+                            Name = "service",
                         },
                     },
-                };
+                },
             }
-
-            output.Add($"{crd.Metadata.Name.Replace('.', '_')}.{outputFormat.GetFileExtension()}", crd);
-        }
+            : new() { Strategy = "None" };
     }
 }

src/KubeOps.Cli/README.md

@@ -53,6 +53,9 @@ If your operator includes webhooks (mutations or validations), additional resour
 - **Service**: For exposing webhook endpoints
 - **Secret Generators**: For managing webhook certificates
 
+Generated CRDs explicitly use `conversion.strategy: None` unless a conversion webhook is registered for the CRD.
+When one is registered, the strategy is `Webhook` and the corresponding webhook client configuration is generated.
+
 ### Install
 
 Installs the operator and its CRDs into a Kubernetes cluster.

src/KubeOps.Transpiler/CrdSchemaAttributeValidator.cs

@@ -47,6 +47,8 @@ internal static class CrdSchemaAttributeValidator
 
     public static void Validate(PropertyInfo prop, V1JSONSchemaProps props, MetadataLoadContext context)
     {
+        ValidateFormatAttribute(prop, context);
+        ValidateEnumValuesAttribute(prop, props);
         ValidateUniqueItems(prop);
         ValidateListTopologyAttributes(prop, props, context);
         ValidateMapTopologyAttribute(prop, props);
@@ -106,6 +108,66 @@ public static void ValidateValidationRuleAttributes(
         }
     }
 
+    private static void ValidateFormatAttribute(PropertyInfo prop, MetadataLoadContext context)
+    {
+        if (prop.GetCustomAttributeData<FormatAttribute>() is not { } formatAttribute)
+        {
+            return;
+        }
+
+        var format = formatAttribute.GetCustomAttributeCtorArg<string?>(context, 0);
+        if (format is not null && string.IsNullOrWhiteSpace(format))
+        {
+            throw InvalidSchemaAttribute(
+                prop,
+                nameof(FormatAttribute),
+                "OpenAPI format must be null or contain at least one non-whitespace character.");
+        }
+    }
+
+    private static void ValidateEnumValuesAttribute(PropertyInfo prop, V1JSONSchemaProps props)
+    {
+        if (prop.GetCustomAttributeData<EnumValuesAttribute>() is null)
+        {
+            return;
+        }
+
+        var values = props.EnumProperty ?? [];
+        if (values.Count == 0)
+        {
+            throw InvalidSchemaAttribute(prop, nameof(EnumValuesAttribute), "At least one enum value is required.");
+        }
+
+        if (values.Distinct().Count() != values.Count)
+        {
+            throw InvalidSchemaAttribute(prop, nameof(EnumValuesAttribute), "Enum values must be unique.");
+        }
+
+        if (values.Any(value => !IsEnumValueCompatible(props, value)))
+        {
+            throw InvalidSchemaAttribute(
+                prop,
+                nameof(EnumValuesAttribute),
+                $"Enum values must match the generated schema type '{props.Type ?? "integer or string"}'.");
+        }
+    }
+
+    private static bool IsEnumValueCompatible(V1JSONSchemaProps props, object value)
+    {
+        if (props.XKubernetesIntOrString.GetValueOrDefault())
+        {
+            return value is string or long;
+        }
+
+        return props.Type switch
+        {
+            "string" => value is string,
+            "integer" => value is long,
+            "number" => value is long or double,
+            _ => false,
+        };
+    }
+
     private static void ValidateUniqueItems(PropertyInfo prop)
     {
         if (prop.GetCustomAttributeData<UniqueItemsAttribute>() is null)