[Plugin Arch] Phase 4 — OpenAPI Management for Plugins

[Al-Pragliola]

Summary

Set up shared OpenAPI schemas and per-plugin spec management so that plugins can define their own API paths and entity-specific schemas while sharing common types like BaseResource, BaseResourceList, and MetadataValue.

Motivation

Every catalog plugin has entities that share a common shape: id, name, externalId, description, customProperties, and timestamps. Without a shared schema definition, each plugin would duplicate these fields, leading to drift and inconsistency. At the same time, each plugin needs autonomy over its own paths and entity-specific schemas.

Scope

• Create a shared common.yaml library at the repository root defining BaseResource, BaseResourceList, MetadataValue, and other common types
• Define a split-file structure within each plugin: openapi.yaml for paths + components.yaml for schemas
• Build a merge script that combines all plugin specs into a unified specification
• Integrate the merge step into the existing make gen pipeline

Acceptance Criteria

• common.yaml defines shared types (BaseResource, BaseResourceList, MetadataValue, etc.)
• Each plugin can define its own openapi.yaml (paths) and components.yaml (schemas) referencing common types
• Merge script produces a valid, unified OpenAPI spec from all plugin specs
• make openapi/validate passes on the merged output
• Code generation (make gen/openapi, make gen/openapi-server) works with the new structure
• make build && make test && make lint pass

Dependencies

• Phase 2 [Plugin Arch] Phase 2 — Plugin System Infrastructure #2528

References

• Parent: [Proposal] Plugin-Based Catalog Architecture and catalog-gen tool to generate new catalog types #2220