[alto] draft-ietf-alto-oam-yang review (Part 1)

["Y. Richard Yang" <[e-mail]>]

Hi Jensen, all,

Thank you for authoring the OAM document. It clearly is a massive effort on
an important task that helps with ALTO development. In the first part of
this review, I will focus on early text and structure. I will review the
yang model details soon.

High-level structure: My understanding of the model structure is that it
consists of (Figure 2)
- a set of alto clients
- an alto server

It helps, to me, that Figure 2 gives all of the top-level structures; that
is, it lists the complete first-level structures under alto-server, instead
of using ...

In particular, the structure appears to be a bit interleaved. For example,

- It looks that the access control is somehow flattened into the top
alto-server container (Figure 2): auth-client and role
Should they belong to a sub structure that defines access control? Such a
contained structure may allow easier replacement/plug and play?

Similar to access control, sever level op also appears to be
flattened (Figure 4). For example, why is cost-type in the top level?

In general, what is the principle to define the current container
structure? It helps to clarify.

==== Some details ====
Abs/Intro: I appreciate that the document follows RFC6291 when using the
terms, Operations, Administration, Maintenance, Management, OAM, and O&M.
But these terms are defined for the context of managing a network, not a
service such as ALTO. It helps to clarify/motivate why this document can
follow RFC6291. It looks like this document uses only O&M and if so, it
helps to make clear that this is the case.

Abs: “The operator can use these data models to set up an ALTO server, ..”
=> “The operator of an ALTO server can use these data models to set up the
ALTO server, “ More generally, it helps to give an order of the workflow.
For example, the words “set up” and “create” appear to be redundant. Also,
the abstract mentions sever but the document also has client.

Intro: “This document defines a YANG data model”, but the title and abs say
models. The rest of the 1st paragraph uses one model. It helps to be
consistent in saying models or model. You may search the document and find
model vs models and be consistent (e.g., first para of 4.2). It might be
that a model consists of multiple modules.

Intro: “implementation-agnostic“. It helps to make clear the list in
Section 4.1 early.

Intro: “... the design will also be extensible for future standard
extensions.” This is a hard-to-defend statement because an extension could
be a major change. How about not making this statement?

Overall suggestion: reorganize paragraphs 2,3,4.

Sec. 3.1 “names of data nodes and other data model objects
   are often used without a prefix, as long as it is clear from the
   context in which YANG module each name is defined.  Otherwise, names
   are prefixed using the standard prefix associated with the
   corresponding YANG module”
=> // use singular
“the complete name of a data node or data model object
 includes a prefix, which indicates the YANG module in which the name is
defined.
 We omit the prefix when the YANG module is clear from the
   context;  otherwise, we include the prefix.
   The prefixes indicating the corresponding YANG modules are shown in
Table 1”

Sec. 3.2 3.3: Does Table 1 miss a few prefixes, for example, ncc?

Sec. 4.1: “Functionality/capability configuration of ALTO services.” =>
“Configuring functionality/capability of ALTO services.” to be consistent
with the other items

Sec 4.4: “Figure 1 shows a reference architecture for the ALTO server
 implementation.” => Figure 1 shows a reference architecture for an ALTO
server implementation.” ?

Sec. 5.1: Thanks for providing a reference architecture. Two quick
comments. (1) It helps to say a few words about what a client is and hence
one may get a sense of the client id it. Is it a running instance or a
template?  (2) An immediate reaction is that a “data source” can be another
alto client, for multi-domain integration.

Sec. 5.3 “The ALTO server instance contains a set of data nodes
server-level operation and management for ALTO that are shown in Figure 4.”
Fragmented sentence?

Sec. 5.3.2 shonw
Sec. 5: ird -> IRD in text because it is an acronym?