tableau.proto

// Protoconf - Tableau's data interchange format
// https://tableauio.github.io/

syntax = "proto3";

package tableau;

import "google/protobuf/descriptor.proto";

option go_package = "github.com/tableauio/tableau/proto/tableaupb";
option java_package = "com.tableau.protobuf";
option java_outer_classname = "TableauProto";
option java_multiple_files = true;
option objc_class_prefix = "TPB";
option csharp_namespace = "Tableau.Protobuf.Tableau";

// Option field numbers must be in the range 50000-99999. This range
// is reserved for internal use within individual organizations.

extend google.protobuf.FileOptions {
  WorkbookOptions workbook = 50000;
}

extend google.protobuf.MessageOptions {
  WorksheetOptions worksheet = 50000;
  bool union = 50001;
}

extend google.protobuf.FieldOptions {
  FieldOptions field = 50000;
}

extend google.protobuf.EnumOptions {
  EnumOptions etype = 50000;
}

extend google.protobuf.EnumValueOptions {
  EnumValueOptions evalue = 50000;
}

extend google.protobuf.OneofOptions {
  optional OneofOptions oneof = 50000;
}

message WorkbookOptions {
  string name = 1;  // Workbook name
}

message WorksheetOptions {
  // Worksheet name
  string name = 1;
  // Exact row number of column name definition at a worksheet.
  //
  // Default: 1.
  int32 namerow = 2;
  // Exact row number of column type definition at a worksheet.
  //
  // Default: 2.
  int32 typerow = 3;
  // Exact row number of column note definition at a worksheet.
  //
  // Default: 3.
  int32 noterow = 4;
  // Start row number of data at a worksheet.
  //
  // Default: 4.
  int32 datarow = 5;
  // Interchange the rows and columns of worksheet.
  bool transpose = 6;
  // Tags for usage, e.g.: "1,2" specifying loading servers. Specially,
  // "*" means all servers.
  string tags = 7;
  // The line number of column name definition in a cell. 0 means
  // the whole cell.
  //
  // Default: 0.
  int32 nameline = 8;
  // The line number of column type definition in a cell. 0 means
  // the whole cell.
  //
  // Default: 0.
  int32 typeline = 9;
  // Nested naming of the namerow.
  bool nested = 10;
  // Separator for:
  //    1. separating in-cell list elements.
  //    2. separating in-cell map items.
  //
  // Default: ",".
  string sep = 11;
  // Subseparator for separating in-cell map Key-Value pair.
  //
  // Default: ":".
  string subsep = 12;
  // Merger merge multiple workbook sheets (comma-separated) into one
  // with same schema. E.g.: Item1.xlsx,Item2.xlsx,ItemAward*.xlsx.
  repeated string merger = 13;
  // Merge adjacent rows with the same key. If the key cell is not set,
  // it will be treated the same as the nearest key above the same column.
  bool adjacent_key = 14;
  // In order to track field presence of basic types (numeric, string, bytes,
  // and enums), the generated field will be labeled "optional".
  bool field_presence = 15;
  // Indicate this XML sheet is a template or not. Template sheet structure will
  // only be parsed based on metasheet "@TABLEAU" in comments.
  bool template = 16;
  // Sheet mode.
  Mode mode = 17;
  // Scatter convert multiple workbook sheets (comma-separated) separately
  // with same schema. E.g.: Item1.xlsx,Item2.xlsx,ItemAward*.xlsx.
  repeated string scatter = 18;

  ////////// Loader related options below //////////
  // Generate OrderedMap accessers or not.
  bool ordered_map = 50;
  // Generate index accessers, and multiple index columns are comma-separated.
  // Format: <ColumnName>[@IndexName], if IndexName is not set, it will be this
  // column’s parent struct type name.
  //
  // Composite indexes (or multicolumn indexes) are in the form: ([column1, column2, column3,...])[@IndexName]
  //
  // Examples:
  //  - ID
  //  - ID@Item
  //  - (ID,Type)
  //  - (ID,Type)@Item
  //  - ID, (ID,Type)@Item
  repeated string index = 51;
}

message EnumOptions {
  string name = 1;  // Alias.
}
message EnumValueOptions {
  string name = 1;  // Alias.
}

message OneofOptions {
  string name = 1;   // Alias. NOT USED currently.
  string field = 2;  // Field name.
}

