schema.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.pubsub.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.PubSub.V1";
option go_package = "google.golang.org/genproto/googleapis/pubsub/v1;pubsub";
option java_multiple_files = true;
option java_outer_classname = "SchemaProto";
option java_package = "com.google.pubsub.v1";
option php_namespace = "Google\\Cloud\\PubSub\\V1";
option ruby_package = "Google::Cloud::PubSub::V1";

// Service for doing schema-related operations.
service SchemaService {
  option (google.api.default_host) = "pubsub.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/pubsub";

  // Creates a schema.
  rpc CreateSchema(CreateSchemaRequest) returns (Schema) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*}/schemas"
      body: "schema"
    };
    option (google.api.method_signature) = "parent,schema,schema_id";
  }

  // Gets a schema.
  rpc GetSchema(GetSchemaRequest) returns (Schema) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/schemas/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists schemas in a project.
  rpc ListSchemas(ListSchemasRequest) returns (ListSchemasResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=projects/*}/schemas"
    };
    option (google.api.method_signature) = "parent";
  }

  // Deletes a schema.
  rpc DeleteSchema(DeleteSchemaRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/{name=projects/*/schemas/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Validates a schema.
  rpc ValidateSchema(ValidateSchemaRequest) returns (ValidateSchemaResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*}/schemas:validate"
      body: "*"
    };
    option (google.api.method_signature) = "parent,schema";
  }

  // Validates a message against a schema.
  rpc ValidateMessage(ValidateMessageRequest)
      returns (ValidateMessageResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*}/schemas:validateMessage"
      body: "*"
    };
  }
}

// A schema resource.
message Schema {
  option (google.api.resource) = {
    type: "pubsub.googleapis.com/Schema"
    pattern: "projects/{project}/schemas/{schema}"
  };

  // Possible schema definition types.
  enum Type {
    // Default value. This value is unused.
    TYPE_UNSPECIFIED = 0;

    // A Protocol Buffer schema definition.
    PROTOCOL_BUFFER = 1;

    // An Avro schema definition.
    AVRO = 2;
  }

  // Required. Name of the schema.
  // Format is `projects/{project}/schemas/{schema}`.
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // The type of the schema definition.
  Type type = 2;

  // The definition of the schema. This should contain a string representing
  // the full definition of the schema that is a valid schema definition of
  // the type specified in `type`.
  string definition = 3;
}

// Request for the CreateSchema method.
message CreateSchemaRequest {
  // Required. The name of the project in which to create the schema.
  // Format is `projects/{project-id}`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "pubsub.googleapis.com/Schema"
    }
  ];

  // Required. The schema object to create.
  //
  // This schema's `name` parameter is ignored. The schema object returned
  // by CreateSchema will have a `name` made using the given `parent` and
  // `schema_id`.
  Schema schema = 2 [(google.api.field_behavior) = REQUIRED];

  // The ID to use for the schema, which will become the final component of
  // the schema's resource name.
  //
  // See https://cloud.google.com/pubsub/docs/admin#resource_names for resource
  // name constraints.
  string schema_id = 3;
}

// View of Schema object fields to be returned by GetSchema and ListSchemas.
enum SchemaView {
  // The default / unset value.
  // The API will default to the BASIC view.
  SCHEMA_VIEW_UNSPECIFIED = 0;

  // Include the name and type of the schema, but not the definition.
  BASIC = 1;

  // Include all Schema object fields.
  FULL = 2;
}

// Request for the GetSchema method.
message GetSchemaRequest {
  // Required. The name of the schema to get.
  // Format is `projects/{project}/schemas/{schema}`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
  ];

  // The set of fields to return in the response. If not set, returns a Schema
  // with `name` and `type`, but not `definition`. Set to `FULL` to retrieve all
  // fields.
  SchemaView view = 2;
}

// Request for the `ListSchemas` method.
message ListSchemasRequest {
  // Required. The name of the project in which to list schemas.
  // Format is `projects/{project-id}`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/Project"
    }
  ];

  // The set of Schema fields to return in the response. If not set, returns
  // Schemas with `name` and `type`, but not `definition`. Set to `FULL` to
  // retrieve all fields.
  SchemaView view = 2;

  // Maximum number of schemas to return.
  int32 page_size = 3;

  // The value returned by the last `ListSchemasResponse`; indicates that
  // this is a continuation of a prior `ListSchemas` call, and that the
  // system should return the next page of data.
  string page_token = 4;
}

// Response for the `ListSchemas` method.
message ListSchemasResponse {
  // The resulting schemas.
  repeated Schema schemas = 1;

  // If not empty, indicates that there may be more schemas that match the
  // request; this value should be passed in a new `ListSchemasRequest`.
  string next_page_token = 2;
}

// Request for the `DeleteSchema` method.
message DeleteSchemaRequest {
  // Required. Name of the schema to delete.
  // Format is `projects/{project}/schemas/{schema}`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
  ];
}

// Request for the `ValidateSchema` method.
message ValidateSchemaRequest {
  // Required. The name of the project in which to validate schemas.
  // Format is `projects/{project-id}`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/Project"
    }
  ];

  // Required. The schema object to validate.
  Schema schema = 2 [(google.api.field_behavior) = REQUIRED];
}

// Response for the `ValidateSchema` method.
message ValidateSchemaResponse {}

// Request for the `ValidateMessage` method.
message ValidateMessageRequest {
  // Required. The name of the project in which to validate schemas.
  // Format is `projects/{project-id}`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/Project"
    }
  ];

  oneof schema_spec {
    // Name of the schema against which to validate.
    //
    // Format is `projects/{project}/schemas/{schema}`.
    string name = 2 [
      (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
    ];

    // Ad-hoc schema against which to validate
    Schema schema = 3;
  }

  // Message to validate against the provided `schema_spec`.
  bytes message = 4;

  // The encoding expected for messages
  Encoding encoding = 5;
}

// Response for the `ValidateMessage` method.
message ValidateMessageResponse {}

// Possible encoding types for messages.
enum Encoding {
  // Unspecified
  ENCODING_UNSPECIFIED = 0;

  // JSON encoding
  JSON = 1;

  // Binary encoding, as defined by the schema type. For some schema types,
  // binary encoding may not be available.
  BINARY = 2;
}