governing-tag-hierarchy

OpenAPI tag hierarchy structures API documentation navigation by enforcing parent, summary, and kind fields for hierarchical tags, replacing flat structures with a governed taxonomy that improves developer experience.

Migrating from x-tagGroups to native OpenAPI hierarchical tags involves mapping vendor extension groupings into the 3.2.0 hierarchical tag structure with parent fields, enforcing governance rules for documentation portals and SDK grouping.

Tag classification in OpenAPI specifications defines tag types like navigation, badge, lifecycle, and audience to categorize endpoints, enforcing structured governance rules that enhance documentation portal organization and SDK grouping clarity.

Yes, you can enforce governance rules on OpenAPI tag usage for SDK generation by applying hierarchical tag structures and classification types, ensuring consistent endpoint grouping and documentation portal organization across large APIs.

You need hierarchical tags instead of flat tags in OpenAPI when managing hundreds of endpoints, where a governed parent-child taxonomy provides navigability and classification that flat structures cannot support for documentation portals.

Limitations of migrating flat OpenAPI tags to hierarchical structures include ensuring all existing endpoints map correctly to new parent-child relationships and updating documentation portals or SDK grouping logic to support the 3.2.0 hierarchical tag format.