# genart-early review of draft-ietf-gnap-resource-servers-06

CC @larseggert

I am the assigned Gen-ART reviewer for this draft. For background on
Gen-ART, please see the [FAQ](https://wiki.ietf.org/group/gen/GenArtFAQ).
Please resolve these comments along with any other comments you may receive.

## Comments

I don't know much about this area. The doc is well-written and seems
basically in good shape.

### Missing RFC status

Datatracker does not record an intended RFC status for this document.

### Section 2.1.1, paragraph 1
```
     All access tokens have a unique value.  This is the string that is
```
"Unique" in which sense? Between the parties at the time of usage,
between the parties at any time, within the entire domain,
globally?

### Section 2.1.1, paragraph 3
```
     The format and content of the access token value is opaque to the
     client software.  While the client software needs to be able to carry
     and present the access token value, the client software is never
     expected nor intended to be able to understand the token value
     itself.
```
Will it need to understand it sufficiently to determine that it is
unique in some way? (See above.) Also, this concept of opaqueness comes
up in other parts of the document, and it would be good to clarify if the
various parties involved in this protocol are required to verify that
property (and fail operations if it is violated?).

### Section 2.1.2, paragraph 3
```
     In a [JWT] formatted token or a token introspection response, this
     corresponds to the iss claim.
```
What is an "iss claim"? (A reference may be helpful.)

### Section 2.1.3, paragraph 2
```
     In a [JWT] formatted token or token introspection response, this
     corresponds to the aud claim.
```
What is an "aud claim"? (A reference may be helpful.)

### Section 5.3, paragraph 4
```
     *  the format's definition is sufficiently unique from other formats
        provided by existing parameters.
```
"sufficiently unique" is pretty vague, and give a lot of leeway to the
 experts. What would an example of "not sufficiently unique" be?

### Section 5.5, paragraph 4
```
     *  the claim's definition is sufficiently orthogonal to other claims
        defined in the registry so as avoid overlapping functionality.
```
See above, wrt "sufficiently unique". Other registries below have
similar verbiage; it would be nice to be a bit more descriptive in what the
expert should actually check here.

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### Grammar/style

#### Section 2.1.4, paragraph 4
```
ss_token section of the grant response response in Section 3.2 of [GNAP]. Fo
                              ^^^^^^^^^^^^^^^^^
```
Possible typo: you repeated a word.

#### Section 3.1, paragraph 3
```
ys by reference or by value in a similar fashion to a client instance callin
                            ^^^^^^^^^^^^^^^^^^^^
```
Consider replacing this phrase with the adverb "similarly" to avoid wordiness.

#### Section 3.3, paragraph 19
```
oken is no longer valid. Expressed as a integer seconds from UNIX Epoch. iat
                                      ^
```
Use "an" instead of "a" if the following word starts with a vowel sound, e.g.
"an article", "an hour".

#### Section 3.3, paragraph 20
```
en was issued by the AS. Expressed as a integer seconds from UNIX Epoch. nbf
                                      ^
```
Use "an" instead of "a" if the following word starts with a vowel sound, e.g.
"an article", "an hour".

#### Section 3.3, paragraph 20
```
this token is not valid. Expressed as a integer seconds from UNIX Epoch. aud
                                      ^
```
Use "an" instead of "a" if the following word starts with a vowel sound, e.g.
"an article", "an hour".

#### Section 6.1, paragraph 1
```
, a system can follow a principle of least disclosure to each RS. 6.9. Resour
                                     ^^^^^
```
A determiner may be missing.

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF], You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT].

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments
[IRT]: https://github.com/larseggert/ietf-reviewtool