Subject: Re: [OPSAWG] AD Review of draft-ietf-opsawg-service-model-explained

From: "Adrian Farrel" <[email-masked]>
Date: Sun, 24 Sep 2017 15:10:28 +0100

Hi Benoit,

>> In RFC 8199, we made a distinction between model and YANG modules.
>> This is why we defined the terms "Network Service YANG modules" and
>> "Network Element YANG modules" and not models.  You should follow this
>> convention. After all, from the abstract, this document focuses on YANG.
>> Ex: should "model" be replaced by "YANG module"?
>
> The definition imported from 7950 by 8199 looks like a reasonable distinction
> and we will attempt to apply it here. I hope I am not importing too much 
> thought from SMI but isn't a "model" built from one or modules? A model is
> used to "model" some larger entity or function, while a module is used to
> describe a component of an entity or a granular function.
>
> Probably just some cleanup needed through this document. I'll have a go.

Well, now I'm struggling and I wonder if you can help.

What I see from 7950 is that a "YANG module" is a compilable blob of YANG that may include other modules or specific constructs from another module. That is clear enough.

What is less clear is what a "data model" is or is not. I think that if, for example, I wanted to model a router, I would construct a data model from one or mode YANG modules that encode various aspects of the router. You could, I suppose, present that construct as a module its own right. 

And that leads me to ask you when it is appropriate to use term "data model".

8199 doesn't offer me a lot of clarity. For example, section 1 says:
      For example, a
      Layer 2 Virtual Private Network (L2VPN) YANG module might be a
      Network Service YANG Module, ready to be used as a service model
      by a network operator.

Later (in 2.1) it says that a module "describes an abstract model"
And (in 2.2) that a module "provides a coherent data model representation"

All this means (I think) that modules are documentation, but models are used.

It's all a bit esoteric for me and I can't find a way forward :-(

What I want to do is observe that:
- Modules a constructed from YANG and may include other whole YANG
   modules or specific elements from other YANG modules
- Modules describe may define pieces of modelling that are only useful
   when applied in a context. For example, a module might define a YANG
   construct for a timestamp or an interface, but those constructs would 
   only be useful when included in another module that gave context to
   the timestamp or interface.
- Modules may also describe data models for components or
   sub-components of a managed system (often by including YANG from
   other modules).
- Not all modules provide data models that are independently useful,
   but some do. And one example is that when we want to model something
   like a service, we use a service model that is presented in a single YANG
   module. Thus, it is perfectly reasonable that 7223 is called "A YANG Data
   Model for Interface Management" and 8049 is a "YANG Data Model for
   L3VPN Service Delivery".
 
So, my inclination is to include pointers to the 7950 definitions, and to carefully re-read the text in our draft, but not to make a wholesale change of terms.

Any clues?

Thanks,
Adrian

---

From: "Adrian Farrel" <[email-masked]>
Date: Wed, 27 Sep 2017 09:12:22 +0100

> For now I'll complete the AD writeup, and put it in AD watching,
> revised ID needed state. Once y'all have figured out an answer I'll
> hit the Go button.

Fair enough, Warren.

I have an update ready with changes for everyone else's comment, so we are "close".

I know that Benoit is busy fellow, but if you find yourself able to nudge him then please do.

Adrian

---

From: "Adrian Farrel" <[email-masked]>
Date: Wed, 27 Sep 2017 09:32:54 +0100

Hi Tom,
Long time!

> > What I see from 7950 is that a "YANG module" is a compilable blob of
> > YANG that may include other modules or specific constructs from another
> > module. That is clear enough.
> >
> > What is less clear is what a "data model" is or is not. I think that
> > if, for example, I wanted to model a router, I would construct a data
> > model from one or mode YANG modules that encode various aspects of the
> > router. You could, I suppose, present that construct as a module its own
> > right.
> >
> >    when applied in a context. For example, a module might define a
> >    YANG construct for a timestamp or an interface, but those constructs
> >    would only be useful when included in another module that gave
>  >   context to the timestamp or interface.
> >    but some do. And one example is that when we want to model
> >    something like a service, we use a service model that is presented
> >    in a single YANG module. Thus, it is perfectly reasonable that 7223 is
> >    called "A YANG Data Model for Interface Management" and 8049 is a
> >    "YANG Data Model for L3VPN Service Delivery".
> >
> > So, my inclination is to include pointers to the 7950 definitions, and
> > to carefully re-read the text in our draft, but not to make a wholesale
> > change of terms.
> >
> > Any clues?
> 
> Adrian,
> 
> What jumps out at me, as being an infelicitous of language,  is the
> first sentence,
> "   The IETF has produced many data modules in the YANG modeling
>    language.  "
> and that is because of 'data module'.
> 
> Modules are compilable, as you say, because they are written in a
> language, a data definition language, such as SMI, ABNF or even YANG, so
> what you have is a SMI module or a YANG module; they appear in an RFC
> and define a schema for data, arguably they are not the data itself, so
> I think that 'data
> module' is an oxymoron and that first sentence should be
> "   The IETF has produced many modules in the YANG modeling
>    language. "

That is good.
We can avoid all "data modules". Four instances.

> When RFC7950 defines data model as 'A data model describes how data is
> represented and accessed' I think that it misses the point somewhat,
> that a data model is in contrast to an information model as described in
> RFC3444. That RFC suggests  that all SMI modules are data models and so
> by implication so would all YANG modules be.
> 
> A YANG module for routing or interfaces can or will be a data
> model but will a YANG module that defines data types for routing be?
> um, unsure.
> 
> I myself would avoid all uses of 'data model'

But we have all the weight of recorded history :-)

I've also cleaned up "YANG model". That seems to be wrong: we either have "data
models" or "YANG modules".

But the big distinction still eludes me. Perhaps you are right that the way
forward is just to dodge the issue and only talk about modules.

Adrian

---

From: Benoit Claise <[email-masked]>
Date: Wed, 27 Sep 2017 11:27:31 +0200

Hi Adrian,

Some of this has been discussed on YANG doctors list some time ago. Bad 
luck, before it was archived.
Good news, I explained the conclusions on the NETMOD mailing list. See 
https://mailarchive.ietf.org/arch/search/?email_list=netmod&q=Terminology+%3D%3E+YANG+module+versus+YANG+data+model+versus+YANG+model+%3A+please+don%27t+use+%22YANG+model%22+any+longer

So in our document, we removed the term "YANG model".
Personally, I try to avoid the term "YANG data model". If it's written 
in YANG, then it's a YANG _module_.
And the term "data model" is a more generic term, regardless of the 
language (SMI, YANG, etc.)

Are we consistent across all documents? No
Should we try to be consistent? Ideally
Am I going to hold a DISCUSS on this? Absolutely not.

Bottom line, do your best. That should be an easy enough guideline, right?
So "my inclination is to include pointers to the 7950 definitions, and 
to carefully re-read the text in our draft" is about right.

Regards, Benoit

> .