Structured Output

Use output_schema when you want output.content returned as a JSON object instead of free-form text. This is useful for returning predictable fields, extracting entities, or feeding Research API output into another typed system.

output_schema is supported with standard, deep, exhaustive, and frontier research effort. It is not supported with lite. Sending output_schema with research_effort: "lite" returns 422.

curl -X POST https://api.you.com/v1/research \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What are OpenAI structured output schema constraints?",
    "research_effort": "standard",
    "output_schema": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "verdict": {
          "type": "string",
          "enum": ["supported", "mixed", "unsupported"]
        }
      },
      "required": ["summary", "verdict"],
      "additionalProperties": false
    }
  }'

When output_schema is provided, the structured result is returned in output.content and output.content_type is object. Sources remain in output.sources. The API does not add citation fields into your schema object automatically.

{
  "output": {
    "content": {
      "summary": "The schema must be object-rooted and require all declared properties.",
      "verdict": "supported"
    },
    "content_type": "object",
    "sources": []
  }
}

Schema Rules

output_schema follows a narrow JSON Schema subset designed for reliable structured generation.

Required rules:

• The root must be an object.
• The root must not use top-level anyOf.
• Every object must define properties.
• Every object must set additionalProperties: false.
• Every property must be listed in required. To make a field optional, keep it in required and make it nullable—see Optional and Nullable Fields.
• Recursive schemas are not supported.
• A property’s type must not be a bare {"type": "null"}. Use a nullable union such as {"type": ["string", "null"]} instead.

Supported patterns include nested objects, arrays, enums, nested anyOf, and non-recursive $defs and $ref.

Unsupported keywords:

• allOf
• contains
• not
• dependentRequired
• dependentSchemas
• format
• if / then / else
• maxContains / minContains
• maxItems / minItems
• maxLength / minLength
• maxProperties / minProperties
• maximum / minimum
• multipleOf
• pattern
• patternProperties
• propertyNames
• unevaluatedItems / unevaluatedProperties
• uniqueItems

Selected limits:

If the schema is invalid, the request fails validation before model execution. The schema string budget counts property names, $defs names, enum values, and const values. It applies to schema shape only. Request-level limits such as total task spec size are enforced separately at the request layer.

A schema is rejected with 422 before any model execution if it exceeds any limit above (depth, property count, enum count, or string budget) or violates a Schema Rule. The error message names the specific limit or rule.

Optional and Nullable Fields

Every property you declare must appear in required. This is what makes structured generation reliable—the model always emits every field—and it matches OpenAI Structured Outputs.

To express a value that may be unknown or not applicable, keep the field in required but make its type nullable by adding "null". The model returns null when the value isn’t available instead of guessing.

Use the concise form (equivalent to string | null):

"gtin": { "type": ["string", "null"] }

An anyOf spelling is also valid but more verbose—prefer the concise form above:

"gtin": { "anyOf": [{ "type": "string" }, { "type": "null" }] }

Omitting a field from required produces an invalid schema—the request fails validation before execution. Nullability is the only mechanism for “may be absent.”

Response behavior

• A nullable field with no available value is returned as null.
• A non-nullable required field with no available value forces the model to emit something anyway (typically an empty string "" for strings). Required fields are never omitted from the response, and the model does not fabricate a citation-backed value to fill them. If a field can legitimately be unknown, make it nullable so you get a clean null instead of "".

Example

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "gtin": { "type": ["string", "null"] }
  },
  "required": ["name", "gtin"],
  "additionalProperties": false
}

Conditional Structure

Conditional keywords (if / then / else, dependentRequired, dependentSchemas) are not supported. To express “field Y is required only when X”—for example, price_usd is required only when in_stock is true—model the object as a discriminated anyOf union: one branch per case, with a shared field pinned to a distinct value via enum.

{
  "type": "object",
  "properties": {
    "product": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "in_stock":  { "type": "boolean", "enum": [true] },
            "name":      { "type": "string" },
            "price_usd": { "type": ["number", "null"] }
          },
          "required": ["in_stock", "name", "price_usd"],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": { "in_stock": { "type": "boolean", "enum": [false] } },
          "required": ["in_stock"],
          "additionalProperties": false
        }
      ]
    }
  },
  "required": ["product"],
  "additionalProperties": false
}

When in_stock is true, name is required—when false, only in_stock is allowed. This is the same pattern OpenAI Structured Outputs uses, so one schema works across both.

Using Source Control and Structured Output Together

source_control and output_schema can be combined in a single request. For example, you can restrict research to specific domains while requesting a structured response:

curl -X POST https://api.you.com/v1/research \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What are the FDA-approved GLP-1 receptor agonists and their indications?",
    "research_effort": "deep",
    "source_control": {
      "include_domains": ["fda.gov", "nih.gov", "pubmed.ncbi.nlm.nih.gov"],
      "freshness": "year"
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "drugs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "brand_name": { "type": "string" },
              "generic_name": { "type": "string" },
              "manufacturer": { "type": "string" },
              "approved_indications": {
                "type": "array",
                "items": { "type": "string" }
              },
              "approval_year": { "type": "string" }
            },
            "required": ["brand_name", "generic_name", "manufacturer", "approved_indications", "approval_year"],
            "additionalProperties": false
          }
        },
        "summary": { "type": "string" }
      },
      "required": ["drugs", "summary"],
      "additionalProperties": false
    }
  }'

The Finance Research API does not support output_schema. If you need structured JSON, use the Research API.

View full API reference

Next Steps