OpenAPI normalization and preservation

CodepotG provides a normalized contract while preserving original OpenAPI information.

Every major object follows three layers:

Preservation rules

Root raw document

Use api.raw only as a forward-compatibility escape hatch. Prefer normalized values whenever CodepotG understands the field.

Object raw values

Normalized objects also expose local raw source:

Extensions

Unknown extension keys remain available under extensions with original names. Known x-codegen metadata is normalized first.

References

Reference normalization preserves:

Circular references remain references rather than recursively expanding the graph.

Presence-aware values

Values such as defaults, consts, examples, nullable settings, UI settings, cache settings, security overrides, and entity behavior can be absent or explicitly null.

Presence-aware values expose:

OpenAPI root

The normalized root preserves:

Components

All reusable component registries remain addressable:

JSON Schema

CodepotG preserves known identity, annotation, validation, array, object, composition, condition, and reference keywords from OpenAPI 3.0 and 3.1.

Important groups include:

Version compatibility

OpenAPI 3.0 and 3.1 represent nullability, exclusive bounds, schema dialects, and JSON Schema support differently. CodepotG records:

Templates should render normalized meaning unless the target specifically needs source-version behavior.

Diagnostics

A value can be unsupported and still preserved. Silent loss is the unacceptable condition.

The intended invariant is:

Template guidance

Use values in this order:

1. normalized property;
2. normalized derived view;
3. extension;
4. local raw object;
5. root raw document.

Document any template dependency on raw-only values so it can migrate when a normalized field becomes available.