Hi James,
On Wed, May 03, 2023 at 07:50:07PM +0000, Gould, James wrote:
> In relation to the example JSONPath in the draft, they are based on
> the unredacted RDAP lookup response in Figure 11 and are snippets
> from the redacted RDAP lookup response in Figure 12. They are not
> intended to provide an example for a broader set of unredacted RDAP
> responses, such as having multiple entities with the same role.
Right, but section 3.1 has:
An example of redacting an RDAP object is removing the
administrative contact from the RDAP response and including the
following "redacted" member:
"redacted": [
{
"name": {
"type": "Administrative Contact"
},
"prePath": "$.entities[?(@.roles[0]=='administrative')]",
"method": "removal"
}
]
i.e., it's presented as being of general application, and it's not
until much later in the document that the caveats around multiple
roles are noted (in section 5.2). The obvious fix is to note in the
text that the examples assume single-role entities, but even with that
approach there's no way for a client to know that a server will
include only single-role entities, and if the client doesn't know
that, then they are left with the (incorrect) inference from my
previous mail (that entities where the first role in the array is
administrative have been removed). Removing the prePath in this sort
of case addresses the problem.
> Validating the JSONPath has been discussed previously on the mailing
> list, but the approach for the draft was to use https://jsonpath.com
> with the RDAP lookup response in Figure 11 and validate that the
> example JSONPath resulted in the desired JSON members. The use of
> the wildcard (*) states in draft-ietf-jsonpath-base-12:
>
> A wildcard * (Section 2.3.2) in the expression [*] selects all
> children of a node and in the expression ..[*] selects all
> descendants of a node.
>
> The use of $.entities[?(@.roles[*]=='administrative')] does not look
> to match the definition and fails with https://jsonpath.com.
>
> I provide more detailed responses to your feedback embedded below.
>
> On 4/25/23, 8:16 PM, "regext on behalf of Tom Harrison"
> <regext-boun...@ietf.org <mailto:regext-boun...@ietf.org> on behalf of
> t...@apnic.net <mailto:t...@apnic.net> wrote:
>> On Mon, Apr 17, 2023 at 03:27:23PM +0200, Antoin Verschuren wrote:
>>> The document editors have indicated that the following document is
>>> ready for submission to the IESG to be considered for publication as
>>> a Proposed Standard:
>>>
>>> ...
>>
>> Looks good overall, some minor comments/suggestions.
>>
>> Per previous mail from Pawel and Mario, some of the JSON path
>> expressions are not quite right for entities that have multiple
>> roles. There are some issues with the guidance added to the
>> document to account for this, though, and some further updates in
>> this space that would be useful. (We rely on entities having
>> multiple roles in our server implementation at the moment, for
>> reference, and returning a copy of each entity per role as a
>> workaround is not ideal, particularly when addressing the comments
>> here shouldn't be difficult.) To summarise these issues (mostly
>> along the lines of the comments from Pawel and Mario):
>>
>> - The first example use of prePath has a value of:
>>
>> $.entities[?(@.roles[0]=='administrative')]
>>
>> But all that a client can infer from this path is that all
>> entities with "administrative" as their first role have been
>> removed. Since there are no guarantees around ordering of roles
>> within an entity, this doesn't necessarily mean that all
>> entities with "administrative" as one of their roles have been
>> removed from the resulting object. It would be better to use a
>> more general expression in this example (and the others like it)
>> that captured the intent more clearly. Per earlier mail from
>> Pawel, something like:
>>
>> $.entities[?(@.roles[*]=='administrative')]
>>
>> should do the job, though I wasn't able to determine the syntax
>> that would be acceptable for draft-ietf-jsonpath-base.
>
> This JSONPath would not comply with draft-ietf-jsonpath-base. You
> can use the guidance provided by including multiple “redacted”
> member fields with JSONPath entries (“prePath” or “postPath” ) or
> decide not to use the JSONPath (“prePath” or “postPath” ) and signal
> it with a registered “name” child member, such as:
>
> "redacted": [
> {
> "name": {
> "type": "Administrative Contact"
> },
> "method": "removal"
> }
> ]
Signalling via "name" exclusively is sensible, but if that's the
approach that has to be used for multiple-role entities, and it works
for single-role entities as well, and it would avoid the problem with
the ambiguous prePath, why not update the examples to use this
approach? Assuming that the document registers the associated types,
this would also increase implementation consistency, which will make
things easier on clients. (Even if the signalling is unregistered,
and relies on "description", it at least puts the client on notice
that if they want to understand what's happening more precisely,
they'll need to get that information out of band.)
>> - Section 5.2 at point 4 has:
>>
>> When an entity has multiple roles, include "redacted"
>> members for each role using the role index. This will
>> result in duplicate "redacted" members, but will enable the
>> client to treat redaction consistently when there is a
>> single role per entity or multiple roles per entity.
>>
>> It's not clear why this advice is present, when compared with
>> e.g. having the redacted members be a mapping from the server's
>> policies. For example, if the policy is that administrative
>> contacts not be returned, then a single "redacted" entry with a
>> prePath like "$.entities[?(@.roles[*]=='administrative')]"
>> clearly conveys that message to the client, and the client will
>> understand that those entities will be removed regardless of any
>> additional roles that they might have. How do multiple redacted
>> members enable the client to treat redaction consistently?
>
> I believe for your case, it may be better to signal using the “name”
> field only, such as “Administrative Contact”. The JSONPath
> expression that you’re referencing is not valid, so it’s not an
> option.
Using "name" makes sense, but it's still not clear to me why including
"redacted" members for each role would be useful in the multiple-role
case. Is this specifically about situations where the server policy
is such that e.g. both administrative and registrant role entities are
redacted?
>> - Section 5.2 at point 5 has:
>>
>> When there are multiple entities with the same role, include
>> "redacted" members for each entity using the entity index
>> instead of the role. A JSONPath can be created that
>> identifies the entity based on an index of a role selector
>> nodelist, such as "$.entities[?(@.roles[0]=='technical')][0]"
>> for the first entity with the "technical" role. Using the
>> entity index, such as "$.entities[1]", is simpler and
>> recommended.
>>
>> Similarly to the previous point, removing by index obscures the
>> server's intent. To use the example given above, if the server's
>> policy is that the first entity with a technical role is omitted,
>> then the first expression (though with 'roles[*]' instead of
>> 'roles[0]') conveys that message more clearly than removal by way
>> of index. (If the server's behaviour can't be conveyed by way of a
>> JSON path, e.g. where an entity is omitted because they have opted
>> out of being included in responses, then simply omitting the
>> prePath and relying on a specific registered redacted name for the
>> behaviour would make things clearer for the client than presenting
>> an entity index that they can't resolve/use.)
>
> Yes, you are correct. Maybe an update is to add the use of the
> “name” field approach to section 5.2 as a possible JSONPath Server
> Consideration. Do you agree? I still believe consideration 4 and 5
> are options that the server can choose to use.
Per earlier comments, using "name" makes sense, but I don't see a case
where it would be useful for a server to follow the guidance in
consideration 4 or 5 instead of that. "name" (if relying on "type")
can be used to describe unambiguously what is happening, whereas the
approaches in considerations 4 and 5 cannot. (Particularly with 5,
the JSON path will often resolve successfully when applied to the
response, too.)
>> - Section 5.1 at point 1 has:
>>
>> When the server is using the Redaction By Removal Method
>> (Section 3.1) or the Redaction by Replacement Value Method
>> (Section 3.4) with an alternate field value, the JSONPath
>> expression of the "prePath" member will not resolve
>> successfully with the redacted response. The client can
>> first key off the "name" member for display logic and
>> utilize a template RDAP response overlaid with the redacted
>> response to successfully resolve the JSONPath expression.
>>
>> There is an earlier thread where the "template RDAP response" is
>> discussed, but it was noted there that it would likely be difficult
>> to construct a one-size-fits-all template response. I think that's
>> correct, given the flexibility of the underlying data format, but
>> that in turns means that a "template RDAP response" would have to
>> be generated on a per-server basis (something that was also flagged
>> in that thread). There's no guidance for clients (or servers) on
>> this point, though. Omitting the last sentence here will address
>> the problem.
>
> The last sentence is the guidance for the client.
Right, but in the absence of guidance about the generation or use of
such responses, a client might not turn their mind to the various
risks here (e.g. there's no one-size-fits-all template, a template
might work for some servers but not others, if the server hasn't
confirmed the template then there's a chance that overlaying the
redacted response will lead to misleading results).
> I believe the issue is the use of the word “first” and the use of an
> “and” instead of an “or”. The last sentence could read:
>
> “The client can key off the "name" member for display logic or
> utilize a template RDAP response overlaid with the redacted response
> to successfully resolve the JSONPath expression.”
>
> Those are really the two options to choose from for the client, key
> off of the “name” member or use a template RDAP response with
> overlaying the redacted response. Do you believe this revised
> sentence is better?
No, because it doesn't elaborate "template RDAP response". If
expanding the concept of a template response isn't appealing, then I'd
suggest omitting the template response concept, so the sentence
changes to:
The client can key off the "name" member for display logic related
to the redaction.
If that doesn't work, then maybe noting that generating and using
template RDAP responses is something that is out of scope for the
purposes of this document, and will generally require co-ordination
between the server and the client.
>> - Also on section 5.1 point 1, the prePath expression will sometimes
>> resolve 'successfully' when evaluating the redacted response, in
>> the sense that it can be applied to the response and will return a
>> result. For example, if the first technical-role entity is
>> redacted by removal, but the object contains two technical-role
>> entities, then the prePath will resolve to the second
>> technical-role entity. This could be confusing for implementors,
>> particularly given that the other JSONPath expressions will resolve
>> correctly when evaluated against the redacted response. Some extra
>> text here clarifying that the expression may evaluate
>> 'successfully', but not 'correctly', would be useful.
>>
>> - (Another way of addressing all of the above is to remove prePath
>> altogether, given that it's optional, and given that in most cases
>> servers should use registered redacted names anyway, the
>> descriptions for which can document the associated behaviour
>> clearly and unambiguously.)
>>
>> In the definition for "name" in the "redacted" member, in section 4.2,
>> the text has "[t]he logical name is defined using an object with a
>> 'type' field denoting a registered redacted name (see Section 6.2)".
>> The document uses various names in the examples (e.g. "Administrative
>> Contact" in figure 1) without registering them, though. Registering
>> those names would address the problem, or alternatively the
>> "description" field for unregistered names could be used in the
>> examples instead.
>
> The plan was for the draft to support the framework for
> registration, but to leave the actual registrations up to server
> policy. There is a set of “redacted name” registrations defined in
> Appendix E of the latest RDAP Response Profile
> (https://docs.google.com/document/d/19Hlt-_oID4pb7Pm-Epn4Kfm4PWTxVcpLlb61c34srJ4/edit#heading=h.rxp0nowps88ithat)
> that will be registered once the IANA JSON Values Registry is
> updated to support it and once the RDAP Response Profile is final
> and published.
OK, but an implementor picking this up today could end up using a
series of unregistered names inadvertently, by relying on the
examples. Assuming they aren't going to be registered in this
document, what about changing the examples to use "name"."description"
instead of "name"."type"?
(On a related point, there are some inconsistencies with the use of
"type" and "description" in the document. For example, figure 1 has
"type" with a value of "Administrative Contact", while figure 11 has
"description" with a value of "Administrative Contact".)
>> Section 6.2 has:
>>
>> Two new JSON Values Registry Type field values are used to register
>> pre-defined redacted name and reason values:
>>
>> "redacted name": Redacted name being registered. The registered
>> redacted name is referenced using the "type" field of the
>> redacted "name" field.
>>
>> "redacted reason": Redacted reason being registered. The registered
>> redacted reason is referenced using the "type" field of the
>> redacted "reason" field.
>>
>> "redacted expression language": Redacted expression language being
>> registered. The registered redacted expression language is
>> referenced using the "pathLang" field.
>>
>> The following values should be registered by the IANA in the RDAP
>> JSON Values Registry described in [RFC7483]: ...
>>
>> This would read better if the first sentence took account of the
>> "redacted expression language" registration as well, or alternatively
>> if similar text was added after the "redacted reason" entry.
>
> It should be “Three new JSON Values Registry Type field values…”
> instead of “Two new JSON Values Registry Type field values…”. Does
> that address your feedback?
No, because the first sentence would become:
Three new JSON Values Registry Type field values are used to
register pre-defined redacted name and reason values
but the third type value here is not for registering pre-defined
redacted name and reason values. Suggested text:
Three new JSON Values Registry Type field values are used to
register pre-defined redacted name, reason, and expression
language values
-Tom
_______________________________________________
regext mailing list
regext@ietf.org
https://www.ietf.org/mailman/listinfo/regext
