Feat/@ai-sdk/google property ordering

[NikitaHerndlhofer]

Background

Google's Generative AI API supports a propertyOrdering extension that allows developers to control the order of properties in structured JSON responses. This feature ensures consistent property ordering in generated objects, which is important for applications that require predictable output formats or when integrating with systems that depend on specific property sequences (for example CoT generation).

Summary

This PR implements comprehensive support for Google's propertyOrdering feature in the AI SDK using a nested object configuration approach. The implementation provides fine-grained control over property ordering at all nesting levels.

Key Features:

• Nested Property Ordering Configuration: Uses recursive object notation where keys represent property names in desired order, and values are either null for leaf properties or nested configurations
• Multi-level Support: Handles deeply nested objects with property ordering at each level
• Type Safety: Full TypeScript support with exported types and proper type inference
• Comprehensive Testing: 25 test cases covering basic usage, deep nesting, partial configurations, and edge cases
• Framework Integration: Works seamlessly with Zod schemas when using generateObject() and streamObject()
• Separation of Concerns: Property ordering configuration is separate from schema definition

Verification

I packaged the @ai-sdk/google package, installed it into a separate project and made several test runs with (and without) different configurations of the propertyOrdering parameter using streamObject() and logging the partialObjectStream into the console. The properties appeared in the specified order and appeared in another order when the propertyOrdering was not specified.
I also used a temperature of 0 and a fixed seed for reproducible results, while leaving everything else (except the propertyOrdering) in place.
I tried different nesting levels, up to 5.

It is easy to test using code like this:

const schema = z.object({
  tagFirst: z.string(),
  tag2: z.object({
    childTagFirst: z.string(),
    childTag1: z.object({
      subChildTagFirst: z.string(),
      subchildTagRandomPosition: z.string(),
      subChildTag1: z.string(),
    }),
    childTag2: z.string(),
    childTagSecond: z.string(),
  }),
  tag3: z.string(),
  tagLast: z.string(),
  tag1: z.string(),
});

const prompt = `
You are a helpful assistant that generates tags for a post.
generate tags!
`;

const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_AI_API_KEY!,
});

const result = streamObject({
  model: google("gemini-2.0-flash-001", {
    propertyOrdering: {
      tagFirst: null,
      tagLast: null,
      tag3: null,
      tag1: null,

      tag2: {
        childTagFirst: null,
        childTag2: null,
        childTagSecond: null,
        childTag1: {
          subchildTagRandomPosition: null,
          subChildTag1: null,
          subChildTagFirst: null,
        },
      },
    },
  }),
  temperature: 0,
  seed: 42,
  schema,
  prompt,
});

result.partialObjectStream.pipeTo(
  new WritableStream({
    write(chunk) {
      console.log(chunk);
    },
  })
);

The output will be following:

{
  tagFirst: 'travel',
  tagLast: 'adventure',
  tag3: 'photography',
  tag1: 'nature',
  tag2: {
    childTagFirst: 'mountains',
    childTag2: 'hiking',
    childTagSecond: 'outdoors',
    childTag1: {
      subchildTagRandomPosition: 'landscape',
      subChildTag1: 'scenery',
      subChildTagFirst: 'trails'
    }
  }
}

Tasks

• Tests have been added / updated (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• Formatting issues have been fixed (run pnpm prettier-fix in the project root)

Related Issues

Fixes #5879

[NikitaHerndlhofer]

@nicoalbanese Hey!
Any chance someone can have a look at this PR ASAP?
I need this feature implemented :)