message FieldOptions {
  string name = 1;    // Scalar type's variable name or composite type's variable name (prefix).
  string note = 2;    // Field note, maybe in another language (Chinese) other than variable name (English).
  string key = 3;     // Only set when this field type is map or keyed-list.
  Layout layout = 4;  // For map/list types with cardinality. Default: LAYOUT_DEFAULT.
  Span span = 5;      // For list element or map value types. Default: SPAN_CROSS_CELL.
  string sep = 6;     // NOT USED yet. Default: ",".
  string subsep = 7;  // NOT USED yet. Default: ":".
  bool optional = 8;  // Whether the field is optional.

  FieldProp prop = 15;  // Property of field.
}

message FieldProp {
  // Usage: {range:"1,10" refer:"Item.ID"}

  // Different interpretations of range:
  //   - number: value range
  //   - string: count of utf-8 code point
  //
  // Format: "1,10", "1,~", "~,10".
  string range = 1;
  // Whether the map key is unique in column.
  // If not set, then auto deduce whether the map key is unique or not.
  optional bool unique = 2;
  // Ensure this field's value is in another sheet's
  // column value space (aka message's field value space).
  //
  // Format: "SheetName.ColumnName" or "SheetName(SheetAlias).ColumnName"
  //
  // Example:
  //  - "SheetName.ColumnName": e.g. "Item.ID", without sheet alias, and
  //    the sheet name is the generated protobuf message name.
  //  - "SheetName(SheetAlias).ColumnName": e.g. "Item(ItemConf).ID", with
  //    sheet alias, and sheet alias is the generated protobuf message name.
  string refer = 3;
  // Ensure this field's value is a sequence and begins with this value.
  // Mainly used for map key and list element.
  optional int64 sequence = 4;
  // Specify custom default value of scalar field.
  string default = 5;
  // Auto detect fixed size of horizontal list or map.
  //  - list size is detected by size of the max present list elements in name row.
  //  - map size is detected by size of the max present map items in name row.
  bool fixed = 6;
  // Specify fixed size of horizontal list or map.
  uint32 size = 7;
  // Specify cell data form for parsing.
  Form form = 8;
  // JSON name of this field. The value is set by protocol compiler. If the
  // user has set a "json_name" option on this field, that option's value
  // will be used. Otherwise, it's deduced from the field's name by converting
  // it to camelCase.
  string json_name = 9;
  // Must fill cell data explicitly if present is true, otherwise
  // an error will be reported.
  bool present = 10;
}

// Layout of list and map.
enum Layout {
  // Default:
  //  - vertical for struct map
  //  - incell for scalar map
  //  - horizontal for struct list
  //  - incell for scalar list
  LAYOUT_DEFAULT = 0;
  LAYOUT_VERTICAL = 1;    // Vertical
  LAYOUT_HORIZONTAL = 2;  // Horizontal
  LAYOUT_INCELL = 3;      // Incell
}

// Field data span of scalar and struct.
enum Span {
  // Default:
  //  - inner cell for scalar type: bool, string, bytes, number, and enum.
  //  - cross cell for struct type: map-value, list-element, and struct-field.
  SPAN_DEFAULT = 0;
  SPAN_CROSS_CELL = 1;  // The field data spans across multiple cells.
  SPAN_INNER_CELL = 2;  // The field data spans inside one cell.
}

// Sheet mode.
enum Mode {
  MODE_DEFAULT = 0;  // Default mode.
  // UE DataTable references:
  //  - https://docs.unrealengine.com/5.1/en-US/data-driven-gameplay-elements-in-unreal-engine/
  //  - https://docs.unrealengine.com/5.1/en-US/BlueprintAPI/EditorScripting/DataTable/
  MODE_UE_CSV = 1;       // CSV format of UE DataTable.
  MODE_UE_JSON = 2;      // JSON format of UE DataTable.
  MODE_ENUM_TYPE = 3;    // Enum type definition in sheet.
  MODE_STRUCT_TYPE = 4;  // Struct type definition in sheet.
  MODE_UNION_TYPE = 5;   // Union type definition in sheet.
}

// Cell data form.
enum Form {
  FORM_DEFAULT = 0;  // Default form which confgen parser defines.
  FORM_TEXT = 1;     // Refer: https://developers.google.com/protocol-buffers/docs/text-format-spec
  FORM_JSON = 2;     // Refer: https://developers.google.com/protocol-buffers/docs/proto3#json
}