Comprehensive Documentation of Supported Input Formats

[koxudaxi]

Goal

To provide clear and comprehensive documentation detailing the support status for various input formats like JsonSchema and OpenAPI, including different drafts like Draft 7 and Draft 2019-09, to help users understand the extent to which they can utilize datamodel-code-generator with different specifications.

Background

The current documentation needs more detailed information on the support status of various input formats. Users may need help understanding what aspects of JsonSchema or OpenAPI are supported, especially concerning different drafts. This lack of clarity could hinder the utilization of datamodel-code-generator to its full extent.

Suggested Documentation Structure:

Supported Input Formats:

List of all supported input formats with a brief description.

JsonSchema:

Support status for Draft 7, Draft 2019-09, etc.
Any known limitations or workarounds.

OpenAPI:

Support status for versions 3.0, 3.1, etc.
Any known limitations or workarounds.

Related Issues

#1578

[9ao9ai9ar]

Please also document the support levels of the YAML parser that datamodel-code-generator uses (currently PyYAML 6.0.1). Per the OpenAPI Specification v3.1.0 (and v3.0.x) recommendation:

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:

• Tags MUST be limited to those allowed by the JSON Schema ruleset.
• Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

PyYAML does not fully support YAML 1.1 or 1.2, but it does at least support merge keys out of a number of YAML 1.1 extensions. The Python YAML parsers that claim to support YAML 1.2 include ruamel.yaml and yamlcore.

For the data type formats, the OpenAPI Initiative Formats Registry can serve as a starting point. For example, uri is mapped to AnyUrl, and commonmark is not a recognized format in datamodel-code-generator.

Reference documentation

• datamodel-code-generator: supported data types (initial work started on this issue)
• python-pydantic-v1 generator: feature set
• Readme: OpenAPI Compatibility Chart and OpenAPI Extensions