[doc] document the binary release search output a bit

docs/api/api/binary_released.rng

@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<grammar 
+    ns="http://buildservice.org/api"
+    xmlns="http://relaxng.org/ns/structure/1.0" 
+    datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
+
+  <include href="obs.rng" />
+
+  <start>
+    <ref name="binary_released-element"/>
+  </start>
+
+  <define ns="" name="binary_released-element">
+    <element name="binary">
+      <attribute name="project">
+        <data type="string" />
+      </attribute>
+      <attribute name="repository">
+        <data type="string" />
+      </attribute>
+      <attribute name="name">
+        <data type="string" />
+      </attribute>
+      <optional>
+        <attribute name="epoch">
+          <data type="string" />
+        </attribute>
+      </optional>
+      <attribute name="version">
+        <data type="string" />
+      </attribute>
+      <attribute name="release">
+        <data type="string" />
+      </attribute>
+      <attribute name="arch">
+        <ref name="build-arch" />
+      </attribute>
+      <optional>
+        <attribute name="medium">
+          <data type="string" />
+        </attribute>
+      </optional>
+      <interleave>
+        <element name="operation">
+          <choice>
+            <value>added</value>    <!-- this is a new binary -->
+            <value>removed</value>  <!-- this binary got removed later. check obsolete time. -->
+            <value>modified</value> <!-- this binary modified a former released one, which became obsolete -->
+          </choice>
+        </element>
+        <optional>
+          <element name="publish">
+            <attribute name="package">
+              <data type="string" />
+            </attribute>
+            <attribute name="time">
+              <data type="string" />
+            </attribute>
+          </element>
+        </optional>
+        <optional>
+          <element name="build">
+            <attribute name="time">
+              <data type="string" />
+            </attribute>
+          </element>
+        </optional>
+        <optional>
+          <element name="obsolete"> <!-- this binary is not part of the repository anymore -->
+            <attribute name="time">
+              <data type="string" />
+            </attribute>
+          </element>
+        </optional>
+        <optional>
+          <element name="supportstatus">
+            <ref name="supportstatus-choices" />
+          </element>
+        </optional>
+        <optional>
+          <element name="updateinfo">
+            <attribute name="id">
+              <data type="string" />
+            </attribute>
+            <attribute name="version"> <!-- this actually the update release counter, but defined as version upstream -->
+              <data type="string" />
+            </attribute>
+          </element>
+        </optional>
+        <optional>
+          <element name="maintainer">
+            <text/> <!-- packager of the update according to the _patchinfo file -->
+          </element>
+        </optional>
+        <optional>
+          <element name="disturl">
+            <text/> <!-- the exact build location and revision -->
+          </element>
+        </optional>
+        <optional>
+          <element name="updatefor"> <!-- a product is refering to this repo as update channel -->
+            <attribute name="project">
+              <data type="string" />
+            </attribute>
+            <attribute name="product">
+              <data type="string" />
+            </attribute>
+          </element>
+        </optional>
+      </interleave>
+    </element>
+  </define>
+</grammar>

docs/api/api/binary_released.xml

@@ -0,0 +1,12 @@
+<binary project="openSUSE:13.1" repository="images" name="package" version="1.0" release="1" arch="i586" medium="DVD">
+  <operation>added</operation>
+  <publish package="pack2" time="2013-09-30 15:50:30 UTC"/>
+  <build time="2013-09-29 15:50:31 UTC"/>
+  <obsolete time="2014-08-01 07:04:34 UTC"/>
+  <supportstatus>l3</supportstatus>
+  <updateinfo id="OBS-2014-42" version="1"/>
+  <maintainer>Iggy</maintainer>
+  <disturl>obs://build.opensuse.org/My:Maintenance:2793/openSUSE_13.1_Update/904dbf574823ac4ca7501a1f4dca0e68-package.openSUSE_13.1_Update</disturl>
+  <updatefor project="openSUSE:13.1" product="openSUSE"/>
+</binary>
+

docs/api/api/channel.rng

@@ -83,13 +83,7 @@
        </optional>
        <optional>
          <attribute name="supportstatus">
-           <choice>
-             <value>l3</value>
-             <value>l2</value>
-             <value>l1</value>
-             <value>acc</value>
-             <value>unsupported</value>
-           </choice>
+           <ref name="supportstatus-choices" />
          </attribute>
        </optional>
        <empty/>

docs/api/api/obs.rng

@@ -107,6 +107,16 @@
     </choice>
   </define>
 
+  <define ns="" name="supportstatus-choices">
+    <choice>
+      <value>l3</value>
+      <value>l2</value>
+      <value>l1</value>
+      <value>acc</value>
+      <value>unsupported</value>
+    </choice>
+  </define>
+
   <define ns="" name="local-role">
     <choice>
       <value>maintainer</value>