Allow developers to define ComponentApis using raw JSON schemas rather than Zod objects

[jacobsimionato]

Some developers want to define a ComponentApi (and a ComponentImplementation) based on a JSON schema that they already maintain in a format other than Zod, e.g. a plain JSON schema object, or a TS interface etc.

Currently, ComponentApi exposes a Zod object as the schema, so this isn't really possible without Zod.

We would ideally have a story for this.

Options:

1. Migrate to Zod 4 which has z.fromJSONSchema() - https://zod.dev/json-schema
2. Tell developers to use https://www.npmjs.com/package/json-schema-to-zod or similar
3. Migrate our underlying logic to use raw JSON schemas instead of Zod

[jacobsimionato]

BTW the google repo only supports Zod 3 imported in 2023, so I think we won't be able to migrate to v4 easily....

[jacobsimionato]

@ditman and @josemontespg do you have thoughts on this?

[piy-ushk]

Given the repo is still using Zod v3, upgrading to v4 only to use 'fromJSONSchema()' might be more effort and risk than it’s worth right now.

A more practical approach could be to take it step by step:-

• keep the current Zod v3 support as-is
• add optional support for raw JSON Schema objects
• detect the schema type at runtime
• continue using the existing flow for Zod schemas
• use Ajv (or something similar) for JSON Schema validation

That would help developers who already maintain JSON/OpenAPI schemas, without needing a major dependency upgrade first.

[josemontespg]

Adding support for another schema format would add surface to the public API of the library, and we would have to maintain both going forward. Before committing to this I'd like to understand the interest for supporting JSON schemas.

IMO, easiest tactical solution would be 2.

Long term, we need a declarative way to represent the schema that can be accessed at runtime. Zod solves this, and it is natural to upgrade to 4. Not just for the fromJSONSchema capabilities, but also for the performance improvements and bug fixes.