From 4e791ee754d14ccd6d73efe04c6f65b6d2f61644 Mon Sep 17 00:00:00 2001
From: Ricki Hirner <hirner@bitfire.at>
Date: Mon, 11 Nov 2024 15:33:48 +0100
Subject: [PATCH] Formally define XML elements with RELAX NG; validate XML
 samples (#52)

---
 content.mkd                                   |  51 ++------
 ...sample-propfind-multistatus-with-vapid.xml |  13 ++
 xml/sample-propfind-multistatus.xml           |  17 +++
 xml/sample-registration.xml                   |   1 -
 xml/sample-web-push-subscription.xml          |   3 +
 xml/validate-samples.rng                      |  31 +++++
 xml/validate.sh                               |   3 +-
 xml/webdav-push.rng                           | 114 ++++++++++++++++++
 xml/webdav-push.xsd                           |  46 -------
 9 files changed, 191 insertions(+), 88 deletions(-)
 create mode 100644 xml/sample-propfind-multistatus-with-vapid.xml
 create mode 100644 xml/sample-propfind-multistatus.xml
 create mode 100644 xml/sample-web-push-subscription.xml
 create mode 100644 xml/validate-samples.rng
 create mode 100644 xml/webdav-push.rng
 delete mode 100644 xml/webdav-push.xsd

diff --git a/content.mkd b/content.mkd
index 6d5f998..3aec24e 100644
--- a/content.mkd
+++ b/content.mkd
@@ -143,20 +143,7 @@ PROPFIND https://example.com/webdav/collection/
 
 HTTP/1.1 207 Multi-Status
 <?xml version="1.0" encoding="utf-8" ?>
-<multistatus xmlns="DAV:" xmlns:P="DAV:Push">
-  <response>
-    <href>/webdav/collection/</href>
-    <prop>
-      <P:transports>
-        <P:web-push />
-        <P:some-other-transport>
-          <P:some-parameter>...</P:some-parameter>
-        </P:some-other-transport>
-      </P:transports>
-      <P:topic>O7M1nQ7cKkKTKsoS_j6Z3w</P:topic>
-    </prop>
-  </response>
-</multistatus>
+{::include xml/sample-propfind-multistatus.xml}
 ~~~
 
 In this case, the requested collection supports WebDAV-Push in general (because it has a push topic). Two push transports can be used:
@@ -170,13 +157,11 @@ In this case, the requested collection supports WebDAV-Push in general (because
 Name: `transports`  
 Namespace: `DAV:Push`  
 Purpose: Indicates which push transports are supported by the server.  
-Definition: `<!ELEMENT transports (web-push | %other-transport)+`  
 Example: see below
 
 Name: `topic`  
 Namespace: `DAV:Push`  
 Purpose: Globally unique identifier for the collection.  
-Definition: `<!ELEMENT topic (#PCDATA)`  
 Description:
 
 Character sequence that identifies a WebDAV collection for push purposes (globally unique). A specific collection could be reachable at different URLs, but it can only have one push topic.
@@ -223,6 +208,7 @@ Sample request for Web Push:
 POST https://example.com/webdav/collection/
 Content-Type: application/xml; charset="utf-8"
 
+<?xml version="1.0" encoding="utf-8" ?>
 {::include xml/sample-registration.xml}
 
 HTTP/1.1 201 Created
@@ -294,18 +280,14 @@ Description:
 This element specifies details about a subscription that shall be notified when the collection is updated. Besides the optional expiration, there must be exactly one `subscription` element that
 defines the subscription details.
 
-Definition: `<!ELEMENT push-register (expires?, subscription)`  
-
 Name: `subscription`  
 Namespace: `DAV:Push`  
 Purpose: Specifies a subscription that shall be notified on updates. Contains exactly one element with details about a specific subscription type. In this document, only the `web-push-subscription` child element is defined.  
-Definition: `<!ELEMENT subscription (web-push-subscription | %other-subscription)`  
 
 Name: `expires`  
 Namespace: `DAV:Push`  
 Purpose: Specifies an expiration date of the registered subscription. Depending on the context, it's either a requested expiration date or an actual expiration date.   
 Description: Specifies an expiration date-time in the `IMF-fixdate` format {{RFC9110}}.  
-Definition: `<!ELEMENT expires (#PCDATA)`  
 Example: `<expires>Sun, 06 Nov 1994 08:49:37 GMT</expires>`
 
 
@@ -357,7 +339,6 @@ A server MAY use some logic like remembering the last successful delivery plus s
 Name: `push-message`  
 Namespace: `DAV:Push`  
 Purpose: Contains information of a push message / notification.  
-Definition: `<!ELEMENT push-message (propstat)`
 
 Example 1:
 
@@ -437,25 +418,20 @@ Element definitions:
 Name: `web-push`  
 Purpose: Specifies the Web Push transport.  
 Description: Used to specify the Web Push Transport in the context of a `<transports>` element, for instance in a list of supported transports.  
-Definition: `<!ELEMENT web-push (EMPTY)`  
 Example: `<web-push/>`
 
 Name: `web-push-subscription`  
 Purpose: Public information of a Web Push subscription that is shared with the WebDAV-Push server (Web Push application server).  
 Description: Used to specify a Web Push subscription in the context of a `<subscription>` element,
 for instance to register a subscription.  
-Definition: `<!ELEMENT web-push-subscription (push-resource)`  
 Example: see below
 
 Name: `push-resource`  
 Purpose: Identifies the endpoint where Web Push notifications are sent to. The push resource is used as the unique identifier for the subscription.  
-Definition: `<!ELEMENT push-resource (#PCDATA)`  
 Example:
 
 ~~~
-<web-push-subscription xmlns="DAV:Push">
-  <push-resource>https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV</push-resource>
-</web-push-subscription>
+{::include xml/sample-web-push-subscription.xml}
 ~~~
 
 
@@ -500,19 +476,7 @@ Example service detection of a WebDAV server that supports VAPID:
 
 ~~~
 <?xml version="1.0" encoding="utf-8" ?>
-<multistatus xmlns="DAV:" xmlns:P="DAV:Push">
-  <response>
-    <href>/webdav/collection/</href>
-    <prop>
-      <P:transports>
-        <P:web-push>
-          <server-public-key type="p256dh">BA1Hxzyi1RUM1b5wjxsn7nGxAszw2u61m164i3MrAIxHF6YK5h4SDYic-dRuU_RCPCfA5aq9ojSwk5Y2EmClBPs</server-public-key>
-        </P:web-push>
-      </P:transports>
-      <P:topic>O7M1nQ7cKkKTKsoS_j6Z3w</P:topic>
-    </prop>
-  </response>
-</multistatus>
+{::include xml/sample-propfind-multistatus-with-vapid.xml}
 ~~~
 
 If available, the client SHOULD use this key to create a restricted subscription at the push service.
@@ -538,3 +502,10 @@ Example for a subscription registration requesting message encryption:
 ~~~
 
 The server uses these data to encrypt the payload and send it to the push service. The client then decrypts the payload again.
+
+
+# XML Schema
+
+~~~
+{::include xml/webdav-push.rng}
+~~~
diff --git a/xml/sample-propfind-multistatus-with-vapid.xml b/xml/sample-propfind-multistatus-with-vapid.xml
new file mode 100644
index 0000000..7f65d00
--- /dev/null
+++ b/xml/sample-propfind-multistatus-with-vapid.xml
@@ -0,0 +1,13 @@
+<multistatus xmlns="DAV:" xmlns:P="DAV:Push">
+  <response>
+    <href>/webdav/collection/</href>
+    <prop>
+      <P:transports>
+        <P:web-push>
+          <P:server-public-key type="p256dh">BA1Hxzyi1RUM1b5wjxsn7nGxAszw2u61m164i3MrAIxHF6YK5h4SDYic-dRuU_RCPCfA5aq9ojSwk5Y2EmClBPs</P:server-public-key>
+        </P:web-push>
+      </P:transports>
+      <P:topic>O7M1nQ7cKkKTKsoS_j6Z3w</P:topic>
+    </prop>
+  </response>
+</multistatus>
diff --git a/xml/sample-propfind-multistatus.xml b/xml/sample-propfind-multistatus.xml
new file mode 100644
index 0000000..4fae513
--- /dev/null
+++ b/xml/sample-propfind-multistatus.xml
@@ -0,0 +1,17 @@
+<multistatus xmlns="DAV:" xmlns:P="DAV:Push">
+  <response>
+    <href>/webdav/collection/</href>
+    <prop>
+      <P:transports>
+        <P:web-push />
+
+        <!-- Not covered by this document:
+        <P:some-other-transport>
+          <P:some-parameter>...</P:some-parameter>
+        </P:some-other-transport>
+        -->
+      </P:transports>
+      <P:topic xmlns="DAV:Push">O7M1nQ7cKkKTKsoS_j6Z3w</P:topic>
+    </prop>
+  </response>
+</multistatus>
diff --git a/xml/sample-registration.xml b/xml/sample-registration.xml
index f63bb1d..fed9c1d 100644
--- a/xml/sample-registration.xml
+++ b/xml/sample-registration.xml
@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="utf-8" ?>
 <push-register xmlns="DAV:Push">
   <subscription>
     <web-push-subscription>
diff --git a/xml/sample-web-push-subscription.xml b/xml/sample-web-push-subscription.xml
new file mode 100644
index 0000000..4958c88
--- /dev/null
+++ b/xml/sample-web-push-subscription.xml
@@ -0,0 +1,3 @@
+<web-push-subscription xmlns="DAV:Push">
+  <push-resource>https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV</push-resource>
+</web-push-subscription>
diff --git a/xml/validate-samples.rng b/xml/validate-samples.rng
new file mode 100644
index 0000000..503e220
--- /dev/null
+++ b/xml/validate-samples.rng
@@ -0,0 +1,31 @@
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+
+  <!-- root elements of examples in document -->
+  <start>
+    <choice>
+      <ref name="multistatus"/>
+      <ref name="subscription-registration"/>
+      <ref name="push-message"/>
+      <ref name="web-push-subscription"/>
+    </choice>
+  </start>
+
+  <define name="multistatus" ns="DAV:">
+    <element name="multistatus">
+      <element name="response">
+        <element name="href">
+          <text/>
+        </element>
+        <element name="prop">
+          <zeroOrMore>
+            <ref name="prop-transports"/>
+            <ref name="prop-topic"/>
+          </zeroOrMore>
+        </element>
+      </element>
+    </element>
+  </define>
+
+  <include href="webdav-push.rng"/>
+
+</grammar>
diff --git a/xml/validate.sh b/xml/validate.sh
index 2e7a24a..6849924 100755
--- a/xml/validate.sh
+++ b/xml/validate.sh
@@ -1,2 +1,3 @@
 #!/bin/sh
-xmllint --schema webdav-push.xsd --noout *.xml
+
+xmlstarlet val -e -r validate-samples.rng *.xml
diff --git a/xml/webdav-push.rng b/xml/webdav-push.rng
new file mode 100644
index 0000000..86078ee
--- /dev/null
+++ b/xml/webdav-push.rng
@@ -0,0 +1,114 @@
+<grammar xmlns="http://relaxng.org/ns/structure/1.0" ns="DAV:Push">
+
+  <!-- New WebDAV collection properties -->
+
+  <define name="prop-transports">
+    <!-- available push transports -->
+    <element name="transports">
+      <choice>
+        <ref name="web-push-transport"/>
+        <!-- or other transport, not covered by this schema -->
+      </choice>
+    </element>
+  </define>
+
+  <define name="prop-topic">
+    <!-- push topic -->
+    <element name="topic">
+      <text/>
+    </element>
+  </define>
+
+
+  <!-- Subscription registration -->
+
+  <define name="subscription-registration">
+    <element name="push-register">
+      <!-- subscription to register -->
+      <element name="subscription">
+        <choice>
+          <ref name="web-push-subscription"/>
+          <!-- or other subscription, not covered by this schema -->
+        </choice>
+      </element>
+
+      <!-- expiration -->
+      <optional>
+        <element name="expires">
+          <text/>   <!-- date-time in IMF-fixdate format -->
+        </element>
+      </optional>
+    </element>
+  </define>
+
+
+  <!-- Push Message -->
+
+  <define name="push-message">
+    <element name="push-message">
+      <element ns="DAV:" name="propstat">       <!-- defined in WebDAV (RFC 4918) -->
+        <optional>
+          <element ns="DAV:" name="status">     <!-- defined in WebDAV (RFC 4918) -->
+            <text/>
+          </element>
+        </optional>
+
+        <element ns="DAV:" name="prop">         <!-- defined in WebDAV (RFC 4918) -->
+          <ref name="prop-topic"/>
+
+          <optional>
+            <element ns="DAV:" name="sync-token"> <!-- defined in Collection Synchronization for WebDAV (RFC 6578) -->
+              <text/>
+            </element>
+          </optional>
+        </element>
+      </element>
+    </element>
+  </define>
+
+
+  <!-- Web Push -->
+
+  <define name="web-push-transport">
+    <element name="web-push">
+      <!-- VAPID key -->
+      <optional>
+        <element name="server-public-key">
+          <attribute name="type">
+            <choice>
+              <value>p256dh</value>
+              <!-- or other type / not covered by this schema -->
+            </choice>
+          </attribute>
+          <text/>
+        </element>
+      </optional>
+    </element>
+  </define>
+
+  <define name="web-push-subscription">
+    <element name="web-push-subscription">
+      <element name="push-resource">
+        <text/>   <!-- push resource (URL) -->
+      </element>
+
+      <!-- message encryption -->
+      <optional>
+        <element name="client-public-key">
+          <attribute name="type">
+            <choice>
+              <value>p256dh</value>
+              <!-- or other type / not covered by this schema -->
+            </choice>
+          </attribute>
+          <text/>
+        </element>
+
+        <element name="auth-secret">
+          <text/>
+        </element>
+      </optional>
+    </element>
+  </define>
+
+</grammar>
diff --git a/xml/webdav-push.xsd b/xml/webdav-push.xsd
deleted file mode 100644
index 4ee8a0a..0000000
--- a/xml/webdav-push.xsd
+++ /dev/null
@@ -1,46 +0,0 @@
-<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="DAV:Push" elementFormDefault="qualified" attributeFormDefault="unqualified" xmlns:push="DAV:Push">
-
-<!-- subscription registration -->
-<element name="push-register">
-  <complexType>
-    <all>
-      <element name="subscription" maxOccurs="1">
-        <complexType>
-          <all>
-            <element name="web-push-subscription" maxOccurs="1">
-              <complexType>
-                <all>
-                  <element name="push-resource" type="anyURI" minOccurs="1"/>
-
-                  <!-- message encryption -->
-                  <element name="client-public-key" minOccurs="0" maxOccurs="1">
-                    <complexType>
-                      <simpleContent>
-                        <extension base="string">
-                          <attribute name="type" type="string" fixed="p256dh" use="required"/>
-                        </extension>
-                      </simpleContent>
-                    </complexType>
-                  </element>
-                  <element name="auth-secret" type="string" minOccurs="0" maxOccurs="1"/>
-                </all>
-              </complexType>
-            </element>
-          </all>
-        </complexType>
-      </element>
-      <element name="expires" type="string" minOccurs="0" maxOccurs="1"/>
-    </all>
-  </complexType>
-</element>
-
-<!-- push message -->
-<element name="push-message">
-  <complexType>
-    <all>
-      <element name="topic" type="string" minOccurs="1"/>
-    </all>
-  </complexType>
-</element>
-
-</schema>