Orphaned Objects in Emitted Open API Document

[mario-guerra]

Clear and concise description of the problem

Issue described by Chris Wood at Ozone API in this talk.

Description:

When emitting Open API documents using TypeSpec, some objects are orphaned without any apparent reason. These orphaned objects are not referenced anywhere in the document, leading to unnecessary clutter and potential confusion. This issue has been observed consistently, and it is unclear why these objects are being orphaned.

This problem requires additional manual steps to identify and remove the orphaned objects, often using overlays or other post-processing tools. A more streamlined approach within TypeSpec would greatly enhance the usability and cleanliness of the emitted Open API documents.

Steps to Reproduce:

1. Define multiple schemas and operations in TypeSpec.
2. Emit the Open API document.
3. Inspect the emitted Open API document for objects that are not referenced anywhere.

Expected Behavior:
TypeSpec should ensure that only referenced objects are included in the emitted Open API document, eliminating any orphaned objects.

Actual Behavior:
The emitted Open API document contains orphaned objects that are not referenced, requiring additional manual steps to remove them.

Additional Context:

• This issue has been encountered during the creation of open finance standards, where maintaining a clean and accurate Open API document is crucial.
• The use of overlays has been necessary to manually remove these orphaned objects, but this adds complexity and potential for error.
• Automating the detection and removal of orphaned objects within TypeSpec would significantly improve the workflow and reduce the need for manual intervention.

I'll follow up with Chris to ask for more details

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[wanlwanl]

Hi @mario-guerra,

Could you clarify if the Orphaned Objects you mentioned include user-defined models? If they do, we should avoid deleting them proactively, as financial technology companies use typespec to declare models. If they do not, could you provide a concrete example? The video and description do not offer specific examples for reference.

Thank you!