Operation.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.
//===----------------------------------------------------------------------===//
/// Describes a single API operation on a path.
module org.openapis.v3.Operation

import "expressions.pkl"
import "ExternalDocs.pkl"
import "HTTPResponse.pkl"
import "Parameter.pkl"
import "PathItem.pkl"
import "Reference.pkl"
import "RequestBody.pkl"
import "Response.pkl"
import "Security.pkl"
import "Server.pkl"

/// A list of tags for API documentation control.
///
/// Tags can be used for logical grouping of operations by resources or any other qualifier.
tags: Listing<String>(isDistinct)?

/// A short summary of what the operation does.
summary: String?

/// A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
@SourceCode { language = "Markdown" }
description: String?

/// Additional external documentation for this operation.
externalDocs: ExternalDocs?

/// Unique string used to identify the operation.
///
/// The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools
/// and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow
/// common programming naming conventions.
operationId: String?

/// A list of parameters that are applicable for this operation.
///
/// If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
/// The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and
/// location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
/// components/parameters.
parameters: Parameters?

// follow the uniqueness standard for parameters set forth by the spec
typealias Parameters =
  Listing<*Parameter | Reference>(
    isDistinctBy((it) -> if (it is Parameter) "\(it.name)\(it.`in`)" else it.`$ref`)
  )

/// The request body applicable for this operation.
///
/// The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined
/// semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by
/// consumers.
requestBody: (*RequestBody | Reference)?

/// The list of possible responses as they are returned from executing this operation.
///
/// Any HTTP status code can be used as the property name, but only one property per code, to describe the expected
/// response for that HTTP statuscode. You can use const values of [HTTPResponse] for this, eg.
///
/// ```pkl
/// [HTTPResponse.OK] { ... }
/// ```
///
/// A Reference Object can link to a response that is defined in the OpenAPI
/// Object's components/responses section. To define a range of response codes, this field MAY contain the uppercase
/// wildcard character X. For example, 2XX represents all response codes between [200-299]. Only the following range
/// definitions are allowed: 1XX, 2XX, 3XX, 4XX, and 5XX. If a response is defined using an explicit code, the explicit
/// code definition takes precedence over the range definition for that code.
responses: Mapping<HTTPResponse.Code | HTTPResponse.CodeWildcard | "default", *Response | Reference>?

/// A map of possible out-of band callbacks related to the parent operation.
///
/// The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a
/// request that may be initiated by the API provider and the expected responses.
callbacks: Mapping<String, *Mapping<expressions.Expression, PathItem> | Reference>?

/// Declares this operation to be deprecated.
///
/// Consumers SHOULD refrain from usage of the declared operation. Default value is false.
deprecated: Boolean?

/// A declaration of which security mechanisms can be used for this operation.
///
/// The list of values includes alternative security requirement objects that can be used. Only one of the security
/// requirement objects need to be satisfied to authorize a request. To make security optional, an empty security
/// requirement ({}) can be included in the array. This definition overrides any declared top-level security. To
/// remove a top-level security declaration, an empty array can be used.
security: Listing<Security.Requirement>?

/// An alternative server array to service this operation.
///
/// If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this
/// value.
servers: Listing<Server>?