Link.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.
//===----------------------------------------------------------------------===//
/// The Link object represents a possible design-time link for a response.
///
/// The presence of a link does not guarantee the caller's ability to
/// successfully invoke it, rather it provides a known relationship and
/// traversal mechanism between responses and other operations.
///
/// Unlike dynamic links (i.e. links provided in the response payload), the
/// OAS linking mechanism does not require link information in the runtime
/// response.
///
/// For computing links, and providing instructions to execute them, a
/// runtime expression is used for accessing values in an operation and using
/// them as parameters while invoking the linked operation.
///
/// A linked operation MUST be identified using either an operationRef or
/// operationId. In the case of an operationId, it MUST be unique and
/// resolved in the scope of the OAS document. Because of the potential
/// for name clashes, the operationRef syntax is preferred for specifications
/// with external references.
module org.openapis.v3.Link

import "expressions.pkl"
import "Server.pkl"

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

/// A relative or absolute URI reference to an OAS operation.
///
/// This field is mutually exclusive of the operationId field, and MUST point to an Operation Object. Relative
/// operationRef values MAY be used to locate an existing Operation Object in the OpenAPI definition.
operationRef: Uri?(!(this != null && operationId != null))

/// The name of an existing, resolvable OAS operation, as defined with a unique operationId.
///
/// This field is mutually exclusive of the operationRef field.
operationId: String?

/// A map representing parameters to pass to an operation as specified with operationId or identified via operationRef.
///
/// The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and
/// passed to the linked operation. The parameter name can be qualified using the parameter location [{in}.]{name}
/// for operations that use the same parameter name in different locations (e.g. path.id).
parameters: Mapping<String, expressions.Expression | Any>?

/// A literal value or {expression} to use as a request body when calling the target operation.
requestBody: (expressions.Expression | Any)?

/// A server object to be used by the target operation.
server: Server?