[I] [Doc] mention the option of testing the schema before uploading it [pulsar]

["jak78 (via GitHub)" <gi...@apache.org>]

jak78 opened a new issue, #21561:
URL: https://github.com/apache/pulsar/issues/21561

   ### Search before asking
   
   - [X] I searched in the [issues](https://github.com/apache/pulsar/issues) and found nothing similar.
   
   
   ### What issue do you find in Pulsar docs?
   
   Per the following discussion: https://github.com/apache/pulsar/discussions/21560
   
   Uploading a valid schema can be challenging. The upload API does not provide much feedback when you upload an invalid schema. That does not help in figuring out why the schema is invalid.
   
   However, an endpoint exists, and it does precisely that.
   
   But this option is not mentioned on the primary doc that most developers read: https://pulsar.apache.org/docs/next/admin-api-schemas/ 
   
   Developers might need some time to locate it, if they manage to find it at all.
   
   ### What is your suggestion?
   
   To improve developer experience, I would suggest adding a `test a schema` section on the following page: https://pulsar.apache.org/docs/next/admin-api-schemas/
   I would recommend adding it just before the `upload a schema section`.
   
   
   ### Any reference?
   
   Discussion: https://github.com/apache/pulsar/discussions/21560
   Endpoint spec: https://pulsar.apache.org/admin-rest-api/?version=3.1.1#operation/SchemasResource_testCompatibility
   
   ### Are you willing to submit a PR?
   
   - [X] I'm willing to submit a PR!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [I] [Doc] mention the option of testing the schema before uploading it [pulsar]

["jak78 (via GitHub)" <gi...@apache.org>]

jak78 commented on issue #21561:
URL: https://github.com/apache/pulsar/issues/21561#issuecomment-1806241559

   Update: the `compatibility` endpoint is finally not designed to validate schemas because:
   - this is not the initial intent of this endpoint
   - it only works when there is an existing schema associated with the topic
   
   Now, I don't think my suggestion is the best one to solve the problem.
   
   I'm going to submit a PR to clarify that the format has to be an [AVRO Schema Declaration](https://avro.apache.org/docs/1.11.1/specification/) (even when you don't use Avro) and mention the link to the Avro spec: https://avro.apache.org/docs/1.11.1/specification/
   
   Then, I would suggest either:
   - updating the `upload` endpoint implementation to provide an explicit error when the schema is invalid
   - or: adding a new endpoint. Its purpose would be to validate a schema and provide a clear error message when the schema is invalid


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [I] [Doc] mention the option of testing the schema before uploading it [pulsar]

["jak78 (via GitHub)" <gi...@apache.org>]

jak78 closed issue #21561: [Doc] mention the option of testing the schema before uploading it
URL: https://github.com/apache/pulsar/issues/21561


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org