Addressing suggestions for being explicit about applicability to all …

…route types, more concise intro, and other minor ones

geps/gep-995/index.md

@@ -5,12 +5,12 @@
 
 ## TLDR
 
-Add a new `name` field to the route rule types (HTTPRouteRule, GRPCRouteRule) to support referencing individual rules by name.
+Add a new optional `name` field to the route rule types ([GRPCRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteRule), [HTTPRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteRule), [TCPRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TCPRouteRule), [TLSRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRouteRule) and [UDPRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.UDPRouteRule)) to support referencing individual rules by name.
 
 ## Goals
 
-* Support referencing individual route rules by name from other resources, such as from metaresource ([GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/).)
-* Support referencing individual route rules by name from condition messages propagated in the status stanza of route resources.
+* Support referencing individual route rules by name from other resources, such as from metaresources as suggested in [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/#apply-policies-to-sections-of-a-resource).
+* Support referencing individual route rules by name from condition messages propagated in the status stanza of route resources as suggested in https://github.com/kubernetes-sigs/gateway-api/issues/1696#issuecomment-1666258188.
 * Support referencing individual route rules by name at other observability and networking tools that are part of the ecosystem based on Gateway API.
 * Provide a rather intuitive API for users of Kubernetes who are familiar with the same pattern employed already by other kinds of resources where lists of complex elements can be declared – e.g. service [ports](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec), pod [containers](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#containers) and pod [volumes](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#volumes).
 * Provide a guide to the implementations about the expected behavior in cases where the name of the route rule is missing (empty value or `nil`.)
@@ -27,21 +27,17 @@ Some kinds of Gateway API types are complex types that support specifying lists
 
 Even with a limited number of elements declared within those lists of resource specification details, without a field that works as a unique identifier of each element (e.g., a `name` field), referring individual ones can often lead to implementations that are inconsistent, complex, and error-prone. This is an issue for any kind of referencing pattern, including for Policy Attachment, status reporting, event logging, etc.
 
-* Implementations can be inconsistent because referencing may rely on the index of the referents within the lists for making the reference, as well as based on repetition in the reference (partially or totally) of values of the referent to match.
+Referencing list elements without a unique identifier is also prone to execution errors, either when relying on how the elements are sorted in the list (i.e., based on the index) or on partial or total repetition of values of the referents. The order of elements within a list may change without necessarily any semantic reason. Complex elements can sometimes differ only subtly from each other, thus easily being overlooked when making the reference and resulting in a higher chance of typos and/or references that are possibly ambiguous or broken. In both cases, such references are fragile and can result in unexpected errors.
 
-* When repetition of values is employed, the complexity associated with the API of the referent itself is brought to the level of the reference, thus adding this other problem to the referencing system. If types and validation rules of the referent are re-used to implement the reference API, their associated complexity adds up to the complexity of validating also the reference values, even though due soly to the repetition across resources.
-
-* Referencing list elements without a unique identifier is also prone to execution errors, either when relying on how the elements are sorted in the list (i.e., based on the index) or on partial or total repetition of values of the referents. The order of elements within a list may change without necessarily any semantic reason. Complex elements can sometimes differ only subtly from each other, thus easily being overlooked when making the reference and resulting in a higher chance of typos and/or references that are possibly ambiguous or broken. In both cases, such references are fragile and can result in unexpected errors.
-
-For the `Gateway` resource, problems above were addressed/mitigated by adding a `name` field to the [`Listener`](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Listener) type ([#724](https://github.com/kubernetes-sigs/gateway-api/issues/).) Listener names are required and must be unique of each listener declared in a gateway. This allowed for more assertive policy attachment relying on _sectionName_, as well as it opened for better implementation of status reporting and log recording of events related to specific gateway listeners.
+For the `Gateway` resource, problems above were addressed/mitigated by adding a `name` field to the [`Listener`](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Listener) type ([#724](https://github.com/kubernetes-sigs/gateway-api/issues/).) Listener names are required and must be unique of each listener declared in a gateway. This allowed for more explicit route and policy attachment relying on _sectionName_, as well as it opened for better implementation of status reporting and log recording of events related to specific gateway listeners.
 
 In general, declaring explicit names for complex list elements is a common pattern in Kubernetes, observed in several other APIs. Examples include [containers](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#containers) and [volumes](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#volumes) of a Pod, [ports](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec) of a Service, and many others.
 
-This GEP aims to rollout the same pattern of declarative `name` fields of these examples to the Gateway API route rule types [`HTTPRouteRule`](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteRule) and [`GRPCRouteRule`](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteRule).
+This GEP aims to rollout the same pattern of declarative `name` fields of these examples to the Gateway API route rule types.
 
 ## API
 
-This GEP proposes to add a new `name` field to the [`HTTPRouteRule`](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteRule) and [`GRPCRouteRule`](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteRule) types.
+This GEP proposes to add a new optional `name` field to the [GRPCRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteRule), [HTTPRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteRule), [TCPRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TCPRouteRule), [TLSRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRouteRule) and [UDPRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.UDPRouteRule) types.
 
 ### Format
 
@@ -63,39 +59,31 @@ This format for the `name` field of route rules differs from the pattern adopted
 
 To preserve backward compatibility with previous version of the affected APIs, the `name` field for route rules should be introduced in the API as optional – i.e., end-user are not forced to add it to their existing or new route objects.
 
-Implementations MAY recomend the usage of the `name` field for enabling specific features, such as for supporting policy attachment targetting individual route rules, and more assertive log messages and/or status reporting that include on the name of the rule. However, because as by API design the presence of the field is optional, implementations MUST take into account that a value may sometimes not be available. For such cases, implementations are free to decide whether to provide the feature depending the `name` field, if the feature is not `core` for compliance, or to enable the feature relying on another method of referencing of choice.
+Implementations MAY recomend the usage of the `name` field for enabling specific features, such as for supporting policy attachment targetting individual route rules, and more assertive log messages and/or status reporting that include on the name of the rule. However, because as by API design the presence of the field is optional, implementations MUST take into account that a value may sometimes not be available. For such cases, implementations are free to decide whether to provide the feature depending the `name` field, if the feature is not required for Core compliance, or to enable the feature relying on another method of referencing of choice.
 
 ### Default value
 
-Implementations SHOULD not assume a default vaule for the `name` field for route rules when not specified by the end-user.
+Implementations MUST NOT assume a default value for the `name` field for route rules when not specified by the end-user.
 
 Please refer to the [Volition](#volition) subsection for alternatives if `name` field is missing.
 
 ### Mutability
 
 Implementations MAY prevent end-users from updating the name of a route rule. If updates are allowed the semantics and behaviour will depend on the underlying implementation.
 
-## Conformance Details
-
-(This section describes the names to be used for the feature or
-features in conformance tests and profiles.
-
-These should be `CamelCase` names that specify the feature as
-precisely as possible, and are particularly important for
-Extended features, since they may be surfaced to users.)
-
 ## Alternatives
 
 ### Reference route rules by index
 - Consistency can be easily broken by adding/removing new rules
 - Less descriptive compared to a name
 
 ### Reference route rules by matching field values of rule
+- Complexity associated with the API types of the referent bubbles up to the level of the reference
 - Consistency can be easily broken due to duplication of values between reference and referent
 - Does not solve for easy referencing in debugging, logging, status messages – i.e. some verbosity required to communicate what route rule the events refers to
 
 ### Break down route objects into smaller ones (with less rules)
-- Could lead to an explosion of route objects containing no more than one rule each, thus defeating the purpose of supporting lists of rules within route objects in the first place
+- Could lead to an explosion of route objects containing a single rule each, thus defeating the purpose of supporting lists of rules within route objects in the first place – though large routes with many rules are also generally discouraged (https://github.com/kubernetes-sigs/gateway-api/issues/1696#issuecomment-1679804122)
 
 ### Use filters to extend behavior of specific route rules
 - Does not solve for easy referencing in debugging, logging, status messages – i.e. some verbosity required to communicate what route rule the events refers to