Hello Sarah,
I had sent approval after reviewing diffs. Attached is xml with answers to
your questions. Look for "[sd]".
@erik.wi...@dret.net <erik.wi...@dret.net> pl review my answers too. Thanks!
On Tue, Mar 4, 2025 at 11:25 AM Sarah Tarrant <starr...@staff.rfc-editor.org>
wrote:
> Hi Sanjay,
>
> We note that you responded to the other email regarding this document's
> AUTH48 status:
>
> > Re: AUTH48: RFC-to-be 9745 <draft-ietf-httpapi-deprecation-header-09>
> for your review
> >
> > I approve.
>
> We ask that, before we mark your approval, you resolve the questions we
> have remaining.
>
> Please let us know if we can be of further assistance as you complete your
> review.
>
> Thank you,
> RFC Editor/st
>
> > On Mar 3, 2025, at 4:02 PM, rfc-edi...@rfc-editor.org wrote:
> >
> > Authors,
> >
> > While reviewing this document during AUTH48, please resolve (as
> necessary) the following questions, which are also in the XML file.
> >
> >
> > 1) <!-- [rfced] Please clarify "(in the sense of URI)" here. Also note
> that we do
> > not see "URI" used elsewhere in the document.
> >
> > Original:
> > The Deprecation HTTP response header field is used to signal to
> > consumers of a resource (in the sense of URI) that the resource will
> > be or has been deprecated.
> > -->
> >
> >
> > 2) <!-- [rfced] We suggest updating "and possibly ways" to improve
> readability of
> > the text. Also, this sentence includes both "Additionally" and
> > "additional". May we replace "additional" with "further" or something
> > similar?
> >
> > Original:
> > Additionally, the deprecation link
> > relation can be used to link to a resource that provides additional
> > information about planned or existing deprecation, and possibly ways
> > in which client application developers can best manage deprecation.
> >
> > Perhaps:
> > Additionally, the deprecation link
> > relation can be used to link to a resource that provides further
> > information about planned or existing deprecation. It may also provide
> ways
> > in which client application developers can best manage deprecation.
> > -->
> >
> >
> > 3) <!-- [rfced] Would it be helpful to update this sentence to clarify
> what the
> > document uses? Note that [STRUCTURED-FIELDS] has been published as an RFC
> > 9651, so we updated the reference entry accordingly. We used [RFC9651] as
> > the citation, bet us know if you prefer to use [STRUCTURED-FIELDS].
> >
> > Original:
> > This document uses "Structured Field Values for HTTP"
> > ([STRUCTURED-FIELDS]) to specify syntax and parsing of date values.
> >
> > Perhaps:
> > This document uses the mechanisms defined in [RFC9651] to
> > specify syntax and parsing of date values.
> > -->
> >
> >
> > 4) <!-- [rfced] May we we update the text starting with "and
> possibly..." as
> > follows to improve the flow of the sentence?
> >
> > Original:
> > This can happen before the actual
> > deprecation, to make a deprecation policy discoverable, or after
> > deprecation, when there may be documentation about the deprecation,
> > and possibly documentation of how to manage it.
> >
> > Perhaps:
> > This can happen before the actual
> > deprecation to make a deprecation policy discoverable or after
> > deprecation when there may be documentation about the deprecation and
> > how to manage it.
> > -->
> >
> >
> > 5) <!-- [rfced] Would it be helpful to update "under which circumstances
> and with
> > which policies" for readability as follows?
> >
> > Original:
> > This may be the documentation explaining under which
> > circumstances and with which policies deprecation might take place.
> >
> > Perhaps:
> > This may be the documentation explaining the
> > circumstances in which deprecation might take place and the
> deprecation policies.
> > -->
> >
> >
> > 6) <!-- [rfced] How may we update "allowing consumers to still" to
> improve
> > clarity?
> >
> > Original:
> > The presence of a Deprecation header field in response is not meant
> > to signal a change in the meaning or function of a resource in the
> > context, allowing consumers to still use the resource in the same way
> > as they did before the resource was declared deprecated.
> >
> > Perhaps:
> > The presence of a Deprecation header field in a response is not meant
> > to signal a change in the meaning or function of a resource in the
> > context; consumers can still use the resource in the same way
> > as they did before the resource was declared deprecated.
> > -->
> >
> >
> > 7) <!-- [rfced] Please review "resource that is documentation" here.
> Should this
> > be updated to "resource documentation", "documentation", or something
> > else?
> >
> > If any changes are made, we will ask IANA to update the "Link Relation
> Types"
> > accordingly prior to publication (link to registry:
> > https://www.iana.org/assignments/link-relations).
> >
> > Original:
> > Description: Refers to a resource that is documentation (intended for
> human
> > consumption) about the deprecation of the link's context.
> >
> > Perhaps:
> > Description: Refers to resource documentation (intended for human
> > consumption) about the deprecation of the link's context.
> >
> > Or:
> > Description: Refers to documentation (intended for human
> > consumption) about the deprecation of the link's context.
> > -->
> >
> >
> > 8) <!-- [rfced] How may we update the text starting with "even though one
> > might..." to improve sentence clarity?
> >
> > Original:
> > Deprecated resources function as
> > they would have without sending the deprecation header field, even
> > though one might consider non-functional details such as making them
> > progressively less efficient with longer response time for example.
> >
> > Perhaps:
> > Deprecated resources function as
> > they would have without sending the Deprecation header field,
> > even though non-functional details may be affected (e.g.,
> > they have less efficiency and longer response times).
> > -->
> >
> >
> > 9) <!-- [rfced] What does "it" refer to in this sentence?
> >
> > Original:
> > In cases where the Deprecation header field value is a date in the
> > future, it can lead to information that otherwise might not be
> > available.
> >
> > Perhaps:
> > In cases where the Deprecation header field value is a date in the
> > future, information might become available that would not be available
> otherwise.
> > -->
> >
> >
> > 10) <!-- [rfced] Some sentences in the document mention deprecation of
> the
> > resource while others mention deprecation of the context. Please review
> > and let us know if any updates are needed.
> >
> > deprecation of "resource":
> > resource will be or has been deprecated
> > resource in context of the message is or will be deprecated
> > resource in context has been deprecated
> > deprecation of the resource
> > deprecation of that specific resource
> > deprecation of a resource(s)
> >
> > deprecation of "context":
> > resource context will be deprecated
> > resource context has been deprecated
> > deprecation of the context
> > deprecation of the resource context
> > deprecation of the link's context
> >
> > Please also review use of "context" and let us know if any updates are
> needed
> > for consistency and clarity.
> >
> > Examples:
> > resource in context of the message
> > resource context
> > resource in context
> > resource in the context
> > link's context
> > -->
> >
> >
> > 11) <!-- [rfced] We note inconsistencies in the terms below throughout
> the
> > text. Should these be uniform? If so, please let us know which form is
> > preferred.
> >
> > Deprecation HTTP response header field
> > Deprecation HTTP header field
> > Deprecation response header field
> > Deprecation header field
> >
> > Sunset HTTP header field
> > Sunset header field
> >
> > deprecation link relation
> > "deprecation" link relation type
> > relation type deprecation
> > deprecation link relation type
> >
> > resource documentation
> > resource's documentation
> >
> > deprecation information
> > deprecation-related information
> > -->
> >
> >
> > 12) <!-- [rfced] We see inconsistent use of <tt> in this document.
> Please review
> > the specific questions below. Note: In the html and pdf outputs, the text
> > enclosed in <tt> is output in fixed-width font; in the txt output, there
> > are no changes to the font.
> >
> > a) For header fields, we see use of both <tt> and no <tt>. See examples
> > below. Which form do you prefer?
> >
> > <tt>Deprecation</tt> header field
> > Deprecation header field
> >
> > <tt>Link</tt> header field
> > Link header field
> >
> > <tt>Sunset</tt> header field
> > Sunset HTTP header field
> >
> >
> > b) For the link relation type, we see use of <tt>, quotation marks, and
> no
> > <tt> or quotation marks. Which form do you prefer?
> >
> > <tt>deprecation</tt> link relation type
> > "deprecation" link relation
> > deprecation link relation
> > -->
> >
> >
> > 13) <!-- [rfced] Please review each artwork element in the xml file.
> Specifically,
> > should any artwork element be tagged as sourcecode or another element?
> > -->
> >
> >
> > 14) <!-- [rfced] Please review the "Inclusive Language" portion of the
> online
> > Style Guide <
> https://www.rfc-editor.org/styleguide/part2/#inclusive_language>
> > and let us know if any changes are needed. Updates of this nature
> typically
> > result in more precise language, which is helpful for readers.
> >
> > Note that our script did not flag any words in particular, but this
> should
> > still be reviewed as a best practice.
> > -->
> >
> >
> > Thank you.
> >
> > RFC Editor/st/rv
> >
> >
> > On Mar 3, 2025, at 1:39 PM, rfc-edi...@rfc-editor.org wrote:
> >
> > *****IMPORTANT*****
> >
> > Updated 2025/03/03
> >
> > RFC Author(s):
> > --------------
> >
> > Instructions for Completing AUTH48
> >
> > Your document has now entered AUTH48. Once it has been reviewed and
> > approved by you and all coauthors, it will be published as an RFC.
> > If an author is no longer available, there are several remedies
> > available as listed in the FAQ (https://www.rfc-editor.org/faq/).
> >
> > You and you coauthors are responsible for engaging other parties
> > (e.g., Contributors or Working Group) as necessary before providing
> > your approval.
> >
> > Planning your review
> > ---------------------
> >
> > Please review the following aspects of your document:
> >
> > * RFC Editor questions
> >
> > Please review and resolve any questions raised by the RFC Editor
> > that have been included in the XML file as comments marked as
> > follows:
> >
> > <!-- [rfced] ... -->
> >
> > These questions will also be sent in a subsequent email.
> >
> > * Changes submitted by coauthors
> >
> > Please ensure that you review any changes submitted by your
> > coauthors. We assume that if you do not speak up that you
> > agree to changes submitted by your coauthors.
> >
> > * Content
> >
> > Please review the full content of the document, as this cannot
> > change once the RFC is published. Please pay particular attention to:
> > - IANA considerations updates (if applicable)
> > - contact information
> > - references
> >
> > * Copyright notices and legends
> >
> > Please review the copyright notice and legends as defined in
> > RFC 5378 and the Trust Legal Provisions
> > (TLP – https://trustee.ietf.org/license-info).
> >
> > * Semantic markup
> >
> > Please review the markup in the XML file to ensure that elements of
> > content are correctly tagged. For example, ensure that <sourcecode>
> > and <artwork> are set correctly. See details at
> > <https://authors.ietf.org/rfcxml-vocabulary>.
> >
> > * Formatted output
> >
> > Please review the PDF, HTML, and TXT files to ensure that the
> > formatted output, as generated from the markup in the XML file, is
> > reasonable. Please note that the TXT will have formatting
> > limitations compared to the PDF and HTML.
> >
> >
> > Submitting changes
> > ------------------
> >
> > To submit changes, please reply to this email using ‘REPLY ALL’ as all
> > the parties CCed on this message need to see your changes. The parties
> > include:
> >
> > * your coauthors
> >
> > * rfc-edi...@rfc-editor.org (the RPC team)
> >
> > * other document participants, depending on the stream (e.g.,
> > IETF Stream participants are your working group chairs, the
> > responsible ADs, and the document shepherd).
> >
> > * auth48archive@rfc-editor.org, which is a new archival mailing list
> > to preserve AUTH48 conversations; it is not an active discussion
> > list:
> >
> > * More info:
> >
> https://mailarchive.ietf.org/arch/msg/ietf-announce/yb6lpIGh-4Q9l2USxIAe6P8O4Zc
> >
> > * The archive itself:
> > https://mailarchive.ietf.org/arch/browse/auth48archive/
> >
> > * Note: If only absolutely necessary, you may temporarily opt out
> > of the archiving of messages (e.g., to discuss a sensitive matter).
> > If needed, please add a note at the top of the message that you
> > have dropped the address. When the discussion is concluded,
> > auth48archive@rfc-editor.org will be re-added to the CC list and
> > its addition will be noted at the top of the message.
> >
> > You may submit your changes in one of two ways:
> >
> > An update to the provided XML file
> > — OR —
> > An explicit list of changes in this format
> >
> > Section # (or indicate Global)
> >
> > OLD:
> > old text
> >
> > NEW:
> > new text
> >
> > You do not need to reply with both an updated XML file and an explicit
> > list of changes, as either form is sufficient.
> >
> > We will ask a stream manager to review and approve any changes that seem
> > beyond editorial in nature, e.g., addition of new text, deletion of
> text,
> > and technical changes. Information about stream managers can be found
> in
> > the FAQ. Editorial changes do not require approval from a stream
> manager.
> >
> >
> > Approving for publication
> > --------------------------
> >
> > To approve your RFC for publication, please reply to this email stating
> > that you approve this RFC for publication. Please use ‘REPLY ALL’,
> > as all the parties CCed on this message need to see your approval.
> >
> >
> > Files
> > -----
> >
> > The files are available here:
> > https://www.rfc-editor.org/authors/rfc9745.xml
> > https://www.rfc-editor.org/authors/rfc9745.html
> > https://www.rfc-editor.org/authors/rfc9745.pdf
> > https://www.rfc-editor.org/authors/rfc9745.txt
> >
> > Diff file of the text:
> > https://www.rfc-editor.org/authors/rfc9745-diff.html
> > https://www.rfc-editor.org/authors/rfc9745-rfcdiff.html (side by side)
> >
> > Alt-diff of the text (allows you to more easily view changes
> > where text has been deleted or moved):
> > https://www.rfc-editor.org/authors/rfc9745-alt-diff.html
> >
> > Diff of the XML:
> > https://www.rfc-editor.org/authors/rfc9745-xmldiff1.html
> >
> >
> > Tracking progress
> > -----------------
> >
> > The details of the AUTH48 status of your document are here:
> > https://www.rfc-editor.org/auth48/rfc9745
> >
> > Please let us know if you have any questions.
> >
> > Thank you for your cooperation,
> >
> > RFC Editor
> >
> > --------------------------------------
> > RFC9745 (draft-ietf-httpapi-deprecation-header-09)
> >
> > Title : The Deprecation HTTP Header Field
> > Author(s) : S. Dalal, E. Wilde
> > WG Chair(s) : Darrel Miller, Rich Salz
> > Area Director(s) : Zaheduzzaman Sarker, Francesca Palombini
> >
>
>
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc [
<!ENTITY nbsp " ">
<!ENTITY zwsp "​">
<!ENTITY nbhy "‑">
<!ENTITY wj "⁠">
]>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude"; ipr="trust200902"
docName="draft-ietf-httpapi-deprecation-header-latest" number="9745" updates="" obsoletes=""
submissionType="IETF" category="std" consensus="true" tocInclude="true" sortRefs="true"
symRefs="true" version="3" xml:lang="en">
<front>
<title>The Deprecation HTTP Header Field</title>
<seriesInfo name="RFC" value="9745" />
<author initials="S." surname="Dalal" fullname="Sanjay Dalal">
<address>
<email>sanjay.da...@cal.berkeley.edu</email>
<uri>https://github.com/sdatspun2</uri>
</address>
</author>
<author initials="E." surname="Wilde" fullname="Erik Wilde">
<address>
<email>erik.wi...@dret.net</email>
<uri>http://dret.net/netdret</uri>
</address>
</author>
<date year="2025" month="March" />
<area>WIT</area>
<workgroup>httpapi</workgroup>
<keyword>HTTP</keyword>
<keyword>deprecation</keyword>
<!-- [rfced] Please clarify "(in the sense of URI)" here. Also note that we do
not see "URI" used elsewhere in the document.
Original:
The Deprecation HTTP response header field is used to signal to
consumers of a resource (in the sense of URI) that the resource will
be or has been deprecated.
-->
<!--[sd]
it is ok as-is -->
<!-- [rfced] We suggest updating "and possibly ways" to improve readability of
the text. Also, this sentence includes both "Additionally" and
"additional". May we replace "additional" with "further" or something
similar?
Original:
Additionally, the deprecation link
relation can be used to link to a resource that provides additional
information about planned or existing deprecation, and possibly ways
in which client application developers can best manage deprecation.
Perhaps:
Additionally, the deprecation link
relation can be used to link to a resource that provides further
information about planned or existing deprecation. It may also provide ways
in which client application developers can best manage deprecation.
-->
<!--[sd]
Your suggestion is good. -->
<abstract>
<t>The Deprecation HTTP response header field is used to signal to
consumers of a resource (in the sense of URI) that the resource will be
or has been deprecated. Additionally, the deprecation link relation can be
used to link to a resource that provides additional information about
planned or existing deprecation and possibly ways in which client
application developers can best manage deprecation.</t>
</abstract>
</front>
<middle>
<section anchor="introduction">
<name>Introduction</name>
<t>Deprecation of an HTTP resource (<xref section="3.1" sectionFormat="of" target="RFC9110" />)
communicates information about the lifecycle of a resource. It encourages client
applications to migrate away from the resource, discourages applications from forming new
dependencies on the resource, and informs applications about the risk of continued
dependence upon the resource.</t>
<t>The act of deprecation does not change any behavior of the resource. It informs client
applications of the fact that a resource will be or has been deprecated. The Deprecation
HTTP response header field can be used to convey this information at runtime and indicate
when the deprecation will be in effect.</t>
<t>In addition to the Deprecation header field, the resource provider can use other header
fields such as the Link header field <xref target="RFC8288" /> to convey additional
information related to deprecation. This can be information such as where to find
documentation related to the deprecation, what can be used as a replacement, and when a
deprecated resource becomes non-operational.</t>
<section anchor="requirements-language">
<name>Notational Conventions</name>
<t> The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>",
"<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD
NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>",
and "<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as described in
BCP 14 <xref target="RFC2119" /> <xref
target="RFC8174" /> when, and only when, they appear in all capitals, as shown here. </t>
<!-- [rfced] Would it be helpful to update this sentence to clarify what the
document uses? Note that [STRUCTURED-FIELDS] has been published as an RFC
9651, so we updated the reference entry accordingly. We used [RFC9651] as
the citation, bet us know if you prefer to use [STRUCTURED-FIELDS].
Original:
This document uses "Structured Field Values for HTTP"
([STRUCTURED-FIELDS]) to specify syntax and parsing of date values.
Perhaps:
This document uses the mechanisms defined in [RFC9651] to
specify syntax and parsing of date values.
-->
<!-- [sd] The draft we referred is now RFC9651. Thanks for replacing. -->
<t>This document uses "<xref target="RFC9651" format="title" />" <xref
target="RFC9651" /> to specify syntax and parsing of date values.</t>
<t>The term "resource" is to be interpreted as defined in <xref
section="3.1" sectionFormat="of" target="RFC9110" />.</t>
</section>
</section>
<section anchor="the-deprecation-http-response-header-field">
<name>The Deprecation HTTP Response Header Field</name>
<t>The <tt>Deprecation</tt> HTTP response header field allows a server to communicate to a
client application that the resource in the context of the message will be or has been
deprecated.</t>
<section anchor="syntax">
<name>Syntax</name>
<t>The <tt>Deprecation</tt> response header field describes the deprecation of the resource
identified with the response it occurred within (see <xref section="6.4.2"
sectionFormat="of" target="RFC9110" />). It conveys the deprecation date, which may be
in the future (the resource context will be deprecated at that date) or in the past (the
resource context was deprecated at that date).</t>
<t><tt>Deprecation</tt> is an Item Structured Header Field; its value <bcp14>MUST</bcp14> be
a Date as per <xref section="3.3.7" sectionFormat="of" target="RFC9651" />.</t>
<t>The following example shows that the resource context was deprecated on Friday, June 30,
2023 at 23:59:59 UTC:</t>
<artwork><![CDATA[
Deprecation: @1688169599
]]></artwork>
</section>
<section anchor="scope">
<name>Scope</name>
<t>The Deprecation header field applies to the resource identified with the response it
occurred within (see <xref section="6.4.2" sectionFormat="of" target="RFC9110" />),
meaning that it announces the upcoming deprecation of that specific resource. However,
there may be scenarios where the scope of the announced deprecation is larger than just
the single resource where it appears.</t>
<t>Resources are free to define such an increased scope, and usually this scope will be
documented by the resource so that consumers of the resource know about the increased
scope and can behave accordingly. When doing so, it is important to take into account that
such increased scoping is invisible for consumers who are unaware of the increased scoping
rules. This means that these consumers will not be aware of the increased scope, and they
will not interpret deprecation information differently from its standard meaning (i.e., it
applies to the resource only).</t>
<t>Using such an increased scope still may make sense, as deprecation information is only a
hint anyway. It is optional information that cannot be depended on, and client
applications should always be implemented in ways that allow them to function without
deprecation information. Increased scope information may help client application
developers to glean additional hints from related resources and thus might allow them to
implement behavior that enables them to make educated guesses about resources becoming
deprecated.</t>
<t>For example, an API might not use Deprecation header fields on all of its resources but
only on designated resources such as the API's home document. This means that deprecation
information is available, but in order to get it, client application developers have to
periodically inspect the home document. In this example, the extended context of the
Deprecation header field would be all resources provided by the API, while the visibility
of the information would only be on the home document.</t>
</section>
</section>
<section anchor="the-deprecation-link-relation-type">
<name>The Deprecation Link Relation Type</name>
<!-- [rfced] May we we update the text starting with "and possibly..." as
follows to improve the flow of the sentence?
Original:
This can happen before the actual
deprecation, to make a deprecation policy discoverable, or after
deprecation, when there may be documentation about the deprecation,
and possibly documentation of how to manage it.
Perhaps:
This can happen before the actual
deprecation to make a deprecation policy discoverable or after
deprecation when there may be documentation about the deprecation and
how to manage it.
-->
<!-- [sd] Your suggestion looks good. -->
<t>In addition to the Deprecation HTTP header field, the server can use links with the
"deprecation" link relation type to communicate to the client application developer where to
find more information about deprecation of the context. This can happen before the actual
deprecation to make a deprecation policy discoverable or after deprecation when there may be
documentation about the deprecation and possibly documentation of how to manage it.</t>
<t>This specification places no restrictions on the representation of the linked deprecation
policy. In particular, the deprecation policy may be available as human-readable
documentation or as a machine-readable description.</t>
<section anchor="documentation">
<name>Documentation</name>
<t>The purpose of the <tt>Deprecation</tt> header field is to provide a hint about
deprecation to the resource consumer. Upon reception of the <tt>Deprecation</tt> header
field, the client application developer can look up the resource's documentation in order
to find deprecation-related information. The documentation <bcp14>MAY</bcp14> provide a
guide and timeline for migrating away from the deprecated resource to a new resource(s)
that replaces the deprecated resource, if applicable. The resource provider can provide a
link to the resource documentation using a <tt>Link</tt> header field with the relation
type <tt>deprecation</tt> as shown below:</t>
<artwork><![CDATA[
Link: <https://developer.example.com/deprecation>;
rel="deprecation"; type="text/html"
]]></artwork>
<!-- [rfced] Would it be helpful to update "under which circumstances and with
which policies" for readability as follows?
Original:
This may be the documentation explaining under which
circumstances and with which policies deprecation might take place.
Perhaps:
This may be the documentation explaining the
circumstances in which deprecation might take place and the deprecation policies.
-->
<!-- [sd] Your suggestion looks good. -->
<t>In this example, the linked content provides additional information
about deprecation of the resource context. There is no Deprecation
header field in the response; thus, the resource is not (yet)
deprecated. However, the resource already exposes a link where
information describing how deprecation is managed for the resource is
available. This may be the documentation explaining under which
circumstances and with which policies deprecation might take
place. For example, a policy may indicate that deprecation of a
resource(s) will always be signaled in the dedicated places at least N
days ahead of the planned deprecation date and then the
resource(s) would be deprecated on the planned date. Or a policy may indicate that the
resource(s) would be deprecated first and then be signaled as
deprecated at dedicated places. The documentation, in addition to the
deprecation policy, may also provide a migration guide explaining to
consumers of the resource how to migrate to a new or alternate
resource(s) before the deprecation date. Such policy and documentation
would be very useful to consumers of the resource to plan ahead and
migrate successfully.</t>
<t>The following example uses the same Link header field but also announces a deprecation
date using a Deprecation header field:</t>
<artwork><![CDATA[
Deprecation: @1688169599
Link: <https://developer.example.com/deprecation>;
rel="deprecation"; type="text/html"
]]></artwork>
<t>Given that the deprecation date is in the past, the linked information resource may have
been updated to include information about the deprecation, allowing consumers to discover
information about the deprecation and how to best manage it.</t>
</section>
</section>
<section anchor="sunset">
<name>Sunset</name>
<t>In addition to the deprecation-related information, if the resource provider wants to
convey to the client application that the deprecated resource is expected to become
unresponsive at a specific point in time, the Sunset HTTP header field <xref
target="RFC8594" /> can be used in addition to the <tt>Deprecation</tt> header field.</t>
<t>The timestamp given in the <tt>Sunset</tt> header field <bcp14>MUST NOT</bcp14> be earlier
than the one given in the <tt>Deprecation</tt> header field. If that happens (for example,
due to misconfiguration of deployment of the resource or an error), the client application
developer <bcp14>SHOULD</bcp14> consult the resource developer to get clarification.</t>
<t>The following example shows that the resource in context was deprecated on Friday, June 30,
2023 at 23:59:59 UTC and its sunset date is Sunday, June 30, 2024 at 23:59:59 UTC. Please
note that for historical reasons the Sunset HTTP header field uses a different data format
for date.</t>
<artwork><![CDATA[
Deprecation: @1688169599
Sunset: Sun, 30 Jun 2024 23:59:59 UTC
]]></artwork>
</section>
<section anchor="resource-behavior">
<name>Resource Behavior</name>
<!-- [rfced] How may we update "allowing consumers to still" to improve
clarity?
Original:
The presence of a Deprecation header field in response is not meant
to signal a change in the meaning or function of a resource in the
context, allowing consumers to still use the resource in the same way
as they did before the resource was declared deprecated.
Perhaps:
The presence of a Deprecation header field in a response is not meant
to signal a change in the meaning or function of a resource in the
context; consumers can still use the resource in the same way
as they did before the resource was declared deprecated.
-->
<!--[sd]
Your suggestion looks good. -->
<t>The act of deprecation does not change any behavior of the resource. The presence of a
Deprecation header field in a response is not meant to signal a change in the meaning or
function of a resource in the context, allowing consumers to still use the resource in the
same way as they did before the resource was declared deprecated.</t>
</section>
<section anchor="iana-considerations">
<name>IANA Considerations</name>
<section anchor="the-deprecation-http-response-header-field-1">
<name>The Deprecation HTTP Response Header Field</name>
<t>The <tt>Deprecation</tt> response header field has been added to the "Hypertext Transfer
Protocol (HTTP) Field Name Registry" (<xref section="16.3.1" sectionFormat="of"
target="RFC9110" />) as follows:</t>
<dl newline="false">
<dt>Field Name:</dt>
<dd>Deprecation</dd>
<dt>Status:</dt>
<dd>permanent</dd>
<dt>Structured Type:</dt>
<dd>Item</dd>
<dt>Reference:</dt>
<dd>RFC 9745, <xref target="the-deprecation-http-response-header-field" format="default" />:
The Deprecation HTTP Header Field</dd>
</dl>
</section>
<section anchor="the-deprecation-link-relation-type-1">
<name>The Deprecation Link Relation Type</name>
<t>The <tt>deprecation</tt> link relation type has been added to the "Link Relation Types"
registry (<xref section="4.2" sectionFormat="of" target="RFC8288" />) as follows:</t>
<!-- [rfced] Please review "resource that is documentation" here. Should this
be updated to "resource documentation", "documentation", or something
else?
If any changes are made, we will ask IANA to update the "Link Relation Types"
accordingly prior to publication (link to registry:
https://www.iana.org/assignments/link-relations).
Original:
Description: Refers to a resource that is documentation (intended for human
consumption) about the deprecation of the link's context.
Perhaps:
Description: Refers to resource documentation (intended for human
consumption) about the deprecation of the link's context.
Or:
Description: Refers to documentation (intended for human
consumption) about the deprecation of the link's context.
-->
<!--[sd]
Resource's documentation and documentation about the depreaction of the link's context could be
two different things. Link may point to the deprecation policy that applies to one or more
resources. -->
<dl newline="false">
<dt>Relation Name:</dt>
<dd>deprecation</dd>
<dt>Description:</dt>
<dd>Refers to a resource that is documentation (intended for human consumption) about the
deprecation of the link's context.</dd>
<dt>Reference:</dt>
<dd>RFC 9745, <xref target="the-deprecation-link-relation-type" format="default" /></dd>
</dl>
</section>
</section>
<section anchor="security-considerations">
<name>Security Considerations</name>
<!-- [rfced] How may we update the text starting with "even though one
might..." to improve sentence clarity?
Original:
Deprecated resources function as
they would have without sending the deprecation header field, even
though one might consider non-functional details such as making them
progressively less efficient with longer response time for example.
Perhaps:
Deprecated resources function as
they would have without sending the Deprecation header field,
even though non-functional details may be affected (e.g.,
they have less efficiency and longer response times).
-->
<!--[sd]
Your suggestion looks good. -->
<!-- [rfced] What does "it" refer to in this sentence?
Original:
In cases where the Deprecation header field value is a date in the
future, it can lead to information that otherwise might not be
available.
Perhaps:
In cases where the Deprecation header field value is a date in the
future, information might become available that would not be available otherwise.
-->
<!--[sd]
"it" is the event of receiving the Depreaction header in response. How about the following?
In cases where the Deprecation header field value is a date in the
future, it informs client application developers about the effective date in future for
deprecation. Therefore, client application developers consuming the resource ...-->
<t>The Deprecation header field should be treated as a hint, meaning that the resource is
indicating (but not guaranteeing with certainty) that it will be or has been deprecated.
Deprecated resources function as they would have without sending the Deprecation header
field, even though one might consider non-functional details such as making them
progressively less efficient with longer response time, for example.</t>
<t>Resource documentation should provide additional information about the deprecation, such as
recommendations for replacement. Developers of client applications consuming the resource <bcp14>
SHOULD</bcp14> always check the referred resource documentation to verify authenticity and
accuracy. In cases where a <tt>Link</tt> header field is used to provide documentation, one
should assume (unless served over HTTPS) that the content of the <tt>Link</tt> header field
may not be secure, private, or integrity-guaranteed, so due caution should be exercised when
using it (see <xref section="5" sectionFormat="of" target="RFC8288" /> for more details). In
cases where the Deprecation header field value is in the past, the client application
developers <bcp14>MUST</bcp14> no longer assume that the behavior of the resource will
remain the same as before the deprecation date. In cases where the Deprecation header field
value is a date in the future, it can lead to information that otherwise might not be
available. Therefore, client application developers consuming the resource <bcp14>SHOULD</bcp14>,
if possible, consult the resource developer to discuss potential impact due to deprecation
and plan for possible transition to a recommended resource(s).</t>
</section>
</middle>
<back>
<displayreference target="RFC9110" to="HTTP" />
<displayreference target="RFC8288" to="LINK" />
<references anchor="sec-normative-references">
<name>Normative References</name>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9110.xml"; />
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8288.xml"; />
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9651.xml"; />
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"; />
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"; />
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8594.xml"; />
</references>
<section anchor="acknowledgments" numbered="false">
<name>Acknowledgments</name>
<t>The authors would like to thank <contact fullname="Nikhil Kolekar" />, <contact
fullname="Darrel Miller" />, <contact fullname="Mark
Nottingham" />, and <contact
fullname="Roberto Polli" /> for their contributions.</t>
<t>The authors take all responsibility for errors and omissions.</t>
</section>
</back>
<!-- [rfced] Some sentences in the document mention deprecation of the
resource while others mention deprecation of the context. Please review
and let us know if any updates are needed.
deprecation of "resource":
resource will be or has been deprecated
resource in context of the message is or will be deprecated
resource in context has been deprecated
deprecation of the resource
deprecation of that specific resource
deprecation of a resource(s)
deprecation of "context":
resource context will be deprecated
resource context has been deprecated
deprecation of the context
deprecation of the resource context
deprecation of the link's context
Please also review use of "context" and let us know if any updates are needed
for consistency and clarity.
Examples:
resource in context of the message
resource context
resource in context
resource in the context
link's context
-->
<!-- [sd]
resource in context is the right term to use where context is used except the following:
link's context
-->
<!-- [rfced] We note inconsistencies in the terms below throughout the
text. Should these be uniform? If so, please let us know which form is
preferred.
Deprecation HTTP response header field
Deprecation HTTP header field
Deprecation response header field
Deprecation header field
Sunset HTTP header field
Sunset header field
deprecation link relation
"deprecation" link relation type
relation type deprecation
deprecation link relation type
resource documentation
resource's documentation
deprecation information
deprecation-related information
-->
<!-- [sd] Yes for consistency. https://datatracker.ietf.org/doc/html/rfc9110#name-header-fields
indicates fields. HTTP response header field is the correct way.
https://datatracker.ietf.org/doc/html/rfc9110#section-6.3 indicates "header fields" (or just
"headers", colloquially). So header is also ok. I would use the same term that is used in RFCs of
other header fields.
Deprecation HTTP response header field or Deprecation HTTP response header
"deprecation" link relation type
resource's documentation
deprecation-related information
-->
<!-- [rfced] We see inconsistent use of <tt> in this document. Please review
the specific questions below. Note: In the html and pdf outputs, the text
enclosed in <tt> is output in fixed-width font; in the txt output, there
are no changes to the font.
a) For header fields, we see use of both <tt> and no <tt>. See examples
below. Which form do you prefer?
<tt>Deprecation</tt> header field
Deprecation header field
<tt>Link</tt> header field
Link header field
<tt>Sunset</tt> header field
Sunset HTTP header field
b) For the link relation type, we see use of <tt>, quotation marks, and no
<tt> or quotation marks. Which form do you prefer?
<tt>deprecation</tt> link relation type
"deprecation" link relation
deprecation link relation
-->
<!-- [sd] with <tt> -->
<!-- [rfced] Please review each artwork element in the xml file. Specifically,
should any artwork element be tagged as sourcecode or another element?
-->
<!-- [sd] Looks good -->
<!-- [rfced] Please review the "Inclusive Language" portion of the online
Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language>
and let us know if any changes are needed. Updates of this nature typically
result in more precise language, which is helpful for readers.
Note that our script did not flag any words in particular, but this should
still be reviewed as a best practice.
-->
<!-- [sd] ok -->
</rfc>--
auth48archive mailing list -- auth48archive@rfc-editor.org
To unsubscribe send an email to auth48archive-le...@rfc-editor.org
