Openapi-specification: `identifier` field for License Objects

[shockey]

License Objects should have an identifier field, which can hold Software Package Data Exchange license identifiers 😄

From the SPDX Specification:

Identifying the license for open source software is critical for both reporting purposes and license compliance. However, determining the license can sometimes be difficult due to a lack of information or ambiguous information. Even when licensing information is present, a lack of consistent notation can make automating the task of license detection very difficult, thus requiring vast amounts of human effort.

https://spdx.org/spdx-specification-21-web-version#h.twlc0ztnng3b

Rationale

The OpenAPI Specification, as we all know, is meant to be machine _and_ human readable[1].

Adding a standardized, machine-readable license field would allow for the following:

• more precision w/r/t specific licenses, without the brittleness of a url field (URL rot is a thing!)
• automatic linking to common licenses in documentation tools, even if the author omits a link
• an index that categorizes APIs by license without relying on license.name string comparison
• an OpenAPI client that automatically checks for compliance with services it interacts with

[darrelmiller]

From first glance at the SPDX spec, that looks like significant overkill for what the API license is trying to do in OpenAPI. If link rot in licenses is an issue, then we should address that because for well known OSS licenses, it shouldn't be an issue.

[darrelmiller]

Based on @OAI/tsc conversations, this is something we would consider. Identifier could be added as a mutually exclusive value with Url.

[lorenzleutgeb]

I also think adopting SPDX would be a good idea. Note however that for proprietary/closed cases, there is neither a SPDX license nor a URL. NPM suggests to use UNLICENSED in place of an SPDX identifier in this case.

[MikeRalphson]

@lorenzleutgeb I've personally found that creates confusion with the Unlicense license. I think omitting an identifier and relying on the name/url would be preferable. Why would there not be a url for a proprietary license?

[lorenzleutgeb]

@MikeRalphson I agree that confusion with the Unlicense is too probable for this to be a nice solution. Still hoping for a better one... My proposal would be to make the license object not required.

The thing that bugs me is that a license is required in any case, even if there is none. The case without license protects the exclusive rights of the author. It is a little unclear what to do with the required name in this case, since there is no licensing. What one might do now is use "NONE", "UNLICENSED" or "All rights reserved." as license name. But that is a hack since effectively there is no license. This is why I pointed at NPM. They have a convention on how to express that there is no license. OpenAPI does not have that.

And for the case of "proprietary" this does not really rule out a proprietary license model and should be distinguished from no license. I guess in the case of a proprietary license, a URL for the license seems reasonable.

But I realize that I am hijacking the original issue a little. If you are considering changing the license object for SPDX then it would be nice to also address my concerns about no license.

[MikeRalphson]

In both OAS 2.0 and 3.0.x the info.license object is optional.

[MikeRalphson]

@shockey do you have the time to move this to a PR?

[silverhook]

If a license is not listed on the SPDX License List, you can still use SPDX annotation to indicate a unique license by prepending LicenseRef- to the (unique) license name. E.g. LicenseRef-My_Very_Own_Look_But_Do_Not_Touch_License-2.0 is a valid SPDX license identifier.

[SamuelMarks]

Is there support for SPDX license expressions yet?

[MikeRalphson]

@SamuelMarks not yet, we just need someone with bandwidth to create a PR against the next minor version.

[MikeRalphson]

2105 was merged into v3.1.0-dev, look out for an RC-0 release soon.