feat: opt-in non-nullable required properties for TypeScript and Python

Adds a `MakeRequiredPropertiesNonNullable` generation flag (CLI:
`--make-required-properties-non-nullable` / `--mrpnn`) that honors the
OpenAPI `required` array and `nullable`/`type:[...,"null"]` markers when
generating models. A property that is required and not explicitly
nullable is generated as non-optional and non-nullable.

The flag defaults to false to preserve the historical all-nullable
behavior for existing clients; no existing generation output changes
unless it is explicitly enabled.

Shared groundwork:
- CodeProperty.IsRequired, populated from the parent schema's required array
- GenerationConfiguration.MakeRequiredPropertiesNonNullable (default false)
- OpenApiSchemaExtensions.IsExplicitlyNullable() (OAS 3.0 + 3.1)
- KiotaBuilder flips Type.IsNullable=false for required, non-explicitly-nullable,
  non-collection custom properties when the flag is on

TypeScript: the interface writer now drops `?` for required properties and
drops `| null` unless the schema is explicitly nullable.

Python: no writer change is required. The dataclass field writer already
gates Optional[...] on IsNullable and retains the `= None` default, so a
required non-nullable property renders as `name: T = None` -- non-Optional
while keeping the default that allows no-arg construction
(create_from_discriminator_value) and valid dataclass field ordering.

Tests: full flag on/off matrix at the builder level (scalar/int/enum/object
ref/collection), TypeScript interface rendering, and Python dataclass field
rendering. Refs #3911.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kev-flex

src/Kiota.Builder/CodeDOM/CodeProperty.cs

@@ -122,6 +122,14 @@ public bool IsPrimaryErrorMessage
     {
         get; set;
     }
+    /// <summary>
+    /// Indicates that this property appeared in the parent schema's <c>required</c> array.
+    /// Set during Code DOM construction in KiotaBuilder; should not be modified by refiners.
+    /// </summary>
+    public bool IsRequired
+    {
+        get; set;
+    }
 
     public object Clone()
     {
@@ -143,6 +151,7 @@ public object Clone()
             OriginalPropertyFromBaseType = OriginalPropertyFromBaseType?.Clone() as CodeProperty,
             Deprecation = Deprecation,
             IsPrimaryErrorMessage = IsPrimaryErrorMessage,
+            IsRequired = IsRequired,
         };
         return property;
     }

src/Kiota.Builder/Configuration/GenerationConfiguration.cs

@@ -65,6 +65,15 @@ public bool UsesBackingStore
     {
         get; set;
     }
+    /// <summary>
+    /// When enabled, properties marked as required in the OpenAPI description and not explicitly nullable
+    /// are generated as non-nullable (and non-optional, for languages that distinguish the two).
+    /// Defaults to false to preserve the historical all-nullable behavior for existing clients.
+    /// </summary>
+    public bool MakeRequiredPropertiesNonNullable
+    {
+        get; set;
+    }
     public bool ExcludeBackwardCompatible
     {
         get; set;
@@ -184,6 +193,7 @@ public object Clone()
             DisableSSLValidation = DisableSSLValidation,
             ExportPublicApi = ExportPublicApi,
             PluginAuthInformation = PluginAuthInformation,
+            MakeRequiredPropertiesNonNullable = MakeRequiredPropertiesNonNullable,
         };
     }
     private static readonly StringIEnumerableDeepComparer comparer = new();

src/Kiota.Builder/Extensions/OpenApiSchemaExtensions.cs

@@ -80,6 +80,20 @@ public static bool HasAnyProperty(this IOpenApiSchema? schema)
     {
         return schema?.Properties is { Count: > 0 };
     }
