Reformating the spec for readability

[sudo-bmitch]

I'm hearing concerns about the readability of the spec, which I can sympathize with. I'd like to gather thoughts on how to improve it and see if the maintainers are open to reformating the content. Here are some suggestions:

• Limit the smallest markdown header, since the current headings are difficult to distinguish from the rest of the text when rendered in GitHub.
• Focus on two audiences, clients and registry implementations. Clients want workflows of APIs to run for different requests. Registry implementations are looking for a list of endpoints to implement.
• With each endpoint, I tend to find a swagger style document easier to follow, with each parameter, header, body, status code, etc.
• To document the client workflows, I think it would be easier to follow if they were split out from the endpoint documentation, potentially including graphics, for those unfamiliar with the OCI specs. Those client workflows could have pointers to the referenced endpoints.

Hi @sudo-bmitch and others, thank you for opening this issue. While writing opentofu/opentofu#2163 we read through the spec several times. Adding visual dividers between deeply nested sections would already go a long way, but I'd be open to working on an OpenAPI spec for OCI as it would enable code generation for many languages.

[Sharpie]

+1 to getting the API section of the spec in OpenAPI format. One additional benefit of this is that it can be loaded into API clients, such as https://www.usebruno.com , which facilitates testing and exploration of the APIs provided by deployed registry services.