Here's a clear overview of the absolutely hilariously bad documented OpenAI schema expectations. Rules and rules and rules and ...

openai-schema-rules.md

Rules for Transforming a JSON Schema into an OpenAI Schema

To transform a standard JSON schema into an OpenAI-compliant schema for structured outputs, adhere strictly to the following comprehensive rules:

General Structure and Syntax

1. Top-Level Structure:

   • The schema must be a JSON object with clearly defined type, properties, and required attributes.
   • Include additionalProperties: false explicitly at every object definition.

2. Required Attributes:

   • All fields and parameters within objects must explicitly appear in the required array. No optional parameters without explicit handling.

Supported Types

• Only the following JSON Schema types are permitted:

  • string
  • number
  • boolean
  • integer
  • object
  • array
  • enum
  • anyOf (with restrictions)

• The root object cannot be of type anyOf.

Field Definitions and Ordering

• Define properties explicitly under properties with exact types and constraints.
• The order of keys in the resulting structured output matches exactly the order defined in the schema.

Optional Fields

• To emulate optional fields, use union types with null explicitly, e.g., "type": ["string", "null"].

Enumerations

• Enumerations must be explicitly defined under the enum key within the property definition.

Array Constraints

• Define arrays explicitly using items with clearly specified item types.
• Unsupported array constraints (unevaluatedItems, contains, minContains, maxContains, minItems, maxItems, uniqueItems) must be omitted.

Object Constraints

• additionalProperties must always be set to false.
• Unsupported object constraints (patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties) must be omitted.

String Constraints

• Unsupported constraints (minlength, maxLength, pattern, format) must be omitted.

Number Constraints

• Unsupported constraints (minimum, maximum, multipleOf) must be omitted.

Nesting and Complexity Limits

• Limit nesting depth to a maximum of five levels.
• Limit total object properties to a maximum of 100 across all nesting levels.

Definitions and References

• JSON Schema $defs and references ($ref) are permitted.
• Explicitly reference nested definitions clearly and accurately.

Recursive Schemas

• Recursion is allowed through:
  • Root recursion ($ref: "#")
  • Explicit recursion via defined paths (e.g., $ref: "#/$defs/linked_list_node").

anyOf Usage

• Nested schemas using anyOf must strictly adhere to the supported subset of JSON schema types.
• Each schema inside anyOf must be fully compliant with these rules.

Schema Metadata

• Clearly define schema metadata including:
  • name: Short descriptive identifier.
  • description: Clear and concise description of schema purpose.
  • strict: true: Mandatory to ensure strict adherence.

Schema Validation

• Ensure each defined schema element strictly adheres to the supported subset of JSON Schema features, omitting any unsupported keywords or constraints explicitly listed above.