Subject: [Netmod-ver-dt] [meeting minutes] RE: YANG package updates

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Fri, 20 Dec 2019 10:56:14 +0000

Minutes from yesterday's short meeting (only Jason, Reshad and I) :

  *   We agreed that we preferred the packages structure below, and that this is a much better way of explaining the relationship between the instance data package files and the on the device packages.
  *   We seemed to reach agreement that the checksum/location is on the right track, but the document should clarify the SHA-256 is *only* based on the instance file contents, not what is in YANG library.  An implication of this is that if the file is not available somewhere then the device cannot provide a checksum.
  *   There wasn't much time spent discussion the version selection, but a couple of points were discussed:
     *   I don't think that we have figured out whether it is right for a schema to be limited to a single package per datastore, or whether it should be a simple union of packages (which might be better for custom schema implementations because then the device doesn't need to "create" packages to represent the union).  I think that I'm now thinking that union might be better.
     *   There was some discussion on whether the name of the schema should match the "name@version" of the packages.  I think that the leaning was towards this being a SHOULD rather than a MUST.
  *   We agreed that having some concrete examples would probably greatly help determine whether we are on the right track with the models, and will probably be very helpful in the version selection draft.

There will be no meeting for the next two weeks.  Hence the next meeting will be 9th Jan.

Thanks,
Rob

From: Netmod-ver-dt <[email-masked]> On Behalf Of Rob Wilton (rwilton)
Sent: 17 December 2019 15:44
To: [email-masked]
Subject: [Netmod-ver-dt] YANG package updates

[Mostly] based on the discussions last Thursday, I have had another ago at updating the packages.  Files pushed to github (as per attached).  Tree output at the end of this email.

1)     I've currently ditched the idea of using "<pkg-name>@<version>" as the identifier for a package and just gone back to separate name and version fields.  This makes the references slightly more verbose/ugly but has the benefit of consistency between the instance data file and the on the device data.

2)     I've renamed the file ietf-yang-package.yang to ietf-yang-package-instance.yang

3)     The structure between the YANG instance data package definition (ignoring the standard fields for all instance data documents) and the package list entry are the same, except that the package list entry also contains the location and checksum.  It doesn't make sense to put these into the instance data document because either they can't be known (checksum) or they are self-referential (location).

module: ietf-yang-package-instance
  structure package:
    +-- name                  pkg-name
    +-- version               pkg-version
     ... this is exactly the same as everything in the package list entry below ...

module: ietf-yl-packages
  augment /yanglib:yang-library:
    +--ro package* [name version]
       +--ro name                  pkg-name
       +--ro version               pkg-versionmodule: ietf-yl-packages
       |  ... matches above, plus the following two fields ...
       +--ro location*     inet:uri
       +--ro checksum?     pkg-types:sha-256-hash

4)     I've removed the "supported-optional-feature" leaf-list from the YANG-library augmentation (to /yanglib:yang-library/yanglib:schema).  I think that it is more consistent to define a separate package for this use case, which can define the features used by the package, and also allows the schema to be available off the device.

I've had another bash at the schema-version-selection YANG module:

5)     The "default-schema" is now also the schema that persistent configuration is restored from.  I.e. I'm thinking that generally the default schema is what the secondary schema are either selected subsets of or are converted into.

6)     Custom-schema are now just a named union of selectable schema.  I.e. it no longer defines a package instance to sit alongside the custom schema, clients have to manage this themselves (which seems reasonable).

7)     I've separated the naming of schema vs the naming of packages defining those schema.  If we follow this path we need to decide whether the names can contain "@" and whether they should match "<name>@<version>".

8)     Schema's now no longer explicitly identify a package to represent the pan-datastore schema.  It still logically exists, but isn't explicitly reported (which keeps the definition closely to RFC8525).

9)     Each schema defines whether it is selectable as a default schema, secondary schema, or as part of a custom schema.  The schema compatibility details are also split out depending on how it is being used.  I.e. to give implementations more control of what types of

Thoughts/comments welcome.

Tree output for the updates.

Version selection:

module: ietf-schema-selection
  +--rw schema-selection
     +--rw default-schema?     -> /schema-selection/schema/name {default-schema}?
     +--rw secondary-schema*   -> /schema-selection/schema/name {secondary-schema}?
     +--rw custom-schema* [name] {custom-schema}?
     |  +--rw name               string
     |  +--rw description?       string
     |  +--rw included-schema*   -> /schema-selection/schema/name
     +--ro schema* [name]
        +--ro name                           string
        +--ro datastores* [datastore]
        |  +--ro datastore    ds:datastore-ref
        |  +--ro package
        |     +--ro name?       -> /yanglib:yang-library/yl-pkg:package/name
        |     +--ro version?    -> /yanglib:yang-library/yl-pkg:package[yl-pkg:name = current()/../name]/version
        |     +--ro checksum?   -> /yanglib:yang-library/yl-pkg:package[yl-pkg:name = current()/../name][yl-pkg:version = current()/../version] /yl-pkg:checksum
        +--ro default-schema-selectable! {default-schema}?
        |  +--ro compatible-secondary-schema*   -> /schema-selection/schema/name
        +--ro secondary-schema-selectable! {secondary-schema}?
        |  +--ro compatible-default-schema*     -> /schema-selection/schema/name
        |  +--ro compatible-secondary-schema*   -> /schema-selection/schema/name
        +--ro custom-schema-selectable! {custom-schema}?
           +--ro combinable-schema*   -> /schema-selection/schema/name

