editions library

Protobuf Editions feature resolution.

Protobuf Editions (starting from Edition 2023) replace the syntax keyword with per-feature defaults that can be overridden at file, message, or field level. This module implements the canonical feature model + resolution algorithm (matching protoc's feature_resolver.cc), plus proto2/proto3 → editions legacy inference.

Ball-portable: top-level functions over plain Map/List/String/int data, so it encodes into the ball_protobuf module and runs on every target engine.

The edition-defaults table below is the ground truth emitted by protoc --edition_defaults_out (see tests/editions/golden/). Refresh it from protoc when upgrading; CI guards against drift.

References:

Constants

enumTypeClosed → const String
Enum type: closed — unknown enum values are treated as the unknown field set (proto2 default).
enumTypeOpen → const String
Enum type: open — unknown enum values are preserved as their integer value (proto3 default).
featureEnumType → const String
featureFieldPresence → const String
featureJsonFormat → const String
featureMessageEncoding → const String
featureRepeatedFieldEncoding → const String
featureUtf8Validation → const String
fieldPresenceExplicit → const String
Field presence: the field has explicit presence tracking (proto2 default for singular fields, proto3 optional fields).
fieldPresenceImplicit → const String
Field presence: the field is implicitly present (proto3 default for scalar fields — no has* method, default value is not serialized).
fieldPresenceLegacyRequired → const String
Field presence: legacy required semantics (proto2 required).
jsonFormatAllow → const String
JSON format: allow — standard Proto3 JSON.
jsonFormatLegacyBestEffort → const String
JSON format: legacy best effort — relaxed parsing for compatibility.
maximumEdition → const int
Highest edition this engine supports.
messageEncodingDelimited → const String
Message encoding: delimited (group-style encoding).
messageEncodingLengthPrefixed → const String
Message encoding: length-prefixed (default for all editions).
minimumEdition → const int
Lowest edition the defaults table covers (proto2 resolves via the LEGACY floor entry).
repeatedFieldEncodingExpanded → const String
Repeated field encoding: expanded — each repeated element gets its own tag-value pair (proto2 default).
repeatedFieldEncodingPacked → const String
Repeated field encoding: packed — scalar repeated fields are encoded as a single length-delimited blob (proto3 default).
utf8ValidationNone → const String
UTF-8 validation: none — no validation is performed (proto2 default).
utf8ValidationVerify → const String
UTF-8 validation: verify — string fields must contain valid UTF-8 (proto3 default).

Functions

baseFeaturesForEdition(int edition) → Map<String, String>
Returns the fully-resolved BASE FeatureSet for edition before any file/message/field overrides: the entry's overridable features merged with its fixed features (fixed wins on conflict). For every supported edition this yields all six runtime features.
editionDefaults(String edition) → Map<String, String>
Returns the default feature map for an edition/syntax string (no overrides). Retained for callers that only need the edition base.
featureKeys() → List<String>
All six runtime FeatureSet keys, in descriptor.proto field order.
hasExplicitPresence(Map<String, String> features) → bool
True when the field tracks presence (EXPLICIT or LEGACY_REQUIRED).
inferLegacyFieldFeatures(String label, String type, bool proto3Optional, String? packed, int edition) → Map<String, String>
Infers the field-level feature overrides implied by a proto2/proto3 field's shape, so a legacy field resolves identically to its editions equivalent.
inferLegacyFileFeatures(String syntax) → Map<String, String>
Infers the fully-resolved FILE-level FeatureSet for a legacy syntax ("proto2" / "proto3", or "" ⇒ proto2).
isClosedEnum(Map<String, String> features) → bool
True when the enum is closed (unknown values routed to the unknown set).
isDelimited(Map<String, String> features) → bool
True when message fields use delimited (group) encoding.
isExpandedRepeated(Map<String, String> features) → bool
True when repeated scalar fields are expanded (one record per element).
isFixedFeature(int edition, String featureKey) → bool
Whether featureKey is FIXED (non-overridable) at edition — i.e. setting it via a features option is a hard error.
isImplicitPresence(Map<String, String> features) → bool
True when the field has implicit (proto3-style) presence.
isOpenEnum(Map<String, String> features) → bool
True when the enum is open (unknown values preserved as integers).
isPackedRepeated(Map<String, String> features) → bool
True when repeated scalar fields are packed.
isRequired(Map<String, String> features) → bool
True when the field is required (LEGACY_REQUIRED).
jsonFormatIsAllow(Map<String, String> features) → bool
True when JSON encoding uses the standard (ALLOW) format rather than the legacy best-effort path.
mergeChildFeatures(int edition, Map<String, String> resolvedParent, Map<String, Object?>? childFeatures) → Map<String, String>
Resolves a child descriptor's FeatureSet: starts from the parent's already-fully-resolved features and applies this descriptor's explicit features overrides on top.
mergeFeatureSet(Map<String, String> base, Map<String, Object?>? overrides, int edition) → Map<String, String>
Merges overrides onto a copy of base using protobuf MergeFrom semantics: a present override key replaces the base value; an absent feature keeps the base value (later-set-wins, unset-leaves-prior). base is not mutated — a new map is returned.
requiresUtf8Validation(Map<String, String> features) → bool
True when string fields require UTF-8 validation.
resolveFeatures(String edition, Map<String, Object?>? fileFeatures, Map<String, Object?>? messageFeatures, Map<String, Object?>? fieldFeatures) → Map<String, String>
Back-compat convenience wrapper: resolves features down the common file → message → field chain for an edition/syntax string.
resolveFileFeatures(int edition, Map<String, Object?>? fileFeatures) → Map<String, String>
Resolves the file-level FeatureSet for edition with the file's explicit features overrides applied on top of the edition base.
validateEditionInRange(int edition) → void
Validates that edition is within the supported [minimumEdition, maximumEdition] range (the test-only editionUnstable is allowed above the max). Throws ArgumentError otherwise.