On Fri, Oct 3, 2025 at 7:40 AM Camilo Cardona <[email protected]> wrote:
> Hello all, > > With everybody’s permission, I’ll kidnap this message to refer to this > draft we published a couple of weeks ago: > > https://datatracker.ietf.org/doc/draft-cardona-claise-onion-yang-coverage/ > > We created a prototype of a tool to measure how much coverage of the yang > modules were covered by examples. However, to work on this, we needed to > actually extract them correctly from the document and validate them. In > the draft we propose something for that. > > This is relevant to questions 1 and 3. The normative part of the examples > is something that Med has been explaining to me recently. It makes sense, > but it should be clearly explained for anybody creating documents with > models. > > IMO it is quite useful to have instance examples in the document along with the YANG module(s). Some details are still unclear. Instance validation can be complex. A validation context is required, since not every example attempts to demonstrate the same thing. Protocol examples are common. e.g. a RESTCONF GET request is followed by a JSON snippet that represents a possible reply from the server. Validation test automation may not be possible without structured context metadata, unless only validations for top-level GET responses are in scope. The WG decided (in RFC 8407) that only normative YANG modules can use CODE BEGINS. That does not mean a new tag cannot be created; it just means that this one is not suitable for examples. Thanks, > Camilo Cardona > Andy > On 29 Sep 2025, at 20:00, Mahesh Jethanandani <[email protected]> > wrote: > > [Changing the subject line as the discussion is tangential to the work at > hand] > > Hi Andy/Tom, > > Here is how I am trying to rationalize this: > > > - Should (complete, and not code snippets) example modules (or > instance data examples) be validated? Per rfc8407bis, Section 3.2.1, it is > pretty clear that they should be validated. > - Are those examples normative? The answer is no, and that is why the > examples should exist in the non-normative section of the draft. > - Separate from that, the question is how the examples can be > validated? The tools can validate them only if they are standalone files. > To create those standalone files, they have to be extracted from the draft. > Would you agree that how we extract them is less important than being able > to do so? > > > We can discuss whether we need a different tag to extract (complete) > examples, but given the current toolset, I do not believe we have a > conflict in how the examples are extracted and named. > > Cheers. > > On Sep 24, 2025, at 9:36 AM, Andy Bierman <[email protected]> wrote: > > On Wed, Sep 24, 2025 at 4:26 AM tom petch <[email protected]> wrote: > >> From: Mahesh Jethanandani <[email protected]> >> Sent: 23 September 2025 21:47 >> >> Hi Tom, >> >> My take is that code markers only say where the code begins and where it >> ends. It does not distinguish between it being YANG, MIB, an example or >> any other piece of code. The code markers can specify which file the said >> code should extract into. We do not need separate code markers for >> different pieces of code. >> >> <tp> >> >> Colour me confused. If we do not need separate code markers for >> different 'types' of code (which I agree with), then that tells me that the >> CODE START and CODE END should not appear in this I-D but should be >> replaced by CODE BEGINS and CODE ENDS. >> >> > > Correct. > > https://www.ietf.org/archive/id/draft-ietf-netmod-rfc8407bis-28.html#name-code-components > > Note that the MUST NOT rule in 3.2.1 is not being followed, and example > modules are commonly > documented as code components. > > There was discussion about EXAMPLE BEGINS/ENDS, but a new macro like that > was not added. > There was discussion about the importance of IETF Trust IPR issues > associated with code components. > That is why the guidelines draft distinguishes between normative and > non-normative YANG modules. > > Since examples are quite common in all I-Ds, this seems like an important > precedent being set here. > As a consumer of RFCs, I do not really want dozens of extracted files for > ad-hoc example snippets. > These snippets are not code components, and it would be better to handle > example validation another way. > > > > Mahesh Jethanandani > [email protected] > > > > > > > _______________________________________________ > netmod mailing list -- [email protected] > To unsubscribe send an email to [email protected] > > >
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
