fix(cli): fern definition respects extra-properties when validating e…

…xamples (#5520)

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

@@ -0,0 +1,41 @@
+## 0.46.18
+**`(fix):`** If an object or request is annotated with `extra-properties: true` then the user can provide an example that includes
+extra properties that are no longer in the schema. 
+
+For example, check out this fern definition 
+
+```yml service.yml
+types:
+  Item: 
+    extra-properties: true
+    properties:
+      id: string
+
+
+service:
+  auth: false
+  base-path: ""
+  endpoints:
+    create:
+      method: POST
+      path: /item
+      request:
+        name: CreateItemRequest
+        body:
+          extra-properties: true
+          properties:
+            id: string
+      response:
+        type: Item
+      examples:
+        - name: "Item"
+          request:
+            id: "123"
+            foo: "bar" # extra property in the example
+          response:
+            body:
+              id: "123"
+              foo: "bar" # extra property in the example
+```
+
+

packages/cli/cli/versions.yml

@@ -1,3 +1,47 @@
+- changelogEntry:
+    - summary: |
+        If an object or request is annotated with `extra-properties: true` then the user can provide an example that includes
+        extra properties that are no longer in the schema. 
+
+        For example, check out this fern definition 
+        
+        ```yml service.yml
+        types:
+          Item: 
+            extra-properties: true
+            properties:
+              id: string
+
+
+        service:
+          auth: false
+          base-path: ""
+          endpoints:
+            create:
+              method: POST
+              path: /item
+              request:
+                name: CreateItemRequest
+                body:
+                  extra-properties: true
+                  properties:
+                    id: string
+              response:
+                type: Item
+              examples:
+                - name: "Item"
+                  request:
+                    id: "123"
+                    foo: "bar" # extra property in the example
+                  response:
+                    body:
+                      id: "123"
+                      foo: "bar" # extra property in the example
+        ```
+      type: fix
+  irVersion: 53
+  version: 0.46.18
+
 - changelogEntry:
     - summary: |
         Support parsing string values for boolean defaults in OpenAPI schemas.

packages/cli/fern-definition/validator/src/rules/valid-example-endpoint-call/__test__/fixtures/extra-properties/definition/api.yml

@@ -0,0 +1,3 @@
+name: extra-properties
+auth: bearer
+default-environment: Production

packages/cli/fern-definition/validator/src/rules/valid-example-endpoint-call/__test__/fixtures/extra-properties/definition/extra-properties.yml

@@ -0,0 +1,32 @@
+types:
+  Item: 
+    extra-properties: true
+    properties:
+      id: string
+
+
+service:
+  auth: false
+  base-path: ""
+  endpoints:
+    create:
+      method: POST
+      path: /item
+      request:
+        name: CreateItemRequest
+        body:
+          extra-properties: true
+          properties:
+            id: string
+      response:
+        type: Item
+      examples:
+        - name: "Item"
+          request:
+            id: "123"
+            foo: "bar"
+          response:
+            body:
+              id: "123"
+              foo: "bar"
+

packages/cli/fern-definition/validator/src/rules/valid-example-endpoint-call/__test__/fixtures/extra-properties/generators.yml

@@ -0,0 +1 @@
+{}

packages/cli/fern-definition/validator/src/rules/valid-example-endpoint-call/__test__/valid-example-endpoint-call.test.ts

@@ -525,4 +525,19 @@ describe("valid-example-endpoint-call", () => {
 
         expect(violations).toEqual(expectedViolations);
     });
+
+    it("extra-properties", async () => {
+        const violations = await getViolationsForRule({
+            rule: ValidExampleEndpointCallRule,
+            absolutePathToWorkspace: join(
+                AbsoluteFilePath.of(__dirname),
+                RelativeFilePath.of("fixtures"),
+                RelativeFilePath.of("extra-properties")
+            )
+        });
+
+        const expectedViolations: ValidationViolation[] = [];
+
+        expect(violations).toEqual(expectedViolations);
+    });
 });

packages/cli/fern-definition/validator/src/rules/valid-example-endpoint-call/validateRequest.ts

@@ -1,6 +1,6 @@
-import { ExampleResolver, ExampleValidators, FernFileContext, TypeResolver } from "@fern-api/ir-generator";
 import { FernWorkspace } from "@fern-api/api-workspace-commons";
 import { isInlineRequestBody, RawSchemas } from "@fern-api/fern-definition-schema";
+import { ExampleResolver, ExampleValidators, FernFileContext, TypeResolver } from "@fern-api/ir-generator";
 import { RuleViolation } from "../../Rule";
 
 export function validateRequest({
@@ -35,6 +35,7 @@ export function validateRequest({
                 typeName: undefined,
                 typeNameForBreadcrumb: "<Inlined Request>",
                 rawObject: {
+                    "extra-properties": body["extra-properties"],
                     extends: body.extends,
                     properties: body.properties ?? {}
                 },

packages/cli/generation/ir-generator/src/examples/validateObjectExample.ts

@@ -1,5 +1,5 @@
-import { isPlainObject } from "@fern-api/core-utils";
 import { FernWorkspace, getDefinitionFile } from "@fern-api/api-workspace-commons";
+import { isPlainObject } from "@fern-api/core-utils";
 import { RawSchemas } from "@fern-api/fern-definition-schema";
 import { keyBy } from "lodash-es";
 import { constructFernFileContext, FernFileContext } from "../FernFileContext";
@@ -80,7 +80,9 @@ export function validateObjectExample({
     // check properties on example
     for (const [exampleKey, exampleValue] of Object.entries(example)) {
         const propertyWithPath = allPropertiesByWireKey[exampleKey];
-        if (propertyWithPath == null) {
+        if (rawObject["extra-properties"]) {
+            continue;
+        } else if (propertyWithPath == null) {
             violations.push({
                 message: `Unexpected property "${exampleKey}"`
             });