// SPDX-License-Identifier: Apache-2.0
syntax = "proto3";

package substrait.extensions;

import "google/protobuf/any.proto";

option csharp_namespace = "Substrait.Protobuf";
option go_package = "github.com/substrait-io/substrait-protobuf/go/substraitpb/extensions";
option java_multiple_files = true;
option java_package = "io.substrait.proto";

message SimpleExtensionURN {
  // A surrogate key used in the context of a single plan used to reference the
  // URN associated with an extension.
  // 0 is a valid anchor/reference, but prefer non-zero values for ergonomics.
  uint32 extension_urn_anchor = 1;

  // The extension URN that uniquely identifies this extension. This must follow the
  // format extension:<OWNER>:<ID> and serves as the "namespace" of this extension.
  string urn = 2;
}

// Describes a mapping between a specific extension entity and the URN where
// that extension can be found.
message SimpleExtensionDeclaration {
  oneof mapping_type {
    ExtensionType extension_type = 1;
    ExtensionTypeVariation extension_type_variation = 2;
    ExtensionFunction extension_function = 3;
  }

  // Describes a Type
  message ExtensionType {
    reserved 1;

    // references the extension_urn_anchor defined for a specific extension URN.
    uint32 extension_urn_reference = 4;

    // A surrogate key used in the context of a single plan to reference a
    // specific extension type.
    // 0 is a valid anchor/reference, but prefer non-zero values for ergonomics.
    uint32 type_anchor = 2;

    // the name of the type in the defined extension YAML.
    string name = 3;
  }

  message ExtensionTypeVariation {
    reserved 1;

    // references the extension_urn_anchor defined for a specific extension URN.
    uint32 extension_urn_reference = 4;

    // A surrogate key used in the context of a single plan to reference a
    // specific type variation.
    // Use non-zero values; 0 is reserved for the system-preferred variation.
    uint32 type_variation_anchor = 2;

    // the name of the type in the defined extension YAML.
    string name = 3;
  }

  message ExtensionFunction {
    reserved 1;

    // references the extension_urn_anchor defined for a specific extension URN.
    uint32 extension_urn_reference = 4;

    // A surrogate key used in the context of a single plan to reference a
    // specific function.
    // 0 is a valid anchor/reference, but prefer non-zero values for ergonomics.
    uint32 function_anchor = 2;

    // A function signature
    string name = 3;
  }
}

// A generic object that can be used to embed additional extension information
// into the serialized substrait plan.
message AdvancedExtension {
  // An optimization is helpful information that don't influence semantics. May
  // be ignored by a consumer.
  repeated google.protobuf.Any optimization = 1;

  // An enhancement alter semantics. Cannot be ignored by a consumer.
  google.protobuf.Any enhancement = 2;
}