YANG instance data definition:

module: ietf-yang-package-instance

  structure package:
    +-- name                  pkg-name
    +-- version               pkg-version
    +-- timestamp?            yang:date-and-time
    +-- organization?         string
    +-- contact?              string
    +-- description?          string
    +-- reference?            string
    +-- complete?             boolean
    +-- local?                boolean
    +-- previous-version?     pkg-version
    +-- nbc-changes?          boolean
    +-- tag*                  tags:tag
    +-- mandatory-feature*    scoped-feature
    +-- included-package* [name version]
    |  +-- name                pkg-name
    |  +-- version             pkg-version
    |  +-- replaces-version*   pkg-version
    |  +-- nbc-modified?       boolean
    |  +-- location*           inet:uri
    |  +-- checksum?           pkg-types:sha-256-hash
    +-- module* [name]
    |  +-- name                 yang:yang-identifier
    |  +-- revision?            rev:revision-date-or-label
    |  +-- replaces-revision*   rev:revision-date-or-label
    |  +-- namespace?           inet:uri
    |  +-- location*            inet:uri
    |  +-- checksum?            pkg-types:sha-256-hash
   |  +-- submodule* [name]
    |     +-- name        yang:yang-identifier
    |     +-- revision    yang:revision-identifier
    |     +-- location*   inet:uri
    |     +-- checksum?   pkg-types:sha-256-hash
    +-- import-only-module* [name revision]
       +-- name                 yang:yang-identifier
       +-- revision             rev:revision-date-or-label
       +-- replaces-revision*   rev:revision-date-or-label
       +-- namespace?           inet:uri
       +-- location*            inet:uri
       +-- checksum?            pkg-types:sha-256-hash
       +-- submodule* [name]
          +-- name        yang:yang-identifier
          +-- revision    yang:revision-identifier
          +-- location*   inet:uri
          +-- checksum?   pkg-types:sha-256-hash

YANG library augmentations:

module: ietf-yl-packages
  augment /yanglib:yang-library:
    +--ro package* [name version]
       +--ro name                  pkg-name
       +--ro version               pkg-version
       +--ro timestamp?            yang:date-and-time
       +--ro organization?         string
       +--ro contact?              string
       +--ro description?          string
       +--ro reference?            string
       +--ro complete?             boolean
       +--ro local?                boolean
       +--ro previous-version?     pkg-version
       +--ro nbc-changes?          boolean
       +--ro tag*                  tags:tag
       +--ro mandatory-feature*    scoped-feature
       +--ro included-package* [name version]
       |  +--ro name                pkg-name
       |  +--ro version             pkg-version
       |  +--ro replaces-version*   pkg-version
       |  +--ro nbc-modified?       boolean
       |  +--ro location*           inet:uri
       |  +--ro checksum?           pkg-types:sha-256-hash
       +--ro module* [name]
       |  +--ro name                 yang:yang-identifier
       |  +--ro revision?            rev:revision-date-or-label
       |  +--ro replaces-revision*   rev:revision-date-or-label
       |  +--ro namespace?           inet:uri
       |  +--ro location*            inet:uri
       |  +--ro checksum?            pkg-types:sha-256-hash
       |  +--ro submodule* [name]
       |     +--ro name        yang:yang-identifier
       |     +--ro revision    yang:revision-identifier
       |     +--ro location*   inet:uri
       |     +--ro checksum?   pkg-types:sha-256-hash
       +--ro import-only-module* [name revision]
       |  +--ro name                 yang:yang-identifier
       |  +--ro revision             rev:revision-date-or-label
       |  +--ro replaces-revision*   rev:revision-date-or-label
       |  +--ro namespace?           inet:uri
       |  +--ro location*            inet:uri
       |  +--ro checksum?            pkg-types:sha-256-hash
       |  +--ro submodule* [name]
       |     +--ro name        yang:yang-identifier
       |     +--ro revision    yang:revision-identifier
       |     +--ro location*   inet:uri
       |     +--ro checksum?   pkg-types:sha-256-hash
       +--ro location*             inet:uri
       +--ro checksum?             pkg-types:sha-256-hash
  augment /yanglib:yang-library/yanglib:schema:
    +--ro package
       +--ro name?       -> /yanglib:yang-library/package/name
       +--ro version?    -> /yanglib:yang-library/package[name = current()/../name]/version
       +--ro checksum?   -> /yanglib:yang-library/package[name = current()/../name][version = current()/../version]/checksum

