Moonwalk should allow API designers to express interdependencies between the parameters of an operation.
This is part of the initial Moonwalk Proposal and is broken out here to refine the ideas before creating the ADR.
The Problem to be Solved
All prior versions of OpenAPI used an array to define parameters for an operation. This approach does not provide any formal mechanism for describing interdependencies between parameters. Research [1] has shown that interdependencies are not uncommon in real-world APIs and come in a variety of forms. Issue #256 (opened in 2015) requested this feature and has received over 600 up-votes.
Rather than using an array to define the parameters for an operation, we should use a JSON Schema. The parameters schema must be an object schema and must not have additionalProperties. Each named property of the parameters schema defines an operation parameter. Property names of the parameter schema have the form [<in>.]name, where <in> may be "query", "header", "path", or "cookie". When not specified, <in> defaults to "query".
Note: Combining the <in> and name allows parameters with the same name but different <in>, as is permitted in prior versions of OpenAPI. It also avoids the need to augment JSON Schema for this purpose.
The parameterSchema field would be supported on Operations and on Path Items. If specified on a Path Item, the effective parameter schema for an operation would be the allOf of the path item schema and the operation schema.
The parameter schema may contain JSON Schema assertions to express interdependencies between parameters. Some common interdependencies are described below.
Requires
The presence of a parameter (or a specific parameter value) requires the presence of another parameter.
Example: answerCount must be specified if promote is specified.
Note: There is probably an easier way to express this. Happy for feedback here.
Compatibility with OpenAPI 3.x
I believe that no functionality of OpenAPI 3.x is lost with this proposal. It should be straightforward to transform an existing parameters array to an equivalent parameterSchema.
Moonwalk should allow API designers to express interdependencies between the parameters of an operation.
This is part of the initial Moonwalk Proposal and is broken out here to refine the ideas before creating the ADR.
The Problem to be Solved
All prior versions of OpenAPI used an array to define parameters for an operation. This approach does not provide any formal mechanism for describing interdependencies between parameters. Research [1] has shown that interdependencies are not uncommon in real-world APIs and come in a variety of forms. Issue #256 (opened in 2015) requested this feature and has received over 600 up-votes.
1) "API Specs and Inter-Parameter Dependencies: The Elephant in the Room", Alberto Martin, API Specifications Conference 2022
Proposed solution
Rather than using an array to define the parameters for an operation, we should use a JSON Schema. The parameters schema must be an object schema and must not have
additionalProperties
. Each named property of the parameters schema defines an operation parameter. Property names of the parameter schema have the form[<in>.]name
, where<in>
may be "query", "header", "path", or "cookie". When not specified,<in>
defaults to "query".Note: Combining the
<in>
andname
allows parameters with the same name but different<in>
, as is permitted in prior versions of OpenAPI. It also avoids the need to augment JSON Schema for this purpose.The
parameterSchema
field would be supported on Operations and on Path Items. If specified on a Path Item, the effective parameter schema for an operation would be theallOf
of the path item schema and the operation schema.The parameter schema may contain JSON Schema assertions to express interdependencies between parameters. Some common interdependencies are described below.
Requires
The presence of a parameter (or a specific parameter value) requires the presence of another parameter.
Example:
answerCount
must be specified ifpromote
is specified.Or
Given a set of parameters, one or more of them must be included.
Example: either
title
ordescription
must be specified.OnlyOne
Given a set of parameters, one and only one of them must be included.
Example: either
from
ormessagingServiceId
must be specified but not both.AllOrNone
Given a set of parameters, either all of them are provided or none of them is.
Example:
subject_type
andsubject_id
are both specified or neither is specified.Example:
value
is present if and only iftype
is "bucket"ZeroOrOne
Given a set of parameters, at most one of can be included.
Example: specify zero or one of
forContentOwner
,forDeveloper
,forMine
, orrelatedToVideoId
:Note: There is probably an easier way to express this. Happy for feedback here.
Compatibility with OpenAPI 3.x
I believe that no functionality of OpenAPI 3.x is lost with this proposal. It should be straightforward to transform an existing
parameters
array to an equivalentparameterSchema
.