Documentation

Sum types translate to union types in OpenApi documents via disjointEitherCodec (or via eitherCodec if the encoded JSON is not necessarily disjoint). In this case we ensure that the encodings of MetadataV1, MetadataV2, and MetadataV3 are disjoint by using versionField in the codec for each variant which injects a field into the JSON representation that requires a specific number to parse successfully. (MetadataV1 is the only variant where the version field is optional.)

A codec that represents more than two variants of different types requires nesting disjointEitherCodec. Thankfully in the generated OpenApi documentation these three variants are flattened into a single oneOf list of allowed schemas.