RFC059: Publish OpenAPI (Swagger) definitions under MIT license

Background and rationale

The OpenAPI definition of the iSHARE Framework is a machine-readable description of the HTTP APIs that conforming services and consumers can implement.

There are multiple versions of this definition available, corresponding to various versions of the iSHARE Framework, at https://app.swaggerhub.com/apis/iSHARE/iSHARE_Scheme_Specification/

An iSHARE-compatible component can use this OpenAPI definition to confirm that the component itself, and the parties its communicating with, conform to the specification, and can provide helpful diagnostic messages when something is out-of-spec. The OpenAPI definition can also be used to automatically generate sub code, parse incoming requests and be used in other useful "plumbing" that improves compatibility.

At the BDI, we want to use the OpenAPI definition in our Association Register component, to ensure that its configuration and responses conform to (a subset of) the iSHARE specification. The current implementation contains a copy of the definition as a YAML file copied from the swaggerhub link, above.

We distribute the Association Register under a Free and Open-Source license -- the AGPL. And we want to distribute it both as source code and as runnable artifacts (Docker containers, java standalone jars).

The runnable artifacts need to include the OpenAPI definition in order to work. Under the terms of the AGPL, any person obtaining a copy of the runnable artifact ("object code") needs to be offered access to the full source code, is given permission to run the artifact without restriction, is given permission to modify and convey (copy) the source code.

Currently, all of the framwork documentation, including the OpenAPI definitions, is provided with the following legal notice:

Legal notices

No part of these specifications may be reproduced in any form
by print, photo print, microfilm or any other means or stored 
in an electronic retrieval system, without the prior written 
consent of the iSHARE Foundation ( successor of the project 
organisation), which must never be presumed.

We believe the OpenAPI specification should be seen as part of the source code, and we explicitly want to allow modification and re-distribution of our Association Register code, including the OpenAPI definitions. However, according to the legal notices, we do not have a license to copy and modify the OpenAPI definitions in this way.

Furthermore, we believe the current restrictions on copying and modifying the OpenAPI definitions is standing in the way of wider adoption of the iSHARE Framework and its derivatives, in Open Source as well as in prorietary (closed source) products. The OpenAPI definitions should, as far as is partical and common, be unencumbered by legal and copyright restrictions.

Proposed change: purpose

Provide all versions of the iSHARE OpenAPI definitions under the MIT License, the full terms of which are as follows:

Copyright (c) <year> <copyright holders>

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Proposed change: considerations and requirements

Choice of license:

The MIT license terms allow inclusion with modifications in both Open Source and Proprietary licensed components. It is also a well known license, meaning that implementers do not have to do unnecessary legal work to confirm they are in the clear using the definition.

Ensuring compliance to the Framework:

One of the stated reasons for not currently allowing the definitions to be copied and modified, is to ensure compliance of components built on top of the modifications.

We do not believe compliance/comformance of components should be a factor in licensing the definition: compliance of a component should be determined independently of its source code. Compliance and certification should be independent of copyright and licensing of the specification.