File: //snap/google-cloud-cli/current/lib/googlecloudsdk/command_lib/util/apis/yaml_command_schema.yaml
# Copyright 2017 Google LLC. 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
#
# http://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.
title: command
description: The specification for a full calliope command
definitions:
python_hook:
type: string
# A Python hook points to a module, class, an optionally a sub attribute
# or function. The thing it points to will be called by the framework
# and must have the function signature required by that particular hook.
# If arguments are given (:foo=bar,baz=stuff), The function will first be
# called with those arguments, and the return value will be used as the
# callable hook.
# Examples:
# googlecloudsdk.module:classname
# googlecloudsdk.module:class.attribute
# googlecloudsdk.module:class.function:foo=bar,baz=stuff
pattern: "\\w+(\\.\\w+)+:\\w+(\\.\\w+)*(:\\w+=\\w+(,\\w+=\\w+)*)?"
yaml_reference:
type: string
# Examples:
# googlecloudsdk.module:attribute
# googlecloudsdk.module:attribute.attribute
pattern: "\\w+(\\.\\w+)+:\\w+(\\.\\w+)*"
attribute:
type: string
# Examples: a, a.b, a.c.b
pattern: "\\w+(\\.\\w+)*"
property:
type: string
# Examples: core/project, compute/zone
pattern: "\\w+/\\w+"
argparse_type:
# Something to be used as the type argument for an argparse argument.
oneOf:
# One of the builtin Python types.
- enum: [str, int, long, float, bool, bytes]
# The module path to a function used as the 'type' for the argument.
# The function takes a single parameter which is the parsed string value
# of the argument and returns the converted parsed value.
- $ref: "#/definitions/python_hook"
# Support for arg_parsers.arg_list
- enum: [arg_list, arg_object, arg_json, file_type]
choices:
# A list of valid choices for an argument.
type: array
items:
type: object
additionalProperties: false
required: [arg_value]
properties:
# The choice as it appears on the command line
# (should be lower-kebab-case).
arg_value: {type: [string, number, boolean]}
# The string representation of the API enum value that will be used
# when this choice is selected. Default is derived from arg_value by
# converting to upper case and replacing hyphens with underscores.
enum_value: {type: string}
# The help text to show next to the choice on the man page.
help_text: {type: string}
# Whether or not the choice should be hidden from help text.
hidden: {type: boolean}
flag_spec:
type: array
items:
type: object
additionalProperties: false
properties:
api_field: {type: string}
json_name: {type: string}
help_text: {type: string}
hidden: {type: boolean}
# TODO(b/291130667): enable mutex for arg_object
# one_of_index is to determine which items are in a mutex group.
# Not available for public use yet.
one_of_index: {type: number}
# TODO(b/304805943): enable resource pattern
# resource_pattern is a regex pattern used to verify resource strings.
# Not available for public use yet.
resource_pattern: {type: string}
type: {$ref: "#/definitions/argparse_type"}
spec: {$ref: "#/definitions/flag_spec"}
fallthrough:
required: [hook, hint]
additionalProperties: false
properties:
# A zero-argument Python function that can provide a fallback value for
# the attribute.
hook: {$ref: "#/definitions/python_hook"}
# Text to display to users if no fallthroughs are set (should be
# imperative, to follow "The attribute can be set in the following ways").
hint: {type: string}
value_fallthrough:
required: [value]
additionalProperties: false
properties:
# A fixed value to use for fallthrough.
value: {type: string}
# Text to display to users if no fallthroughs are set (should be
# imperative, to follow "The attribute can be set in the following ways").
hint: {type: string}
arg_fallthrough:
required: [arg_name]
additionalProperties: false
properties:
# Name of a flag or positional whose value can be used as a default.
arg_name: {type: string}
# Whether the other arg is positional. Defaults to False.
is_positional: {type: boolean}
resource_attribute:
# An individual resource arg attribute.
required: [parameter_name, attribute_name, help]
additionalProperties: false
properties:
# The API parameter name that this attribute maps to.
parameter_name: {type: string}
# The name as it should appear on the command line.
attribute_name: {type: string}
# The help text for this attribute.
help: {type: string}
# A property to act as the fallthrough for this attribute when it is not
# provided on the command line.
property: {$ref: "#definitions/property"}
# A list of Python hooks that will act as fallthroughs if the attribute is
# not provided on the command line.
fallthroughs:
type: array
items:
oneOf:
- $ref: "#/definitions/fallthrough"
- $ref: "#/definitions/value_fallthrough"
# The module path to a class that implements remote completion
# for this resource.
completer: {$ref: "#/definitions/python_hook"}
# The ID field of the return value in the response for completions.
completion_id_field: {type: string}
# Field names to use as static field values in any request to
# complete this resource.
completion_request_params:
type: array
items:
type: object
additionalProperties: false
properties:
fieldName: {type: string}
value: {type: string}
resource_spec:
type: object
additionalProperties: false
required: [name, collection, attributes]
properties:
# The name of the resource argument, used for messaging.
name: {type: string}
# The pluralized name if default rules won't work.
plural_name: {type: string}
# The full collection name of the resource argument.
collection: {type: string}
# The api version this spec refers to. If empty, it applies to any
# version.
api_version: {type: string}
# TODO(b/274890004): remove request_id_field from resource_spec
# The field in the create request that should hold the name of the
# resource being created (since create requests don't have the resource
# id as an API parameter.
request_id_field: {$ref: "#/definitions/attribute"}
# The set of attributes that map to the API parameters for this resource's
# collection.
attributes:
type: array
items: {$ref: "#/definitions/resource_attribute"}
# If False, allows the resource to create automatic completers for
# each argument. True by default.
disable_auto_completers: {type: boolean}
multitype_resource_spec:
type: object
additionalProperties: false
required: [name, resources]
properties:
# The name of the resource argument, used for messaging.
name: {type: string}
# The pluralized name if default rules won't work.
plural_name: {type: string}
# All resource specs contained in this one.
# The parsed result will have a "type_" attribute whose name is either the
# name of the resource spec (if all sub-resource specs are unique) or the
# collection name otherwise (such as 'projects.zones.instances'). Note:
# All resources used in this spec must have names.
resources:
type: array
items: {$ref: "#/definitions/resource_spec"}
argument:
oneOf:
- $ref: "#/definitions/arg"
- $ref: "#/definitions/resource_arg"
- $ref: "#/definitions/arg_group"
resource_arg:
description: Describes how to generate the resource arg and its flags
type: object
additionalProperties: false
required: [help_text, resource_spec]
properties:
# The help text for the overall resource arg group.
help_text: {type: string}
# Set to False to force the anchor resource argument to be a flag
# even though it would normally be a positional. This should normally
# not be required for well formed API methods.
is_positional: {type: boolean}
# Set to True if the resource spec is for the parent of the request
# collection instead of for the collection itself. This allows for
# create commands that do not require a name for the new resource.
# Set the `resource_type` property on `request` to include the
# resource type in log messages.
is_parent_resource: {type: boolean}
# Set to True if this resource is the resource being operated on ie
# being described, created, updated, etc. This helps determine which
# resource arg should be validated against the method and included
# in the display name, among other things. Only one resource arg can
# set is_primary_resource to true. If command does not set any resource
# args' is_primary_resource to true, then gcloud will try to assume
# which resource is primary based off of request.method.collection
is_primary_resource: {type: boolean}
# The name to use for the resource arg. If set this is the name that
# will be used for the resource arg in the command. If not set,
# command will use the name from the spec.
arg_name: {type: string}
# List of resource arg attributes to not generate flags for. These
# attributes will need to have fallthroughs in the resource arg spec
# in order to be populated.
removed_flags:
type: array
items: {type: string}
# The field in the create request that should hold the name of the
# resource being created (since create requests don't have the resource
# id as an API parameter.
request_id_field: {$ref: "#/definitions/attribute"}
# a map of attribute names to a list of fallthroughs *specific to
# this command* that will be used if the attribute is not directly
# provided on the command line. Anything in this map takes precedence
# over what's specified in the resource spec by default.
command_level_fallthroughs:
type: object
patternProperties:
.*:
type: array
items: {$ref: "#/definitions/arg_fallthrough"}
# The resource arg specification itself. This corresponds to the
# ResourceSpec and ResourceParameterAttributeConfig objects and does
# not include anything that would go in a presentation spec. It is
# expected that this entire section be imported from a resources.yaml
# file in command_lib.
# (ex !REF googlecloudsdk.command_lib.pubsub.resources:topic)
resource_spec:
oneOf:
# A regular resource arg
- $ref: "#/definitions/resource_spec"
# A multitype resource arg
- $ref: "#/definitions/multitype_resource_spec"
# A mapping of method parameter to format string that can include resource reference params(s)
# (or '__relative_name__' to use the full resource name or '__resource_id__' for resource id)
# for references or APIs that use non-standard naming. For example, if a resource ref has a
# project, location, and instance attribute, but the request URI has the structure
# /projects/{project}/regions/{region}/instances/{instance}, you would use
# resource_method_params:
# region: '{location}'
# To map the resource attribute to the correct method parameter.
resource_method_params:
type: object
patternProperties:
.*: {type: string}
# False if the resource reference should not be auto-parsed into the
# request message. NOTE: if you mark this False, you need to add a hook
# that handles the result of parsing the resource argument for the
# command. For example, if the resource is multi-type, you may want to
# define an modify_request_hook that modifies the request based on
# the parsed type of the resource.
parse_resource_into_request: {type: boolean}
# Use ref.RelativeName() if true, ref.Name() otherwise. Default True.
use_relative_name: {type: boolean}
# If true, will disable validating that the resource arg schema matches the
# request method schema. This is useful for API's that have multiple services
# (and multiple resource collections) that use the same actual resource objects.
override_resource_collection: {type: boolean}
# Whether the flag is required or not.
required: {type: boolean}
# Whether or not the resource arg is plural and should be generated as a list.
repeated: {type: boolean}
# Whether to add clearable update arguments
clearable: {type: boolean}
arg:
required: [help_text]
additionalProperties: false
properties:
# The name of the API field the value of this argument goes into.
# At least one of [api_field, arg_name] must be given.
api_field: {type: string}
# Disables yaml_command_test check for unused arguments. Some arguments get used
# in such a way that static analysis can't catch it.
disable_unused_arg_check: {type: boolean}
# The help text for this individual flag.
help_text: {type: string}
# The name of the argument as it should appear in the CLI. If
# not given it will match the API field name. This does not
# include '--' even if it will be a flag.
# At least one of [api_field, arg_name] must be given.
arg_name: {type: string}
# The name of the argument as it should appear in the JSON. If
# not given it will match the API field name.
json_name: {type: string}
# The module path to a class that implements remote completion
# for this argument.
completer: {$ref: "#/definitions/python_hook"}
# True if this should be forced to be a positional argument
# instead of a flag.
is_positional: {type: boolean}
# The argparse type to use for this argument. See inline options for
# this value.
type:
oneOf:
# A builtin type or hook to a type function.
- $ref: "#/definitions/argparse_type"
# First class support for making this an ArgDict.
- type: object
additionalProperties: false
properties:
arg_dict:
type: object
additionalProperties: false
required: [spec]
properties:
# Set to True to make the ArgDict correspond to a repeated
# key/value pair. For this to work, the spec must contain
# exactly two items. If False, the keys in the dict will be
# the arg names, and the values will be the values for those
# fields. The arg is repeated by specifying the flag multiple
# times.
flatten: {type: boolean}
spec:
type: array
items:
type: object
additionalProperties: false
required: [api_field]
properties:
api_field: {type: string}
# Only applicable for non-flat dicts.
arg_name: {type: string}
type: {$ref: "#/definitions/argparse_type"}
# Only applicable for non-flat dicts.
required: {type: boolean}
choices: {$ref: "#/definitions/choices"}
# custom spec for arg_object type
spec: {$ref: "#/definitions/flag_spec"}
# The argparse action to use for this argument. See inline options for
# this value.
action:
oneOf:
# One of the builtin argparse actions.
- enum: [store, store_true, store_true_false, append]
# The module path to a class that implements argparse's Action class.
- $ref: "#/definitions/python_hook"
# Mark this flag as being deprecated. All the sub elements here
# are passed as kwargs to the calliope.actions.DeprecationAction
# action.
- type: object
additionalProperties: false
properties:
deprecated:
type: object
additionalProperties: false
properties:
# If False, warning message will be printed, otherwise, error message will be
# printed.
removed: {type: boolean}
# Warning message. 'flag_name' template will be replaced with value of flag_name
# parameter.
warn: {type: string}
# Error message. 'flag_name' template will be replaced with value of flag_name
# parameter.
error: {type: string}
# Can be set to False if you want to accept a single value even though the
# API field is repeated. If the API field is not repeated, this attribute
# has no effect.
repeated: {type: boolean}
# The metavar for the generated argument. This will be generated
# automatically if not provided.
metavar: {type: string}
# Overrides the choices that are generated for the argument.
choices: {$ref: "#/definitions/choices"}
# TODO(b/80307139): Combine default and fallback.
# The default value of the argument when not specified. Mutually exclusive
# with fallback. If provided and None, the default of the argument is
# explicitly set to None. If not provided, no default is set on the
# argument.
default: {type: [string, number, boolean, array, 'null']}
# The module path to a function to call (with no arguments) if no value is
# provided; the result of this function will be used for this argument
# (like default, but with a computed value). Mutually exclusive with
# default.
fallback: {$ref: "#/definitions/python_hook"}
# The module path to a function to process the parsed value
# before inserting it into the request message. It takes a
# single value which is the parsed argument's value and returns
# the value that should be inserted into the request.
processor: {$ref: "#/definitions/python_hook"}
# Whether the flag is required or not.
required: {type: boolean}
# Whether the flag is hidden or not.
hidden: {type: boolean}
# TODO(b/280653078): Not ready for public use yet
# Whether to add update flags for update commands.
# Must be used with read_modify_update
clearable: {type: boolean}
arg_group:
type: object
additionalProperties: false
properties:
group:
required: [params]
type: object
additionalProperties: false
properties:
# The help text for the group.
help_text: {type: string}
# Whether the group is required or not.
required: {type: boolean}
# Whether the group is mutually exclusive or not.
mutex: {type: boolean}
# Whether the group is hidden or not.
hidden: {type: boolean}
# Whether the group has an arg_object flag or not in addition to the params.
settable: {type: boolean}
# Whether the group has a clearable flag or not in addition to the params.
clearable: {type: boolean}
# Api field associated with the group.
# Only needed when clearable or settable flags are set to true.
api_field: {type: string}
# The name of the argument group as it should appear in the CLI.
# Only needed when clearable or settable flags are set to true.
arg_name: {type: string}
# How the argument group should be represented in JSON.
json_name: {type: string}
# The group arguments.
params:
type: array
items: {$ref: "#/definitions/argument"}
minItems: 1
type: object
additionalProperties: false
required: [help_text, arguments]
properties:
# Determines whether the command is visible in help text or not.
hidden: {type: boolean}
# Determines whether the command is auto generated or not.
auto_generated: {type: boolean}
# Determines whether the command is available in univserse or not.
universe_compatible: {type: boolean}
# Determines which release tracks this command implementation will apply to.
release_tracks:
type: array
items: {enum: [ALPHA, BETA, GA]}
# The type of command to generate. This is inferred based on the name
# of the command file (convert to uppercase and remove .yaml extension).
command_type:
enum:
- DESCRIBE
- LIST
- DELETE
- CREATE
- UPDATE
- WAIT
- CONFIG_EXPORT
- GET_IAM_POLICY
- SET_IAM_POLICY
- GENERIC
# Corresponds to the detailed_help attribute on command classes. Typically
# looks something like this (brief and description are required):
# help_text:
# brief: Delete a Compute Engine virtual machine.
# description: |
# This command stops, and deletes the given virtual machine instance. Any
# boot disks associated with this instance are also deleted.
# examples: |
# To delete an instance:
#
# $ {command} INSTANCE_NAME --zone ZONE
help_text:
type: object
additionalProperties: false
required: [brief, description]
patternProperties:
brief: {type: string}
description: {type: string}
examples: {type: string}
.*: {type: string}
# Determines whether the command is deprecated.
# If is_removed is false, a warning will be logged when *command* is run,
# otherwise an *exception* will be thrown containing error message.
# Command help output will be modified to include warning/error message
# depending on value of is_removed.
# Command help text will automatically hidden from the reference
# documentation if is_removed is True.
deprecate:
type: object
additionalProperties: false
required: [is_removed]
properties:
is_removed: {type: boolean}
warning: {type: string}
error: {type: string}
# Attributes about the API request the command will make.
request: &request
description: Describes information about the API that this command calls
type: object
additionalProperties: false
required: [collection]
oneOf:
- required: [modify_request_hooks]
- required: [create_request_hook]
- required: [issue_request_hook]
- allOf:
- not: {required: [modify_request_hooks]}
- not: {required: [create_request_hook]}
- not: {required: [issue_request_hook]}
properties:
# The full collection name of the resource the command operates on.
# A list of collections is used whenever the request is a multitype ie
# a resource with different parent paths.
collection: {type: [string, array]}
# If true, will disable validating that a resource arg is specified if
# the collection requires a params from a resource.
disable_resource_check: {type: boolean}
# The type of the resource the command operates on to be used for logging.
display_resource_type: {type: string}
# The API version to use, defaults to API set as gcloud default.
api_version: {type: string}
# The name of the method to call to perform the operation. Optional if
# your command is one of the supported command types (not Generic).
method: {type: string}
# Used for methods that return paginated results. If set to True, makes a single api
# request rather than utilizing YieldFromList method. YieldFromList method makes
# continuous api request until the limit is reached or all results are returned.
# Defaults to False
disable_pagination: {type: boolean}
# The module path to a function to call to modify the API method
# to call to perform the operation. The provided or default `method`
# will be used to parse the arguments, then this function will be called
# with two arguments: a resource ref to the parsed resource and the parsed
# args namespace. The returned string will be the method used to create
# and issue the request.
modify_method_hook: {$ref: "#/definitions/python_hook"}
# TODO(b/272076207): Remove resource_method_params when surfaces are updated
# A mapping of method parameter to format string that can include resource reference params(s)
# (or '__relative_name__' to use the full resource name or '__resource_id__' for resource id)
# for references or APIs that use non-standard naming. For example, if a resource ref has a
# project, location, and instance attribute, but the request URI has the structure
# /projects/{project}/regions/{region}/instances/{instance}, you would use
# resource_method_params:
# region: '{location}'
# To map the resource attribute to the correct method parameter.
resource_method_params:
type: object
patternProperties:
.*: {type: string}
# TODO(b/272076207): Remove parse_resource_into_request when surfaces are updated
# False if the resource reference should not be auto-parsed into the
# request message. NOTE: if you mark this False, you need to add a hook
# that handles the result of parsing the resource argument for the
# command. For example, if the resource is multi-type, you may want to
# define an modify_request_hook that modifies the request based on
# the parsed type of the resource.
parse_resource_into_request: {type: boolean}
# A mapping of request field names to static values to insert into the
# request. Specifying simple values here accomplishes the same as a
# a custom request generator, but is simpler. For example, if you had an
# an API that could work in several modes, but we only use one in the
# command, you could set:
# static_fields:
# requests.features.type: TYPE1
# To always populate that field with the correct mode.
static_fields:
type: object
patternProperties:
.*: {}
# The module path to a function to call to modify the API request
# before it is invoked. All registered arguments will be processed
# into the request, before this is called. This is a function
# that takes 3 arguments: a resource ref to the parsed resource,
# the parsed args namespace, and the created request. It must return
# an apitools request message that will be passed to the API method
# defined in this section.
modify_request_hooks:
type: array
items: {$ref: "#/definitions/python_hook"}
# The module path to a function to call to create the API request
# rather than having it done automatically. This is a function
# that takes 2 arguments: a resource ref to the parsed resource, and
# the parsed args namespace. It must return an apitools request
# message that will be passed to the API method defined in this
# section.
create_request_hook: {$ref: "#/definitions/python_hook"}
# The module path to a function to call to issue an API request
# rather than having it done automatically. This is a function
# that takes 2 arguments: a resource ref to the parsed resource, and
# the parsed args namespace. It should create a request, make the
# API call, and return the response.
issue_request_hook: {$ref: "#/definitions/python_hook"}
# TODO(b/272076207): Remove use_relative_name when surfaces are updated
# Use ref.RelativeName() if true, ref.Name() otherwise. Default True.
use_relative_name: {type: boolean}
# Configuration for handling the API response.
response:
type: object
additionalProperties: false
properties:
# TODO(b/80311963): Support all resource paths here.
# The field in the response that is the id of the resource (just the
# name, not the relative name or URI). This is used to construct a
# URI for resources out of the result of a list command. If not
# provided, there won't be a --uri flag on the list command.
id_field: {type: string, pattern: "\\w+"}
# The attribute of the API response to return (instead of the entire
# response.
result_attribute: {$ref: "#/definitions/attribute"}
# If given, the response will be searched for error information and an
# exception raised if found. This is useful for batch request methods
# that return 200 even though something may have failed.
error:
type: object
additionalProperties: false
properties:
# The dotted path of the field whose presence indicates that an
# error has occured. This is 'error' by default if the error section
# is declared.
field: {$ref: "#/definitions/attribute"}
# If the error message is found, extract the error code from this
# field within that message.
code: {$ref: "#/definitions/attribute"}
# If the error message is found, extract the error message from this
# field within that message.
message: {$ref: "#/definitions/attribute"}
# The list of module paths to functions to call to modify the response
# returned by the API request. These functions take 2 arguments: the API
# response first and the parsed args namespace second. They must return a
# modified response. The functions are called in a chain, one after
# another, after result_attribute and error are processed, but before
# id_field.
modify_response_hooks:
type: array
items: {$ref: "#/definitions/python_hook"}
# If present, indicates that this API method uses operations and the --async
# flag will be set up.
async: &async
description: Describes how to poll and report the result of the operation
type: object
additionalProperties: false
required: [collection]
properties:
# The full collection name of the operation collection for this API.
# A list of collections is used whenever the request is a multitype ie
# a resource with different parent paths.
collection: {type: [string, array]}
# The API version to use, defaults to API version specified in the request
# section.
api_version: {type: string}
# The API method to call to get the operation ('get' by default).
method: {type: string}
# The message to print when the request is issued. The default depends on
# the command type.
request_issued_message: {type: string}
# The field in the operation message that corresponds to the operation's
# full name ('name' by default). Not used by Wait commands.
response_name_field: {type: string}
# Override whether the command should get the resulting resource after
# the operation is done, or just return the operation result. This is
# True by default (except for Delete and Wait commands).
extract_resource_result: {type: boolean}
# A mapping of method parameter to operation reference field for
# references or APIs that use non-standard naming.
operation_get_method_params:
type: object
patternProperties:
.*: {type: string}
# The attribute of the result to return from polling. If
# extract_resource_result is False, this is an attribute on the
# operation, if True it is on the resource itself.
result_attribute: {$ref: "#/definitions/attribute"}
# The module path to a function to call to modify the API request
# before it is invoked. All registered arguments will be processed
# into the request, before this is called. This is a function
# that takes 3 arguments: a resource ref to the parsed resource,
# the parsed args namespace, and the created request. It must return
# an apitools request message that will be passed to the API method
# defined in this section.
modify_request_hooks:
type: array
items: {$ref: "#/definitions/python_hook"}
state:
type: object
additionalProperties: false
required: [field, success_values]
properties:
# The field to check for status. Polling continues until it matches
# something in success_values or error_values. ('done' by default).
field: {type: string}
# Values that indicate that the operation is done and finished
# successfully. ('True' by default).
success_values: {type: array, items: {type: [boolean, string]}}
# Values that indicate that the operation is done but finished
# unsuccessfully. (Nothing by default).
error_values: {type: array, items: {type: [boolean, string]}}
error:
type: object
additionalProperties: false
required: [field]
properties:
# If this field is set when the operation completes, it will be
# used to generate an error message and polling stops. ('error' by
# default).
field: {type: string}
# Enumerates the API fields (other than those specifying the resource to act
# on) that arguments should be generated.
arguments:
type: object
additionalProperties: false
properties:
# The module path to a function to call to generate extra arguments
# that for whatever reason cannot be defined here. It is a function that
# takes no arguments and returns a list of calliope.base.Action
# objects that will be added to the parser. These arguments will not
# be processed automatically so you will need to implement
# request.modify_request_hooks to insert something into the request based
# on these arguments.
additional_arguments_hook: {$ref: "#/definitions/python_hook"}
# TODO(b/272076207): Remove resource when surfaces are updated
# This section declares how to generate the arguments and flags that
# correspond to the resource being operated on by this command.
resource:
description: Describes how to generate the resource arg and its flags
type: object
additionalProperties: false
required: [help_text, spec]
properties:
# The help text for the overall resource arg group.
help_text: {type: string}
# Set to False to force the anchor resource argument to be a flag
# even though it would normally be a positional. This should normally
# not be required for well formed API methods.
is_positional: {type: boolean}
# Set to True if the resource spec is for the parent of the request
# collection instead of for the collection itself. This allows for
# create commands that do not require a name for the new resource.
# Set the `resource_type` property on `request` to include the
# resource type in log messages.
is_parent_resource: {type: boolean}
# The name to use for the resource arg. If set this is the name that
# will be used for the resource arg in the command. If not set,
# command will use the name from the spec.
arg_name: {type: string}
# List of resource arg attributes to not generate flags for. These
# attributes will need to have fallthroughs in the resource arg spec
# in order to be populated.
removed_flags:
type: array
items: {type: string}
# a map of attribute names to a list of fallthroughs *specific to
# this command* that will be used if the attribute is not directly
# provided on the command line. Anything in this map takes precedence
# over what's specified in the resource spec by default.
command_level_fallthroughs:
type: object
patternProperties:
.*:
type: array
items: {$ref: "#/definitions/arg_fallthrough"}
# The resource arg specification itself. This corresponds to the
# ResourceSpec and ResourceParameterAttributeConfig objects and does
# not include anything that would go in a presentation spec. It is
# expected that this entire section be imported from a resources.yaml
# file in command_lib.
# (ex !REF googlecloudsdk.command_lib.pubsub.resources:topic)
spec:
oneOf:
# A regular resource arg
- $ref: "#/definitions/resource_spec"
# A multitype resource arg
- $ref: "#/definitions/multitype_resource_spec"
# A hook to get the display name of the parsed resource. Used for
# logging. Takes two arguments: the resource ref and a parsed args
# namespace.
# Example:
# def DisplayNameHook(resource_ref, args):
# if args.CONCEPTS.xyz.Parse().type_.name == 'parentType':
# return 'name not specified'
# return resource_ref.Name()
display_name_hook: {$ref: "#/definitions/python_hook"}
# If true, will disable validating that the resource arg schema matches the
# request method schema. This is useful for API's that have multiple services
# (and multiple resource collections) that use the same actual resource objects.
override_resource_collection: {type: boolean}
# Enumerates the API fields that need to be set and information
# about each argument to generate.
params:
type: array
items: {$ref: "#/definitions/argument"}
labels:
type: object
additionalProperties: false
description: Handles resource labels for resource create/update (go/api-label)
required: [api_field]
properties:
api_field: {type: string}
# Removes arguments from the parser
exclude:
type: array
items:
type: string
# Information about how to collect input from the user.
input:
type: object
additionalProperties: false
properties:
# An optional confirmation prompt to show before actually performing the
# operation. The string may have named format substitutions in it which
# will be replaced with attributes of the resource being operated on.
confirmation_prompt: {type: string}
default_continue: {type: boolean}
# Information about how to show output to the user.
output:
type: object
additionalProperties: false
properties:
# Corresponds to the default output format setting on the command.
format: {type: string}
# Corresponds to the default output flatten setting on the command.
flatten: {type: array}
# Additional information for handling the IAM Commands.
iam:
type: object
additionalProperties: false
properties:
# Path to the policy/updateMask fields in the SetIamRequest message for
# APIs that use non-standard naming.
# Example: 'setMyAPIIamPolicyRequest'
set_iam_policy_request_path: {type: string}
# A mapping of policy message type names to apitools message types for
# APIs that use non-standard naming.
# Example: policy: MyApiPolicy
message_type_overrides:
type: object
patternProperties:
.*: {type: string}
# The indicator for IAM condition. If True, the command can accept condition
# as part of a IAM policy binding. Default is False.
enable_condition: {type: boolean}
# Whether to hide special member types `allUsers` and `allAuthenticatedUsers` as potential
# values for the `member` flag. Default is False.
hide_special_member_types: {type: boolean}
# Override policy version. Default is None.
policy_version: {type: number}
# Path to the policy_version field for APIs that use non-standard mapping.
get_iam_policy_version_path: {type: string}
# Additional information for handling the update commands.
update:
type: object
additionalProperties: false
properties:
# True when the update command requires an extra get api call.
# False by default.
read_modify_update: {type: boolean}
# Disable the field mask auto generation in the update commands.
# False by default.
disable_auto_field_mask: {type: boolean}
# Additional information for generic commands
generic:
type: object
additionalProperties: false
properties:
# Used for commands where pagination is enabled. When pagination is enabled, list
# flags are automatically added. Setting disable_paging_flags prevents list
# flags from being automatically added. This allows users to opt out of flags or
# add their own flags
disable_paging_flags: {type: boolean}
# Additional information for handling the import commands.
import:
type: object
additionalProperties: false
properties:
# True when the import command should return early if it detects the imported resource
# has no changes from the resource on the service.
abort_if_equivalent: {type: boolean}
# True when the import command should create the resource if it does not already exist
# on the service.
create_if_not_exists: {type: boolean}
# Attributes about the create request the command will make if the resource does not already
# exist on the service. The create request will use all configuration from the parent
# request configuration unless explicitly specified here.
create_request: *request
# Attributes about the asynchronous behavior for the above create command. The create request
# will use all settings from the parent asynchronous configuration unless explicitly
# specified here.
create_async: *async
# If set, the create command will not use operations, and will not use the settings
# form the parent asynchronous configuration.
no_create_async: {type: boolean}