Hi Tom,
please find my comments below.
Il 19/05/2022 08:35, Tom Harrison ha scritto:
Hi James,
On Wed, May 18, 2022 at 11:59:05AM +0000, Gould, James wrote:
On Wed, May 18, 2022 at 09:12:16AM +1000, Tom Harrison wrote:
The uniqueness aspect of the registry is fine, as is the 'null suffix'
part. I'm more concerned with the confusing way in which the various
documents interact in this respect and the fact that two different
'types' of values will be registered (advisedly) from now on.
I don't believe there will be any confusion since the purpose of the
registry is to ensure the uniqueness of the prefixes and identifiers
used by the RDAP extensions and the purpose of the referenced
specification is to define their usage.
Having reviewed the relevant text again, I think I know what happened
here (which is relevant to what to do next). RFC 7480 has:
For extensibility purposes, this document defines an IANA registry
for prefixes used in JSON [RFC7159] data serialization and URI
path segments (see Section 8).
Later in that document:
The purpose of this registry is to ensure uniqueness of extension
identifiers. The extension identifier is used as a prefix in JSON
names and as a prefix of path segments in RDAP URLs.
Followed by an example registration:
Extension identifier: lunarNic
Registry operator: The Registry of the Moon, LLC
Published specification: http://www.example/moon_apis/rdap
Person & email address to contact for further information:
Professor Bernardo de la Paz <[email protected]>
Intended usage: COMMON
lunarNic is not otherwise mentioned in RFC 7480. But RFC 7483 (not
9083) has:
When custom JSON values are inserted into responses, conformance
to those custom specifications MUST use a string prefixed with the
appropriate identifier from the IANA RDAP Extensions registry
specified in [RFC7480].
with an example conformance value of "lunarNic_level_0". It then goes
on to give example lunarNic fields like "lunarNic_beforeOneSmallStep".
For a user looking at this prior to the publication of RFC 9083, it
looks like:
- the prefix is what is registered as the extension identifier;
- if a conformance value begins with the prefix, then
the response is in accordance with the corresponding extension;
- such a response may contain new fields that begin with the prefix;
and
- the relevant server may support additional paths that begin with
the prefix, per the extension documentation.
Then there is Patrick Mevzek's thread (beginning at
https://mailarchive.ietf.org/arch/msg/regext/o0o4gpLNOpt5fficODoJr8LP-qM/)
from 2019, where his understanding is basically per the above, noting
some issues with this:
- is the text after the prefix in the conformance value free-form?
are there any requirements around that text more generally?
- if free-form text is permitted, then an extension identifier like
"cidr" means that no other extension beginning with "cidr" can be
registered, because a client would not be able to distinguish the
conformance values: is that intentional?
- why do some extensions embed the version in the extension?
after which Scott and Andy note that they expect the conformance
values to be exact matches for the extension identifiers, and that the
same will be addressed in 7483bis (i.e. 9083). That happens by
changing the following text in 7483:
When custom JSON values are inserted into responses, conformance
to those custom specifications MUST use a string prefixed with the
appropriate identifier from the IANA RDAP Extensions registry
specified in [RFC7480].
such that it becomes:
When custom JSON values are inserted into responses, conformance
to those custom specifications MUST be indicated by including a
unique string literal value registered in the IANA RDAP Extensions
registry specified in [RFC7480].
but neither 7480 nor the example lunarNic fields in 7483 are updated
to suit, leading to the current situation where it appears (at least
on one reading) that the conformance value must be used as the prefix.
If the change in 9083 is considered to be a mistake, and registering
prefixes is considered acceptable, then possibly the simplest option
is to:
- submit an erratum against 9083;
- continue registering extensions, but register only the prefixes;
and
- write a document clarifying all of this, as well as noting
conventions around versioning and so on, to avoid some of the
problems Patrick raised around namespacing and similar.
[ML] This is exactly what I was meaning in an earlier post of mine when
I wrote that version information should be excluded from the extension
identifier and rdapConformance tag should start with the extension
identifier and, optionally, end with the version number separated by
"_level_" or "_".
Having prefixes that include the version number would result in
producing breaking changes even when the changes wouldn't normally break
the REST API contract such as adding a new optional member to a response
extension or adding an optional parameter to an URI path.
Minor versions could be separated by dot so that it would be easy to
derive programmatically the extension identifier and the version
information by searching an rdapConformance tag for the last occurrence
of "_level_" (or secondly "_").
As the only consequence, i would recommend to correct the registered
extension identifiers ending with the string "_0" by removing the
version information.
Since all of such extension identifiers seems to me corresponding to
RDAP profiles, no breaking change would affect the current requests and
responses.
Otherwise, I consider James's proposal as a practicable alternative
permitting RDAP operators to exlcude version information from response
fields and URI path segments..
Best,
Mario
This has some added benefits:
- only one registry is needed; and
- the entries in the existing registry are all fine and do not need
to be changed (so long as conformance values are permitted to be
exact matches for extension identifiers, which doesn't seem to be
problematic).
It does mean that a given extension is restricted to a single
field/path prefix, but I'm not sure that that's a serious problem, or
at least I don't think there are any documents pending that are using
multiple prefixes.
-Tom
_______________________________________________
regext mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/regext
--
Dr. Mario Loffredo
Technological Unit “Digital Innovation”
Institute of Informatics and Telematics (IIT)
National Research Council (CNR)
via G. Moruzzi 1, I-56124 PISA, Italy
Phone: +39.0503153497
Web: http://www.iit.cnr.it/mario.loffredo
_______________________________________________
regext mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/regext
