feat(cli): Add additional-properties-defaults-to setting for OpenAPI specs in generators.yml. (#6621)

* Add setting for OpenAPI specs in generators.yml.

* chore: update changelog

Author: Swimburger

fern/apis/generators-yml/definition/generators.yml

@@ -277,6 +277,10 @@ types:
       example-generation:
         type: optional<OpenAPIExampleGenerationSchema>
         docs: Fine-tune your example generation
+      additional-properties-defaults-to:
+        type: optional<boolean>
+        docs: Configure what `additionalProperties` should default to when not explicitly defined on a schema. Defaults to `false`.
+        default: false
 
   FormParameterEncoding:
     enum:

fern/pages/changelogs/cli/2025-04-01.mdx

@@ -0,0 +1,5 @@
+## 0.57.12
+**`(feat):`** Add `additional-properties-defaults-to` setting for OpenAPI specs in generators.yml.
+This setting lets you change the default value for the `additionalProperties` field in the generated IR.
+
+

fern/pages/changelogs/csharp-sdk/2025-04-01.mdx

@@ -0,0 +1,4 @@
+## 1.15.13
+**`(chore):`** Mark `AdditionalProperties` property as experiment using XML docs.
+
+

generators-yml.schema.json

@@ -1512,6 +1512,16 @@
               "type": "null"
             }
           ]
+        },
+        "additional-properties-defaults-to": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "additionalProperties": false

packages/cli/api-importers/openapi/openapi-ir-parser/src/openapi/v3/converters/endpoint/convertRequest.ts

@@ -260,7 +260,7 @@ export function convertRequest({
             fullExamples: jsonMediaObject.examples,
             additionalProperties:
                 !isReferenceObject(jsonMediaObject.schema) &&
-                isAdditionalPropertiesAny(jsonMediaObject.schema.additionalProperties),
+                isAdditionalPropertiesAny(jsonMediaObject.schema.additionalProperties, context.options),
             source
         });
     }

packages/cli/api-importers/openapi/openapi-ir-parser/src/options.ts

@@ -47,6 +47,11 @@ export interface ParseOpenAPIOptions {
     asyncApiNaming: "v1" | "v2";
 
     exampleGeneration: generatorsYml.OpenApiExampleGenerationSchema | undefined;
+
+    /**
+     * Configure what `additionalProperties` should default to when not explicitly defined on a schema. Defaults to `false`.
+     */
+    additionalPropertiesDefaultsTo: boolean;
 }
 
 export const DEFAULT_PARSE_OPENAPI_SETTINGS: ParseOpenAPIOptions = {
@@ -69,7 +74,8 @@ export const DEFAULT_PARSE_OPENAPI_SETTINGS: ParseOpenAPIOptions = {
     exampleGeneration: undefined,
     defaultFormParameterEncoding: "json",
     useBytesForBinaryResponse: false,
-    respectForwardCompatibleEnums: false
+    respectForwardCompatibleEnums: false,
+    additionalPropertiesDefaultsTo: false
 };
 
 export function getParseOptions({
@@ -138,6 +144,10 @@ export function getParseOptions({
         respectForwardCompatibleEnums:
             overrides?.respectForwardCompatibleEnums ??
             options?.respectForwardCompatibleEnums ??
-            DEFAULT_PARSE_OPENAPI_SETTINGS.respectForwardCompatibleEnums
+            DEFAULT_PARSE_OPENAPI_SETTINGS.respectForwardCompatibleEnums,
+        additionalPropertiesDefaultsTo:
+            overrides?.additionalPropertiesDefaultsTo ??
+            options?.additionalPropertiesDefaultsTo ??
+            DEFAULT_PARSE_OPENAPI_SETTINGS.additionalPropertiesDefaultsTo
     };
 }

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertAdditionalProperties.ts

@@ -11,6 +11,7 @@ import {
     Source
 } from "@fern-api/openapi-ir";
 
+import { ParseOpenAPIOptions } from "../options";
 import { SchemaParserContext } from "./SchemaParserContext";
 import { convertSchema } from "./convertSchemas";
 import { isReferenceObject } from "./utils/isReferenceObject";
@@ -35,7 +36,7 @@ export function convertAdditionalProperties({
     generatedName: string;
     title: string | undefined;
     breadcrumbs: string[];
-    additionalProperties: boolean | OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject;
+    additionalProperties: undefined | boolean | OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject;
     description: string | undefined;
     availability: Availability | undefined;
     wrapAsNullable: boolean;
@@ -46,7 +47,11 @@ export function convertAdditionalProperties({
     source: Source;
     namespace: string | undefined;
 }): SchemaWithExample {
-    if (typeof additionalProperties === "boolean" || isAdditionalPropertiesAny(additionalProperties)) {
+    if (additionalProperties === undefined) {
+        additionalProperties = context.options.additionalPropertiesDefaultsTo;
+    }
+
+    if (typeof additionalProperties === "boolean" || isAdditionalPropertiesAny(additionalProperties, context.options)) {
         return wrapMap({
             nameOverride,
             generatedName,
@@ -222,10 +227,11 @@ export function wrapMap({
 }
 
 export function isAdditionalPropertiesAny(
-    additionalProperties: boolean | OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject | undefined
+    additionalProperties: boolean | OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject | undefined,
+    options: ParseOpenAPIOptions
 ): boolean {
     if (additionalProperties == null) {
-        return false;
+        return options.additionalPropertiesDefaultsTo;
     }
     if (typeof additionalProperties === "boolean") {
         return additionalProperties;

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/convertObject.ts

@@ -260,7 +260,8 @@ export function convertObject({
         fullExamples,
         additionalProperties,
         availability,
-        source
+        source,
+        context
     });
 }
 
@@ -277,7 +278,8 @@ export function wrapObject({
     fullExamples,
     additionalProperties,
     availability,
-    source
+    source,
+    context
 }: {
     nameOverride: string | undefined;
     generatedName: string;
@@ -292,6 +294,7 @@ export function wrapObject({
     additionalProperties: boolean | OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject | undefined;
     availability: Availability | undefined;
     source: Source;
+    context: SchemaParserContext;
 }): SchemaWithExample {
     if (wrapAsNullable) {
         return SchemaWithExample.nullable({
@@ -308,7 +311,7 @@ export function wrapObject({
                 allOfPropertyConflicts,
                 groupName,
                 fullExamples,
-                additionalProperties: isAdditionalPropertiesAny(additionalProperties),
+                additionalProperties: isAdditionalPropertiesAny(additionalProperties, context.options),
                 availability: undefined,
                 source,
                 inline: undefined
@@ -329,7 +332,7 @@ export function wrapObject({
         allOfPropertyConflicts,
         groupName,
         fullExamples,
-        additionalProperties: isAdditionalPropertiesAny(additionalProperties),
+        additionalProperties: isAdditionalPropertiesAny(additionalProperties, context.options),
         availability,
         source,
         inline: undefined