First-class YAML support in tooling

[powerman]

Maybe it's worth to add first-class YAML support in tools - just like swagger does?

API description is often written manually, and JSON isn't the best format for this (mostly because of missing comments, missing anchors/internal $ref for reusing schema/parts of schema, and requirement to omit comma after last element of array/object).

Ability to use .yml file in playground and other tools instead of json will be really convenient.

[github-actions]

Welcome to OpenRPC! Thank you for taking the time to create an issue. Please review the guidelines

[BelfordZ]

Hey @powerman Thanks for asking a highly relevant question. I'll do my best to explain the rational in ignoring all other notations for data representation other than JSON.

The non-biblical-level arguments of JSON vs YAML (trying to avoid addressing JSON vs YAML specifically, giving as unbiased of logic for why as possible):

1. Less to support is less to support. Generally if we can get away with not building something, we try that first.
2. Since OpenRPC is specific to JSON-RPC interfaces, we have an excuse to bias ourselves towards JSON.
3. The tools we build try to have minimal interface surface area. Only having to support documents in JSON format is one way that we can reduce said surface area.
4. Since YAML is trivially converted to JSON, the user may chose how they want to do this if required.

[powerman]

I wholeheartedly agree with all of above when we talk about tools. But my question was about UI and playground (sorry if this wasn't clear).

Playground is supposed to be the place where developers write and edit API description… and it isn't convenient to do this in JSON… or at least not as convenient as in YAML (and the difference is big enough to make many people avoid using playground at all - IMO). There are a lot of reasons why it's not convenient enough, I believe they're obvious, and there is no needs to mention each of them. Also, if we write YAML and then later convert it to JSON then we lose ability to copy it to playground, play with it, modify a bit, and then copy back to source YAML file (I often used swagger's playground this way).

Another "UI" point is ability to embed and serve original API description. It's really useful to be able to append to API endpoint some predefined path like /openrpc.{json,yml} and get all information about the API. But thing is, with JSON we lose really important part of API description: comments. And while in theory fields like summary/description should be able to replace comments, in practice (with swagger) they doesn't (most swagger.yml I work with used a lot of comments, while description field wasn't used that often - I suppose this is another one UI-specific thing, probably ability to write comment at same line as commented field, or because comments just doesn't "feels" as heavy/formal as separate description field…).

[BelfordZ]

Thanks for the quick follow up. I really appreciate the time you have taken to explain how we can make playground better for more users. I'm gonna talk it over with our playground guy @shanejonas and see what he thinks.

I think that yaml inside of playground as you suggested might be a happy-middle-ground, where we dont need to explicitly take a stance on supporting yaml, but the utility is there for those who want it.

The risk that it becomes a precedent for adding yaml support to all the tools, which IMO would be an overall negative for the aforementioned reasons. Let's see what Shane has to say though.

As for the endpoint part -- have you looked at the added reserved method 'rpc.discover'? It sounds awfully similar to how you've described the `/openrpc.{json,yaml}.

Thanks again for opening the issue. Might I ask that you open a new issue and reference this one, but from the https://github.com/open-rpc/playground repo?

[powerman]

Yeah, I've seen rpc.discover, and it's fine to use it - if it'll be able to return response in both JSON and YAML (to keep comments) formats. Maybe add rpc.discover.yaml method. And to make this possible we won't be able to limit YAML support by only playground tool. That's why I believe this issue belongs here and not playground repo. Anyway, I'll open new issue there because implementation of YAML support in playground is a separate task.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[BelfordZ]

@powerman At the moment, adding such a feature to the spec would open the flood gates for any custom format.

JSON-RPC isnt YAML-RPC or XML-RPC. I hope you can understand the hard stance on this one. Please don't let this dissuade you from looking for ways of using yaml with open rpc, such as using vendor extensions or making proposals with wider appeal that would enable such yaml use.

Thanks again for the time and thought.