Hi, I reviewed draft-ietf-regext-rdap-extensions-14, and I have the following feedback with suggested text where appropriate:
Section 2.2 “Syntax”: OLD Similarly, RDAP extensions MUST NOT define an extension identifier starting with a substring being an existing extension identifier appended with an underscore. NEW Similarly, RDAP extensions MUST NOT define an extension identifier starting with a substring of an existing extension identifier appended with an underscore. I recommend injecting some of Section 2.3 “Bare Extension Identifiers” into Section 2.2 and formally defining the ABNF for an RDAP extension identifier, which revises the “name” ABNF rule defined in Section 6 of [RFC 7480] and formally defines the RDAP extension (variable / element / parameter) ABNF. A good name needs to be given to the RDAP extension elements that use the RDAP extension identifier as a prefix. OLD For this reason, this document updates the guidance of [RFC7480<https://www.rfc-editor.org/info/rfc7480>] regarding underscore characters: RDAP extensions MUST NOT use an underscore character in their RDAP extension identifier. Implementers should be aware that many existing extension identifiers do contain underscore characters. NEW This document updates the ABNF “name” rule in [RFC7480] to not allow the use of an underscore character in the RDAP extension identifier. The revised ABNF [RFC5234] “name” rule is: name = ALPHA *( ALPHA / DIGIT ) Implementers should be aware that existing extension identifiers do contain underscore characters. Added at the end of section 2.2 that following to replace Section 2.3 “Bare Extension Identifiers”: NEW (Replaces Section 2.3 “Bare Extension Identifiers”) The [RFC 7480] ABNF “name” rule referenced JSON Names, where there was no requirement to include the suffix for JSON members, and Section 2.1 of [RFC 9083] included the language “JSON responses SHOULD have member names prefixed with a short identifier followed by an underscore followed by a meaningful name”. This contradiction led to the use of a Bare Extension Identifier, where a JSON member uses the extension identifier without the use of an underscore followed by a meaningful name. That is, the extension identifier is used "bare" and not appended with an underscore character and subsequent names. Consider the example in Section 2.5.2<https://datatracker.ietf.org/doc/html/draft-ietf-regext-rdap-extensions#child_json_values>. Using the bare extension identifier pattern, that example could be written as: { "rdapConformance": [ "rdap_level_0", "exampleExt" ], "objectClassName": "domain", "ldhName": "example.com", "remarks": [ { "description": [ "Query the database." "JSON replaces the Whois." "Structured data flows." ] } ], "exampleExt": { "firstInitial": "R", "lastName": "SomePerson" } } While [RFC9083<https://www.rfc-editor.org/info/rfc9083>] is specific to JSON, the use of a bare extension identifier also applies to other identifiers of RDAP extensions, such as query parameters and object class names. Identifiers of an RDAP extension which need a prefix to avoid name collision with identifiers of other RDAP extensions or RDAP as specified in [RFC7480<https://www.rfc-editor.org/info/rfc7480>], [RFC9082<https://www.rfc-editor.org/info/rfc9082>], and [RFC9083<https://www.rfc-editor.org/info/rfc9083>] are referred to as namespaced identifiers. prefixed identifiers are clearly syntactically distinguishable from identifiers defined by the core RDAP specifications, which provides more flexibility to implementers and helps with debugging and similar. The syntax for extension elements (JSON member, query parameters, object class name, HTTP headers, path segments, media type parameter, etc.) is defined by the “extension-element” ABNF rule: extension-element = name “_” ALPHA *( ALPHA / DIGIT / “_” ) Implementers should be aware that existing extension elements use Bare Extension Identifiers. Section 2.3 “Bare Extension Identifiers”: I recommend moving into Section 2.2 “Syntax” as described above, since the formal definition of the extension-element ABNF rule cleanly defines what designers need to use going forward in place of defining what designers must not do. Section 2.5.1 “Basic Requirements” I don’t recommend mirroring the “harshMistressNotes” with the “In space,”, “nobody can hear you scream” example from RFC 9083 in draft-ietf-regext-rdap-extensions, even though I believe it’s a reference to the book “The Moon is a Harsh Mistress”. I recommend neutralizing the example in draft-ietf-regext-rdap-extensions. Replicating the RFC 9083 is not needed and providing the required use of the “rdapConformance” could be provided alone with a neutralized example: OLD [RFC9083<https://www.rfc-editor.org/info/rfc9083>] states: Clients of these JSON responses SHOULD ignore unrecognized JSON members in responses. This document updates this guidance… NEW [RFC9083<https://www.rfc-editor.org/info/rfc9083>] states: Clients of these JSON responses SHOULD ignore unrecognized JSON members in responses. As Section 4.1<https://rfc-editor.org/rfc/rfc9083#section-4.1> of [RFC9083<https://www.rfc-editor.org/info/rfc9083>] requires the use of the "rdapConformance" data structure, and the "objectClassName" string is required of all object class instances, the complete example from [RFC9083<https://www.rfc-editor.org/info/rfc9083>] would be with a change the last “lunarNIC” member: { "rdapConformance": [ "rdap_level_0", "lunarNIC" ], "objectClassName": "domain", "handle": "ABC123", "ldhName": "example.com", "lunarNIC_beforeOneSmallStep": "TRUE THAT!", "remarks": [ { "description": [ "She sells sea shells down by the sea shore.", "Originally written by Terry Sullivan." ] } ], "lunarNIC_spaceNotes": [ "In space,", "nobody can hear you." ] Section 2.5.5 “rdapConformance Population” Nit – I recommend naming the Section 2.1.1 extension identifiers for clarity, so readers don’t need to follow the reference to determine the type of extension being referenced. It’s not perfectly clear whether the OLD A strict interpretation of this wording where “construction of the response” refers only to the JSON structure would rule out the use of Section 2.1.1<https://datatracker.ietf.org/doc/html/draft-ietf-regext-rdap-extensions#profiles> extension identifiers NEW A strict interpretation of this wording where “construction of the response” refers only to the JSON structure would rule out the use of profile extension identifiers [Section 2.1.1<https://datatracker.ietf.org/doc/html/draft-ietf-regext-rdap-extensions#profiles>] It’s not clear from the guidance whether the profile extension identifiers are expected to be returned in the response, which I believe they should based on “understand the semantic meaning of the content within the JSON”. I recommend making this explicit, since the profile extension identifiers were raised as an interpretation issue with: OLD …a response MUST include in the "rdapConformance" array only those extension identifiers necessary for a client to deserialize the JSON and understand the semantic meaning of the content within the JSON, and each extension identifier MUST be free from conflict with the other identifiers with respect to their syntax and semantics. NEW …a response MUST include in the "rdapConformance" array only those extension identifiers necessary for a client to deserialize the JSON and understand the semantic meaning of the content within the JSON, which includes the profile extension identifiers. Each extension identifier MUST be free from conflict with the other identifiers with respect to their syntax and semantics. Section 5.3 “Extensions Referencing Other Extensions” Nit – I recommend naming the Section 2.1.1 extension identifiers for clarity. OLD As stated in Section 2.1.1<https://datatracker.ietf.org/doc/html/draft-ietf-regext-rdap-extensions#profiles>, …. NEW As stated for profile extensions [Section 2.1.1<https://datatracker.ietf.org/doc/html/draft-ietf-regext-rdap-extensions#profiles>], … Should there be guidance to include a normative reference in a dependent extension to the other extension for clarity to the client and server that there is a dependent relationship between the two extensions? This could go further by including language in the extension defining the dependent relationship explicitly. OLD …extensions may rely on other extensions by stipulating the usage of those other extensions. NEW …extensions may rely on other extensions by stipulating the usage of those other extensions. Dependencies between extensions MUST be defined using a normative reference in the dependent extension and SHOULD include an explicit description of the dependency. Section 5.4 “Extension Versioning” I like the formal definition of the terms “revision” and “replacement”. This helps a great deal in clarifying the guidance. The last paragraph references a 2011 blog post, MNOT-VERSIONING. This could be perceived as a normative reference. As far as I can tell, the guidance from the post was never included in an RFC, so I recommend removing the reference entirely, to reduce confusion. The extensions draft should provide guidance based on RDAP extension definition experience and operational experience. I agree with “Backwards-compatible changes should be favored over incompatible ones.”, but I don’t believe that “Newer versions of extensions are not to break existing clients” is realistic based on the progression of RDAP extensions in the working group. This would also require protocol designers to reliably predict what client implementers will do, which is not possible. RDAP is a stateless protocol and doesn’t have a predefined set of clients, which may expect different versions of an RDAP extensions (old or new). RDAP is defined to ensure that clients are resilient to change by requiring clients to ignore unknown JSON names. Extension designers need to consider versioning throughout the maturity of the extension, which includes determining when to change the extension identifier and whether to use a versioning extension, or its own versioning technique. Clients need to be aware of the extension interface supported by the server, which can include breaking and non-breaking changes. Below is my recommendation for the language in the draft. OLD Versioning of RDAP extensions is expected to follow the general principles described in [MNOT-VERSIONING<https://mnot.net/blog/2011/web_api_versioning_smackdown>]: * Newer versions of extensions are not to break existing clients. * Backwards-compatible changes should be favored over incompatible ones NEW Versioning of RDAP extensions needs to be considered with the following goals: * Backwards-compatible changes should be favored over incompatible ones * Changes to the extension interface should be transparent to the client by changing of the extension identifier (replacement above), use of a versioning extension such as draft-ietf-regext-rdap-versioning, or defining versioning directly into the extension. Section 5.4.1 “Breaking Changes in Revisions” In reviewing the list of breaking changes, I have the following feedback to the list items: “Contracting a set of values when that set is not defined in an IANA registry to be found in a protocol element in a request” – Wouldn’t this be considered a non-breaking change unless it was a value provided by the client in the query? The client would support a superset of values, so the removal of one of the values should not break a client expecting the old interface. Section 5.4.3 “Compatibility of Replacements” I view this section as providing guidance or considerations to extension implementers and designers for replacements (e.g., when an extension identifier changes). I recommend using the term “Considerations” in the title to make it clear the goal of the section. OLD Title: Compatibility of Replacements NEW Title: Extension Replacement Considerations I like scoping the sub-sections of Section 5.4.3 with “replacements”, which as when the extension identifier changes. We need to ensure that the strategies are explicitly not considered. Considering that designers and implementers may take different approaches that listed in the sub-sections, to clarify this I would add the word “non-exhaustive” to to the last sentence. OLD Strategies for using a replacement in a transition are described below. NEW The non-exhaustive list of considerations for using a replacement in a transition are described below: Section 5.4.3.1 “Non-overlapping Replacements” This is certainly an option, but I haven’t seen an instance where this has been implemented in new versions of an RDAP extension. I don’t have an issue included this consideration if the sub-sections of 5.4.3 are defined as a non-exhaustive list of considerations. Section 5.4.3.2 “Overlapping Replacements” I don’t support this consideration for the extension authors, since extension replacements can have overlapping structures, but defining an inheritance hierarchy between extension replacements does not allow for the extension replacements to stand on their own. This will add a permanent inheritance dependency between RDAP extensions that should be avoided. The versioning extension did add relationship (“predecessor” and “successor”) support between the extensions, where the server can define the supported set of opaque extensions, their relationship, and when the extension will start and end being supported. If the concept of “Overlapping Replacements” is supported by the working group, then a relationship type will need to be added, such as “inherited” in this case. -- JG [cid87442*[email protected]] James Gould Fellow Engineer [email protected]<applewebdata://13890C55-AAE8-4BF3-A6CE-B4BA42740803/[email protected]> 703-948-3271 12061 Bluemont Way Reston, VA 20190 Verisign.com<http://verisigninc.com/>
_______________________________________________ regext mailing list -- [email protected] To unsubscribe send an email to [email protected]
