Generate Schema-Compliant JSON from Architectural Text with the Gemini API

What will you learn in this guide?

A project brief, material note, or space description often arrives as free-form text. When you need to extract fields such as room name, material, and intended use from that text, a natural-language response alone can make subsequent processing more difficult. The Gemini API’s structured output feature lets you ask the model to follow a predefined JSON Schema.

This walkthrough covers three points: defining the expected fields, describing the task and constraints in a clear prompt, and then adding the appropriate schema to the API request. The examples are tailored to architectural workflows; the prompts below do not appear verbatim in the sources—they are original examples based on the documented methods.

Requirements and scope

Google’s documentation mentions JSON Schema support in the REST API for structured outputs. For the Google GenAI SDKs, it shows Pydantic on the Python side and Zod on the JavaScript side as options for defining schemas. The source also includes examples for Java, Go, and other languages; this guide uses an easy-to-adapt JSON Schema draft rather than code.

The documentation examples note that Zod must be installed for JavaScript; however, these sources do not provide information about SDK versions, account requirements, or pricing. Before starting a project, check the relevant Gemini API documentation for the current requirements of the SDK and model you plan to use. The top of the documentation says Gemini 4 Argon is available, while the example code uses the model name gemini-3.8-flash. Don’t assume that the example model name is automatically current or suitable for every use case.

1. Define the fields to extract

Before preparing a schema, decide which data you want to extract from the text and what type each field should be. For example, the draft below is designed to extract the space name, specified material, and functional description from an interior design brief. Basic JSON Schema structures such as object, properties, string, and required are consistent with the examples shown in the source.

{
  "type": "object",
  "properties": {
    "mekan_adi": { "type": "string" },
    "malzeme": { "type": "string" },
    "islev": { "type": "string" }
  },
  "required": ["mekan_adi", "malzeme", "islev"]
}

All three fields are required here. If the source text doesn’t specify a field, explain in the prompt what should happen—for example, you could ask for the field to be left blank or marked as “not specified.” The right choice depends on how the project data will be handled; making this decision upfront when defining the schema helps teams get consistent results.

2. State the task and input clearly

A good prompt clearly describes the task, the text to work on, and the response format. Google’s prompt design guide recommends using clear, specific instructions and, where necessary, stating constraints and formatting expectations. You can adapt the example below to your own brief fields.

Aşağıdaki iç mekân proje brief’inden mekân adını, açıkça belirtilen malzemeyi ve mekânın işlevini çıkar. Yalnızca verilen metindeki bilgilere dayan. Bir bilgi metinde yoksa bunu “belirtilmemiş” olarak yaz. Yanıtı, sağlanan JSON şemasındaki alanlarla uyumlu bir JSON nesnesi olarak üret.

Brief: Zemin katta yer alan okuma alanında meşe kaplama yüzeyler ve ortak çalışma masaları bulunuyor.

This prompt provides the text as input, defines the extraction task, and specifies what to do with unknown fields. The structured output feature also ensures the expected response follows the schema. The prompt and schema should describe the same fields: don’t request new keys in the prompt that aren’t in the schema, and don’t omit requested fields from the schema.

3. Narrow the constraints to fit the project

In architectural documents, it’s important to distinguish interpretation from source information. If you’re extracting a material list, explicitly ask the model not to add products or technical specifications that aren’t in the text. For example, the prompt below focuses only on gathering written materials from a space description.

Bu mahal açıklamasında adı geçen kaplama ve yüzey malzemelerini çıkar. Yeni malzeme önerme, eş anlamlı veya marka tahmini ekleme. Sonucu yalnızca malzeme adlarından oluşan bir liste olarak ver.

Açıklama: Giriş holünde terrazzo döşeme ve boyalı alçı duvar yüzeyi kullanılacaktır.

This example requests a list, so don’t use it directly for the same task as the previous schema, which expects a JSON object. The response format depends on the need: when using structured outputs, the schema should match the result described in the prompt. Rather than reusing a single schema for different kinds of tasks, reassess each task’s fields and data types.

4. Show the format with an example response

If the requested classification or writing pattern is open to interpretation when described in natural language, adding short examples can make the format clearer. Google’s guide says that with a few-shot approach, you can show the model example inputs and the expected response format; clear and varied examples are useful.

Aşağıdaki örnekteki alanları kullanarak yeni mahal notunu sınıflandır.

Örnek not: “Mutfak tezgâhı kuvars kompozit, dolap kapakları mat lake.”
Örnek çıktı: {"mekan": "Mutfak", "malzemeler": ["kuvars kompozit", "mat lake"]}

Yeni not: “Çalışma odasında ahşap parke ve sıva üzeri boya bulunuyor.”
Yalnızca aynı alan düzeninde yanıt ver.

This example shows the output structure; you still need to define the schema that will be used in the actual API request. The source guide says you can start with a small number of examples and may need to test the number based on the use case. It also warns that too many examples can cause the model to overfit.

Common mistakes

The most common issue is specifying requirements only in the prompt without defining a schema on the API side. Google says simple JSON formats can be requested in natural language, but recommends the structured output feature for more complex JSON Schema needs. Another issue is having the schema and prompt request different fields or response formats. First clarify the fields and types, then write the prompt to match that structure.

Another mistake is expecting the model to fill in details that aren’t in the source when the text is ambiguous. Specify in the prompt what information to extract, what to leave out, and how to represent missing data. A schema helps maintain formatting consistency; it doesn’t automatically guarantee that the project source is accurate or complete. Comparing generated records with the original brief is important, especially in delivery and documentation workflows.

Use in architecture and visualization workflows

This approach can be useful for architecture firms, interior designers, and students who need to organize large numbers of project notes into the same fields. Extracting material names, space types, or functional descriptions from room descriptions provides an organized starting point for workflows that pass this data on to another tool. The sources don’t describe integration with a specific BIM, CAD, or visualization application, so connections and compatibility need to be assessed separately.

Firms should first test whether the fields are useful on a small set of texts, then check how the same schema and prompt perform across different briefs. For students, this method offers a practical way to combine extracting data from free-form text with understanding JSON structure. The sources don’t provide information about hardware, licensing, or API usage costs; verify these with the relevant service documentation before moving into production.

Next steps

Start with a single use case, such as extracting materials from a room note. Define the fields and build the schema, then try it with a prompt that gives clear instructions. Compare the results with the source text, look for recurring errors, and add examples to the prompt only when genuinely needed. If you’re using Python, consider Pydantic; if you’re using JavaScript, consider Zod for defining schemas. REST API use is also supported in the documentation.

As the project grows, document schema changes and expected fields within the team. This makes it easier to track whether the same data structure is being maintained across different tasks involving architectural briefs. The goal at the outset isn’t to automate everything, but to test a recurring text-based task using clear rules and a response format that can be checked.

Sources and license

This guide has been adapted into Turkish from Google’s “Structured outputs” and “Prompt design strategies” documentation. Both sources are licensed under CC BY 4.0.