Clarifying Behavior for Missing in Attribute in ParameterObject

[leidenheit]

The current Arazzo Specification 1.0.0 allows the in attribute in the ParameterObject to be optional. However, it does not specify the expected behavior if this attribute is missing. This lack of clarity can lead to inconsistent interpretations and implementations.

This proposal defines a standard behavior and recommended practices for handling missing in attributes.

Current State
In the ParameterObject section of the specification, the in attribute is optional but no default behavior is specified.

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

Problem
If in is missing:

1. Tools and implementations may interpret the parameter differently.
2. Developers may assume default behavior (e.g., body) that is not explicitly stated.
3. Validation tools and code generators may produce inconsistent results.

Proposed Solution

1. Default Behavior:
   If the in attribute is missing, the parameter will be treated as part of the request body by default.
   • Rationale: This assumption aligns with typical API design, where many parameters are passed in the body.
2. Future Requirement:
   In a future version of the specification, the in attribute should become mandatory for all parameters:
   • Requirement: Validation tools should throw an error if in is missing.
   • Transition Period: Warnings will remain in place for a defined period to provide time for adoption.

Benefits

1. Clear, standardized behavior for missing in attributes.
2. Consistency across tools and implementations.
3. Encourages best practices for parameter definitions.

[frankkilcommins]

@leidenheit thanks for raising.

The current text regarding when the in field should be specified and what's expected if it's omitted is described as follows:

When the step in context specifies a workflowId, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an operationId), the in field MUST be specified.

What this tries to articulate is that the in property is ONLY optional if the step in which the parameters are being defined specifies a workflowId. This means that the step is invoking another workflow and not an API operation and thus all parameters should be mappable into the targeted workflow Inputs Object.

[leidenheit]

Thanks for clarification. Now I see.