[yang-doctors] Re: draft-ietf-opsawg-rfc5706bis-01 early Yangdoctors review

[[e-mail]]

Hi Joe/Martin, all,

A YANG-related reco in your document Joe that I think needs also more awareness is this part:

   Data Models (e.g., YANG) and other schema artifacts (JSON schema,
   YAML, CDDL, etc.) may be consumed out of the RFCs that specify them.
   As such, it is recommended that operational aspects for a data model
   (and similar artifacts) are documented as part of the model itself.
   Such considerations should not be duplicated in the narrative part of
   a specification that includes such artifacts.

A document that follows this approach is https://datatracker.ietf.org/doc/draft-ietf-ippm-ioam-integrity-yang/

Cheers,
Med

De : Joe Clarke (jclarke) <[e-mail]>
Envoyé : lundi 23 février 2026 16:39
À : Martin Björklund <[e-mail]>; [e-mail]
Cc : [e-mail]; [e-mail]
Objet : Re: [yang-doctors] draft-ietf-opsawg-rfc5706bis-01 early Yangdoctors review


Thanks for the review, Martin.

Section 5.3 was updated based on the GENART review, but I see that we need to do a bit better to tie the IM to what is discussed in Section 5.3.1.  I'll raise a GH issue for this.

One thing we wanted to call attention to is that we're recommending more documentation in the service-level YANG module itself that describes how one derives service-level status from device-level implementation.  This is mentioned in Section 5.3.2.  Are you generally okay with this?

Joe

From: Martin Björklund via Datatracker <[e-mail]<mailto:[e-mail]>>
Date: Monday, February 2, 2026 at 04:21
To: [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>
Cc: [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>, [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>
Subject: [yang-doctors] draft-ietf-opsawg-rfc5706bis-01 early Yangdoctors review
Document: draft-ietf-opsawg-rfc5706bis
Title: Guidelines for Considering Operations and Management in IETF Specifications
Reviewer: Martin Björklund
Review result: Ready with Nits

Hi,

This is my YANG doctors review of draft-ietf-opsawg-rfc5706bis-01.

This document contains general guidelines for operational
considerations in IETF documents.  From a YANG point of view, it
doesn't contain any YANG models, but provides some guidelines on when
and how to use YANG.

I have just one question and it is regarding the recommendations for
Information Models (IM).  The draft has an implicit recommendation in
section 5.3:

  Although this document recommends using English text (the official
  language for IETF specifications) to describe an Information Model,
  including a complementary YANG module helps translate abstract
  concepts into implementation-specific Data Models.

It later says in 5.3.1:

  When defining an Information Model using YANG Data Structure
  Extensions [...]

It is not clear to me what you mean here.  In section 5.3 it seems you
recommend including a Data Model YANG module (not an IM, since the IM
is in english text).  But then in 5.3.1 you mention a YANG module
for the IM as well, but there is no other discussion about using YANG
for the IM.

Also, I think it would be clearer to have an explicit recommendation
in section 5.3:

  This document recommends using English text...


/martin


_______________________________________________
yang-doctors mailing list -- [e-mail]<mailto:[e-mail]>
To unsubscribe send an email to [e-mail]<mailto:[e-mail]>
____________________________________________________________________________________________________________
Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
Thank you.