# Document Shepherd Write-Up for Group Documents
*This version is dated 4 July 2022.*
Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.
Note that some numbered items contain multiple related questions; please be sure
to answer all of them.
## Document History
>1. Does the working group (WG) consensus represent the strong concurrence of a
> few individuals, with others being silent, or did it reach broad agreement?
It had broad, although at times shallow, consensus. Nobody was ever really
opposed. This is typical of the HTTPAPI WG, which has a mix of people who are
interested in different aspects of HTTP API's.
>2. Was there controversy about particular points, or were there decisions where
> the consensus was particularly rough?
Earlier in the draft history, there was a suggestion that this concept is really
part of a larger lifecycle for APIs. After a couple of months nobody stepped
forward to work on such a document, and the Chairs decided (backed by no
opposition from the WG membership) to proceed with "just" deprecation.
There was also a (relatively) large amount of discussion around one
particular issue,
https://github.com/ietf-wg-httpapi/deprecation-header/issues/11 The Chairs
determined rough consensus for the authors's proposed resolution.
>3. Has anyone threatened an appeal or otherwise indicated extreme discontent?
If > so, please summarize the areas of conflict in separate email messages to
the > responsible Area Director. (It should be in a separate email because
this > questionnaire is publicly available.)
No, neither.
>4. For protocol documents, are there existing implementations of the contents
of > the document? Have a significant number of potential implementers
indicated > plans to implement? Are any existing implementations reported
somewhere, > either in the document itself (as [RFC 7942][3] recommends) or
elsewhere > (where)?
The draft lists several implementations in Appendix A, including other IETF
work at https://tools.ietf.org/html/draft-loffredo-regext-rdap-jcard-deprecation
Implementations and questions have been discussed on many websites, including
StackOverflow, the Python library GitHub, and a nice blog post (at
https://imhoratiu.wordpress.com/2021/01/20/respectful-rest-apis-sunset-and-deprecation-http-headers/)
which compare header with Sunset (RFC 8594)
## Additional Reviews
>5. Do the contents of this document closely interact with technologies in other
> IETF working groups or external organizations, and would it therefore
benefit > from their review? Have those reviews occurred? If yes, describe
which > reviews took place.
There is membership overlap with HTTPBIS WG, which is the obvious place to
collaborate and it has been done informally.
>6. Describe how the document meets any required formal expert review criteria,
> such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.
None needed.
>7. If the document contains a YANG module, has the final version of the module
> been checked with any of the [recommended validation tools][4] for syntax
and > formatting validation? If there are any resulting errors or warnings,
what is > the justification for not fixing them at this time? Does the YANG
module > comply with the Network Management Datastore Architecture (NMDA) as
specified > in [RFC 8342][5]?
n/a
>8. Describe reviews and automated checks performed to validate sections of the
> final version of the document written in a formal language, such as XML
code, > BNF rules, MIB definitions, CBOR's CDDL, etc.
n/a
## Document Shepherd Checks
>9. Based on the shepherd's review of the document, is it their opinion that
this > document is needed, clearly written, complete, correctly designed, and
ready > to be handed off to the responsible Area Director?
Yes.
>10. Several IETF Areas have assembled [lists of common issues that their
> reviewers encounter][6]. For which areas have such issues been identified
> and addressed? For which does this still need to happen in subsequent
> reviews?
ART (now WIT). No issues.
>11. What type of RFC publication is being requested on the IETF stream ([Best
> Current Practice][12], [Proposed Standard, Internet Standard][13],
> [Informational, Experimental or Historic][14])? Why is this the proper type
> of RFC? Do all Datatracker state attributes correctly reflect this intent?
standards track and that makes sense since it defines a new HTTP header field.
>12. Have reasonable efforts been made to remind all authors of the intellectual
> property rights (IPR) disclosure obligations described in [BCP 79][7]? To
> the best of your knowledge, have all required disclosures been filed? If
> not, explain why. If yes, summarize any relevant discussion, including
links > to publicly-available messages when applicable.
Yes. No IPR claims.
>13. Has each author, editor, and contributor shown their willingness to be
> listed as such? If the total number of authors and editors on the front
page > is greater than five, please provide a justification.
Yes, both of them want to be listed as authors.
>14. Document any remaining I-D nits in this document. Simply running the
[idnits > tool][8] is not enough; please review the ["Content Guidelines" on
> authors.ietf.org][15]. (Also note that the current idnits tool generates >
some incorrect warnings; a rewrite is underway.)
Nothing important. One missing reference to the RFC for URI.
>15. Should any informative references be normative or vice-versa? See the [IESG
> Statement on Normative and Informative References][16].
There's a down ref question in the nits output which we would like guidance on.
Other then that, all seems fine.
>16. List any normative references that are not freely available to anyone. Did
> the community have sufficient access to review any such normative
> references?
None.
>17. Are there any normative downward references (see [RFC 3967][9] and [BCP
> 97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
> list them.
The doc references "SFBIS" draft, so this should probably be put in the same
cluster as that. See https://datatracker.ietf.org/doc/draft-ietf-httpbis-sfbis/
>18. Are there normative references to documents that are not ready to be
> submitted to the IESG for publication or are otherwise in an unclear state?
> If so, what is the plan for their completion?
Just the one; see prev question.
>19. Will publication of this document change the status of any existing RFCs?
If > so, does the Datatracker metadata correctly reflect this and are those
RFCs > listed on the title page, in the abstract, and discussed in the >
introduction? If not, explain why and point to the part of the document >
where the relationship of this document to these other RFCs is discussed.
No changes.
>20. Describe the document shepherd's review of the IANA considerations section,
> especially with regard to its consistency with the body of the document.
> Confirm that all aspects of the document requiring IANA assignments are
> associated with the appropriate reservations in IANA registries. Confirm
> that any referenced IANA registries have been clearly identified. Confirm
> that each newly created IANA registry specifies its initial contents,
> allocations procedures, and a reasonable name (see [RFC 8126][11]).
There are no new registries. There are two registry additions and both are
accurate with the rest of the document and seem fine to me.
>21. List any new IANA registries that require Designated Expert Review for
> future allocations. Are the instructions to the Designated Expert clear?
> Please include suggestions of designated experts, if appropriate.
n/a