diff --git a/.github/workflows/gen_index_html.sh b/.github/workflows/gen_index_html.sh index 75e760f..59e666f 100644 --- a/.github/workflows/gen_index_html.sh +++ b/.github/workflows/gen_index_html.sh @@ -60,7 +60,7 @@ for branch in $SORTED; do echo "
html / text / xml
" >> index.html if [ $branch = "main" ]; then - echo " Diff with Datatracker " >> index.html + echo " Diff with Datatracker " >> index.html else echo " Diff with Main " >> index.html fi diff --git a/.github/workflows/pull_request_updated.yml b/.github/workflows/pull_request_updated.yml index 63ecdb8..c1dd15a 100644 --- a/.github/workflows/pull_request_updated.yml +++ b/.github/workflows/pull_request_updated.yml @@ -85,7 +85,7 @@ jobs: } - name: Test summary line for changes run: | - echo "${{env.SUMMARY_LINE}}" | grep -qF "0 flaws (~~), 3 warnings (==), 7 comments (--)" || { + echo "${{env.SUMMARY_LINE}}" | grep -qF "0 flaws (~~), 3 warnings (==), 3 comments (--)" || { echo "::error::Idnits summary line different - examine why (fix workflow if needed)" exit 1 } @@ -123,10 +123,29 @@ jobs: # fi # + ensure_checklist_complete: + name: Ensure Checklist Complete + runs-on: ubuntu-latest + #needs: add_checklist + steps: + - name: Ensure Checklist Complete + uses: peter-evans/find-comment@v4 + id: fc + with: + issue-number: ${{github.event.number}} + comment-author: 'github-actions[bot]' + body-includes: 'All of the following must be verified before merging to `main`.' + - run: | + if ${{ contains(steps.fc.outputs.comment-body, '[ ] Updated') }} ; then + echo "All checklist items must be selected." + exit 1 + fi + + update_github_pages: name: Update the GitHub Page runs-on: ubuntu-latest - needs: [xml2rfc, idnits_v2] + needs: xml2rfc permissions: pages: write id-token: write diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a113cfd..ff1e65d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,72 +17,11 @@ BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being subject to a Simplified BSD License) in Contributions. -# Production Process - -All updates to the documents in this repository are made via pull requests (PRs) -submitted via the GitHub user interface. Anyone may submit a PR. See below for -more information about how PRs are reviewed and merged/closed. - -As these documents are currently individual drafts (I-Ds), in the IETF sense, it -is not yet necessary to get consensus for changes made here. - -Ultimately, this document will be submitted to the NETMOD WG for consideration -for adoption. At that time, WG consensus will be held for all of the updates -made up to that point. - -However, until then, given the complexity of this effort, all updates (PRs) are -subject to a GitHub-enabled review process. Only the designated experts (i.e., the -`yang2-owners` team) and the PR-owner(s) participate in the review process. - -A PR will be automatically-merged as soon as all of the following are true: - - The PR is up-to-date with the current `main` branch. - - All automated GitHub Workflow Actions pass (xml2rfc, idnits, etc.). - - There are at least three "approvals". - - There are no "request changes". - - All "conversations" resolved - -Disclaimer: as no "experts" have been "designated" yet, the Editor has been -force-merging the PRs. This hasn't been an issue so far, as the changes to -date have been editorial. As soon as experts have been designated, the -ability for the Editor to force-merge will be removed. - -In order to facilitate this process, it is expected that each PR will focus -on a single item, albeit taking it to completion. That is, the PR completely -updates all three documents, as needed. For instance, in addition to the -primary update, the PR must (as needed) update ancillarly sections: - - Summary of Changes from RFC 7950 - - IANA Considerations - - Security Considerations - - Normative References - - Informative References - - Acknowledgements - - etc. - -A checklist for such things is automatically attached to PRs when they -are opened to ensure these updates occur. - -For complex issues, aspiring PR authors are encouraged to request -a "kickoff" discussion with the designated experts by creating a -"design" (a Markdown file in the `/designs` directory) and submitting -a PR to add just that file to the repository. Doing so triggers the -exact same merge-requirements listed above so, once the "design PR" -is merged, it is safe to proceed with the settled-upon approach. - -Please note that, once these documents is adopted as a NETMOD WG document, -the same PR-process discussed above will continue with one modification: -instead of PRs being automatically-merged, they will instead block on -the Editor to ensure there is WG-consensus for the change. - -Note that this is a necessary but largely perfunctorial gesture, as already -the update was approaved by the designated experts, leaving little room -for an objection to be raised. - - # Build Artifacts Each PR-update and PR-merge causes a GitHub Workflow to execute that generates and publishes build artifacts (the draft compiled in its various formats) to be published to the -[Build artifacts for YANG2](https://netmod-wg.github.io/yang2) +[Build artifacts for YANG XML](https://netmod-wg.github.io/yang-xml) page. diff --git a/Makefile b/Makefile index 75853b0..45f4ddb 100644 --- a/Makefile +++ b/Makefile @@ -48,6 +48,7 @@ $(draft)-$(next_ver).xml: $(draft).xml $(draft)-$(next_ver).txt: $(draft)-$(next_ver).xml @echo "Making $@ from $<..." $(xml2rfc) --v3 $< -o $@ --text --no-pagination + $(xml2rfc) --v3 $< -o $@.paged.txt --text $(draft)-$(next_ver).html: $(draft)-$(next_ver).xml @echo "Making $@ from $<..." diff --git a/README.md b/README.md index 9b2f010..9d6420a 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,16 @@ -# YANG 2.0 +# YANG XML -This is the repository for the document `draft-yn-netmod-yang2` -(The YANG 2.0 Data Modeling Language). +This is the repository for the document `draft-yn-netmod-yang-xml` +(XML Encoding of YANG Data). -The initial initial goal is to make RFC 7950 not be XML or NETCONF specific, -thus setting a baseline for subsequent changes. This is accomplished by: - - removing the "XML Encoding Rules" sections. - - removing the "NETCONF <l;edit-config> Operations" sections. - - removing the "NETCONF XML Encoding Rules" sections. - - removing the "Example Usage" sections. - - making remaining examples be both XML and JSON. - -XML-specific text moves to `draft-yn-netmod-yang-xml` (XML Encoding -of Data Modeled with YANG). +The document mimics RFC 7951 (JSON Encoding of YANG Data), whilst +incoporating content from RFC 7951. The XML has comments indicating +where content was sourced. ## Build Artifacts and Diffs -https://netmod-wg.github.io/yang2 +https://netmod-wg.github.io/yang-xml GitHub workflow actions are used to automatically build, test, and publish the three drafts, in the `html`, `txt`, and `xml` formats. @@ -33,7 +26,7 @@ The webpage also provide links to: All contributions are made using pull requests (PRs). -Please see the [contributing](https://github.com/netmod-wg/yang2/blob/main/CONTRIBUTING.md) page for details. +Please see the [contributing](https://github.com/netmod-wg/yang-xml/blob/main/CONTRIBUTING.md) page for details. ## Command Line Usage diff --git a/draft-yn-netmod-yang-xml.xml b/draft-yn-netmod-yang-xml.xml new file mode 100644 index 0000000..ce5c9a4 --- /dev/null +++ b/draft-yn-netmod-yang-xml.xml @@ -0,0 +1,977 @@ + + + + + + +]> + + + + + + + + + + + XML Encoding of Data Modeled with YANG + + Watsen Networks +
+ kent+ietf@watsen.net +
+ + + Operations + NETMOD Working Group + yang + xml + + This document defines encoding rules for representing YANG modeled + configuration data, state data, parameters of Remote Procedure Call (RPC) + operations or actions, and notifications defined using XML. + + + Discussion Venues + Discussion of this document takes place on the Network + Modeling Working Group mailing list, which is archived at + . + To subscribe: + This document is developed on GitHub at ). + If you wish to contribute, please consider opening a pull request (PR). + See the README file for details. + + + + +
+ This document defines encoding rules for representing YANG + modeled configuration + data, state data, parameters of Remote Procedure Call (RPC) + operations or actions, and notifications defined using + the Extensible Markup Language (XML) . +
+ +
+ + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", + and "OPTIONAL" in this document are to be interpreted as described + in BCP 14 + when, and only when, they appear in all capitals, as shown here. + The following terms are defined in : +
    +
  • action
    • +
  • anydata
    • +
  • anyxml
    • +
  • augment
    • +
  • container
    • +
  • data node
    • +
  • data tree
    • +
  • identity
    • +
  • instance identifier
    • +
  • leaf
    • +
  • leaf-list
    • +
  • list
    • +
  • module
    • +
  • RPC operation
    • +
  • submodule
    • +
