Overview

This PR implements the missing encoding, itemEncoding, and prefixEncoding fields for the OpenApiEncoding class as specified in the OpenAPI 3.2.0 specification.

Problem

The OpenApiEncoding class was missing several fields from the OpenAPI 3.2.0 specification:

• encoding: A dictionary that allows encoding objects to have their own nested encoding specifications, creating a recursive structure similar to how the OpenApiMediaType class has an encoding dictionary
• itemEncoding: Encoding object for array items
• prefixEncoding: Encoding objects for tuple-style arrays

According to the OpenAPI 3.2.0 spec, the Encoding Object should support these nested encoding configurations to handle complex data structures.

Solution

Added support for all three fields with the following changes:

1. Model: Added three new properties to OpenApiEncoding class:
   • Encoding as IDictionary<string, OpenApiEncoding>?
   • ItemEncoding as OpenApiEncoding?
   • PrefixEncoding as IList<OpenApiEncoding>?
2. Copy Constructor: Implemented deep copy logic for all new properties to ensure proper object cloning
3. Version-Aware Serialization:
   • For OpenAPI 3.2+: Serializes as native fields (encoding, itemEncoding, prefixEncoding)
   • For OpenAPI 3.1 and earlier: Serializes as extension fields (x-oai-encoding, x-oai-itemEncoding, x-oai-prefixEncoding)
4. Deserialization: Added V32 deserializer support to parse all three fields from YAML/JSON documents
5. Tests: Added comprehensive tests for both deserialization and serialization in JSON and YAML formats, including backward compatibility tests

Example Usage

contentType: application/json
encoding:
  nestedField:
    contentType: application/xml
    style: form
    explode: true
  anotherField:
    contentType: text/plain
itemEncoding:
  contentType: application/xml
  style: form
prefixEncoding:
  - contentType: text/plain
    style: simple
  - contentType: application/octet-stream

Testing

• ✅ All 1457 tests pass (398 in Readers.Tests, 1005 in Tests, 54 in Hidi.Tests)
• ✅ Added 5 new tests covering deserialization and serialization scenarios for all new fields
• ✅ Added backward compatibility test confirming v3.1 serialization uses x-oai-* extensions
• ✅ CodeQL security scan: 0 vulnerabilities
• ✅ Updated public API approval file

Breaking Changes

None. This is a backward-compatible addition that only affects OpenAPI 3.2 documents with nested encoding structures. For older versions, the new fields are automatically serialized as extensions to maintain compatibility.

Fixes #51

Fixes #51

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.