Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 Unlike all other fields , we do not say that it is REQUIRED . I suspect this is just a typo , otherwise let 's clarify in the text . 
 This is address by the PR which makes the formats consistent . Marking as duplicate of 
 While reading through the latest draft , I found the expression of whether a request / response element is REQUIRED , OPTIONAL ( or even perhaps conditional ) is not very consistent . For instance in the top of nothing is defined about whether any of the top level request elements ( access_token , subject , client , etc ) are required or not ? Whereas in later sections like definitions for sub - request elements like " flags " ends with a sentence " This field is OPTIONAL " . And finally another convention is being used like in section where each request / response element definition starts with REQUIRED or OPTIONAL . For general readability of the document I suggest using one explicit convention across the entire document for all request / response data model elements , the following rule might suffice . For every request / response data model element , the definition should start with one of the following words OPTIONAL CONDITIONAL . If the definition is CONDITIONAL then the rest of the elements definition must stipulate the conditions under which the element will or will not be present . 
 I agree that consistency is better and more readable , and the editors will make an editorial pass to clean up things like this throughout the document . Note that CONDITIONAL is not a normative term , while REQUIRED and OPTIONAL both are , so we ca n't use the exact rule as suggested here . 
 Thanks agree this is purely editorial and therefore perhaps not high priority for the editors right now . However , w.r.t to conditional elements what do you propose the convention be for this ? As even though the term CONDITIONAL is not defined under BCP14 some way to convey this meaning in an elements definition may be useful from a readability perspective .
Paragraph (version A):
The "interact" field MUST contain the "start" key, and MAY contain
the "finish" and "hints" keys.  The value of each key is an array
which contains strings or JSON objects as defined below.
Paragraph (version A):
The following sections detail requests for interaction modes.
Additional interaction modes are defined in IANA.
Paragraph (version B):
The following sections detail requests for interaction hints.
Additional interaction hints are defined in IANA.
Paragraph (version A):
If the client instance indicates that it can request-interact-
usercode and the AS supports this mode for the client instance's
request, the AS responds with a "user_code" field.  This field is an
object that contains the following members.
Paragraph (version B):
If the client instance indicates that it can request-interact-
usercode and the AS supports this mode for the client instance's
request, the AS responds with a "user_code_uri" object that contains
the following members.
Paragraph (version A):
The JOSE header MUST contain the "kid" parameter of the key bound to
this signer for this request.  The "alg" parameter MUST be set to a
value appropriate for the key identified by "kid" and MUST NOT be
"none".
Paragraph (version A):
To protect the request, the JWS header MUST contain the following
additional parameters.
Paragraph (version B):
To protect the request, the JWS header contains the following claims.
Paragraph (version A):
While it is expected that many APIs will have their own properties, a
set of common properties are defined here.  Specific API
implementations SHOULD NOT re-use these fields with different
semantics or syntax.  The available values for these properties are
determined by the API being protected at the RS.
Paragraph (version B):
While it is expected that many APIs will have their own properties, a
set of common properties are defined here.  Specific API
implementations SHOULD NOT re-use these fields with different
semantics or syntax.  The available values for these properties are
determined by the API being protected at the RS.  All values are
OPTIONAL at the discretion of the API definition.
Paragraph (version A):
The information returned from this method is for optimization
purposes only.  The AS MAY deny any request, or any portion of a
request, even if it lists a capability as supported.  For example, a
given client instance can be registered with the "mtls" key proofing
mechanism, but the AS also returns other proofing methods, then the
AS will deny a request from that client instance using a different
proofing mechanism.
Paragraph (version B):
The information returned from this method is for optimization
purposes only.  The AS MAY deny any request, or any portion of a
request, even if it lists a capability as supported.  For example, a
given client instance can be registered with the "mtls" key proofing
mechanism, but the AS also returns other proofing methods from the
discovery document, then the AS will still deny a request from that
client instance using a different proofing mechanism.