{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cloud.google.com/storage/docs/json_api/v1/buckets",
  "title": "Google Cloud Storage Bucket",
  "description": "Schema for a Google Cloud Storage bucket resource as returned by the Cloud Storage JSON API v1. A bucket is a container for objects stored in Cloud Storage. Buckets are associated with a project, have globally unique names, and provide configuration for storage class, location, access control, lifecycle management, versioning, and encryption.",
  "type": "object",
  "required": ["name"],
  "properties": {
    "kind": {
      "type": "string",
      "const": "storage#bucket",
      "description": "The kind of item this is. For buckets, this is always storage#bucket."
    },
    "id": {
      "type": "string",
      "description": "The ID of the bucket. For buckets, this is the same value as the name property. Read-only.",
      "examples": ["my-bucket", "example-project-data"]
    },
    "selfLink": {
      "type": "string",
      "format": "uri",
      "description": "The URI of this bucket. Read-only.",
      "examples": ["https://storage.googleapis.com/storage/v1/b/my-bucket"]
    },
    "projectNumber": {
      "type": "string",
      "description": "The project number of the project the bucket belongs to. Read-only.",
      "examples": ["123456789012"]
    },
    "name": {
      "type": "string",
      "description": "The name of the bucket. Bucket names must be globally unique across all of Cloud Storage, contain only lowercase letters, numbers, hyphens, underscores, and dots, and must be between 3 and 63 characters long.",
      "minLength": 3,
      "maxLength": 63,
      "pattern": "^[a-z0-9][a-z0-9._-]{1,61}[a-z0-9]$",
      "examples": ["my-bucket", "example-project-data", "company.backups.2024"]
    },
    "timeCreated": {
      "type": "string",
      "format": "date-time",
      "description": "The creation time of the bucket in RFC 3339 format. Read-only.",
      "examples": ["2024-01-15T09:00:00.000Z"]
    },
    "updated": {
      "type": "string",
      "format": "date-time",
      "description": "The modification time of the bucket metadata in RFC 3339 format. Read-only.",
      "examples": ["2024-06-20T14:30:00.000Z"]
    },
    "metageneration": {
      "type": "string",
      "description": "The metadata generation of this bucket. Used for preconditions and for detecting changes in metadata. Every update to the bucket's metadata increments this value. Read-only.",
      "examples": ["1", "5"]
    },
    "location": {
      "type": "string",
      "description": "The location of the bucket. Object data for objects in the bucket resides in physical storage within this region. Can be a multi-region (e.g., US, EU, ASIA), dual-region (e.g., US-EAST1+US-WEST1), or single region (e.g., US-EAST1).",
      "examples": ["US", "US-EAST1", "EUROPE-WEST1", "ASIA-SOUTHEAST1"]
    },
    "locationType": {
      "type": "string",
      "description": "The type of location that the bucket resides in. Read-only.",
      "enum": ["multi-region", "region", "dual-region"]
    },
    "storageClass": {
      "type": "string",
      "description": "The default storage class of the bucket, used for newly created objects when no storage class is specified. Objects can be stored in Standard, Nearline, Coldline, or Archive storage.",
      "enum": ["STANDARD", "NEARLINE", "COLDLINE", "ARCHIVE"],
      "examples": ["STANDARD"]
    },
    "etag": {
      "type": "string",
      "description": "HTTP 1.1 Entity tag for the bucket. Read-only."
    },
    "defaultEventBasedHold": {
      "type": "boolean",
      "description": "Whether or not to automatically apply an event-based hold to new objects added to the bucket. Event-based holds remain on an object until explicitly removed.",
      "default": false
    },
    "rpo": {
      "type": "string",
      "description": "The Recovery Point Objective (RPO) of this bucket. Set to ASYNC_TURBO to enable Turbo Replication on dual-region buckets, providing a lower RPO of 15 minutes instead of the default.",
      "enum": ["DEFAULT", "ASYNC_TURBO"]
    },
    "acl": {
      "type": ["array", "null"],
      "description": "Access controls on the bucket, containing one or more bucketAccessControls resources. Not returned in list responses unless projection=full is specified.",
      "items": {
        "$ref": "#/$defs/BucketAccessControl"
      }
    },
    "defaultObjectAcl": {
      "type": ["array", "null"],
      "description": "Default access controls to apply to new objects when no ACL is provided.",
      "items": {
        "$ref": "#/$defs/ObjectAccessControl"
      }
    },
    "iamConfiguration": {
      "$ref": "#/$defs/IamConfiguration"
    },
    "encryption": {
      "type": ["object", "null"],
      "description": "Encryption configuration for the bucket. Specifies a default Cloud KMS key for encrypting objects inserted into this bucket.",
      "properties": {
        "defaultKmsKeyName": {
          "type": "string",
          "description": "A Cloud KMS key resource name that will be used to encrypt objects inserted into this bucket if no encryption method is specified. The key must be in the same location as the bucket.",
          "examples": ["projects/my-project/locations/us/keyRings/my-keyring/cryptoKeys/my-key"]
        }
      }
    },
    "lifecycle": {
      "type": ["object", "null"],
      "description": "The bucket's lifecycle configuration. Lifecycle management lets you set a Time to Live (TTL) for objects, or automatically transition objects to different storage classes based on conditions.",
      "properties": {
        "rule": {
          "type": "array",
          "description": "A lifecycle management rule, consisting of an action and the condition(s) under which the action will be taken.",
          "items": {
            "$ref": "#/$defs/LifecycleRule"
          }
        }
      }
    },
    "logging": {
      "type": ["object", "null"],
      "description": "The bucket's logging configuration, which defines the destination bucket and optional name prefix for the current bucket's access logs.",
      "properties": {
        "logBucket": {
          "type": "string",
          "description": "The destination bucket where the current bucket's access logs are placed."
        },
        "logObjectPrefix": {
          "type": "string",
          "description": "A prefix for log object names. Defaults to the name of the source bucket."
        }
      }
    },
    "versioning": {
      "type": ["object", "null"],
      "description": "The bucket's versioning configuration. When enabled, Cloud Storage retains a noncurrent object version each time a live object version is replaced or deleted.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether object versioning is fully enabled for the bucket."
        }
      }
    },
    "website": {
      "type": ["object", "null"],
      "description": "The bucket's website configuration, controlling how the service behaves when accessing bucket contents as a web site.",
      "properties": {
        "mainPageSuffix": {
          "type": "string",
          "description": "If the requested object path is missing, the service ensures the path has a trailing / and then appends this suffix. This allows the creation of index.html objects to represent directory pages.",
          "examples": ["index.html"]
        },
        "notFoundPage": {
          "type": "string",
          "description": "If the requested object path is missing and any mainPageSuffix object is missing, the service returns the named object from this bucket as the content for a 404 Not Found result.",
          "examples": ["404.html"]
        }
      }
    },
    "cors": {
      "type": ["array", "null"],
      "description": "The bucket's Cross-Origin Resource Sharing (CORS) configuration to support requests from web applications running in browsers.",
      "items": {
        "$ref": "#/$defs/CorsConfiguration"
      }
    },
    "retentionPolicy": {
      "type": ["object", "null"],
      "description": "The bucket's retention policy, which defines the minimum age an object in the bucket must reach before it can be deleted or replaced.",
      "properties": {
        "retentionPeriod": {
          "type": "string",
          "description": "The duration in seconds that objects need to be retained. Retention duration must be greater than zero and less than 100 years (3,155,760,000 seconds).",
          "examples": ["86400", "2592000"]
        },
        "effectiveTime": {
          "type": "string",
          "format": "date-time",
          "description": "The earliest date and time that the policy was effective. Read-only."
        },
        "isLocked": {
          "type": "boolean",
          "description": "Whether or not the retention policy is locked. A locked retention policy cannot be removed or the retention period shortened. Read-only once locked."
        }
      }
    },
    "softDeletePolicy": {
      "type": ["object", "null"],
      "description": "The bucket's soft delete policy. When enabled, deleted objects are retained for a specified period and can be recovered.",
      "properties": {
        "retentionDurationSeconds": {
          "type": "string",
          "description": "The number of seconds that soft-deleted objects will be retained and recoverable. Must be at least 604800 (7 days) and at most 7776000 (90 days).",
          "examples": ["604800", "2592000"]
        },
        "effectiveTime": {
          "type": "string",
          "format": "date-time",
          "description": "The time from which the soft delete policy is or will be effective. Read-only."
        }
      }
    },
    "autoclass": {
      "type": ["object", "null"],
      "description": "The bucket's Autoclass configuration. When enabled, Autoclass automatically transitions objects in the bucket to appropriate storage classes based on each object's access pattern.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether Autoclass is enabled for this bucket."
        },
        "toggleTime": {
          "type": "string",
          "format": "date-time",
          "description": "The time at which Autoclass was last enabled or disabled for the bucket. Read-only."
        },
        "terminalStorageClass": {
          "type": "string",
          "description": "The storage class that objects in the bucket eventually transition to if they are not read for a certain length of time. Valid values are NEARLINE and ARCHIVE.",
          "enum": ["NEARLINE", "ARCHIVE"]
        },
        "terminalStorageClassUpdateTime": {
          "type": "string",
          "format": "date-time",
          "description": "The time at which the terminal storage class was last updated. Read-only."
        }
      }
    },
    "hierarchicalNamespace": {
      "type": ["object", "null"],
      "description": "The bucket's hierarchical namespace configuration. When enabled, the bucket supports folders and managed folders as organizational structures.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether hierarchical namespace is enabled for the bucket."
        }
      }
    },
    "labels": {
      "type": ["object", "null"],
      "description": "User-provided labels, in key/value pairs. Labels are used to organize and filter buckets. Keys and values must be 63 characters or less and conform to RFC 1035.",
      "additionalProperties": {
        "type": "string"
      },
      "examples": [
        {
          "environment": "production",
          "team": "data-engineering"
        }
      ]
    },
    "customPlacementConfig": {
      "type": ["object", "null"],
      "description": "The bucket's custom placement configuration for Custom Dual Regions.",
      "properties": {
        "dataLocations": {
          "type": "array",
          "description": "The list of regional locations in which data is placed.",
          "items": {
            "type": "string"
          },
          "minItems": 2,
          "maxItems": 2,
          "examples": [["US-EAST1", "US-WEST1"]]
        }
      }
    },
    "satisfiesPZS": {
      "type": "boolean",
      "description": "Whether the bucket satisfies zone separation requirements. Read-only."
    }
  },
  "additionalProperties": true,
  "$defs": {
    "BucketAccessControl": {
      "type": "object",
      "description": "An access-control entry for a bucket.",
      "required": ["entity", "role"],
      "properties": {
        "kind": {
          "type": "string",
          "const": "storage#bucketAccessControl",
          "description": "The kind of item this is."
        },
        "id": {
          "type": "string",
          "description": "The ID of the access-control entry."
        },
        "selfLink": {
          "type": "string",
          "format": "uri",
          "description": "The link to this access-control entry."
        },
        "bucket": {
          "type": "string",
          "description": "The name of the bucket."
        },
        "entity": {
          "type": "string",
          "description": "The entity holding the permission, in one of the following forms: user-userId, user-email, group-groupId, group-email, domain-domain, project-team-projectId, allUsers, or allAuthenticatedUsers.",
          "examples": ["user-example@gmail.com", "group-admins@example.com", "allUsers"]
        },
        "role": {
          "type": "string",
          "description": "The access permission for the entity.",
          "enum": ["OWNER", "WRITER", "READER"]
        },
        "email": {
          "type": ["string", "null"],
          "format": "email",
          "description": "The email address associated with the entity, if any."
        },
        "domain": {
          "type": ["string", "null"],
          "description": "The domain associated with the entity, if any."
        },
        "entityId": {
          "type": ["string", "null"],
          "description": "The ID for the entity, if any."
        },
        "etag": {
          "type": "string",
          "description": "HTTP 1.1 Entity tag for the access-control entry."
        },
        "projectTeam": {
          "type": ["object", "null"],
          "description": "The project team associated with the entity, if any.",
          "properties": {
            "projectNumber": {
              "type": "string",
              "description": "The project number."
            },
            "team": {
              "type": "string",
              "description": "The team.",
              "enum": ["editors", "owners", "viewers"]
            }
          }
        }
      }
    },
    "ObjectAccessControl": {
      "type": "object",
      "description": "An access-control entry for an object or default object ACL on a bucket.",
      "required": ["entity", "role"],
      "properties": {
        "kind": {
          "type": "string",
          "const": "storage#objectAccessControl",
          "description": "The kind of item this is."
        },
        "id": {
          "type": "string",
          "description": "The ID of the access-control entry."
        },
        "selfLink": {
          "type": "string",
          "format": "uri",
          "description": "The link to this access-control entry."
        },
        "bucket": {
          "type": "string",
          "description": "The name of the bucket."
        },
        "object": {
          "type": ["string", "null"],
          "description": "The name of the object, if applied to an object."
        },
        "generation": {
          "type": ["string", "null"],
          "description": "The content generation of the object, if applied to an object."
        },
        "entity": {
          "type": "string",
          "description": "The entity holding the permission.",
          "examples": ["user-example@gmail.com", "allUsers"]
        },
        "role": {
          "type": "string",
          "description": "The access permission for the entity.",
          "enum": ["OWNER", "READER"]
        },
        "email": {
          "type": ["string", "null"],
          "format": "email",
          "description": "The email address associated with the entity, if any."
        },
        "domain": {
          "type": ["string", "null"],
          "description": "The domain associated with the entity, if any."
        },
        "entityId": {
          "type": ["string", "null"],
          "description": "The ID for the entity, if any."
        },
        "etag": {
          "type": "string",
          "description": "HTTP 1.1 Entity tag for the access-control entry."
        },
        "projectTeam": {
          "type": ["object", "null"],
          "description": "The project team associated with the entity, if any.",
          "properties": {
            "projectNumber": {
              "type": "string",
              "description": "The project number."
            },
            "team": {
              "type": "string",
              "description": "The team.",
              "enum": ["editors", "owners", "viewers"]
            }
          }
        }
      }
    },
    "IamConfiguration": {
      "type": ["object", "null"],
      "description": "The bucket's IAM configuration, including uniform bucket-level access and public access prevention settings.",
      "properties": {
        "uniformBucketLevelAccess": {
          "type": ["object", "null"],
          "description": "The bucket's uniform bucket-level access configuration. When enabled, access is controlled exclusively through IAM policies and ACLs are disabled.",
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Whether uniform bucket-level access is enabled. Once the lock time passes, this becomes permanent."
            },
            "lockedTime": {
              "type": ["string", "null"],
              "format": "date-time",
              "description": "The deadline for changing iamConfiguration.uniformBucketLevelAccess.enabled from true to false. After the deadline passes, the configuration becomes immutable."
            }
          }
        },
        "publicAccessPrevention": {
          "type": "string",
          "description": "The bucket's public access prevention configuration. When set to enforced, prevents ACLs and IAM policies from granting public access.",
          "enum": ["inherited", "enforced"]
        }
      }
    },
    "LifecycleRule": {
      "type": "object",
      "description": "A lifecycle management rule, which is made of an action to take and the condition(s) under which the action will be taken.",
      "properties": {
        "action": {
          "type": "object",
          "description": "The action to take when lifecycle conditions are met.",
          "properties": {
            "type": {
              "type": "string",
              "description": "Type of the action. Delete permanently deletes the object, SetStorageClass changes the storage class, and AbortIncompleteMultipartUpload aborts incomplete multipart uploads.",
              "enum": ["Delete", "SetStorageClass", "AbortIncompleteMultipartUpload"]
            },
            "storageClass": {
              "type": "string",
              "description": "Target storage class. Required only when the action type is SetStorageClass.",
              "enum": ["STANDARD", "NEARLINE", "COLDLINE", "ARCHIVE"]
            }
          },
          "required": ["type"]
        },
        "condition": {
          "type": "object",
          "description": "The condition(s) under which the action will be taken. All conditions must be met for the action to occur.",
          "properties": {
            "age": {
              "type": "integer",
              "description": "Age of an object in days. The condition is satisfied when an object reaches the specified age.",
              "minimum": 0,
              "examples": [30, 90, 365]
            },
            "createdBefore": {
              "type": "string",
              "format": "date",
              "description": "A date in RFC 3339 format (YYYY-MM-DD). Objects created before midnight of this date satisfy the condition."
            },
            "customTimeBefore": {
              "type": "string",
              "format": "date",
              "description": "A date in RFC 3339 format (YYYY-MM-DD). Objects whose custom time is earlier than this date satisfy the condition."
            },
            "daysSinceCustomTime": {
              "type": "integer",
              "description": "Number of days elapsed since the user-specified custom time.",
              "minimum": 0
            },
            "daysSinceNoncurrentTime": {
              "type": "integer",
              "description": "Number of days elapsed since the noncurrent timestamp of an object. Relevant only for versioned objects.",
              "minimum": 0
            },
            "isLive": {
              "type": ["boolean", "null"],
              "description": "Relevant only for versioned objects. If true, this condition matches live objects; if false, it matches noncurrent objects."
            },
            "matchesPattern": {
              "type": "string",
              "description": "A regular expression that satisfies the RE2 syntax. This condition is satisfied when the name of the object matches the pattern."
            },
            "matchesPrefix": {
              "type": "array",
              "description": "Objects having any of the specified name prefixes satisfy this condition.",
              "items": {
                "type": "string"
              }
            },
            "matchesSuffix": {
              "type": "array",
              "description": "Objects having any of the specified name suffixes satisfy this condition.",
              "items": {
                "type": "string"
              }
            },
            "matchesStorageClass": {
              "type": "array",
              "description": "Objects having any of the storage classes specified by this condition satisfy this condition.",
              "items": {
                "type": "string",
                "enum": ["STANDARD", "NEARLINE", "COLDLINE", "ARCHIVE", "MULTI_REGIONAL", "REGIONAL", "DURABLE_REDUCED_AVAILABILITY"]
              }
            },
            "noncurrentTimeBefore": {
              "type": "string",
              "format": "date",
              "description": "A date in RFC 3339 format (YYYY-MM-DD). Objects whose noncurrent time is earlier than this date satisfy the condition."
            },
            "numNewerVersions": {
              "type": "integer",
              "description": "Relevant only for versioned objects. If the value is N, this condition is satisfied when there are at least N versions (including the live version) newer than this version of the object.",
              "minimum": 0
            }
          }
        }
      }
    },
    "CorsConfiguration": {
      "type": "object",
      "description": "A CORS configuration entry for the bucket.",
      "properties": {
        "origin": {
          "type": "array",
          "description": "The list of Origins eligible to receive CORS response headers. The value * is permitted as a wildcard.",
          "items": {
            "type": "string"
          },
          "examples": [["https://example.com", "https://app.example.com"]]
        },
        "method": {
          "type": "array",
          "description": "The list of HTTP methods on which to include CORS response headers (GET, OPTIONS, POST, etc.). The value * is permitted as a wildcard.",
          "items": {
            "type": "string"
          },
          "examples": [["GET", "POST", "PUT", "DELETE"]]
        },
        "responseHeader": {
          "type": "array",
          "description": "The list of HTTP headers other than the simple response headers to give permission for the user-agent to share across domains.",
          "items": {
            "type": "string"
          },
          "examples": [["Content-Type", "x-goog-meta-*"]]
        },
        "maxAgeSeconds": {
          "type": "integer",
          "description": "The value, in seconds, to return in the Access-Control-Max-Age header used in preflight responses.",
          "minimum": 0,
          "examples": [3600]
        }
      }
    }
  }
}