Subject: [netmod] Best Practice for Modeling Special Values

From: JOEY BOYD <[email-masked]>
Date: Mon, 2 May 2016 20:53:11 +0000

I would like to get some guidance on best practice for modeling special values. For certain technologies, the management specification notes special integer values to represent certain conditions. 

For example, an SNR margin could be defined as an unsigned 8-bit integer where the values of 0-30 represent the margin in dB and a special value, 255, which represents the value is unavailable (a valid use case when the line is not synchronized).

In the past, we have defined MIB objects using the same type and special integer value as defined in the management specification. This means that users of the MIB need to be aware of all special values defined and how they map to what they represent. We duplicated this in our current YANG model as well.

leaf snr-margin {
  type uint8 {
    range "0..30 | 255";
  }
}

Recently, I proposed in BBF to model these special values in a more explicit manner as a union between an enumeration and an integer. Given the example above, you could have this.

leaf snr-margin {
  type union {
    type enumeration {
      enum unavailable;
    }
    type uint8 {
      range "0..30";
    }
  }
}

This allows for all special values to be mapped to explicit values instead of numeric ones. This proposal was met with some opposition on the implementation side of things as being more complex than necessary as the special integer value is sufficient and requires no extra processing to parse a union of string and integer.

I now ask this working group what are your opinions on this with respect to a best practice of modeling? Should we continue down the legacy path of modeling special integer values or would a better solution be to use a union of an enumeration and integer to define these special values more explicitly at the expense of implementation complexity?

Best regards,
Joey

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 03 May 2016 12:30:32 +0200 (CEST)

Hi,

JOEY BOYD <[email-masked]> wrote:
> I would like to get some guidance on best practice for modeling
> special values. For certain technologies, the management specification
> notes special integer values to represent certain conditions.
> 
> For example, an SNR margin could be defined as an unsigned 8-bit
> integer where the values of 0-30 represent the margin in dB and a
> special value, 255, which represents the value is unavailable (a valid
> use case when the line is not synchronized).
> 
> In the past, we have defined MIB objects using the same type and
> special integer value as defined in the management specification. This
> means that users of the MIB need to be aware of all special values
> defined and how they map to what they represent. We duplicated this in
> our current YANG model as well.
> 
> leaf snr-margin {
>   type uint8 {
>     range "0..30 | 255";
>   }
> }
> 
> Recently, I proposed in BBF to model these special values in a more
> explicit manner as a union between an enumeration and an
> integer. Given the example above, you could have this.
> 
> leaf snr-margin {
>   type union {
>     type enumeration {
>       enum unavailable;
>     }
>     type uint8 {
>       range "0..30";
>     }
>   }
> }
> 
> This allows for all special values to be mapped to explicit values
> instead of numeric ones. This proposal was met with some opposition on
> the implementation side of things as being more complex than necessary
> as the special integer value is sufficient and requires no extra
> processing to parse a union of string and integer.
> 
> I now ask this working group what are your opinions on this with
> respect to a best practice of modeling? Should we continue down the
> legacy path of modeling special integer values or would a better
> solution be to use a union of an enumeration and integer to define
> these special values more explicitly at the expense of implementation
> complexity?

In general I prefer the explicit solution.  I think it is easier for
the end user who doesn't to have remember what the special values
mean, especially if you have more than one special value:
 
   "snr-margin": 255

   "snr-margin": 254

   "snr-margin": "unavailable"

   "snr-margin": "auto"  (whatever that is)

On the implementation side, well, that's an implmenetation issue.  I
our code the difference is really marginal.  It is always tricky if
you design (standard) data models based on the implementation in one
specific toolkit.

/martin

---

From: "Guballa, Jens (Nokia - DE)" <[email-masked]>
Date: Tue, 3 May 2016 12:21:02 +0000

Hi,

> -----Original Message-----
> From: netmod [mailto:[email-masked]] On Behalf Of EXT Martin
> Bjorklund
> Sent: Dienstag, 3. Mai 2016 12:31
> To: [email-masked]
> Cc: [email-masked]
> Subject: Re: [netmod] Best Practice for Modeling Special Values
> 
> Hi,
> 
> > explicit manner as a union between an enumeration and an integer.
> > Given the example above, you could have this.
> >
> > leaf snr-margin {
> >   type union {
> >     type enumeration {
> >       enum unavailable;
> >     }
> >     type uint8 {
> >       range "0..30";
> >     }
> >   }
> > }
> >
> In general I prefer the explicit solution.  I think it is easier for the
end user
> who doesn't to have remember what the special values mean, especially if
> you have more than one special value:
> 
>    "snr-margin": 255
> 
>    "snr-margin": 254
> 
> On the implementation side, well, that's an implmenetation issue.  I our
code
> the difference is really marginal.  It is always tricky if you design
(standard)
> data models based on the implementation in one specific toolkit.

[JG] I agree. Using enumerations provides additional semantics. And if
needed you can even add the value statement to the enum.
IMO, implementation should follow the data model, not vice versa. 

Jens
> 
> 
> /martin
> 
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod