[Peerpress-xml] XML schemas.

[Joakim Ziegler]

I've started outlining XML schemas for Peer Press. So far, I've written up
the spec for the master site list, which will reside on peerpress.org and
list all member sites, and the per-site siteinfo file, which is what the
master site list will point to. Still pending is the per-site story list, and
the format for individual stories. There's also the matter of taxonomy, I'll
write a mail about that right after this. In the meantime, please take a look
at this, and offer your comments.

-----

Peer Press XML Schema Drafts.

This outlines the different XML datatypes used in Peer Press 0.1. There are
several different document types that are necessary for Peer Press operation,
including the master site list, the site information file, the site item list,
and the individual item.



The Master Site List.

This is the list that can be fetched from peerpress.org and mirrors, which
lists the necessary info about all Peer Press member sites. It's intended to
contain enough information to identify, point to, and describe sites.

sitelist - the entire list
  site - a single site. Has an id attribute which gives the site a unique
         identifier 
    name - freeform name of the site
    description - one paragraph description of the site
    taxonomy - the site's taxonomy set goes under here
    languages - the languages the site publishes in
    licensetypes - the licensing categories this site publishes in
    frontpageuri - the frontpage for this site
    techcontact - a mail address for technical inquiries to this site
    editorialcontact - a mail address for editorial inquiries to this site
    licensingcontact - a mail address for licensing inquiries to this site
    mirrors - a list of known mirrors for this site
      mirror - a single mirror for this site. Has a "country" attribute which
               is the iso 3361 two-letter country code for this country
        baseuri - uri for the site's service list on this mirror
        techcontact - a mail address for technical inquiries about this mirror


Example sitelist:

<sitelist>


  <site id="kuro5hin.org" system="scoop" version="pp0.1">
    <name>Kuro5hin</name>

    <description>
      Dedicated to technology and culture from the trenches, Kuro5hin's news
      items are submitted and chosen by the community.
    </description>

    <taxonomy>
      Some taxonomy scheme here.
    </taxonomy>

    <languages>
    EN_us
    </languages>

    <licensetypes>pp-exclusive, fee-based</licensetypes>

    <frontpageuri>http://www.kuro5hin.org/</frontpageuri>

    <techcontact>tech at kuro5hin.org</frontpageuri>
    <editorialcontact>rusty at kuro5hin.org</frontpageuri>
    <licensingcontact>licensing at kuro5hin.org</licensingcontact>
    
    <mirrors>

    <mirror country="us">
      <baseuri>http://www.kuro5hin.org/peerpress/services.xml</baseuri>
      <techcontact>tech at kuro5hin.org/</techcontact>
    </mirror>

    <mirror country="us">
      <baseuri>http://www.advogato.org/peerpress/mirrors/kuro5hin.org/services.xml</baseuri>
      <techcontact>mirrors at advogato.org/</techcontact>
    </mirror>

    <mirror country="no">
      <baseuri>http://www.peerpress.org/mirrors/kuro5hin.org/services.xml</baseuri>
      <techcontact>mirrors at peerpress.org/</techcontact>
    </mirror>

    </mirrors>    

  </site>


  <site id="advogato.org" system="virgule" version="pp0.1">
    <name>Advogato</name>

    <description>
      The free software developer's advocate. Advogato is a discussion forum
      and advocacy resource for free software developers. Features high-level
      development and free software philosophical discussions, a trust metric
      and certification system, and hosted diaries.
    </description>

    <taxonomy>
      Some taxonomy scheme here.
    </taxonomy>

    <languages>
    EN_us
    </languages>

    <licensetypes>pp-exclusive</licensetypes>

    <frontpageuri>http://www.advogato.org/</frontpageuri>

    <techcontact>tech at advogato.org</frontpageuri>
    <editorialcontact>raph.advogato.org</frontpageuri>
    <licensingcontact>licensing at advogato.org</licensingcontact>
    
    <mirrors>

    <mirror country="us">
      <baseuri>http://www.advogato.org/peerpress/services.xml</baseuri>
      <techcontact>tech at advogato.org/</techcontact>
    </mirror>

    <mirror country="us">
      <baseuri>http://www.kuro5hin.org/peerpress/mirrors/advogato.org/services.xml</baseuri>
      <techcontact>mirrors at kuro5hin.org/</techcontact>
    </mirror>

    <mirror country="no">
      <baseuri>http://www.peerpress.org/mirrors/advogato.org/services.xml</baseuri>
      <techcontact>mirrors at peerpress.org/</techcontact>
    </mirror>

    </mirrors>    

  </site>