+ The following terms are defined in : +
    +
  • configuration data
    • +
  • notification
    • +
  • state data
    • +
+
+ +
+ + + This document defines XML encoding for YANG data trees and their + subtrees. It is always assumed that there may be one or more top-level + elements in XML-encoded configuration data and state data. RPC operations + and notifications contain a single top-level element. + + Instances of YANG data nodes (leafs, containers, leaf-lists, lists, + anydata nodes, and anyxml nodes) are encoded as XML elements having + the name of the YANG data node. ) defines + how the name is qualified with a namespace, and the following sections + deal with the value part. The encoding rules are identical for all + types of data trees, i.e., configuration data, state data, parameters + of RPC operations, actions, and notifications. + + With the exception of "anydata" encoding (), all rules in + this document are also applicable to YANG 1.0 . + + With the exception of anyxml and schema-less anydata nodes, it is + possible to map an XML-encoded data tree to other encodings, such as + the JSON encoding as defined in , and vice + versa. However, such conversions require the YANG data model to be + available. +
+ +
+ + + An XML element name is always identical to the identifier of the + corresponding YANG data node. + + All XML elements encoding YANG data are namespace qualified. The + XML default namespace is never used in YANG encoded data. + + The namespace of an XML element is either inherited from its ancestor + or set using the "xmlns" attribute in the element. + + The "xmlns" attribute may either set the XML default namespace or + define a prefix for the namespace. Note that the same XML may be + encoded differently by different implementations. For instance, + the following two XML documents are the same. + + Document 1: +
+ + +]]> + +
+ + Document 2: +
+ + +]]> + +
+ + The "namespace" statement of a module determines the namespace + of all data node names defined in that module. If a data node is + defined in a submodule, then the namespace of the main module is used. + + A namespace MUST be set for all top-level XML elements and then + also whenever the namespaces of the data node and its parent node + are different. + + For example, consider the following YANG module: + +
+ + + +
+ + If the data model consists only of this module, then the following is + valid XML-encoded configuration data: + +
+ + + 54 + +]]> + +
+ + Note that the top-level element sets the default namespace which + "foo" leaf inherits its parent container "top". + + Now, assume that the container "top" is augmented from another + module, "example-barmod": + +
+ + + +
+ + Valid XML-encoded configuration data containing both leafs may then + look like this: +
+ + + 54 + true + +]]> + +
+ + The "bar" leaf's element sets a new default namespace + because its parent is defined in a different module. + + Explicit namespace prefixes are sometimes needed when encoding + values of the "identityref" and "instance-identifier" types. See + and + for details. + + To improve readability of XML, a client or server + that generates XML or XPath that uses prefixes SHOULD use the prefix + defined by the module as the XML namespace prefix, unless there is a + conflict. + +
+ +
+ +
+ + A leaf node is encoded as an XML element. The element's local name + is the leaf's identifier, and its namespace is the module's XML + namespace (see ). + The value of the leaf node is encoded to XML according to the + type (see for type encoding rules) and is + sent as character data in the element. + + + Example: For the leaf node definition +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +123 +]]> + +
+
+ +
+ + A container node is encoded as an XML element. The element's local name is + the container's identifier, and its namespace is the module's XML namespace + (see ). + The container's child nodes are encoded as subelements to the container + element. If the container defines RPC or action input or output parameters, + these subelements are encoded in the same order as they are defined within the + "container" statement. Otherwise, the subelements are encoded in any + order. + Any whitespace between the subelements to the container is insignificant, + i.e., an implementation MAY insert whitespace characters between + subelements. + If a non-presence container does not have any child nodes, the container + may or may not be present in the XML encoding. + + + Example: For the container definition +
+ + + +
+ the following is valid XML-encoded instance data: +
+ + + 123 + +]]> + +
+
+ +
+ + A leaf-list node is encoded as a series of XML elements. Each element's + local name is the leaf-list's identifier, and its namespace is the module's + XML namespace (see ). There is no XML element + surrounding the leaf-list as a whole. + The value of each leaf-list entry is encoded to XML according to the type + and is sent as character data in the element (see for + type encoding rules). + The XML elements representing leaf-list entries MUST appear in the order + specified by the user if the leaf-list is "ordered-by user"; otherwise, the + order is implementation dependent. The XML elements representing leaf-list + entries MAY be interleaved with elements for siblings of the leaf-list, unless + the leaf-list defines RPC or action input or output parameters. + + + Example: For the leaf-list definition +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +123 +0 +]]> + +
+
+ +
+ + A list is encoded as a series of XML elements, one for each entry in the + list. Each element's local name is the list's identifier, and its namespace is + the module's XML namespace (see ). There is no XML + element surrounding the list as a whole. + The list's key nodes are encoded as subelements to the list's identifier + element, in the same order as they are defined within the "key" statement. + The rest of the list's child nodes are encoded as subelements to the list + element, after the keys. If the list defines RPC or action input or output + parameters, the subelements are encoded in the same order as they are defined + within the "list" statement. Otherwise, the subelements are encoded in any + order. + Any whitespace between the subelements to the list entry is insignificant, + i.e., an implementation MAY insert whitespace characters between + subelements. + The XML elements representing list entries MUST appear in the order + specified by the user if the list is "ordered-by user"; otherwise, the order + is implementation dependent. The XML elements representing list entries MAY be + interleaved with elements for siblings of the list, unless the list defines + RPC or action input or output parameters. + + + Example: For the list definition +
+ + + +
+ the following is a valid XML-encoded instance: +
+ + + 123 + zig + + + 456 + zag + +]]> + +
+
+ +
+ + An anydata node is encoded as an XML element. The element's local name is + the anydata's identifier, and its namespace is the module's XML namespace (see + ). The value of the anydata node is a set of nodes, + which are encoded as XML subelements to the anydata element. + + + The anydata data node serves as a container for an arbitrary set of + nodes that otherwise appear as normal YANG-modeled data. A data + model for anydata content may or may not be known at runtime. In the + latter case, converting XML-encoded instances to other encodings, such + as JSON may be impossible. + + + Note that any XML prefixes used in the encoding are local to each + instance encoding. This means that the same XML may be encoded differently + by different implementations. + + + Example: For the anydata definition +
+ + + +
+ the following is a valid XML-encoded instance: +
+ + + + 2014-07-29T13:43:01Z + + fault + + Ethernet0 + + major + + + +]]> + +
+
+ +
+ + + + + An anyxml node is encoded the same as an anydata node. Please see + for how the anydata node is encoded. + +
+ +
+ + Apart from instances of YANG data nodes, XML elements MAY contain + XML attributes for special purposes, such as encoding metadata + . The exact syntax and semantics of such + members are outside the scope of this document. +
+ +
+ +
+ + The type of the XML value in an instance of the leaf or leaf-list + data node depends on the type of that data node, as specified in the + following subsections. + + All of the examples in this section use a YANG "leaf-list" solely + as means to illustrate multiple variations of the type. + +
+ + + All numeric types (int8, int16, int32, uint8, uint16, uint32, + int64, uint64, and decimal64) are represented as a text value + conforming the to lexical representation for the type described + in and + . + + + Example: For the "int16" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +4711 +-123 +0xf00f +-0xf +052 +-052 +]]> + +
+
+ +
+ + + A "string" value is represented as character data conforming + the to lexical representation for the type described in + . + + Example: For the "string" type +
+ + + +
+ + the following is a valid XML-encoded instance: +
+ +This string is all on one line. +This string is: + - on more than one line. + - contains tab characters. + +]]> + +
+ +
+ +
+ + + A "boolean" value is represented as the corresponding + literal name "true" or "false". + + + Example: For the "boolean" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +true +false +]]> + +
+
+ +
+ + An "enumeration" value is represented as character data conforming + the to lexical representation for the type described in + . + Example: For the "enumeration" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +one +two +three +]]> + +
+
+ +
+ + A "bits" value is represented as character data conforming + the to lexical representation for the type described in + . + + Example: For the "bits" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +zero +zero one +zero one two +]]> + +
+
+ +
+ + A "binary" value is represented as character data conforming + the to lexical representation for the type described in + . + Example: For the "binary" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +SGVsbG8gQm9iCg== +SGVsbG8gQWxpY2UK +]]> + +
+
+ +
+ + A "leafref" value is represented as character data conforming + the to lexical representation for the type described in + . + Example: For the "leafref" type +
+ + + +
+ the following is valid XML-encoded instance data: +
+ +up + +eth0 +eth1 +eth2 + +red +green +blue +]]> + +
+
+ +
+ + A "identityref" value is represented as character data containing the + namespace qualified name of the referenced identity. As defined in + , namespaces are either explicitly qualified + using a prefix, or implicitly qualified using the default namespace + for the XML element that containing the identityref value. + + + Example: For the "identityref" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +ec:blowfish +x:blowfish +emc:aes +aes +]]> + +
+ In the above example: +
    +
  • The first element uses the prefix from the imported module, + per best practice.
    • +
  • The second element uses a local prefix, as is allowed.
    • +
  • The third element uses the prefix from the local module, + per best practice but, as before, a local prefix is allowed.
    • +
  • The fourth element uses the default namespace, assuming + it is "urn:example:my-crypto".
    • +
