Re: [Asap] Document Shepherd review of draft-ietf-asap-siptrunkingcapability-link-01

["Derek Engi (deengi)" <[e-mail]>]

Hi Jean and all, here are our comments to the suggested changes:

> * this document can still provide a non-normative description of capability set documents;
> * the intended status of the document can be Informative rather than Standards Track (which is still okay according to the > IANA registration policy of "Specification Required" for link relation types [1]); and
> * the BCP 14 boilerplate ("The key words "MUST", "MUST NOT", "REQUIRED"...) and its references can be removed.

We agree with these comments and will remove the BCP 14 reference and change to the Informative track.

> It would be good to use the term "capability set document" consistently. That is,
> s/ capability set / capability set document
> s/ capability document / capability set document

Noted, we will update the next draft to replace the various forms with “capability set document”.

> Abstract
> Perhaps (stating what uses the link relation type more clearly and removing some redundancy):

Agreed, we will adopt the suggested changes into the abstract.

> Section 1:
>
> Current:
>
>   RFC 8288 [RFC8288] defined a way of indicating relationships between
>   resources on the Web. This document specifies the 'sip-trunking-
>   capability' link relation type according to the rules of RFC 8288
>   [RFC8288].
>
> Perhaps (changing verb tense and reducing the number of citation tags):

Agreed, we will remove the duplicate citation tag and s/defined/defines.

> Section 3
> Perhaps (removing expansions of abbreviations, making the normative statement informative)

Agreed, the suggested changes will be adopted.

> Section 4:
> Perhaps (Clarifying where the location is provided and also rephrasing because the URI itself doesn't contain the parameters, the capability set document does, but the reader already knows that):
>
>   The URI of the capability set document is returned to the
>   network device in the "href" attribute.

Agreed, this suggestion makes the response action clear.

> Perhaps (s/ and provide / in order to provide):
>
>   The ITSP may use an authentication framework such as OAuth 2.0
>   [RFC6749] to determine the identity of the enterprise telephony
>   network in order to provide the appropriate capability set document.

We will update this section with the proposed change.

> Section 5 (updating the preposition and capitalization):
>
>   s / under the "Link Relation Types" Registry / in the "Link Relation Types" registry
>
>
> Acknowledgements (using a serial comma per the RFC Style Guide [2]):
>
>   s / Peterson and / Peterson, and
>
>
> References (making "Reference" plural):
>
>   s / 8.2. Informative Reference / 8.2. Informative References

No issues here, we will fix up each of these per your recommendations.

Thanks as always for the comments and suggestions!

--
Derek Engi
[e-mail]


From: A. Jean Mahoney <[e-mail]>
Date: Saturday, January 21, 2023 at 1:10 PM
To: [e-mail] <[e-mail]>, [e-mail] <[e-mail]>
Subject: Document Shepherd review of draft-ietf-asap-siptrunkingcapability-link-01
Hi all,

While I was performing my Doc Shepherd review of this I-D, question #11 of the Doc Shepherd review template ("What type of RFC publication is being requested...?") caused me to consider the only normative statement in the document:

   The capability set document
   SHOULD be composed of structured and machine-readable parameters that
   could be easily converted into configuration data to meet the
   communication requirements of the service provider.

It seems that the above statement would be better captured in the draft-ietf-asap-auto-peer document rather than in this document because the statement doesn't really have any bearing on the definition and registration of the link relation type.

If that's the case, then:

  * this document can still provide a non-normative description of capability set documents;
  * the intended status of the document can be Informative rather than Standards Track (which is still okay according to the IANA registration policy of "Specification Required" for link relation types [1]); and
  * the BCP 14 boilerplate ("The key words "MUST", "MUST NOT", "REQUIRED"...) and its references can be removed.


The following suggestions are for improving readability and fixing some nits:

General:

Because ITSP is expanded in the abstract, it does not have to be expanded again and can be used throughout the document in place of "Internet Telephony Service Provider", "service provider", or "SIP service provider". The same goes for SIP and "Session Initiation Protocol".

It would be good to use the term "capability set document" consistently. That is,

s/ capability set / capability set document
s/ capability document / capability set document


Abstract:

Current:

   This specification defines the 'sip-trunking-capability' link
   relation type that may be used for the retrieval of capabilities and
   configuration requirements from Internet Telephony Service Providers
   (ITSPs).  A Session Initiation Protocol (SIP) trunking capability set
   is defined to allow the transfer of technical requirements needed for
   seamless peering between SIP-based enterprise telephony networks and
   ITSPs where an exchange of parameters and configuration information
   is required.

Perhaps (stating what uses the link relation type more clearly and removing some redundancy):

   This specification defines the 'sip-trunking-capability' link
   relation type that may be used by an enterprise telephony Session
   Initiation Protocol (SIP) network to retrieve a SIP trunking
   capability set document, which contains the capabilities and
   configuration requirements of an Internet Telephony Service
   Provider (ITSP). These technical requirements allow for seamless
   peering between SIP-based enterprise telephony networks and the ITSP.


Section 1:

Current:

   RFC 8288 [RFC8288] defined a way of indicating relationships between
   resources on the Web. This document specifies the 'sip-trunking-
   capability' link relation type according to the rules of RFC 8288
   [RFC8288].

Perhaps (changing verb tense and reducing the number of citation tags):

   RFC 8288 defines a way of indicating relationships between
   resources on the Web [RFC8288]. This document specifies the 'sip-trunking-
   capability' link relation type according to the rules of RFC 8288.



Section 3:

Current:

   The document describes the configuration parameters required
   to successfully establish SIP trunking between an enterprise and
   service provider SIP telephony network.  The capability set document
   SHOULD be composed of structured and machine-readable parameters that
   could be easily converted into configuration data to meet the
   communication requirements of the service provider.  The need for an
   enterprise telephony network to obtain a capability set document from
   an Internet Telephony Service Provider (ITSP) is documented in
   Automatic Peering for SIP Trunks [I-D.ietf-asap-sip-auto-peer].

Perhaps (removing expansions of abbreviations, making the normative statement informative):

   The capability set document describes the configuration parameters required
   to successfully establish SIP trunking between an enterprise and
   an ITSP network.  The capability set document
   is composed of structured and machine-readable parameters that
   can be converted into configuration data to meet the
   communication requirements of the ITSP.  The need for an
   enterprise telephony network to obtain a capability set document from
   an ITSP is documented in
   "Automatic Peering for SIP Trunks" [I-D.ietf-asap-sip-auto-peer].



Section 4:

Current:

   The capability set location is returned to the source device
   referencing the URI that contains parameters for peering.

Perhaps (Clarifying where the location is provided and also rephrasing because the URI itself doesn't contain the parameters, the capability set document does, but the reader already knows that):

   The URI of the capability set document is returned to the
   network device in the "href" attribute.


Current:

   The ITSP may use an authentication framework such as OAuth 2.0
   [RFC6749] to determine the identity of the enterprise telephony
   network and provide the appropriate capability set document.

Perhaps (s/ and provide / in order to provide):

   The ITSP may use an authentication framework such as OAuth 2.0
   [RFC6749] to determine the identity of the enterprise telephony
   network in order to provide the appropriate capability set document.



Section 5 (updating the preposition and capitalization):

   s / under the "Link Relation Types" Registry / in the "Link Relation Types" registry


Acknowledgements (using a serial comma per the RFC Style Guide [2]):

   s / Peterson and / Peterson, and


References (making "Reference" plural):

   s / 8.2. Informative Reference / 8.2. Informative References



I'm glad to see an update of draft-ietf-asap-auto-peer, but I note that it doesn't capture the updated name of the link relation type (s / sipTrunkingCapability / sip-trunking-capability).


Thanks!
Jean

[1] https://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1
[2] https://www.rfc-editor.org/rfc/rfc7322#section-3.2