</sitelist>



The Site Information File

This is the information each site publishes, which contains all the site
information found in the master site list, plus URLs for all services on that
site. This site info file is what the baseuri in the master site list points
to, and the master site list is expected to update itself by fetching
information from each baseuri at regular intervals. The use of a list of
services makes it easy to organize the directory structure and scripts on a
given site in the way that's most convenient and in line with the scripting
language and/or site engine used.

siteinfo - the entire file
  name - freeform name of the site
  description - one paragraph description of the site
  taxonomy - the site's taxonomy set goes under here
  languages - the languages the site publishes in
  licensetypes - the licensing categories this site publishes in
  frontpageuri - the frontpage for this site
  techcontact - a mail address for technical inquiries to this site
  editorialcontact - a mail address for editorial inquiries to this site
  licensingcontact - a mail address for licensing inquiries to this site
  techcontact - email address for technical inquiries about this site
  mirrors - a list of known mirrors for this site
    mirror - a single mirror for this site. Has a "country" attribute which
             is the iso 3361 two-letter country code for this country
      baseuri - uri for the site's service list on this mirror
      techcontact - a mail address for technical inquiries about this mirror
  services - a list of pp services provided by this site
    service - a single service. Has the attribute id to give the service a unique
              identifier string.
      baseuri - the base uri to get this service. If this uses HTTP GET key/value
                pairs, it should only actually contain the ones that are
                unchanged for all uses of the service. A client should use the
                concept of a known service identifier to deduce what variables to
                append to the uri, they are not enumerated in the XML file
                itself.


Example Site Information File:


<siteinfo id="kuro5hin.org" system="scoop" version="pp0.1">

    <name>Kuro5hin</name>

    <description>
      Dedicated to technology and culture from the trenches, Kuro5hin's news
      items are submitted and chosen by the community.
    </description>

    <taxonomy>
      Some taxonomy scheme here.
    </taxonomy>

    <languages>
    EN_us
    </languages>

    <licensetypes>pp-exclusive, fee-based</licensetypes>

    <frontpageuri>http://www.kuro5hin.org/</frontpageuri>

    <techcontact>tech at kuro5hin.org</frontpageuri>
    <editorialcontact>rusty at kuro5hin.org</frontpageuri>
    <licensingcontact>licensing at kuro5hin.org</licensingcontact>
    
    <mirrors>

      <mirror country="us">
        <baseuri>http://www.kuro5hin.org/peerpress/services.xml</baseuri>
        <techcontact>tech at kuro5hin.org/</techcontact>
      </mirror>

      <mirror country="us">
        <baseuri>http://www.advogato.org/peerpress/mirrors/kuro5hin.org/services.xml</baseuri>
        <techcontact>mirrors at advogato.org/</techcontact>
      </mirror>

      <mirror country="no">
        <baseuri>http://www.peerpress.org/mirrors/kuro5hin.org/services.xml</baseuri>
        <techcontact>mirrors at peerpress.org/</techcontact>
      </mirror>

    </mirrors>


    <services>

      <service id="list_items">
        <baseuri>http://www.peerpress.org/services/listitems.php</baseuri> 
      </service>

      <service id="search_item_archive">
        <baseuri>http://www.peerpress.org/services/searcharchive.php</baseuri>
        <techcontact>foobar at kuro5hin.org</techcontact>
      </service>

    </services>

</siteinfo>


-----

-- 
Joakim Ziegler - Helix Code web monkey - joakim at helixcode.com - Radagast at IRC
      FIX sysop - free software coder - FIDEL & Conglomerate developer
            http://www.avmaria.com/ - http://www.helixcode.com/