ValueError: dictionary update sequence element #0 has length 1; 2 is required

[stativ]

When allOf refers to schema that is not an object but a string, sphinx-build fails when generating examples with a following error

      File "/home/stativ/development/workdir/astra-open-api/.venv/lib/python3.13/site-packages/sphinxcontrib/openapi/schema_utils.py", line 67, in example_from_schema
        example.update(example_from_schema(sub_schema))
        ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ValueError: dictionary update sequence element #0 has length 1; 2 is required

Minimal Example

test.yaml

openapi: 3.0.3
info:
  version: 1.0.0
  title: Bug example
paths:
  /test:
    get:
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                title: SomeTitle
                type: object
                properties:
                  timestamp:
                    allOf:
                      - $ref: '#/components/schemas/Timestamp'
components:
  schemas:
    Timestamp:
      type: string
      example: 2022-09-12 13:09:16:18

index.rst

.. openapi:: test.yaml
   :generate-examples-from-schemas:

SW Versions

• sphinx-openapi commit e2c4473
• sphinx 8.2.3

[dstrodtman]

Confirming this on 0.9.0 with a second real-world spec, and adding a detail that may help whoever picks it up: the failure isn't limited to the old renderer's :examples:. It also blocks :generate-examples-from-schemas: on the httpdomain renderer, which is the only way to get examples out of that renderer today given #165.

Reproduced on Ray's Jobs API spec (ray-project/ray, doc/source/cluster/running-applications/job-submission/openapi.yml). Same traceback, same line:

File ".../sphinxcontrib/openapi/schema_utils.py", line 67, in example_from_schema
    example.update(example_from_schema(sub_schema))
ValueError: dictionary update sequence element #0 has length 1; 2 is required

The trigger in that spec is the pattern you identified, and it shows up twice, both times from the common "enum in a separate component, referenced through allOf so a sibling description can be attached" idiom:

JobDetails:
  type: object
  properties:
    type:
      description: The type of job.
      allOf:
        - $ref: '#/components/schemas/JobType'
    status:
      description: The status of the job.
      allOf:
        - $ref: '#/components/schemas/JobStatus'

JobType:
  type: string          # <- not an object
  enum: [SUBMISSION, DRIVER]
JobStatus:
  type: string          # <- not an object
  enum: [PENDING, RUNNING, STOPPED, SUCCEEDED, FAILED]

That idiom is what code generators emit for a documented enum property, so this is likely to be common in generated specs rather than a corner case. Notably driver_info in the same schema uses allOf toward an actual object and is fine, which isolates it to the non-object target rather than to allOf itself.

Without examples enabled the same spec renders cleanly with zero warnings under sphinx-build -W, so the crash is specific to the example-generation path.

Reading example_from_schema, the allOf branch assumes every subschema resolves to a mapping it can merge into a dict. When a subschema is a scalar it returns a scalar (here the first enum value), and dict.update on a string raises. A fix presumably needs to decide what merging a scalar into an allOf composition even means — for a type: string target the composed example arguably just is that scalar, so returning it rather than merging would be one reading.

Related: #172 covers the downstream half of scalar example handling on the old renderer, where a schema-derived string example is emitted unencoded into an application/json body. Same underlying question of how a scalar-derived example should be represented.

Environment

• sphinxcontrib-openapi 0.9.0
• Sphinx 8.2.3
• Python 3.12.13