googleapis/google/cloud/retail/v2/product.proto

// Copyright 2020 Google LLC
//
// 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.

syntax = "proto3";

package google.cloud.retail.v2;

import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/retail/v2/common.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

option csharp_namespace = "Google.Cloud.Retail.V2";
option go_package = "google.golang.org/genproto/googleapis/cloud/retail/v2;retail";
option java_multiple_files = true;
option java_outer_classname = "ProductProto";
option java_package = "com.google.cloud.retail.v2";
option objc_class_prefix = "RETAIL";
option php_namespace = "Google\\Cloud\\Retail\\V2";
option ruby_package = "Google::Cloud::Retail::V2";
option (google.api.resource_definition) = {
  type: "retail.googleapis.com/Branch"
  pattern: "projects/{project}/locations/{location}/catalogs/{catalog}/branches/{branch}"
};

// Product captures all metadata information of items to be recommended or
// searched.
message Product {
  option (google.api.resource) = {
    type: "retail.googleapis.com/Product"
    pattern: "projects/{project}/locations/{location}/catalogs/{catalog}/branches/{branch}/products/{product}"
  };

  // The type of this product.
  enum Type {
    // Default value. Default to
    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY] if unset.
    TYPE_UNSPECIFIED = 0;

    // The primary type.
    //
    // As the primary unit for predicting, indexing and search serving, a
    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
    // [Product][google.cloud.retail.v2.Product] is grouped with multiple
    // [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
    // [Product][google.cloud.retail.v2.Product]s.
    PRIMARY = 1;

    // The variant type.
    //
    // [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
    // [Product][google.cloud.retail.v2.Product]s usually share some common
    // attributes on the same
    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
    // [Product][google.cloud.retail.v2.Product]s, but they have variant
    // attributes like different colors, sizes and prices, etc.
    VARIANT = 2;

    // The collection type. Collection products are bundled
    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
    // [Product][google.cloud.retail.v2.Product]s or
    // [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
    // [Product][google.cloud.retail.v2.Product]s that are sold together, such
    // as a jewelry set with necklaces, earrings and rings, etc.
    COLLECTION = 3;
  }

  // Product availability. If this field is unspecified, the product is
  // assumed to be in stock.
  enum Availability {
    // Default product availability. Default to
    // [Availability.IN_STOCK][google.cloud.retail.v2.Product.Availability.IN_STOCK]
    // if unset.
    AVAILABILITY_UNSPECIFIED = 0;

    // Product in stock.
    IN_STOCK = 1;

    // Product out of stock.
    OUT_OF_STOCK = 2;

    // Product that is in pre-order state.
    PREORDER = 3;

    // Product that is back-ordered (i.e. temporarily out of stock).
    BACKORDER = 4;
  }

  // Immutable. Full resource name of the product, such as
  // `projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/product_id`.
  //
  // The branch ID must be "default_branch".
  string name = 1 [(google.api.field_behavior) = IMMUTABLE];

  // Immutable. [Product][google.cloud.retail.v2.Product] identifier, which is
  // the final component of [name][google.cloud.retail.v2.Product.name]. For
  // example, this field is "id_1", if
  // [name][google.cloud.retail.v2.Product.name] is
  // `projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/id_1`.
  //
  // This field must be a UTF-8 encoded string with a length limit of 128
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // Google Merchant Center property
  // [id](https://support.google.com/merchants/answer/6324405). Schema.org
  // Property [Product.sku](https://schema.org/sku).
  string id = 2 [(google.api.field_behavior) = IMMUTABLE];

  // Immutable. The type of the product. This field is output-only.
  Type type = 3 [(google.api.field_behavior) = IMMUTABLE];

  // Variant group identifier. Must be an
  // [id][google.cloud.retail.v2.Product.id], with the same parent branch with
  // this product. Otherwise, an error is thrown.
  //
  // For [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
  // [Product][google.cloud.retail.v2.Product]s, this field can only be empty or
  // set to the same value as [id][google.cloud.retail.v2.Product.id].
  //
  // For VARIANT [Product][google.cloud.retail.v2.Product]s, this field cannot
  // be empty. A maximum of 2,000 products are allowed to share the same
  // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
  // [Product][google.cloud.retail.v2.Product]. Otherwise, an INVALID_ARGUMENT
  // error is returned.
  //
  // Google Merchant Center Property
  // [item_group_id](https://support.google.com/merchants/answer/6324507).
  // Schema.org Property
  // [Product.inProductGroupWithID](https://schema.org/inProductGroupWithID).
  //
  // This field must be enabled before it can be used. [Learn
  // more](/recommendations-ai/docs/catalog#item-group-id).
  string primary_product_id = 4;

  // Product categories. This field is repeated for supporting one product
  // belonging to several parallel categories. Strongly recommended using the
  // full path for better search / recommendation quality.
  //
  //
  // To represent full path of category, use '>' sign to separate different
  // hierarchies. If '>' is part of the category name, please replace it with
  // other character(s).
  //
  // For example, if a shoes product belongs to both
  // ["Shoes & Accessories" -> "Shoes"] and
  // ["Sports & Fitness" -> "Athletic Clothing" -> "Shoes"], it could be
  // represented as:
  //
  //      "categories": [
  //        "Shoes & Accessories > Shoes",
  //        "Sports & Fitness > Athletic Clothing > Shoes"
  //      ]
  //
  // Must be set for [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
  // [Product][google.cloud.retail.v2.Product] otherwise an INVALID_ARGUMENT
  // error is returned.
  //
  // At most 250 values are allowed per
  // [Product][google.cloud.retail.v2.Product]. Empty values are not allowed.
  // Each value must be a UTF-8 encoded string with a length limit of 5,000
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // Google Merchant Center property
  // [google_product_category][mc_google_product_category]. Schema.org property
  // [Product.category] (https://schema.org/category).
  //
  // [mc_google_product_category]:
  // https://support.google.com/merchants/answer/6324436
  repeated string categories = 7;

  // Required. Product title.
  //
  // This field must be a UTF-8 encoded string with a length limit of 128
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // Google Merchant Center property
  // [title](https://support.google.com/merchants/answer/6324415). Schema.org
  // property [Product.name](https://schema.org/name).
  string title = 8 [(google.api.field_behavior) = REQUIRED];

  // Product description.
  //
  // This field must be a UTF-8 encoded string with a length limit of 5,000
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // Google Merchant Center property
  // [description](https://support.google.com/merchants/answer/6324468).
  // schema.org property [Product.description](https://schema.org/description).
  string description = 10;

  // Highly encouraged. Extra product attributes to be included. For example,
  // for products, this could include the store name, vendor, style, color, etc.
  // These are very strong signals for recommendation model, thus we highly
  // recommend providing the attributes here.
  //
  // Features that can take on one of a limited number of possible values. Two
  // types of features can be set are:
  //
  // Textual features. some examples would be the brand/maker of a product, or
  // country of a customer. Numerical features. Some examples would be the
  // height/weight of a product, or age of a customer.
  //
  // For example: `{ "vendor": {"text": ["vendor123", "vendor456"]},
  // "lengths_cm": {"numbers":[2.3, 15.4]}, "heights_cm": {"numbers":[8.1, 6.4]}
  // }`.
  //
  // A maximum of 150 attributes are allowed. Otherwise, an INVALID_ARGUMENT
  // error is returned.
  //
  // The key must be a UTF-8 encoded string with a length limit of 5,000
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  map<string, CustomAttribute> attributes = 12;

  // Custom tags associated with the product.
  //
  // At most 250 values are allowed per
  // [Product][google.cloud.retail.v2.Product]. This value must be a UTF-8
  // encoded string with a length limit of 1,000 characters. Otherwise, an
  // INVALID_ARGUMENT error is returned.
  //
  // This tag can be used for filtering recommendation results by passing the
  // tag as part of the
  // [PredictRequest.filter][google.cloud.retail.v2.PredictRequest.filter].
  //
  // Google Merchant Center property
  // [custom_label_0–4](https://support.google.com/merchants/answer/6324473).
  repeated string tags = 13;

  // Product price and cost information.
  //
  // Google Merchant Center property
  // [price](https://support.google.com/merchants/answer/6324371).
  PriceInfo price_info = 14;

  // The timestamp when this [Product][google.cloud.retail.v2.Product] becomes
  // available recommendation and search.
  google.protobuf.Timestamp available_time = 18;

  // The online availability of the [Product][google.cloud.retail.v2.Product].
  // Default to
  // [Availability.IN_STOCK][google.cloud.retail.v2.Product.Availability.IN_STOCK].
  //
  // Google Merchant Center Property
  // [availability](https://support.google.com/merchants/answer/6324448).
  // Schema.org Property [Offer.availability](https://schema.org/availability).
  Availability availability = 19;

  // The available quantity of the item.
  google.protobuf.Int32Value available_quantity = 20;

  // Canonical URL directly linking to the product detail page.
  //
  // This field must be a UTF-8 encoded string with a length limit of 5,000
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // Google Merchant Center property
  // [link](https://support.google.com/merchants/answer/6324416). Schema.org
  // property [Offer.url](https://schema.org/url).
  string uri = 22;

  // Product images for the product.
  //
  // A maximum of 300 images are allowed.
  //
  // Google Merchant Center property
  // [image_link](https://support.google.com/merchants/answer/6324350).
  // Schema.org property [Product.image](https://schema.org/image).
  repeated Image images = 23;
}