エディションの機能設定

Protobufエディションの機能と、それらがProtobufの挙動にどのように影響するか。

このトピックでは、リリース済みのエディションバージョンに含まれる機能の概要を説明します。以降のエディションの機能は、このトピックに追加されます。新しいエディションについては、ニュースセクションでお知らせします。

新しいスキーマ定義コンテンツで機能設定を構成する前に、なぜそれらを使用しているのかを必ず理解してください。機能のカーゴカルトは避けてください。

Prototiller

Prototillerは、シンタックスバージョンとエディション間でprotoスキーマ構成ファイルを更新するコマンドラインツールです。まだリリースされていませんが、このトピック全体で参照されています。

機能

以下のセクションには、エディションの機能を使用して構成可能なすべての挙動が含まれています。proto2またはproto3の挙動の維持では、proto定義ファイルがproto2またはproto3ファイルのように動作するように、デフォルトの挙動をオーバーライドする方法を示します。エディションと機能が連携して挙動を設定する方法の詳細については、Protobufエディションの概要を参照してください。

機能設定は異なるレベルで適用される

ファイルレベル: これらの設定は、オーバーライド設定を持たないすべての要素（メッセージ、フィールド、enumなど）に適用されます。

非ネスト: メッセージ、enum、およびサービスは、ファイルレベルで行われた設定をオーバーライドできます。それらは、オーバーライドされない限り、その中のすべて（メッセージフィールド、enum値）に適用されますが、他の並列のメッセージやenumには適用されません。

ネスト: oneof、メッセージ、およびenumは、ネストされているメッセージからの設定をオーバーライドできます。

最下位レベル: フィールド、拡張、enum値、拡張範囲、およびメソッドは、設定をオーバーライドできる最下位レベルです。

以下の各セクションには、機能が適用できるスコープを示すコメントがあります。次のサンプルは、各スコープに適用されたモック機能を示しています

edition = "2024";

// File-level scope definition
option features.bar = BAZ;

enum Foo {
  // Enum (non-nested scope) definition
  option features.bar = QUX;

  A = 1;
  B = 2;
}

message Corge {
  // Message (non-nested scope) definition
  option features.bar = QUUX;

  message Garply {
    // Message (nested scope) definition
    option features.bar = WALDO;
    string id = 1;
  }

  // Field (lowest-level scope) definition
  Foo A = 1 [features.bar = GRAULT];
}

«««< HEAD この例では、最下位レベルのスコープ機能定義の「GRAULT"」設定が、非ネストスコープの「QUUX」設定をオーバーライドします。また、Garplyメッセージ内では、「WALDO」が「QUUX」をオーバーライドします。

«««< HEAD

`features.default_symbol_visibility`

この機能は、メッセージとenumのデフォルトの可視性を設定し、他のprotoからインポートされたときにそれらを利用可能または利用不可にすることを可能にします。この機能を使用すると、デッドシンボルが削減され、より小さなバイナリを作成できます。

ファイル全体にデフォルトを設定するのに加えて、localおよびexportキーワードを使用して、フィールドごとの挙動を設定できます。詳細については、export / local キーワードを参照してください。

利用可能な値

EXPORT_ALL: これはEdition 2024より前のデフォルトです。すべてのメッセージとenumはデフォルトでエクスポートされます。
EXPORT_TOP_LEVEL: すべてのトップレベルシンボルはデフォルトでエクスポートされ、ネストされたシンボルはデフォルトでローカルになります。
LOCAL_ALL: すべてのシンボルはデフォルトでローカルになります。
STRICT: すべてのシンボルはデフォルトでローカルです。ネストされた型はエクスポートできませんが、メッセージ { enum {} reserved 1 to max; } の特別なケースの注意点があります。これは新しいprotoに推奨される設定です。

適用可能なスコープ: Enum, Message

追加されたバージョン: Edition 2024

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`EXPORT_TOP_LEVEL`
2023	`EXPORT_ALL`
proto3	`EXPORT_ALL`
proto2	`EXPORT_ALL`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のサンプルは、protoスキーマ定義ファイルの要素に機能を適用する方法を示しています

// foo.proto
edition = "2024";

// Symbol visibility defaults to EXPORT_TOP_LEVEL. Setting
// default_symbol_visibility overrides these defaults
option features.default_symbol_visibility = LOCAL_ALL;

