Removing the body from possible values of the in Attribute in ParameterObject

[leidenheit]

The Arazzo Specification 1.0.0 allows body as a valid value for the in attribute in ParameterObject. However, this usage is inconsistent with modern API design practices and specifications such as OpenAPI, where the request body is handled separately from parameters. This proposal suggests removing body as an allowable value for in in the ParameterObject.

Current State
The in attribute of the ParameterObject allows several values, including query, header, path, cookie, and body.

"in": {
  "description": "Defines the location of the parameter (query, path, header, cookie, body).",
  "type": "string",
  "enum": ["query", "header", "path", "cookie", "body"]
}

Problem

1. Duplication of Responsibility:
   Allowing body as a value for in duplicates the responsibility of specifying a request body, which is already handled via the requestBody object.
2. Inconsistency with OpenAPI:
   OpenAPI Specification 3.x and beyond do not support body as part of the parameter location (in). Instead, all request body content is managed via requestBody.
3. Ambiguity:
   Mixing parameters and request body definitions can lead to confusion in tooling, validation, and developer understanding.

Proposed Solution

1. Remove body from the enum of ParameterObject.in
   The body value should be removed as a valid option from the in attribute in the ParameterObject. The valid values for in would then be limited to:
   • query
   • header
   • path
   • cookie
2. Use requestBody for all request body content
   For parameters intended to be part of the body, developers should use the requestBody property instead of including them in parameters.
3. Update the Specification
   Modify the definition of in in the ParameterObject to reflect this change:

"in": {
  "description": "Defines the location of the parameter (query, path, header, cookie).",
  "type": "string",
  "enum": ["query", "header", "path", "cookie"]
}

Benefits

1. Alignment with OpenAPI:
   This change ensures better compatibility and consistency with OpenAPI practices.
2. Improved Developer Clarity:
   Separating body content from parameters makes workflows easier to understand and maintain.

[frankkilcommins]

@leidenheit thanks for raising.

Unfortunately we missed removing body from the Parameter Object in field description as part of #162 when adding support for supplying request bodies. This is a typo and we'll fix in the next patch release.

As you'll see in the Parameter Object description, it's mentioned that there are only 4 possible values for the in property which are "path", "query", "header", "cookie".

The expectation is that a body would be supplied using the Request Body Object which is leverage as by a Steps requestBody fixed field - see https://spec.openapis.org/arazzo/latest.html#fixed-fields-3