Thanks,
Rob

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Fri, 20 Dec 2019 14:14:49 +0000

Hi Rob,

About this:  " An implication of this is that if the file is not available somewhere then the device cannot provide a checksum."

We're you thinking that in order for a server to populate that checksum field, it would actually go out via the URI and find a file and run a checksum over it (and then report that checksum in this tree)?

That isn't how I was thinking of this. I was thinking that a server would have a-priori knowledge of the expected checksums of any packages that it advertises.  So the availability of the file wouldn't affect whether the server can return the checksum or not.

Jason

From: Netmod-ver-dt <[email-masked]> On Behalf Of Rob Wilton (rwilton)
Sent: Friday, December 20, 2019 5:56 AM
To: [email-masked]
Subject: [Netmod-ver-dt] [meeting minutes] RE: YANG package updates

Thanks,
Rob

From: Netmod-ver-dt <[email-masked]<mailto:[email-masked]>> On Behalf Of Rob Wilton (rwilton)
Sent: 17 December 2019 15:44
To: [email-masked]<mailto:[email-masked]>
Subject: [Netmod-ver-dt] YANG package updates

module: ietf-yl-packages

Version selection:

  structure package:
    +-- name                  pkg-name
    +-- version               pkg-version

module: ietf-yl-packages

Thanks,
Rob

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Fri, 20 Dec 2019 14:47:08 +0000

On Dec 20, 2019, at 09:14, Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]<mailto:[email-masked]>> wrote:

Hi Rob,

Sorry I’ve been MIA for a while.  Other travel and projects have kept me occupied.

I review the minutes, and I agree with Jason.  I would expect the server to be pre-loaded with checksums from know, consistent files.  It would be incumbent on the clients to find the right files to match those checksums.  The clients could pull them down directly from the server or through a URI pointer.

Joe

Jason

Minutes from yesterday’s short meeting (only Jason, Reshad and I) :

  *   We agreed that we preferred the packages structure below, and that this is a much better way of explaining the relationship between the instance data package files and the on the device packages.
  *   We seemed to reach agreement that the checksum/location is on the right track, but the document should clarify the SHA-256 is *only* based on the instance file contents, not what is in YANG library.  An implication of this is that if the file is not available somewhere then the device cannot provide a checksum.
  *   There wasn’t much time spent discussion the version selection, but a couple of points were discussed:

     *   I don’t think that we have figured out whether it is right for a schema to be limited to a single package per datastore, or whether it should be a simple union of packages (which might be better for custom schema implementations because then the device doesn’t need to “create” packages to represent the union).  I think that I’m now thinking that union might be better.
     *   There was some discussion on whether the name of the schema should match the “name@version” of the packages.  I think that the leaning was towards this being a SHOULD rather than a MUST.

Thanks,
Rob

1)      I’ve currently ditched the idea of using “<pkg-name>@<version>” as the identifier for a package and just gone back to separate name and version fields.  This makes the references slightly more verbose/ugly but has the benefit of consistency between the instance data file and the on the device data.
2)      I’ve renamed the file ietf-yang-package.yang to ietf-yang-package-instance.yang
3)      The structure between the YANG instance data package definition (ignoring the standard fields for all instance data documents) and the package list entry are the same, except that the package list entry also contains the location and checksum.  It doesn’t make sense to put these into the instance data document because either they can’t be known (checksum) or they are self-referential (location).

module: ietf-yl-packages
       |  .... matches above, plus the following two fields ...

4)      I’ve removed the “supported-optional-feature” leaf-list from the YANG-library augmentation (to /yanglib:yang-library/yanglib:schema).  I think that it is more consistent to define a separate package for this use case, which can define the features used by the package, and also allows the schema to be available off the device.

I’ve had another bash at the schema-version-selection YANG module:
5)      The “default-schema” is now also the schema that persistent configuration is restored from.  I.e. I’m thinking that generally the default schema is what the secondary schema are either selected subsets of or are converted into.
6)      Custom-schema are now just a named union of selectable schema.  I.e. it no longer defines a package instance to sit alongside the custom schema, clients have to manage this themselves (which seems reasonable).
7)      I’ve separated the naming of schema vs the naming of packages defining those schema.  If we follow this path we need to decide whether the names can contain “@” and whether they should match “<name>@<version>”.
8)      Schema’s now no longer explicitly identify a package to represent the pan-datastore schema.  It still logically exists, but isn’t explicitly reported (which keeps the definition closely to RFC8525).
9)      Each schema defines whether it is selectable as a default schema, secondary schema, or as part of a custom schema.  The schema compatibility details are also split out depending on how it is being used.  I.e. to give implementations more control of what types of

Version selection:

  structure package:
    +-- name                  pkg-name
    +-- version               pkg-version

module: ietf-yl-packages

Thanks,
Rob

_______________________________________________
Netmod-ver-dt mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/netmod-ver-dt