// Top-level symbols are exported by default in Edition 2024; applying the local
// keyword overrides this
export message LocalMessage {
  int32 baz = 1;
  // Nested symbols are local by default in Edition 2024; applying the export
  // keyword overrides this
  enum ExportedNestedEnum {
    UNKNOWN_EXPORTED_NESTED_ENUM_VALUE = 0;
  }
}

// bar.proto
edition = "2024";

import "foo.proto";

message ImportedMessage {
  // The following is valid because the imported message explicitly overrides
  // the visibility setting in foo.proto
  LocalMessage bar = 1;

  // The following is not valid because default_symbol_visibility is set to
  // `LOCAL_ALL`
  // LocalMessage.ExportedNestedEnum qux = 2;
}

`features.enforce_naming_style`

Edition 2024で導入されたこの機能は、スタイルガイドで定義されている厳格な命名スタイル強制を有効にし、protoがデフォルトでラウンドトリップ可能であることを保証します。オプトアウトするには機能値を使用します

利用可能な値

STYLE2024: 命名に関するスタイルガイドへの厳格な準拠を強制します。
STYLE_LEGACY: Edition 2024以前のレベルのスタイルガイド強制を適用します。

適用可能なスコープ: File

追加されたバージョン 2024

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`STYLE2024`
2023	`STYLE_LEGACY`
proto3	`STYLE_LEGACY`
proto2	`STYLE_LEGACY`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルは、Edition 2023のファイルを示しています

Edition 2023はデフォルトで STYLE_LEGACY になるため、非準拠のフィールド名は問題ありません

edition = "2023";

message Foo {
  // A non-conforming field name is not a problem
  int64 bar_1 = 1;
}

Edition 2025はデフォルトで STYLE2024 になるため、非準拠のフィールド名を維持するにはオーバーライドが必要です

edition = "2024";

// To keep the non-conformant field name, override the STYLE2024 setting
option features.enforce_naming_style = "STYLE_LEGACY";

message Foo {
  int64 bar_1 = 1;
}

||||||| dcf50a2 の親 (このドキュメントの変更には以下が含まれます:) この例では、フィールドスコープの機能定義の `GRAULT` 設定が、メッセージスコープの QUUX 設定をオーバーライドします。

この例では、最下位レベルのスコープ機能定義の「GRAULT"」設定が、非ネストスコープの「QUUX」設定をオーバーライドします。また、Garplyメッセージ内では、「WALDO」が「QUUX」をオーバーライドします。

dcf50a2 (このドキュメントの変更には以下が含まれます:)

||||||| 81fd217 の親 (このドキュメントの変更には以下が含まれます:)

`features.default_symbol_visibility`

利用可能な値

EXPORT_ALL: これはEdition 2024より前のデフォルトです。すべてのメッセージとenumはデフォルトでエクスポートされます。
EXPORT_TOP_LEVEL: すべてのトップレベルシンボルはデフォルトでエクスポートされ、ネストされたシンボルはデフォルトでローカルになります。
LOCAL_ALL: すべてのシンボルはデフォルトでローカルになります。
STRICT: すべてのシンボルはデフォルトでローカルです。ネストされた型はエクスポートできませんが、メッセージ { enum {} reserved 1 to max; } の特別なケースの注意点があります。これは新しいprotoに推奨される設定です。

適用可能なスコープ: Enum, Message

追加されたバージョン: Edition 2024

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`EXPORT_TOP_LEVEL`
2023	`EXPORT_ALL`
proto3	`EXPORT_ALL`
proto2	`EXPORT_ALL`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のサンプルは、protoスキーマ定義ファイルの要素に機能を適用する方法を示しています

// foo.proto
edition = "2024";

// Symbol visibility defaults to EXPORT_TOP_LEVEL. Setting
// default_symbol_visibility overrides these defaults
option features.default_symbol_visibility = LOCAL_ALL;

// Top-level symbols are exported by default in Edition 2024; applying the local
// keyword overrides this
export message LocalMessage {
  int32 baz = 1;
  // Nested symbols are local by default in Edition 2024; applying the export
  // keyword overrides this
  enum ExportedNestedEnum {
    UNKNOWN_EXPORTED_NESTED_ENUM_VALUE = 0;
  }
}

// bar.proto
edition = "2024";

import "foo.proto";

message ImportedMessage {
  // The following is valid because the imported message explicitly overrides
  // the visibility setting in foo.proto
  LocalMessage bar = 1;

  // The following is not valid because default_symbol_visibility is set to
  // `LOCAL_ALL`
  // LocalMessage.ExportedNestedEnum qux = 2;
}

