From: K Shiva <shiva_kr@riseup.net>

This patch adds new elements <title> and <description> to the Network XML.
- The <title> attribute holds a short title defined by the user and
  cannot contain newlines.
- The <description> attribute holds any documentation that the user
  wants to store.
- Schema definitions of <title> and <description> have been moved from
  domaincommon.rng to basictypes.rng for use by network and future objects.

Signed-off-by: K Shiva Kiran <shiva_kr@riseup.net>
---
This is a v2 of:
https://listman.redhat.com/archives/libvir-list/2023-June/240473.html
diff to v1:
- Corrected commit message.
- Adds <title> and <description> XML strings to virBuffer.

 docs/formatnetwork.rst            | 11 +++++++++++
 src/conf/network_conf.c           | 18 ++++++++++++++++++
 src/conf/network_conf.h           |  2 ++
 src/conf/schemas/basictypes.rng   | 15 +++++++++++++++
 src/conf/schemas/domaincommon.rng | 15 ---------------
 src/conf/schemas/network.rng      | 10 ++++++++++
 6 files changed, 56 insertions(+), 15 deletions(-)

diff --git a/docs/formatnetwork.rst b/docs/formatnetwork.rst
index b5dc29db07..ee07f7d505 100644
--- a/docs/formatnetwork.rst
+++ b/docs/formatnetwork.rst
@@ -30,6 +30,8 @@ The first elements provide basic metadata about the virtual network.
    <network ipv6='yes' trustGuestRxFilters='no'>
      <name>default</name>
      <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
+     <title>A short description - title - of the network</title>
+     <description>Some human readable description</description>
      <metadata>
        <app1:foo xmlns:app1="http://app1.org/app1/">..</app1:foo>
        <app2:bar xmlns:app2="http://app1.org/app2/">..</app2:bar>
@@ -47,6 +49,7 @@ The first elements provide basic metadata about the virtual network.
    the virtual network. The format must be RFC 4122 compliant, eg
    ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/creating a
    new network, a random UUID is generated. :since:`Since 0.3.0`
+``metadata``
    The ``metadata`` node can be used by applications to store custom metadata in
    the form of XML nodes/trees. Applications must use custom namespaces on their
    XML nodes/trees, with only one top-level element per namespace (if the
@@ -65,6 +68,14 @@ The first elements provide basic metadata about the virtual network.
    documentation for more details. Note that an explicit setting of this
    attribute in a portgroup or the individual domain interface will override the
    setting in the network.
+``title``
+   The optional element ``title`` provides space for a short description of the
+   network. The title should not contain any newlines. :since:`Since 9.5.0` .
+``description``
+   The content of the ``description`` element provides a human readable
+   description of the network. This data is not used by libvirt in any
+   way, it can contain any information the user wants. :since:`Since 9.5.0`
+
 
 Connectivity
 ~~~~~~~~~~~~
diff --git a/src/conf/network_conf.c b/src/conf/network_conf.c
index 73788b6d87..427635250c 100644
--- a/src/conf/network_conf.c
+++ b/src/conf/network_conf.c
@@ -281,6 +281,8 @@ virNetworkDefFree(virNetworkDef *def)
     virNetDevBandwidthFree(def->bandwidth);
     virNetDevVlanClear(&def->vlan);
 
+    g_free(def->title);
+    g_free(def->description);
     xmlFreeNode(def->metadata);
 
     if (def->namespaceData && def->ns.free)
@@ -1599,6 +1601,17 @@ virNetworkDefParseXML(xmlXPathContextPtr ctxt,
         def->uuid_specified = true;
     }
 
+    /* Extract short description of network (title) */
+    def->title = virXPathString("string(./title[1])", ctxt);
+    if (def->title && strchr(def->title, '\n')) {
+        virReportError(VIR_ERR_XML_ERROR, "%s",
+                       _("Network title can't contain newlines"));
+        return NULL;
+    }
+
+    /* Extract documentation if present */
+    def->description = virXPathString("string(./description[1])", ctxt);
+
     /* check if definitions with no IPv6 gateway addresses is to
      * allow guest-to-guest communications.
      */
@@ -2311,6 +2324,11 @@ virNetworkDefFormatBuf(virBuffer *buf,
     virUUIDFormat(uuid, uuidstr);
     virBufferAsprintf(buf, "<uuid>%s</uuid>\n", uuidstr);
 
+    virBufferEscapeString(buf, "<title>%s</title>\n", def->title);
+
+    virBufferEscapeString(buf, "<description>%s</description>\n",
+                          def->description);
+
     if (virXMLFormatMetadata(buf, def->metadata) < 0)
         return -1;
 
diff --git a/src/conf/network_conf.h b/src/conf/network_conf.h
index 2b2e9d15f0..5a1bdb1284 100644
--- a/src/conf/network_conf.h
+++ b/src/conf/network_conf.h
@@ -249,6 +249,8 @@ struct _virNetworkDef {
     unsigned char uuid[VIR_UUID_BUFLEN];
     bool uuid_specified;
     char *name;
+    char *title;
+    char *description;
     int   connections; /* # of guest interfaces connected to this network */
 
     char *bridge;       /* Name of bridge device */
diff --git a/src/conf/schemas/basictypes.rng b/src/conf/schemas/basictypes.rng
index 2d6f1a2c84..26eb538077 100644
--- a/src/conf/schemas/basictypes.rng
+++ b/src/conf/schemas/basictypes.rng
@@ -610,6 +610,21 @@
     </choice>
   </define>
 
+  <!--
+    title and description element, may be placed anywhere under the root
+    -->
+  <define name="title">
+    <element name="title">
+      <ref name="objectNameWithSlash"/>
+    </element>
+  </define>
+
+  <define name="description">
+    <element name="description">
+      <text/>
+    </element>
+  </define>
+
   <define name="metadata">
     <element name="metadata">
       <zeroOrMore>
diff --git a/src/conf/schemas/domaincommon.rng b/src/conf/schemas/domaincommon.rng
index fcf9e00600..a4360a4036 100644
--- a/src/conf/schemas/domaincommon.rng
+++ b/src/conf/schemas/domaincommon.rng
@@ -8,21 +8,6 @@
   <include href="nwfilter_params.rng"/>
   <include href="privatedata.rng"/>
 
-  <!--
-    description and title element, may be placed anywhere under the root
-    -->
-  <define name="description">
-    <element name="description">
-      <text/>
-    </element>
-  </define>
-
-  <define name="title">
-    <element name="title">
-      <ref name="objectNameWithSlash"/>
-    </element>
-  </define>
-
   <define name="createMode">
     <data type="unsignedInt">
       <param name="pattern">0[0-7]{3}|[0-7]{1,3}</param>
diff --git a/src/conf/schemas/network.rng b/src/conf/schemas/network.rng
index 4317572208..cda174ab4b 100644
--- a/src/conf/schemas/network.rng
+++ b/src/conf/schemas/network.rng
@@ -37,6 +37,16 @@
           <text/>
         </element>
 
+        <!-- <title> element -->
+        <optional>
+          <ref name="title"/>
+        </optional>
+
+        <!-- <description> element -->
+        <optional>
+          <ref name="description"/>
+        </optional>
+
         <!-- <metadata> element -->
         <optional>
           <ref name="metadata"/>
-- 
2.41.0