+ +
+ +
+ An "empty" value is represented as an empty XML element. + Example: For the "empty" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ + +]]> + +
+
+ +
+ A "union" value is represented as character data conforming + the to lexical representation for the type described in + . + Example: For the "union" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +16 +32 +64 +unbounded +]]> + +
+
+ +
+ + A "instance-identifier" value is represented as character data. + All node names in an instance-identifier value MUST be qualified with + explicit namespace prefixes, and these prefixes MUST be declared + in the XML namespace scope in the instance-identifier's XML + element. + Any prefixes used in the encoding are local to each instance encoding. + This means that the same instance-identifier may be encoded + differently by different implementations. + + + Example: For the "instance-identifier" type +
+ + + +
+ the following is a valid XML-encoded instance: +
+ +/ex:system/ex:services/ex:ssh +/ex:system/ex:services/ex:ssh/ex:port +/ex:system/ex:user[ex:name='fred'] +/ex:system/ex:user[ex:name='fred']/ex:type +/ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] +/ex:system/ex:service[ex:name='foo'][ex:enabled=''] +/ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] +/ex:stats/ex:port[3] +]]> + +
+
+ +
+ +
+
+ +
+
+ + + + + + + + + + + Extensible Markup Language (XML) 1.0 (Fifth Edition) + + + + + + + + + + + Namespaces in XML 1.0 (Third Edition) + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Substantial amounts of text in this document was copied from + and . The authors wish to thank Martin Björklund and + Ladislav Lhotka for authoring RFC 7950 and RFC 7951, respectively. +
+ +