`features.enforce_naming_style`

利用可能な値

STYLE2024: 命名に関するスタイルガイドへの厳格な準拠を強制します。
STYLE_LEGACY: Edition 2024以前のレベルのスタイルガイド強制を適用します。

適用可能なスコープ: File

追加されたバージョン 2024

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`STYLE2024`
2023	`STYLE_LEGACY`
proto3	`STYLE_LEGACY`
proto2	`STYLE_LEGACY`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルは、Edition 2023のファイルを示しています

Edition 2023はデフォルトで STYLE_LEGACY になるため、非準拠のフィールド名は問題ありません

edition = "2023";

message Foo {
  // A non-conforming field name is not a problem
  int64 bar_1 = 1;
}

Edition 2025はデフォルトで STYLE2024 になるため、非準拠のフィールド名を維持するにはオーバーライドが必要です

edition = "2024";

// To keep the non-conformant field name, override the STYLE2024 setting
option features.enforce_naming_style = "STYLE_LEGACY";

message Foo {
  int64 bar_1 = 1;
}

81fd217 (このドキュメントの変更には以下が含まれます:)

`features.enum_type`

この機能は、定義されたセットに含まれていないenum値がどのように処理されるかの挙動を設定します。openおよびclosed enumの詳細については、Enumの挙動を参照してください。

この機能はproto3ファイルには影響しないため、このセクションにはproto3ファイルの変更前後の例はありません。

利用可能な値

CLOSED: Closed enumは、範囲外のenum値をunknown field setに格納します。
OPEN: Open enumは、範囲外の値を直接そのフィールドにパースします。

適用可能なスコープ: File, Enum

追加されたバージョン 2023

シンタックス/エディションごとのデフォルトの挙動

«««< HEAD

シンタックス/エディション	デフォルト
2024	`OPEN`
2023	`OPEN`
proto3	`OPEN`
proto2	`CLOSED`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `OPEN`

シンタックス/エディション	デフォルト
2024	`OPEN`
2023	`OPEN`
proto3	`OPEN`
proto2	`CLOSED`

81fd217 (このドキュメントの変更には以下が含まれます:)

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

enum Foo {
  A = 2;
  B = 4;
  C = 6;
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

enum Foo {
  // Setting the enum_type feature overrides the default OPEN enum
  option features.enum_type = CLOSED;
  A = 2;
  B = 4;
  C = 6;
}

`features.field_presence`

この機能は、フィールドのプレゼンス、つまりprotobufフィールドに値があるかどうかの概念を追跡するための挙動を設定します。

利用可能な値

LEGACY_REQUIRED: フィールドはパースとシリアライズに必須です。明示的に設定された値はすべて（デフォルト値と同じであっても）ワイヤにシリアライズされます。
EXPLICIT: フィールドには明示的なプレゼンス追跡があります。明示的に設定された値はすべて（デフォルト値と同じであっても）ワイヤにシリアライズされます。単数のプリミティブフィールドの場合、EXPLICITに設定されたフィールドに対してhas_*関数が生成されます。
IMPLICIT: フィールドにはプレゼンス追跡がありません。デフォルト値は（明示的に設定されていても）ワイヤにシリアライズされません。IMPLICITに設定されたフィールドに対してhas_*関数は生成されません。

適用可能なスコープ: File, Field

«««< HEAD «««< HEAD 追加されたバージョン: 2023 ||||||| dcf50a2の親 (このドキュメントの変更には以下が含まれます:) Edition 2023でのデフォルト値: `EXPLICIT`

Edition 2023でのデフォルトの挙動: EXPLICIT

dcf50a2 (このドキュメントの変更には以下が含まれます:) ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) Edition 2023でのデフォルトの挙動: EXPLICIT ======= 追加されたバージョン: 2023 81fd217 (このドキュメントの変更には以下が含まれます:)

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`EXPLICIT`
2023	`EXPLICIT`
proto3	`IMPLICIT`*
proto2	`EXPLICIT`

* proto3はIMPLICITですが、フィールドにoptionalラベルがある場合はEXPLICITのように動作します。詳細については、Proto3 APIにおけるプレゼンスを参照してください。

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

