Protocol Buffers バージョン2 言語仕様

Protocol Buffers 言語のバージョン2 (proto2) の言語仕様リファレンス。

構文は拡張バッカス・ナウア記法 (EBNF) を用いて指定されています

|   alternation
()  grouping
[]  option (zero or one time)
{}  repetition (any number of times)

proto2 の使用に関する詳細については、言語ガイドを参照してください。

字句要素

文字と数字

letter = "A" ... "Z" | "a" ... "z"
capitalLetter =  "A" ... "Z"
decimalDigit = "0" ... "9"
octalDigit   = "0" ... "7"
hexDigit     = "0" ... "9" | "A" ... "F" | "a" ... "f"

識別子

ident = letter { letter | decimalDigit | "_" }
fullIdent = ident { "." ident }
messageName = ident
enumName = ident
fieldName = ident
oneofName = ident
mapName = ident
serviceName = ident
rpcName = ident
streamName = ident
messageType = [ "." ] { ident "." } messageName
enumType = [ "." ] { ident "." } enumName
groupName = capitalLetter { letter | decimalDigit | "_" }

整数リテラル

intLit     = decimalLit | octalLit | hexLit
decimalLit = [-] ( "1" ... "9" ) { decimalDigit }
octalLit   = [-] "0" { octalDigit }
hexLit     = [-] "0" ( "x" | "X" ) hexDigit { hexDigit }

浮動小数点リテラル

floatLit = [-] ( decimals "." [ decimals ] [ exponent ] | decimals exponent | "."decimals [ exponent ] ) | "inf" | "nan"
decimals  = [-] decimalDigit { decimalDigit }
exponent  = ( "e" | "E" ) [ "+" | "-" ] decimals

ブーリアン

boolLit = "true" | "false"

文字列リテラル

strLit = strLitSingle { strLitSingle }
strLitSingle = ( "'" { charValue } "'" ) | ( '"' { charValue } '"' )
charValue = hexEscape | octEscape | charEscape | unicodeEscape | unicodeLongEscape | /[^\0\n\\]/
hexEscape = '\' ( "x" | "X" ) hexDigit [ hexDigit ]
octEscape = '\' octalDigit [ octalDigit [ octalDigit ] ]
charEscape = '\' ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | '\' | "'" | '"' )
unicodeEscape = '\' "u" hexDigit hexDigit hexDigit hexDigit
unicodeLongEscape = '\' "U" ( "000" hexDigit hexDigit hexDigit hexDigit hexDigit |
                              "0010" hexDigit hexDigit hexDigit hexDigit

空のステートメント

emptyStatement = ";"

定数

constant = fullIdent | ( [ "-" | "+" ] intLit ) | ( [ "-" | "+" ] floatLit ) |
                strLit | boolLit | MessageValue

MessageValue はText Format 言語仕様で定義されています。

構文

syntax ステートメントは、protobuf のバージョンを定義するために使用されます。

syntax = "syntax" "=" ("'" "proto2" "'" | '"' "proto2" '"') ";"

import ステートメント

import ステートメントは、他の .proto ファイルの定義をインポートするために使用されます。

import = "import" [ "weak" | "public" ] strLit ";"

例

import public "other.proto";

パッケージ

パッケージ指定子は、プロトコルメッセージタイプ間の名前の衝突を防ぐために使用できます。

package = "package" fullIdent ";"

例

package foo.bar;

オプション

オプションは、proto ファイル、メッセージ、enum、サービスで使用できます。オプションは、protobuf 定義のオプションまたはカスタムオプションのいずれかです。詳細については、言語ガイドのオプションを参照してください。

option = "option" optionName  "=" constant ";"
optionName = ( ident | bracedFullIdent ) { "." ( ident | bracedFullIdent ) }
bracedFullIdent = "(" ["."] fullIdent ")"

例

option java_package = "com.example.foo";

フィールド

フィールドは、プロトコルバッファメッセージの基本的な要素です。フィールドには、通常フィールド、グループフィールド、oneof フィールド、マップフィールドがあります。フィールドには、ラベル、型、およびフィールド番号があります。

label = "required" | "optional" | "repeated"
type = "double" | "float" | "int32" | "int64" | "uint32" | "uint64"
      | "sint32" | "sint64" | "fixed32" | "fixed64" | "sfixed32" | "sfixed64"
      | "bool" | "string" | "bytes" | messageType | enumType
fieldNumber = intLit;

通常フィールド

各フィールドには、ラベル、型、名前、フィールド番号があります。また、フィールドオプションを持つことができます。

field = label type fieldName "=" fieldNumber [ "[" fieldOptions "]" ] ";"
fieldOptions = fieldOption { ","  fieldOption }
fieldOption = optionName "=" constant

例

optional foo.bar nested_message = 2;
repeated int32 samples = 4 [packed=true];

グループフィールド

この機能は非推奨であり、新しいメッセージタイプを作成する際には使用しないでください。代わりにネストされたメッセージタイプを使用してください。

グループは、メッセージ定義内で情報をネストする1つの方法です。グループ名は大文字で始める必要があります。

