Parameter.pkl

//===----------------------------------------------------------------------===//
// Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//===----------------------------------------------------------------------===//
module org.openapis.v3.Parameter

extends "BaseParameter.pkl"

import "MediaType.pkl"
import "Reference.pkl"
import "Schema.pkl"

/// The name of the parameter.
///
/// Parameter names are case sensitive.
///
/// * If in is "path", the name field MUST correspond to a template expression occurring within the path field in the
///   Paths Object. See Path Templating for further information.
/// * If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition
///   SHALL be ignored.
/// * For all other cases, the name corresponds to the parameter name used by the in property.
name: String

/// The location of the parameter.
`in`: "query" | "header" | "path" | "cookie"

/// Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;=
/// to be included without percent-encoding.
///
/// This property only applies to parameters with an in value of query. The default value is false.
allowReserved: Boolean(implies(`in` == "query"))?

/// Determines whether this parameter is mandatory.
///
/// If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property
/// MAY be included and its default value is false.
required: Boolean?((`in` == "path").implies(this == true))

/// Allowed values for a parameter's style.
typealias Style =
  "matrix" | "label" | "form" | "simple" | "spaceDelimited" | "pipeDelimited" | "deepObject"

/// Describes how the parameter value will be serialized depending on the type of the parameter value.
///
/// Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.
style: Style(
  if (List("matrix", "label").contains(this))
    `in` == "path"
  else if (this == "form")
    List("query", "cookie").contains(`in`)
  else if (this == "simple")
    List("header", "path").contains(`in`)
  else
    `in` == "query"
)?

/// The schema defining the type used for the parameter.
schema: (*Schema | Reference)?

/// A map containing the representations for the parameter.
///
/// The key is the media type and the value describes it. The map MUST only contain one entry.
content: Mapping<MediaType.MediaTypeName, MediaType>(length == 1)?