+    /// <summary>
+    /// Indicates whether the schema explicitly permits null.
+    /// Covers OAS 3.0 <c>nullable: true</c> and OAS 3.1 <c>type: [..., "null"]</c>,
+    /// as well as the OAS 3.1 <c>anyOf: [{ type: null }]</c> pattern.
+    /// </summary>
+    internal static bool IsExplicitlyNullable(this IOpenApiSchema? schema)
+    {
+        if (schema is null) return false;
+        // OAS 3.0 nullable: true or OAS 3.1 type includes null
+        if ((schema.Type & JsonSchemaType.Null) is JsonSchemaType.Null) return true;
+        // OAS 3.1 anyOf [ { type: null } ] pattern
+        return schema.AnyOf?.Any(static x =>
+            (x.Type & JsonSchemaType.Null) is JsonSchemaType.Null && !x.HasAnyProperty()) ?? false;
+    }
     public static bool IsInclusiveUnion(this IOpenApiSchema? schema, uint exclusiveMinimumNumberOfEntries = 1)
     {
         return schema?.AnyOf?.Count(static x => IsSemanticallyMeaningful(x, true)) > exclusiveMinimumNumberOfEntries;

src/Kiota.Builder/KiotaBuilder.cs

@@ -661,7 +661,7 @@ public async Task ApplyLanguageRefinementAsync(GenerationConfiguration config, C
 
     public async Task CreateLanguageSourceFilesAsync(GenerationLanguage language, CodeNamespace generatedCode, CancellationToken cancellationToken)
     {
-        var languageWriter = LanguageWriter.GetLanguageWriter(language, config.OutputPath, config.ClientNamespaceName, config.UsesBackingStore, config.ExcludeBackwardCompatible);
+        var languageWriter = LanguageWriter.GetLanguageWriter(language, config.OutputPath, config.ClientNamespaceName, config.UsesBackingStore, config.ExcludeBackwardCompatible, config.MakeRequiredPropertiesNonNullable);
         var stopwatch = new Stopwatch();
         stopwatch.Start();
         var codeRenderer = CodeRenderer.GetCodeRender(config);
@@ -1174,7 +1174,7 @@ private CodeIndexer[] CreateIndexer(string childIdentifier, string childType, Co
     }
     private static readonly StructuralPropertiesReservedNameProvider structuralPropertiesReservedNameProvider = new();
 
-    private CodeProperty? CreateProperty(string childIdentifier, string childType, IOpenApiSchema? propertySchema = null, CodeTypeBase? existingType = null, CodePropertyKind kind = CodePropertyKind.Custom)
+    private CodeProperty? CreateProperty(string childIdentifier, string childType, IOpenApiSchema? propertySchema = null, CodeTypeBase? existingType = null, CodePropertyKind kind = CodePropertyKind.Custom, bool isRequired = false)
     {
         var propertyName = childIdentifier.CleanupSymbolName();
         if (structuralPropertiesReservedNameProvider.ReservedNames.Contains(propertyName))
@@ -1196,6 +1196,7 @@ private CodeIndexer[] CreateIndexer(string childIdentifier, string childType, Co
             ReadOnly = propertySchema?.ReadOnly ?? false,
             Type = resultType,
             Deprecation = propertySchema?.GetDeprecationInformation(),
+            IsRequired = isRequired,
             IsPrimaryErrorMessage = kind == CodePropertyKind.Custom &&
                                         propertySchema is { Extensions: not null } &&
                                         propertySchema.Extensions.TryGetValue(OpenApiPrimaryErrorMessageExtension.Name, out var openApiExtension) &&
@@ -1221,6 +1222,23 @@ openApiExtension is OpenApiPrimaryErrorMessageExtension primaryErrorMessageExten
             prop.DefaultValue = stringDefaultJsonValue2.ToString();
         }
 
+        // When the property is required and its schema does not explicitly allow null, mark the type as
+        // non-nullable so writers can drop the nullability/optionality markers. Gated on the configuration
+        // flag so the historical all-nullable behavior is preserved by default.
+        // Collections are excluded: IsNullable on a collection type controls both the outer collection
+        // nullability AND the element nullability (e.g. list of Status? vs list of Status), and the
+        // serialization APIs always expect a nullable element collection. The cloning avoids mutating a
+        // shared/cached type reference (the same definition can back multiple properties).
+        var isCollection = existingType != null
+            ? existingType.CollectionKind != CodeTypeBase.CodeTypeCollectionKind.None
+            : propertySchema.IsArray();
+        if (config.MakeRequiredPropertiesNonNullable && kind == CodePropertyKind.Custom && isRequired && !propertySchema.IsExplicitlyNullable() && !isCollection)
+        {
+            if (existingType != null)
+                prop.Type = (CodeTypeBase)existingType.Clone();
+            prop.Type.IsNullable = false;
+        }
+
         if (existingType == null)
         {
             prop.Type.CollectionKind = propertySchema.IsArray() ? CodeTypeBase.CodeTypeCollectionKind.Complex : default;
@@ -2434,7 +2452,8 @@ private void CreatePropertiesForModelClass(OpenApiUrlTreeNode currentNode, IOpen
                             LogOmittedPropertyInvalidSchema(x.Key, model.Name, currentNode.Path);
                             return null;
                         }
-                        return CreateProperty(x.Key, definition.Name, propertySchema: propertySchema, existingType: definition);
+                        var isRequired = schema.Required?.Contains(x.Key) ?? false;
+                        return CreateProperty(x.Key, definition.Name, propertySchema: propertySchema, existingType: definition, isRequired: isRequired);
                     })
                     .OfType<CodeProperty>()
                     .ToArray() ?? [];

src/Kiota.Builder/Writers/LanguageWriter.cs

@@ -178,13 +178,13 @@ protected void AddOrReplaceCodeElementWriter<T>(ICodeElementWriter<T> writer) wh
             Writers[typeof(T)] = writer;
     }
     private readonly Dictionary<Type, object> Writers = []; // we have to type as object because dotnet doesn't have type capture i.e eq for `? extends CodeElement`
-    public static LanguageWriter GetLanguageWriter(GenerationLanguage language, string outputPath, string clientNamespaceName, bool usesBackingStore = false, bool excludeBackwardCompatible = false)
+    public static LanguageWriter GetLanguageWriter(GenerationLanguage language, string outputPath, string clientNamespaceName, bool usesBackingStore = false, bool excludeBackwardCompatible = false, bool makeRequiredPropertiesNonNullable = false)
     {
         return language switch
         {
             GenerationLanguage.CSharp => new CSharpWriter(outputPath, clientNamespaceName),
             GenerationLanguage.Java => new JavaWriter(outputPath, clientNamespaceName),
-            GenerationLanguage.TypeScript => new TypeScriptWriter(outputPath, clientNamespaceName),
+            GenerationLanguage.TypeScript => new TypeScriptWriter(outputPath, clientNamespaceName, makeRequiredPropertiesNonNullable),
             GenerationLanguage.Ruby => new RubyWriter(outputPath, clientNamespaceName),
             GenerationLanguage.PHP => new PhpWriter(outputPath, clientNamespaceName, usesBackingStore),
             GenerationLanguage.Python => new PythonWriter(outputPath, clientNamespaceName, usesBackingStore),

src/Kiota.Builder/Writers/TypeScript/CodePropertyWriter.cs

@@ -28,24 +28,32 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w
         switch (codeElement.Parent)
         {
             case CodeInterface:
-                WriteCodePropertyForInterface(codeElement, writer, returnType, isFlagEnum);
+                WriteCodePropertyForInterface(codeElement, writer, returnType, isFlagEnum, conventions.MakeRequiredPropertiesNonNullable);
                 break;
             case CodeClass:
                 throw new InvalidOperationException($"All properties are defined on interfaces in TypeScript.");
         }
     }
-    private static void WriteCodePropertyForInterface(CodeProperty codeElement, LanguageWriter writer, string returnType, bool isFlagEnum)
+    private static void WriteCodePropertyForInterface(CodeProperty codeElement, LanguageWriter writer, string returnType, bool isFlagEnum, bool makeRequiredPropertiesNonNullable)
     {
+        var collectionSuffix = isFlagEnum ? "[]" : string.Empty;
         switch (codeElement.Kind)
         {
             case CodePropertyKind.RequestBuilder:
                 writer.WriteLine($"get {codeElement.Name.ToFirstCharacterLowerCase()}(): {returnType};");
                 break;
             case CodePropertyKind.QueryParameter:
-                writer.WriteLine($"{codeElement.Name.ToFirstCharacterLowerCase()}?: {returnType}{(isFlagEnum ? "[]" : string.Empty)};");
+                writer.WriteLine($"{codeElement.Name.ToFirstCharacterLowerCase()}?: {returnType}{collectionSuffix};");
                 break;
             default:
-                writer.WriteLine($"{codeElement.Name.ToFirstCharacterLowerCase()}?: {returnType}{(isFlagEnum ? "[]" : string.Empty)} | null;");
+                // When enabled, a required property is non-optional (no `?`), and drops `| null` unless its
+                // schema is explicitly nullable. Otherwise the historical optional + nullable form is kept.
+                var suppressOptionalAndNull = makeRequiredPropertiesNonNullable && codeElement.IsRequired;
+                var optionalMarker = suppressOptionalAndNull ? string.Empty : "?";
+                var nullSuffix = suppressOptionalAndNull
+                    ? (codeElement.Type.IsNullable ? " | null" : string.Empty)
+                    : " | null";
+                writer.WriteLine($"{codeElement.Name.ToFirstCharacterLowerCase()}{optionalMarker}: {returnType}{collectionSuffix}{nullSuffix};");
                 break;
         }
     }

src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs

@@ -12,6 +12,13 @@ namespace Kiota.Builder.Writers.TypeScript;
 
 public class TypeScriptConventionService : CommonLanguageConventionService
 {
+    /// <summary>
+    /// When true, required and not-explicitly-nullable properties are rendered as non-optional
+    /// (no <c>?</c>) and non-nullable (no <c>| null</c>). Defaults to false to preserve the
+    /// historical behavior where every model property is optional and nullable.
+    /// </summary>
+    public bool MakeRequiredPropertiesNonNullable { get; init; }
+
 #pragma warning disable CA1707 // Remove the underscores
     public const string TYPE_INTEGER = "integer";
     public const string TYPE_INT64 = "int64";

src/Kiota.Builder/Writers/TypeScript/TypeScriptWriter.cs

@@ -4,10 +4,13 @@ namespace Kiota.Builder.Writers.TypeScript;
 
 public class TypeScriptWriter : LanguageWriter
 {
-    public TypeScriptWriter(string rootPath, string clientNamespaceName)
+    public TypeScriptWriter(string rootPath, string clientNamespaceName, bool makeRequiredPropertiesNonNullable = false)
     {
         PathSegmenter = new TypeScriptPathSegmenter(rootPath, clientNamespaceName);
-        var conventionService = new TypeScriptConventionService();
+        var conventionService = new TypeScriptConventionService
+        {
+            MakeRequiredPropertiesNonNullable = makeRequiredPropertiesNonNullable
+        };
         AddOrReplaceCodeElementWriter(new CodeClassDeclarationWriter(conventionService, clientNamespaceName));
         AddOrReplaceCodeElementWriter(new CodeBlockEndWriter(conventionService));
         AddOrReplaceCodeElementWriter(new CodeEnumWriter(conventionService));

src/kiota/Handlers/KiotaGenerateCommandHandler.cs

@@ -86,6 +86,7 @@ public override async Task<int> InvokeAsync(ParseResult parseResult, Cancellatio
         bool excludeBackwardCompatible = parseResult.GetValue(ExcludeBackwardCompatibleOption);
         bool clearCache = parseResult.GetValue(ClearCacheOption);
         bool disableSSLValidation = parseResult.GetValue(DisableSSLValidationOption);
+        bool makeRequiredPropertiesNonNullable = parseResult.GetValue(MakeRequiredPropertiesNonNullableOption);
         bool includeAdditionalData = parseResult.GetValue(AdditionalDataOption);
         string? className = parseResult.GetValue(ClassOption);
         AccessModifier typeAccessModifier = parseResult.GetValue(TypeAccessModifierOption);
@@ -152,6 +153,7 @@ public override async Task<int> InvokeAsync(ParseResult parseResult, Cancellatio
         Configuration.Generation.CleanOutput = cleanOutput;
         Configuration.Generation.ClearCache = clearCache;
         Configuration.Generation.DisableSSLValidation = disableSSLValidation;
+        Configuration.Generation.MakeRequiredPropertiesNonNullable = makeRequiredPropertiesNonNullable;
 
         var (loggerFactory, logger) = GetLoggerAndFactory<KiotaBuilder>(parseResult, Configuration.Generation.OutputPath);
         using (loggerFactory)
@@ -233,6 +235,10 @@ public required Option<bool> DisableSSLValidationOption
     {
         get; init;
     }
+    public required Option<bool> MakeRequiredPropertiesNonNullableOption
+    {
+        get; init;
+    }
 
     private static void CreateTelemetryTags(ActivitySource? activitySource, GenerationLanguage language, bool backingStore,
         bool excludeBackwardCompatible, bool clearCache, bool disableSslValidation, bool cleanOutput, string? output,

src/kiota/KiotaHost.cs

@@ -589,6 +589,8 @@ private static Command GetGenerateCommand(IServiceProvider serviceProvider)
 
         var disableSSLValidationOption = GetDisableSSLValidationOption(defaultConfiguration.DisableSSLValidation);
 
+        var makeRequiredPropertiesNonNullableOption = GetMakeRequiredPropertiesNonNullableOption(defaultConfiguration.MakeRequiredPropertiesNonNullable);
+
         var command = new Command("generate", "Generates a REST HTTP API client from an OpenAPI description file.") {
             descriptionOption,
             manifestOption,
@@ -610,6 +612,7 @@ private static Command GetGenerateCommand(IServiceProvider serviceProvider)
             dvrOption,
             clearCacheOption,
             disableSSLValidationOption,
+            makeRequiredPropertiesNonNullableOption,
         };
         command.Action = new KiotaGenerateCommandHandler
         {
@@ -633,6 +636,7 @@ private static Command GetGenerateCommand(IServiceProvider serviceProvider)
             DisabledValidationRulesOption = dvrOption,
             ClearCacheOption = clearCacheOption,
             DisableSSLValidationOption = disableSSLValidationOption,
+            MakeRequiredPropertiesNonNullableOption = makeRequiredPropertiesNonNullableOption,
             ServiceProvider = serviceProvider,
         };
         return command;
@@ -719,6 +723,17 @@ private static Option<bool> GetDisableSSLValidationOption(bool defaultValue)
         return disableSSLValidationOption;
     }
 
+    internal static Option<bool> GetMakeRequiredPropertiesNonNullableOption(bool defaultValue = false)
+    {
+        var option = new Option<bool>("--make-required-properties-non-nullable")
+        {
+            DefaultValueFactory = _ => defaultValue,
+            Description = "When enabled, properties marked as required in the OpenAPI description and not explicitly nullable are generated as non-nullable (and non-optional, for languages that distinguish the two). Disabled by default to preserve the previous behavior where all properties are nullable.",
+        };
+        option.Aliases.Add("--mrpnn");
+        return option;
+    }
+
     private static void AddStringRegexValidator(Option<string> option, Regex validator, string parameterName, bool allowEmpty = false)
     {
         option.Validators.Add(input =>