Fixed swapped schema references in nodes info API buffer fields

[hye-on]

Description

Fixed incorrectly referenced schemas in nodes info API buffer fields by swapping the schema types between total_indexing_buffer and total_indexing_buffer_in_bytes .

Issues Resolved

Related to opensearch-project/OpenSearch#16910

Related PR

opensearch-project/OpenSearch#17070

Comments

This change will be effective from version 3.0.0 onwards

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

Changes Analysis

Commit SHA: d6b2b4e
Comparing To SHA: 439bf38

API Changes

Summary

└─┬Components
  └─┬nodes.info___NodeInfo
    ├─┬total_indexing_buffer_in_bytes
    │ └──[🔀] $ref (58382:11)❌ 
    └─┬total_indexing_buffer
      └──[🔀] $ref (58375:11)❌ 

Document Element	Total Changes	Breaking Changes
components	2	2

• ❌ BREAKING Changes: 2 out of 2
• Modifications: 2
• Breaking Modifications: 2

Report

The full API changes report is available at: https://github.com/opensearch-project/opensearch-api-specification/actions/runs/14095554681/artifacts/2827865851

API Coverage

	Before	After	Δ
Covered (%)	663 (64.94 %)	663 (64.94 %)	0 (0 %)
Uncovered (%)	358 (35.06 %)	358 (35.06 %)	0 (0 %)
Unknown	49	49	0

[dblock]

@Xtansia I read the related issue, this is correct right?

[dblock]

Actually we now have a failing test. The spec needs to work correctly for all versions, how do we fix this?

[hye-on]

Actually we now have a failing test. The spec needs to work correctly for all versions, how do we fix this?

@dblock I noticed that PR opensearch-project/OpenSearch#17070 will implement changes from OpenSearch 3.0.0. Can the api-specification repository define different specifications per version? Or should I wait until OpenSearch 3.0.0 is released to submit this PR?

I've reviewed the failing test files and related files (tests/default/nodes/nodes.yaml, tests/default/nodes/usage.yaml, json_schemas/test_story.schema.yaml, and others) but couldn't identify where to make changes. (Does the test payload response come from OpenSearch itself?) If I've missed any files that should be reviewed, I would greatly appreciate your guidance.

Thank you for taking the time to review this and for your help! :)

[dblock]

@hye-on In general we would do this:

1. Annotate the current schema for both fields with x-version-removed: 3.0.
2. Add the new schema with x-version-added: 3.0.

See https://github.com/opensearch-project/opensearch-api-specification/blob/main/DEVELOPER_GUIDE.md#openapi-extensions for field details.

Since the tools don't allow the same field name twice, I think we need to do something like this:

        total_indexing_buffer_in_bytes:
          oneOf:
            - $ref: '_common.yaml#/components/schemas/HumanReadableByteCount'
              x-version-removed: 3.0
            - $ref: '_common.yaml#/components/schemas/ByteCount'
              x-version-added: 3.0

You can run the merge (see https://github.com/opensearch-project/opensearch-api-specification/blob/main/DEVELOPER_GUIDE.md#spec-merger) with an option to target 3.0 and it should remove the oneOf that's not matching.

If that doesn't work, then let's do the above minus the x-version options with a comment.

[github-actions]

Spec Test Coverage Analysis

Total	Tested
594	593 (99.83 %)

[hye-on]

@dblock
Thank you for your kind guidance.
When I added the x-version-removed and x-version-added tags, the 3.0 version test failed.

As you guided, after removing the tags, the 3.0 test is now working.
Thank you.

I notice that the Check Links is failing (502 Network error: Bad Gateway).
If there's anything I need to fix, please let me know.

Thank you again for taking the time to help me ! :)

[dblock]

@hye-on you have to update the SHA to OpenSearch 3.0 to a newer one with opensearch-project/OpenSearch#17070 merged in https://github.com/opensearch-project/opensearch-api-specification/blob/main/.github/workflows/test-spec.yml#L65.

It's not always trivial to find a complete distribution of OpenSearch 3.0 that has all the plugins, so other tests may fail, but worth a try on 1-2 newer revisions available in DockerHub. Otherwise add the x-version- headers and we can keep this open until we find one.