feat: add support for Title, PropertyLimits, UniqueItems, XListType, XMapType, and XListMapKeys attributes (#1160)

This PR adds support for several `JSONSchemaProps` fields that were
previously missing from the CRD transpiler, narrowing the gap between
what Kubernetes supports and what can be expressed via C# attributes.

New attributes:

| Attribute | JSONSchemaProps field | Notes |
|---|---|---|
| `[Title]` | `title` | String, property or class level |
| `[PropertyLimits]` | `minProperties` / `maxProperties` | Long, uses
`-1` sentinel like `[Length]` |
| `[UniqueItems]` | `uniqueItems` | Marker attribute (bool) |
| `[XListType]` | `x-kubernetes-list-type` | Enum: `Atomic`, `Set`,
`Map` |
| `[XMapType]` | `x-kubernetes-map-type` | Enum: `Granular`, `Atomic` |
| `[XListMapKeys]` | `x-kubernetes-list-map-keys` | `params string[]` |

The remaining unmapped fields (`default`, `example`,
`allOf`/`oneOf`/`anyOf`/`not`, `patternProperties`, `dependencies`,
`definitions`, `additionalItems`) require recursive schema structures or
arbitrary JSON, which can't be expressed through C# attributes.

Closes #943

Author: torjue

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

@@ -137,11 +137,14 @@ public class EntitySpec
 - `[RangeMinimum]` and `[RangeMaximum]`: Defines numeric value ranges
 - `[MultipleOf]`: Specifies that a number must be a multiple of a given value
 - `[Items]`: Defines minimum and maximum items for arrays
+- `[UniqueItems]`: Marks an array property as requiring unique items (`uniqueItems: true`)
+- `[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
 
 ### 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
 
 ### Display Attributes
@@ -154,6 +157,9 @@ public class EntitySpec
 - `[Ignore]`: Excludes a property or entity from CRD generation
 - `[PreserveUnknownFields]`: Allows unknown fields on the annotated object (`x-kubernetes-preserve-unknown-fields: true`). The known fields are still transpiled and validated, so you keep a structural schema for what you model while permitting extra fields. Works the same whether placed on a property or on a class/type: if the type cannot be represented (it contains a circular reference or an otherwise non-transpilable member), it gracefully falls back to an opaque `type: object` with `x-kubernetes-preserve-unknown-fields: true` instead of failing — making this the recommended way to model complex, externally generated, or self-referencing types.
 - `[EmbeddedResource]`: Marks a property as an embedded Kubernetes resource. The property type is never traversed; the schema is always an opaque embedded `type: object`.
+- `[XListType]`: Annotates an array to describe its topology (`XListType.Atomic`, `XListType.Set`, or `XListType.Map`). Maps to `x-kubernetes-list-type`.
+- `[XMapType]`: Annotates an object to describe its topology (`XMapType.Granular` or `XMapType.Atomic`). Maps to `x-kubernetes-map-type`.
+- `[XListMapKeys]`: Specifies the keys used as the index for a list with `XListType.Map` (e.g., `[XListMapKeys("name", "port")]`). Maps to `x-kubernetes-list-map-keys`.
 
 :::note
 The CRD transpiler maps property types recursively. A **circular type reference** that is not opted out via `[PreserveUnknownFields]` or `[Ignore]` cannot be represented as a finite OpenAPI schema and raises a descriptive `TranspilationFailedException` during generation. Annotate the offending property or type with `[PreserveUnknownFields]` or `[Ignore]`, or restructure the type to remove the cycle.

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

@@ -0,0 +1,30 @@
+// 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 property count limits for object properties.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public class PropertyLimitsAttribute(long minProperties = -1, long maxProperties = -1) : Attribute
+{
+    /// <summary>
+    /// Define the minimum number of properties.
+    /// </summary>
+    public long? MinProperties => minProperties switch
+    {
+        -1 => null,
+        _ => minProperties,
+    };
+
+    /// <summary>
+    /// Define the maximum number of properties.
+    /// </summary>
+    public long? MaxProperties => maxProperties switch
+    {
+        -1 => null,
+        _ => maxProperties,
+    };
+}

src/KubeOps.Abstractions/Entities/Attributes/TitleAttribute.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>
+/// Defines a title for a property.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property | AttributeTargets.Class)]
+public class TitleAttribute(string title) : Attribute
+{
+    /// <summary>
+    /// The given title for the property.
+    /// </summary>
+    public string Title => title;
+}

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

@@ -0,0 +1,11 @@
+// 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 that array items must be unique.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public class UniqueItemsAttribute : Attribute;

src/KubeOps.Abstractions/Entities/Attributes/XListMapKeysAttribute.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>
+/// Annotates an array with x-kubernetes-list-type "map" by specifying the keys used as the index of the map.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public class XListMapKeysAttribute(params string[] keys) : Attribute
+{
+    /// <summary>
+    /// The keys used as the index of the map.
+    /// </summary>
+    public string[] Keys => keys;
+}

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

@@ -0,0 +1,40 @@
+// 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>
+/// The topology type for an array property.
+/// </summary>
+public enum XListType
+{
+    /// <summary>
+    /// The list is treated as a single entity, like a scalar.
+    /// Atomic lists will be entirely replaced when updated.
+    /// </summary>
+    Atomic,
+
+    /// <summary>
+    /// Sets are lists that must not have multiple items with the same value.
+    /// </summary>
+    Set,
+
+    /// <summary>
+    /// These lists are like maps in that their elements have a non-index key
+    /// used to identify them. Order is preserved upon merge.
+    /// </summary>
+    Map,
+}
+
+/// <summary>
+/// Annotates an array to further describe its topology.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public class XListTypeAttribute(XListType listType) : Attribute
+{
+    /// <summary>
+    /// The list type.
+    /// </summary>
+    public XListType ListType => listType;
+}

src/KubeOps.Abstractions/Entities/Attributes/XMapTypeAttribute.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>
+/// The topology type for an object property.
+/// </summary>
+public enum XMapType
+{
+    /// <summary>
+    /// These maps are actual maps (key-value pairs) and each field is independent
+    /// from each other. This is the default behaviour for all maps.
+    /// </summary>
+    Granular,
+
+    /// <summary>
+    /// The map is treated as a single entity, like a scalar.
+    /// Atomic maps will be entirely replaced when updated.
+    /// </summary>
+    Atomic,
+}
+
+/// <summary>
+/// Annotates an object to further describe its topology.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public class XMapTypeAttribute(XMapType mapType) : Attribute
+{
+    /// <summary>
+    /// The map type.
+    /// </summary>
+    public XMapType MapType => mapType;
+}

src/KubeOps.Transpiler/Crds.cs

@@ -108,6 +108,8 @@ public static V1CustomResourceDefinition Transpile(
                     Type = Object,
                     Description =
                         type.GetCustomAttributeData<DescriptionAttribute>()?.GetCustomAttributeCtorArg<string>(context, 0),
+                    Title =
+                        type.GetCustomAttributeData<TitleAttribute>()?.GetCustomAttributeCtorArg<string>(context, 0),
                     Properties = type.GetProperties()
                         .Where(p => !IgnoredToplevelProperties.Contains(p.Name.ToLowerInvariant())
                                     && p.GetCustomAttributeData<IgnoreAttribute>() == null)
@@ -337,6 +339,9 @@ private static V1JSONSchemaProps Map(
         props.Description ??= prop.GetCustomAttributeData<DescriptionAttribute>()
             ?.GetCustomAttributeCtorArg<string>(context, 0);
 
+        props.Title ??= prop.GetCustomAttributeData<TitleAttribute>()
+            ?.GetCustomAttributeCtorArg<string>(context, 0);
+
         if (prop.IsNullable())
         {
             // Default to Nullable to null to avoid generating `nullable:false`
@@ -354,8 +359,11 @@ private static V1JSONSchemaProps Map(
 
         if (prop.GetCustomAttributeData<ItemsAttribute>() is { } items)
         {
-            props.MinItems = items.GetCustomAttributeCtorArg<long>(context, 0);
-            props.MaxItems = items.GetCustomAttributeCtorArg<long>(context, 1);
+            var minItems = items.GetCustomAttributeCtorArg<long>(context, 0);
+            props.MinItems = minItems == -1 ? null : minItems;
+
+            var maxItems = items.GetCustomAttributeCtorArg<long>(context, 1);
+            props.MaxItems = maxItems == -1 ? null : maxItems;
         }
 
         if (prop.GetCustomAttributeData<LengthAttribute>() is { } length)
@@ -367,6 +375,15 @@ private static V1JSONSchemaProps Map(
             props.MaxLength = maxLength == -1 ? null : maxLength;
         }
 
+        if (prop.GetCustomAttributeData<PropertyLimitsAttribute>() is { } properties)
+        {
+            var minProperties = properties.GetCustomAttributeCtorArg<long>(context, 0);
+            props.MinProperties = minProperties == -1 ? null : minProperties;
+
+            var maxProperties = properties.GetCustomAttributeCtorArg<long>(context, 1);
+            props.MaxProperties = maxProperties == -1 ? null : maxProperties;
+        }
+
         if (prop.GetCustomAttributeData<MultipleOfAttribute>() is { } multi)
         {
             props.MultipleOf = multi.GetCustomAttributeCtorArg<double>(context, 0);
@@ -391,6 +408,28 @@ private static V1JSONSchemaProps Map(
                 rangeMin.GetCustomAttributeCtorArg<bool>(context, 1);
         }
 
+        if (prop.GetCustomAttributeData<UniqueItemsAttribute>() is not null)
+        {
+            props.UniqueItems = true;
+        }
+
+        if (prop.GetCustomAttributeData<XListTypeAttribute>() is { } listType)
+        {
+            props.XKubernetesListType = listType.GetCustomAttributeCtorArg<XListType>(context, 0)
+                .ToString().ToLowerInvariant();
+        }
+
+        if (prop.GetCustomAttributeData<XMapTypeAttribute>() is { } mapType)
+        {
+            props.XKubernetesMapType = mapType.GetCustomAttributeCtorArg<XMapType>(context, 0)
+                .ToString().ToLowerInvariant();
+        }
+
+        if (prop.GetCustomAttributeData<XListMapKeysAttribute>() is { } listMapKeysAttr)
+        {
+            props.XKubernetesListMapKeys = listMapKeysAttr.GetCustomAttributeCtorArrayArg<string>(0);
+        }
+
         if (preservesUnknownFields)
         {
             props.XKubernetesPreserveUnknownFields = true;
@@ -586,6 +625,9 @@ private static V1JSONSchemaProps MapObjectType(
                         Description =
                             type.GetCustomAttributeData<DescriptionAttribute>()
                                 ?.GetCustomAttributeCtorArg<string>(context, 0),
+                        Title =
+                            type.GetCustomAttributeData<TitleAttribute>()
+                                ?.GetCustomAttributeCtorArg<string>(context, 0),
                         Properties = type
                             .GetProperties()
                             .Where(p => p.GetCustomAttributeData<IgnoreAttribute>() == null)