Skip to content

Commit a2aef5b

Browse files
editions features: document Go Protobuf api_level
The previous change took care of the “Edition 2023 to 2024” paragraph, but the page was lacking api_level documentation altogether. PiperOrigin-RevId: 808919192
1 parent be0afc6 commit a2aef5b

File tree

1 file changed

+51
-0
lines changed

1 file changed

+51
-0
lines changed

content/editions/features.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -624,6 +624,57 @@ languages. Using these features requires you to import the corresponding
624624
*_features.proto file from the language's runtime. The examples in the following
625625
sections show these imports.
626626

627+
### `features.(pb.go).api_level` {#go-api_level}
628+
629+
**Languages:** Go
630+
631+
The `api_level` feature enables you to select which API version the Go protobuf
632+
plugin should generate code for. The Opaque API is the latest version of the
633+
Protocol Buffers implementation for the Go programming language. The previous
634+
version is now called Open Struct API. See the
635+
[Go Protobuf: Releasing the Opaque API](https://go.dev/blog/protobuf-opaque)
636+
blog post for an introduction.
637+
638+
**Values available:**
639+
640+
* `API_OPEN`: The Open Struct API generates struct types that are open to
641+
direct access.
642+
* `API_HYBRID`: Hybrid is a step between Open and Opaque: The Hybrid API also
643+
includes accessor methods (so you can update your code), but still exports
644+
the struct fields as before. There is no performance difference; this API
645+
level only helps with the migration.
646+
* `API_OPAQUE`: With the Opaque API, the struct fields are hidden and can no
647+
longer be directly accessed. Instead, the new accessor methods allow for
648+
getting, setting, or clearing a field.
649+
650+
**Applicable to the following scopes:** Message, File
651+
652+
**Added in:** Edition 2023
653+
654+
**Default behavior per syntax/edition:**
655+
656+
Syntax/edition | Default
657+
-------------- | ------------
658+
2023 | `API_OPEN`
659+
2024 | `API_OPAQUE`
660+
661+
**Note:** Feature settings on different schema elements
662+
[have different scopes](#cascading).
663+
664+
You can set the `api_level` feature starting in edition 2023:
665+
666+
```proto
667+
edition = "2023";
668+
669+
import "google/protobuf/go_features.proto";
670+
671+
// Remove this line after migrating the code to the Opaque API.
672+
option features.(pb.go).api_level = API_HYBRID;
673+
```
674+
675+
See also:
676+
[Opaque API: Migration](/reference/go/opaque-migration)
677+
627678
### `features.(pb.cpp).enum_name_uses_string_view` {#enum-name-string-view}
628679

629680
**Languages:** C++

0 commit comments

Comments
 (0)