Request for NMOS Specifications in OpenAPI Specification 3 Format

[1mamute]

Hello,

I'm writing to request the possibility of publishing the NMOS specifications in OpenAPI Specification 3 format, currently available only in RAML format. My intention with this request is to broaden the accessibility and usability of these specifications for a wider range of developers and communities.

I believe that there are several compelling reasons to consider the migration (or to keep both formats):

• RAML versioning: The latest version of RAML is 1.0, which was released back in 2016. Since then, many advancements have occurred in the web APIs ecosystem which may not be fully covered by the RAML specification.
• Robustness of OpenAPI Specification (OAS): The OAS specification keeps evolving, for example, the most recent version of OAS (3.1) has included support for the latest JSON Schema drafts, asynchronous APIs and other important features that may be relevant to a NMOS implementation.
• Active community: The OpenAPI initiative and its surrounding open-source community are notably more active compared to RAML. As a result, there are more up-to-date resources and tools developed within this ecosystem, which could make development quicker and more efficient of NMOS implementations.

I fully acknowledge the potential complexity of this task and do not underestimate the effort required to transition from RAML to OpenAPI. However, I believe that the long-term benefits, particularly in terms of adaptability and extensibility, could outweigh the initial investment.

Thanks!

[garethsb]

Thank you. We recognize the benefits of adopting OpenAPI, so it's on the backlog but it needs to be weighed against expansion of NMOS in new areas and the cost of maintaining/supporting existing RAML-based specs. @AMWA-TV/nmos-architecture-review

[Julusian]

As of February 2024, the RAML specification repository on github has been archived https://github.com/raml-org/raml-spec. I can't find anything explicitly saying that the specification has been deprecated, but the archiving is an indicator of this.

[peterbrightwell]

Thanks for spotting this @Julusian -- if it is actually deprecated (and that repo is what raml.org's specification links to), then that may help prioritise the issue, which as @garethsb says is already on the backlog.

[peterbrightwell]

I've contacted raml.org, and it seems that repo might have been archived due to activity, but that is not the same as meaning RAML is deprecated. The company who contacted me to reply said that RAML has been "overshadowed for new spec development" but they will also continue to support RAML tooling for the foreseeable future.