group = label "group" groupName "=" fieldNumber messageBody

例

repeated group Result = 1 {
    required string url = 1;
    optional string title = 2;
    repeated string snippets = 3;
}

Oneof と oneof フィールド

oneof は、oneof フィールドと oneof 名で構成されます。oneof フィールドにはラベルがありません。

oneof = "oneof" oneofName "{" { option | oneofField } "}"
oneofField = type fieldName "=" fieldNumber [ "[" fieldOptions "]" ] ";"

例

oneof foo {
    string name = 4;
    SubMessage sub_message = 9;
}

マップフィールド

マップフィールドには、キー型、値型、名前、フィールド番号があります。キー型は、任意の整数型または文字列型であることができます。キー型は enum にはできません。

mapField = "map" "<" keyType "," type ">" mapName "=" fieldNumber [ "[" fieldOptions "]" ] ";"
keyType = "int32" | "int64" | "uint32" | "uint64" | "sint32" | "sint64" |
          "fixed32" | "fixed64" | "sfixed32" | "sfixed64" | "bool" | "string"

例

map<string, Project> projects = 3;

拡張と予約

拡張と予約は、フィールド番号またはフィールド名の範囲を宣言するメッセージ要素です。

拡張

拡張は、メッセージ内のフィールド番号の範囲がサードパーティの拡張に利用可能であることを宣言します。他の開発者は、元のファイルを編集することなく、自身の .proto ファイル内でこれらの数値タグを使用して、あなたのメッセージタイプに新しいフィールドを宣言できます。

extensions = "extensions" ranges ";"
ranges = range { "," range }
range =  intLit [ "to" ( intLit | "max" ) ]

例

extensions 100 to 199;
extensions 4, 20 to max;

このトピックの詳細については、拡張宣言を参照してください。

予約

予約は、メッセージ内で使用できないフィールド番号またはフィールド名の範囲を宣言します。

reserved = "reserved" ( ranges | strFieldNames ) ";"
strFieldNames = strFieldName { "," strFieldName }
strFieldName = "'" fieldName "'" | '"' fieldName '"'

例

reserved 2, 15, 9 to 11;
reserved "foo", "bar";

トップレベル定義

Enum 定義

enum 定義は、名前と enum 本体で構成されます。enum 本体には、オプション、enum フィールド、および reserved ステートメントを含めることができます。

enum = "enum" enumName enumBody
enumBody = "{" { option | enumField | emptyStatement | reserved } "}"
enumField = ident "=" [ "-" ] intLit [ "[" enumValueOption { ","  enumValueOption } "]" ]";"
enumValueOption = optionName "=" constant

例

enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 2 [(custom_option) = "hello world"];
}

Message 定義

メッセージは、メッセージ名とメッセージ本体で構成されます。メッセージ本体には、フィールド、ネストされた enum 定義、ネストされたメッセージ定義、extend ステートメント、拡張、グループ、オプション、oneof、マップフィールド、および reserved ステートメントを含めることができます。同じメッセージスキーマ内で同じ名前の2つのフィールドを含めることはできません。

message = "message" messageName messageBody
messageBody = "{" { field | enum | message | extend | extensions | group |
option | oneof | mapField | reserved | emptyStatement } "}"

例

message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    required int64 ival = 1;
  }
  map<int32, string> my_map = 2;
  extensions 20 to 30;
}

メッセージ内で宣言されたエンティティは、名前の競合があってはなりません。以下はすべて禁止されています。

message MyMessage {
  optional string foo = 1;
  message foo {}
}

message MyMessage {
  optional string foo = 1;
  oneof foo {
    string bar = 2;
  }
}

message MyMessage {
  optional string foo = 1;
  extend Extendable {
    optional string foo = 2;
  }
}

message MyMessage {
  optional string foo = 1;
  enum E {
    foo = 0;
  }
}

Extend

同じまたはインポートされた .proto ファイル内のメッセージが拡張のために範囲を予約している場合、そのメッセージは拡張できます。

extend = "extend" messageType "{" {field | group} "}"

例

extend Foo {
  optional int32 bar = 126;
}

Service 定義

service = "service" serviceName "{" { option | rpc | emptyStatement } "}"
rpc = "rpc" rpcName "(" [ "stream" ] messageType ")" "returns" "(" [ "stream" ]
messageType ")" (( "{" { option | emptyStatement } "}" ) | ";" )

例

service SearchService {
  rpc Search (SearchRequest) returns (SearchResponse);
}

Proto ファイル

proto = [syntax] { import | package | option | topLevelDef | emptyStatement }
topLevelDef = message | enum | extend | service

proto ファイルの例

syntax = "proto2";
import public "other.proto";
option java_package = "com.example.foo";
enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 1;
  EAA_FINISHED = 2 [(custom_option) = "hello world"];
}
message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    required int64 ival = 1;
  }
  repeated Inner inner_message = 2;
  optional EnumAllowingAlias enum_field = 3;
  map<int32, string> my_map = 4;
  extensions 20 to 30;
}
message Foo {
  optional group GroupMessage = 1 {
    optional bool a = 1;
  }
}