message Foo {
  required int32 x = 1;
  optional int32 y = 2;
  repeated int32 z = 3;
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

message Foo {
  // Setting the field_presence feature retains the proto2 required behavior
  int32 x = 1 [features.field_presence = LEGACY_REQUIRED];
  int32 y = 2;
  repeated int32 z = 3;
}

以下はproto3ファイルを示しています

syntax = "proto3";

message Bar {
  int32 x = 1;
  optional int32 y = 2;
  repeated int32 z = 3;
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

<<<<<<< HEAD
<<<<<<< HEAD
edition = "2024";
// Setting the file-level field_presence feature matches the proto3 implicit default
||||||| parent of dcf50a2 (This documentation change includes the following:)
edition = "2023";
=======
edition = "2023";
||||||| parent of 81fd217 (This documentation change includes the following:)
edition = "2023";
=======
edition = "2024";
>>>>>>> 81fd217 (This documentation change includes the following:)
// Setting the file-level field_presence feature matches the proto3 implicit default
>>>>>>> dcf50a2 (This documentation change includes the following:)
option features.field_presence = IMPLICIT;

message Bar {
  int32 x = 1;
  // Setting the field_presence here retains the explicit state that the proto3
  // field has because of the optional syntax
  int32 y = 2 [features.field_presence = EXPLICIT];
  repeated int32 z = 3;
}

エディションでは、requiredおよびoptionalラベルはもはや存在しないことに注意してください。対応する挙動はfield_presence機能で明示的に設定されます。

`features.json_format`

この機能は、JSONのパースとシリアライズの挙動を設定します。

この機能はproto3ファイルには影響しないため、このセクションにはproto3ファイルの変更前後の例はありません。エディションの挙動はproto3の挙動と一致します。

利用可能な値

ALLOW: ランタイムはJSONのパースとシリアライズを許可する必要があります。JSONへの明確なマッピングが存在することを確認するために、protoレベルでチェックが適用されます。
LEGACY_BEST_EFFORT: ランタイムはJSONのパースとシリアライズに最善を尽くします。ランタイムで未指定の挙動（多対1または1対多のマッピングなど）を引き起こす可能性のある特定のprotoが許可されます。

適用可能なスコープ: File, Message, Enum

追加されたバージョン 2023

シンタックス/エディションごとのデフォルトの挙動

«««< HEAD

シンタックス/エディション	デフォルト
2024	`ALLOW`
2023	`ALLOW`
proto3	`ALLOW`
proto2	`LEGACY_BEST_EFFORT`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `ALLOW`

シンタックス/エディション	デフォルト
2024	`ALLOW`
2023	`ALLOW`
proto3	`ALLOW`
proto2	`LEGACY_BEST_EFFORT`

81fd217 (このドキュメントの変更には以下が含まれます:)

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

message Foo {
  // Warning only
  string bar = 1;
  string bar_ = 2;
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

<<<<<<< HEAD
<<<<<<< HEAD
edition = "2024";
option features.json_format = LEGACY_BEST_EFFORT;
||||||| parent of dcf50a2 (This documentation change includes the following:)
edition = "2023";
features.json_format = LEGACY_BEST_EFFORT;
=======
edition = "2023";
||||||| parent of 81fd217 (This documentation change includes the following:)
edition = "2023";
=======
edition = "2024";
>>>>>>> 81fd217 (This documentation change includes the following:)
option features.json_format = LEGACY_BEST_EFFORT;
>>>>>>> dcf50a2 (This documentation change includes the following:)

message Foo {
  string bar = 1;
  string bar_ = 2;
}

`features.message_encoding`

この機能は、シリアライズ時のフィールドのエンコード方法を設定します。

この機能はproto3ファイルには影響しないため、このセクションにはproto3ファイルの変更前後の例はありません。

言語によっては、「グループのような」フィールドは、proto2との後方互換性を提供するために、生成されたコードやテキスト形式で予期しない大文字化が行われることがあります。メッセージフィールドが「グループのような」と見なされるのは、以下のすべての条件が満たされた場合です

DELIMITEDメッセージエンコーディングが指定されている
メッセージ型がフィールドと同じスコープで定義されている
フィールド名が型名を小文字にしたものと完全に一致する

利用可能な値

LENGTH_PREFIXED: フィールドは、メッセージ構造で説明されているLENワイヤタイプを使用してエンコードされます。
DELIMITED: メッセージ型のフィールドはグループとしてエンコードされます。

適用可能なスコープ: File, Field

追加されたバージョン 2023

シンタックス/エディションごとのデフォルトの挙動

«««< HEAD

シンタックス/エディション	デフォルト
2024	`LENGTH_PREFIXED`
2023	`LENGTH_PREFIXED`
proto3	`LENGTH_PREFIXED`
proto2	`LENGTH_PREFIXED`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `LENGTH_PREFIXED`。Proto3は`DELIMITED`をサポートしていません。

シンタックス/エディション	デフォルト
2024	`LENGTH_PREFIXED`
2023	`LENGTH_PREFIXED`
proto3	`LENGTH_PREFIXED`
proto2	`LENGTH_PREFIXED`

81fd217 (このドキュメントの変更には以下が含まれます:)

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

message Foo {
  group Bar = 1 {
    optional int32 x = 1;
    repeated int32 y = 2;
  }
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

message Foo {
  message Bar {
    int32 x = 1;
    repeated int32 y = 2;
  }
  Bar bar = 1 [features.message_encoding = DELIMITED];
}

`features.repeated_field_encoding`

この機能は、repeatedフィールドに対するproto2/proto3のpackedオプションがエディションに移行されたものです。

利用可能な値

PACKED: プリミティブ型のRepeatedフィールドは、各要素が連結された単一のLENレコードとしてエンコードされます。
EXPANDED: Repeatedフィールドは、各値ごとにフィールド番号付きでエンコードされます。

適用可能なスコープ: File, Field

追加されたバージョン 2023

シンタックス/エディションごとのデフォルトの挙動

«««< HEAD

シンタックス/エディション	デフォルト
2024	`PACKED`
2023	`PACKED`
proto3	`PACKED`
proto2	`EXPANDED`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `PACKED`

シンタックス/エディション	デフォルト
2024	`PACKED`
2023	`PACKED`
proto3	`PACKED`
proto2	`EXPANDED`

81fd217 (このドキュメントの変更には以下が含まれます:)

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

message Foo {
  repeated int32 bar = 6 [packed=true];
  repeated int32 baz = 7;
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";
option features.repeated_field_encoding = EXPANDED;

message Foo {
  repeated int32 bar = 6 [features.repeated_field_encoding=PACKED];
  repeated int32 baz = 7;
}

以下はproto3ファイルを示しています

syntax = "proto3";

message Foo {
  repeated int32 bar = 6;
  repeated int32 baz = 7 [packed=false];
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

message Foo {
  repeated int32 bar = 6;
  repeated int32 baz = 7 [features.repeated_field_encoding=EXPANDED];
}

`features.utf8_validation`

この機能は、文字列がどのように検証されるかを設定します。これは、それをオーバーライドする言語固有のutf8_validation機能がない限り、すべての言語に適用されます。Java言語固有の機能については、features.(pb.java).utf8_validationを参照してください。

この機能はproto3ファイルには影響しないため、このセクションにはproto3ファイルの変更前後の例はありません。

利用可能な値

VERIFY: ランタイムはUTF-8を検証する必要があります。これはデフォルトのproto3の挙動です。
NONE: フィールドは、ワイヤ上で未検証のbytesフィールドのように動作します。パーサーは、無効な文字を置換するなど、予測できない方法でこのタイプのフィールドを処理する場合があります。これはデフォルトのproto2の挙動です。

適用可能なスコープ: File, Field

追加されたバージョン 2023

シンタックス/エディションごとのデフォルトの挙動

«««< HEAD

シンタックス/エディション	デフォルト
2024	`VERIFY`
2023	`VERIFY`
proto3	`VERIFY`
proto2	`NONE`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `VERIFY`

シンタックス/エディション	デフォルト
2024	`VERIFY`
2023	`VERIFY`
proto3	`VERIFY`
proto2	`NONE`

81fd217 (このドキュメントの変更には以下が含まれます:)

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

message MyMessage {
  string foo = 1;
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

message MyMessage {
  string foo = 1 [features.utf8_validation = NONE];
}

言語固有の機能

一部の機能は特定の言語に適用され、他の言語の同じprotoには適用されません。これらの機能を使用するには、言語のランタイムから対応する*_features.protoファイルをインポートする必要があります。以下のセクションの例は、これらのインポートを示しています。

`features.(pb.cpp).enum_name_uses_string_view`

言語: C++

Edition 2024以前は、生成されたすべてのenum型は、enum値からラベルを取得するために以下の関数を提供していましたが、これにはランタイムでstd::stringインスタンスを構築するためのオーバーヘッドがありました

const std::string& Foo_Name(int);

Edition 2024のデフォルトの機能値は、このシグネチャをabsl::string_viewを返すように変更し、ストレージの分離を改善し、メモリ/CPUの節約を可能にします。まだ移行の準備ができていない場合は、これをオーバーライドして以前の挙動に戻すことができます。このトピックの詳細については、移行ガイドのstring_viewの戻り値の型を参照してください。

利用可能な値

true: enumはその値にstring_viewを使用します。
false: enumはその値にstd::stringを使用します。

適用可能なスコープ: Enum, File

追加されたバージョン 2024

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`true`
2023	`false`
proto3	`false`
proto2	`false`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

`features.(pb.java).large_enum`

言語: Java

この言語固有の機能により、コンパイラエラーを引き起こすことなく、Javaで大きなenumを処理する新機能を採用できます。この機能はenumのような挙動を再現しますが、いくつかの顕著な違いがあることに注意してください。たとえば、switch文はサポートされていません。

利用可能な値

true: Javaのenumは新しい機能を使用します。
false: Javaのenumは引き続きJavaのenumを使用します。

適用可能なスコープ: Enum

追加されたバージョン 2024

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`false`
2023	`false`
proto3	`false`
proto2	`false`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

`features.(pb.cpp/pb.java).legacy_closed_enum`

言語: C++, Java

この機能は、open enum型のフィールドがclosed enumであるかのように動作すべきかどうかを決定します。これにより、エディションはJavaとC++におけるproto2とproto3の非準拠の挙動を再現できます。

この機能はproto3ファイルには影響しないため、このセクションにはproto3ファイルの変更前後の例はありません。

利用可能な値

true: enum_typeに関係なく、enumをclosedとして扱います。
false: enum_typeで設定されているものを尊重します。

適用可能なスコープ: File, Field

追加されたバージョン 2023

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`false`
2023	`false`
proto3	`false`
proto2	`true`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

import "myproject/proto3file.proto";

message Msg {
  myproject.proto3file.Proto3Enum name = 1;
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

import "myproject/proto3file.proto";

import "google/protobuf/cpp_features.proto";
import "google/protobuf/java_features.proto";

message Msg {
  myproject.proto3file.Proto3Enum name = 1 [
    features.(pb.cpp).legacy_closed_enum = true,
    features.(pb.java).legacy_closed_enum = true
  ];
}

`features.(pb.java).nest_in_file_class`

言語: Java

この機能は、Javaジェネレータが生成されたクラスをJavaの生成ファイルクラス内にネストするかどうかを制御します。このオプションをYesに設定することは、proto2/proto3/edition 2023でjava_multiple_files = trueを設定することと同じです。

デフォルトのアウタークラス名も、常にキャメルケースの.protoファイル名にProtoを付けたものに更新されます（例：foo/bar_baz.protoはBarBazProtoになります）。java_outer_classnameファイルオプションを使用してこれをオーバーライドし、競合の有無に応じてEdition 2024以前のデフォルトであるBarBazまたはBarBazOuterClassを置き換えることもできます。

利用可能な値

NO: 生成されたクラスをファイルクラス内にネストしません。
YES: 生成されたクラスをファイルクラス内にネストします。
Legacy: java_multiple_filesオプションが設定されている場合に使用される内部値。

適用可能なスコープ: Message, Enum, Service

追加されたバージョン 2024

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`NO`
2023	`LEGACY`
proto3	`LEGACY`
proto2	`LEGACY`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

`features.(pb.cpp).string_type`

言語: C++

この機能は、生成されたコードが文字列フィールドをどのように扱うべきかを決定します。これはproto2とproto3のctypeオプションを置き換え、新しいstring_type機能を提供します。Edition 2023では、フィールドにctypeまたはstring_typeのいずれかを指定できますが、両方は指定できません。Edition 2024では、ctypeオプションは削除されます。

利用可能な値

VIEW: フィールドにstring_viewアクセサを生成します。
CORD: フィールドにCordアクセサを生成します。拡張フィールドではサポートされていません。
STRING: フィールドにstringアクセサを生成します。

適用可能なスコープ: File, Field

追加されたバージョン 2023

シンタックス/エディションごとのデフォルトの挙動

シンタックス/エディション	デフォルト
2024	`VIEW`
2023	`STRING`
proto3	`STRING`
proto2	`STRING`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

message Foo {
  optional string bar = 6;
  optional string baz = 7 [ctype = CORD];
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

import "google/protobuf/cpp_features.proto";

message Foo {
  string bar = 6 [features.(pb.cpp).string_type = STRING];
  string baz = 7 [features.(pb.cpp).string_type = CORD];
}

以下はproto3ファイルを示しています

syntax = "proto3"

message Foo {
  string bar = 6;
  string baz = 7 [ctype = CORD];
}

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

import "google/protobuf/cpp_features.proto";

message Foo {
  string bar = 6 [features.(pb.cpp).string_type = STRING];
  string baz = 7 [features.(pb.cpp).string_type = CORD];
}

`features.(pb.java).utf8_validation`

言語: Java

この言語固有の機能により、Javaのみでファイルレベルの設定をフィールドレベルでオーバーライドできます。

この機能はproto3ファイルには影響しないため、このセクションにはproto3ファイルの変更前後の例はありません。

利用可能な値

DEFAULT: 挙動はfeatures.utf8_validationによって設定されたものと一致します。
VERIFY: ファイルレベルのfeatures.utf8_validation設定をオーバーライドし、JavaのみでVERIFYに強制します。

適用可能なスコープ: Field, File

追加されたバージョン 2023

シンタックス/エディションごとのデフォルトの挙動

«««< HEAD

シンタックス/エディション	デフォルト
2024	`DEFAULT`
2023	`DEFAULT`
proto3	`DEFAULT`
proto2	`DEFAULT`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `DEFAULT`

シンタックス/エディション	デフォルト
2024	`DEFAULT`
2023	`DEFAULT`
proto3	`DEFAULT`
proto2	`DEFAULT`

81fd217 (このドキュメントの変更には以下が含まれます:)

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。

次のコードサンプルはproto2ファイルを示しています

syntax = "proto2";

option java_string_check_utf8=true;

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

Prototillerを実行した後、同等のコードは次のようになるかもしれません

edition = "2024";

import "google/protobuf/java_features.proto";

option features.utf8_validation = NONE;
option features.(pb.java).utf8_validation = VERIFY;
message MyMessage {
  string foo = 1;
  string bar = 2;
}

proto2またはproto3の挙動の維持

エディション形式に移行したいが、生成されたコードの挙動の更新にはまだ対応したくない場合があります。このセクションでは、Prototillerツールが.protoファイルに行う変更を示し、エディションベースのprotoをproto2またはproto3ファイルのように動作させます。

これらの変更がファイルレベルで行われると、proto2またはproto3のデフォルトが得られます。下位レベル（メッセージレベル、フィールドレベル）でオーバーライドして、追加の挙動の違い（required, proto3 optionalなど）を考慮したり、定義をproto2またはproto3とほぼ同じにしたい場合にのみ使用したりできます。

特別な理由がない限り、Prototillerを使用することをお勧めします。Prototillerを使用せずにこれらすべてを手動で適用するには、次のセクションの内容を.protoファイルの先頭に追加します。

Proto2の挙動

以下は、Edition 2023でproto2の挙動を再現するための設定を示しています。

edition = "2023";

import "google/protobuf/cpp_features.proto";
import "google/protobuf/java_features.proto";

option features.field_presence = EXPLICIT;
option features.enum_type = CLOSED;
option features.repeated_field_encoding = EXPANDED;
option features.json_format = LEGACY_BEST_EFFORT;
option features.utf8_validation = NONE;
option features.(pb.cpp).legacy_closed_enum = true;
option features.(pb.java).legacy_closed_enum = true;

Proto3の挙動

以下は、Edition 2023でproto3の挙動を再現するための設定を示しています。

edition = "2023";

import "google/protobuf/cpp_features.proto";
import "google/protobuf/java_features.proto";

option features.field_presence = IMPLICIT;
option features.enum_type = OPEN;
// `packed=false` needs to be transformed to field-level repeated_field_encoding
// features in Editions syntax
option features.json_format = ALLOW;
option features.utf8_validation = VERIFY;
option features.(pb.cpp).legacy_closed_enum = false;
option features.(pb.java).legacy_closed_enum = false;

Edition 2023から2024へ

以下は、Edition 2024でEdition 2023の挙動を再現するための設定を示しています。

edition = "2024";

import option "third_party/protobuf/cpp_features.proto";
import option "third_party/java/protobuf/java_features.proto";

option features.(pb.cpp).string_type = STRING;
option features.enforce_naming_style = STYLE_LEGACY;
option features.default_symbol_visibility = EXPORT_ALL;
option features.(pb.cpp).enum_name_uses_string_view = false;
option features.(pb.java).nest_in_file_class = LEGACY;

注意点と例外

このセクションでは、Prototillerを使用しない場合に手動で行う必要がある変更を示します。

前のセクションで示したファイルレベルのデフォルトを設定すると、ほとんどの場合のデフォルトの挙動が設定されますが、いくつかの例外があります。

Edition 2023以降

optional: optionalラベルのすべてのインスタンスを削除し、ファイルのデフォルトがIMPLICITの場合はfeatures.field_presenceをEXPLICITに変更します。
required: requiredラベルのすべてのインスタンスを削除し、フィールドレベルでfeatures.field_presence=LEGACY_REQUIREDオプションを追加します。
groups: groupsを別のメッセージにアンラップし、フィールドレベルでfeatures.message_encoding = DELIMITEDオプションを追加します。詳細については、features.message_encodingを参照してください。
java_string_check_utf8: このファイルオプションを削除し、features.(pb.java).utf8_validationに置き換えます。言語固有の機能で説明されているように、Javaの機能をインポートする必要があります。
packed: エディション形式に変換されたproto2ファイルの場合、Proto2の挙動で設定したEXPANDEDの挙動が不要な場合は、packedフィールドオプションを削除し、フィールドレベルで[features.repeated_field_encoding=PACKED]を追加します。エディション形式に変換されたproto3ファイルの場合、デフォルトのproto3の挙動が不要な場合は、フィールドレベルで[features.repeated_field_encoding=EXPANDED]を追加します。

Edition 2024以降

(C++) ctype: ctypeオプションのすべてのインスタンスを削除し、features.(pb.cpp).string_typeの値を設定します。
(C++ and Go) weak: weakインポートを削除します。代わりにimport optionを使用します。
(Java) java_multiple_files: java_multiple_filesを削除し、代わりにfeatures.(pb.java).nest_in_file_classを使用します。

エディションの機能設定

Prototiller

機能

features.default_symbol_visibility

features.enforce_naming_style

||||||| dcf50a2 の親 (このドキュメントの変更には以下が含まれます:) この例では、フィールドスコープの機能定義の GRAULT 設定が、メッセージスコープの QUUX 設定をオーバーライドします。

||||||| 81fd217 の親 (このドキュメントの変更には以下が含まれます:)

features.default_symbol_visibility

features.enforce_naming_style

features.enum_type

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: OPEN

features.field_presence

«««< HEAD «««< HEAD 追加されたバージョン: 2023 ||||||| dcf50a2の親 (このドキュメントの変更には以下が含まれます:) Edition 2023でのデフォルト値: EXPLICIT

features.json_format

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: ALLOW

features.message_encoding

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: LENGTH_PREFIXED。Proto3はDELIMITEDをサポートしていません。

features.repeated_field_encoding

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: PACKED

features.utf8_validation

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: VERIFY

言語固有の機能

features.(pb.cpp).enum_name_uses_string_view

features.(pb.java).large_enum

features.(pb.cpp/pb.java).legacy_closed_enum

features.(pb.java).nest_in_file_class

features.(pb.cpp).string_type

features.(pb.java).utf8_validation

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: DEFAULT

proto2またはproto3の挙動の維持

Proto2の挙動

Proto3の挙動

Edition 2023から2024へ

注意点と例外

`features.default_symbol_visibility`

`features.enforce_naming_style`

||||||| dcf50a2 の親 (このドキュメントの変更には以下が含まれます:) この例では、フィールドスコープの機能定義の `GRAULT` 設定が、メッセージスコープの QUUX 設定をオーバーライドします。

`features.default_symbol_visibility`

`features.enforce_naming_style`

`features.enum_type`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `OPEN`

`features.field_presence`

«««< HEAD «««< HEAD 追加されたバージョン: 2023 ||||||| dcf50a2の親 (このドキュメントの変更には以下が含まれます:) Edition 2023でのデフォルト値: `EXPLICIT`

`features.json_format`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `ALLOW`

`features.message_encoding`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `LENGTH_PREFIXED`。Proto3は`DELIMITED`をサポートしていません。

`features.repeated_field_encoding`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `PACKED`

`features.utf8_validation`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `VERIFY`

`features.(pb.cpp).enum_name_uses_string_view`

`features.(pb.java).large_enum`

`features.(pb.cpp/pb.java).legacy_closed_enum`

`features.(pb.java).nest_in_file_class`

`features.(pb.cpp).string_type`

`features.(pb.java).utf8_validation`

注: 異なるスキーマ要素の機能設定は、異なるスコープを持ちます。 ||||||| 81fd217の親 (このドキュメントの変更には以下が含まれます:) proto3での挙動: `DEFAULT`