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

[Martin Björklund <[e-mail]>]

"Joe Clarke (jclarke)" <[e-mail]> wrote:
> 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.

Ok.

> One thing we wanted to call attention to is that we’re recommending
> more documentation in the service-level YANG module itself that

Ok, more documentation in the *service-level* module.  Makes sense.


> 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?

But in 5.3.2 I see:

  Device Models -
  [...] Consideration should be given to how device-level models
  might fit with broader network and service Data Models.


Hmm, this seems to say more documentation in the *device-level* module.


And later:

  A common challenge in YANG Data Model development lies in defining
  the relationships between abstract service or network constructs and
  the underlying device models. Therefore, when designing YANG
  modules, it is important to go beyond simply modeling configuration
  and operational data (i.e., leaf nodes), and also consider how the
  status and relationships of abstract or distributed constructs can
  be reflected based on parameters available in the network.


Here it is not clear if the text refers to the device- or
service-level module.



/martin


> 
> Joe
> 
> From: Martin Björklund via Datatracker <[e-mail]>
> Date: Monday, February 2, 2026 at 04:21
> To: [e-mail] <[e-mail]>
> Cc: [e-mail]
> <[e-mail]>, [e-mail]
> <[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]
> To unsubscribe send an email to [e-mail]