Server Response Does Not Match OpenAPI Schema for ItemsPageObject

[bncszb]

I tried to create a python client using OpenApi Generator, but I ran into some discrepancies.

The server responses for the ItemsPageObject schema do not conform to the declared OpenAPI specification. According to the OpenAPI documentation at https://snowstorm.snomedtools.org/snowstorm/snomed-ct/v3/api-docs/snowstorm, the items and searchAfterArray properties are defined as arrays of objects:

{
"ItemsPageObject": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "limit": {
            "type": "integer",
            "format": "int64"
          },
          "offset": {
            "type": "integer",
            "format": "int64"
          },
          "searchAfter": {
            "type": "string"
          },
          "searchAfterArray": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
}

However, the actual server responses ma contain arrays of primitive values (e.g., strings or numbers) instead of objects. This discrepancy causes validation and deserialization errors when using generated clients (such as those from OpenAPI Generator for Python), which expect a list of dictionaries but receive a list of primitives.

Expected Behavior

The server should return data that matches the OpenAPI schema, specifically:

• items and searchAfterArray should be arrays of objects (JSON objects/dictionaries).

Example:

{
  "items": [ { "id": 1 }, { "id": 2 } ],
  "searchAfterArray": [ { "token": "abc" } ]
}

Actual Behavior

The server is returning arrays of primitive values instead of objects.

Example:

{
  "items": [ "foo", "bar", "baz" ],
  "searchAfterArray": [ 1, 2, 3 ]
}

Impact

• Generated clients fail with validation or deserialization errors.
• Automated tooling and type checking break due to the schema mismatch.
• Consumers of the API must implement workarounds or bypass validation, reducing reliability and maintainability.

Steps to Reproduce

1. Use the OpenAPI documentation to generate a Python client.

    docker run --rm -v "${PWD}:/local/out/python" openapitools/openapi-generator-cli generate \
        -i https://snowstorm.snomedtools.org/snowstorm/snomed-ct \
        -g python \
        -o /local/out/python \
        --package-name {{PACKAGE_NAME}} \
        --artifact-version {{PACKAGE_VERSION}} \
        --git-user-id {{GIT_USER_NAME}} \
        --git-repo-id {{GIT_REPO_ID}} \
        --library urllib3 \
        --additional-properties=packageUrl=https://github.com/{{GIT_USER_NAME}}/{{GIT_REPO_ID}},packageVersion={{PACKAGE_VERSION}},projectName={{PACKAGE_NAME}},packageCompany="{{AUTHOR_NAME}}",authorName="{{AUTHOR_NAME}}",authorEmail="{{AUTHOR_EMAIL}}",packageDescription="Python client for SNOMED CT Snowstorm API"

2. Call an endpoint returning an ItemsPageObject.

from snowstorm_client import ApiClient, ConceptsApi, Configuration

config = Configuration(
    host="https://snowstorm.snomedtools.org/snowstorm/snomed-ct",
)

api_client = ApiClient(config)

api_client.user_agent = "urllib3/2.0.4"

ecl = """< 64572001 |Disease (disorder)| : {
  116676008 |Associated morphology| = << 87642003 |Dislocation|,
  363698007 |Finding site| = << 85537004 |Glenohumeral joint structure|
}"""

concepts = client.find_concepts(
    branch="MAIN",
    active_filter=True,
    term_active=True,
    language=["en"],
    include_leaf_flag=False,
    ecl=ecl,
    limit=1,
    return_id_only=False,
)

print(concepts)

Suggested Solutions

• Update the server implementation to ensure that items and searchAfterArray always return arrays of objects, as specified.
• OR: Update the OpenAPI schema to reflect the actual data structure (e.g., set items: {} to allow any type).
• OR: Add a note in the documentation about the discrepancy and recommended client workarounds.

Thank you for your attention to this issue! Please let me know if more information is needed.

[kaicode]

We could probably remove searchAfterArray from the response because it's not actually needed for anything. Only the searchAfter string is needed for pagination.

[bncszb]

Yeah that could be a solution!

My only concern is that it would only solve this specific issue. But for example for the GET /{branch}/concepts request if the returnIdOnly=True is set, then it the items would be integers, which also wouldn't be acceptable. Maybe the object-s could be changed to any?

[kaicode]

Do you need to regenerate the client regularly, or are you able to generate it and then tweak it to fit?
We are not really early enough in the creation of the Snowstorm API to make lots of changes.
At the moment it's very stable for our current main use cases of supporting the Browser and Authoring Platform.

We do not actually maintain the Snowstorm api-docs JSON. It's generated from the Spring Boot Controllers and their annotations. I don't think we have control over the reported data type of nested objects unfortunately.