add property ordering (#1029)

* add property ordering

* lint

Author: philschmid

examples/Pdf_structured_outputs_on_invoices_and_forms.ipynb

@@ -414,6 +414,72 @@
         "* Learn more about prompting with [media files](https://ai.google.dev/gemini-api/docs/file-prompting-strategies) in the docs, including the supported formats and maximum length.\n",
         "* Learn more about [Structured Outputs](https://ai.google.dev/gemini-api/docs/structured-output?lang=python) in the docs.\n"
       ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "55c03b7e87ba"
+      },
+      "source": [
+        "## Property ordering with Gemini 2.0\n",
+        "\n",
+        "**Important:** Gemini 2.0 models require explicit ordering of keys in structured output schemas. When working with Gemini 2.0, you must define the desired property ordering as a list within the `propertyOrdering` field as part of your schema configuration.\n",
+        "\n",
+        "This ensures consistent and predictable ordering of properties in the JSON response, which is particularly important when the output property order matters for downstream processing."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "82bf6f49188e"
+      },
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "{\n",
+            "  \"invoice_number\": \"12345\",\n",
+            "  \"date\": \"2024-01-15\",\n",
+            "  \"vendor\": \"Acme Corp\",\n",
+            "  \"total_amount\": 1250.00\n",
+            "}\n"
+          ]
+        }
+      ],
+      "source": [
+        "# Example: Specifying property ordering for Gemini 2.0\n",
+        "from google import genai\n",
+        "from google.genai import types\n",
+        "\n",
+        "# Define a schema with explicit property ordering\n",
+        "invoice_schema = types.Schema(\n",
+        "    type=types.Type.OBJECT,\n",
+        "    properties={\n",
+        "        \"invoice_number\": types.Schema(type=types.Type.STRING),\n",
+        "        \"date\": types.Schema(type=types.Type.STRING),\n",
+        "        \"vendor\": types.Schema(type=types.Type.STRING),\n",
+        "        \"total_amount\": types.Schema(type=types.Type.NUMBER),\n",
+        "    },\n",
+        "    # REQUIRED for Gemini 2.0: Specify the exact order of properties, not Gemini 2.5 or newer\n",
+        "    property_ordering=[\"invoice_number\", \"date\", \"vendor\", \"total_amount\"],\n",
+        ")\n",
+        "\n",
+        "# Use the schema with generateContent\n",
+        "client = genai.Client()\n",
+        "\n",
+        "response = client.models.generate_content(\n",
+        "    model=\"gemini-2.0-flash\",\n",
+        "    contents=\"Extract invoice details: Invoice #12345 dated 2024-01-15 from Acme Corp for $1,250.00\",\n",
+        "    config=types.GenerateContentConfig(\n",
+        "        response_mime_type=\"application/json\",\n",
+        "        response_schema=invoice_schema,\n",
+        "    ),\n",
+        ")\n",
+        "\n",
+        "print(response.text)"
+      ]
     }
   ],
   "metadata": {