W3C home > Mailing lists > Public > www-validator-cvs@w3.org > October 2006

validator/htdocs/docs api.html,NONE,1.3.2.2 users.html,1.22.2.1,1.22.2.2

From: Olivier Thereaux via cvs-syncmail <cvsmail@w3.org>
Date: Fri, 13 Oct 2006 07:16:22 +0000
To: www-validator-cvs@w3.org
Message-Id: <E1GYHHK-0004C8-LP@lionel-hutz.w3.org>

Update of /sources/public/validator/htdocs/docs
In directory hutz:/tmp/cvs-serv10602/htdocs/docs

Modified Files:
      Tag: validator-0_7-branch
	users.html 
Added Files:
      Tag: validator-0_7-branch
	api.html 
Log Message:
* moving all outputs to templates instead of inline code
* adding ucn and soap12 outputs as experimental additions
  ( will allow us to plug unicorn to main validator, and also let people 
  actually develop libraries for these outputs)
* deprecating homegrown xml format (in documentation, needs to be in the changelog and announce)

These involve some heavy porting of code from CVS HEAD to 0.7 branch, needs some testing.



--- NEW FILE: api.html ---
<!--#set var="revision" value="\$Id: api.html,v 1.3.2.2 2006/10/13 07:16:19 ot Exp $"
--><!--#set var="date" value="\$Date: 2006/10/13 07:16:19 $"
--><!--#set var="title" value="Documentation of the Programmatic Interface (API) to The W3C Markup Validation Service"
--><!--#set var="relroot" value="../"
--><!--#include virtual="../header.html" -->

<div class="doc">
<h2>Markup Validator Web Service API<br />
SOAP 1.2 validation interface documentation</h2>

<h3 id="TableOfContents">Table of Contents</h3>

    <div id="toc">
      <ul>
        <li><a href="#requestformat">Validation Request Format</a></li>
        <li><a href="#soap12format">SOAP format description</a>
         <ul>
          <li><a href="#soap12_sample">sample SOAP 1.2 validation response</a></li>
          <li><a href="#soap12response">SOAP1.2 response format reference</a></li>
          <li><a href="#soap12message">SOAP1.2 atomic message (error or warning) format reference</a></li>
         </ul>
        </li>
      </ul>
    </div>
    
    <p id="skip"></p>

<h3 id="requestformat">Validation Request Format</h3>

<p>Below is a table of the parameter you can use to send a query to the W3C Markup Validator.</p>
<p>If you want to use W3c's public validation server, use the parameters below
 in conjunction with the following base URI:<br />
<kbd>http://validator.w3.org/check</kbd> <br />
(replace with the address of your own server if you want to call a private instance of the validator.</p>

<p><strong>Note</strong>: If you wish to call the validator programmatically for a batch of documents,
please make sure that your script will <code>sleep</code> for <strong>at least 1 second</strong> 
between requests. The Markup Validation service is a free, public service for all, your respect
is appreciated. thanks.</p>

<table class="refdoc">
<tr>
<th>Parameter</th><th>Description</th><th>Default value</th>
</tr>
<tr>
  <th>uri</th>
  <td>The <acronym title="Universal Resource Locator">URL</acronym> of the document to validate</td>
  <td>None, but either this parameter, or <code>uploaded_file</code>, 
  or <code>fragment</code> must be given.</td>
</tr>
<tr>
  <th>uploaded_file</th>
  <td>The document to validate, POSTed as multipart/form-data</td>
  <td>None, but either this parameter, or <code>uri</code>,   
  or <code>fragment</code> must be given.</td>
</tr>
<tr>
  <th>fragment</th>
  <td>The source of the document to validate. Full documents only. 
  At the moment, will only work if data is sent with the UTF-8 encoding.</td>
  <td>None, but either this parameter, or <code>uri</code>,
  or <code>uploaded_file</code> must be given.</td>
</tr>
<tr>
  <th>output</th>
  <td>triggers the various outputs formats of the validator. If unset, the usual
  Web format will be sent. If set to <code>soap12</code>, the SOAP1.2 interface will 
  be triggered. See <a href="soap12format">below for the SOAP 1.2 response format description</a>.</td>
  <td>unset</td>
</tr>
<tr>
  <th>charset</th>
  <td>Character encoding override: 
  Specify the character encoding to use when parsing the document. When used with
  the auxiliary parameter <code>fbc</code> set to 1, the given encoding will only be used as 
  a fallback value, in case the charset is absent or unrecognized. Note that this parameter
  is ignored if validating a <code>fragment</code> with the direct input interface.</td>
  <td>None, by default the validator detects the charset of the document automatically.</td>
</tr>
<tr>
  <th>doctype</th>
  <td>Document Type override:
  Specify the Document Type (DOCTYPE) to use when parsing the document. When used 
  with  the auxiliary parameter <code>fbd</code> set to 1, the given document type will only be used
  as a fallback value, in case the document's DOCTYPE declaration is missing or unrecognized.</td>
  <td>None, by default the validator detects the document type of the document automatically.</td>
</tr>
<tr>
  <th>verbose</th>
  <td>In the web interface, when set to 1, will make error messages, explanations 
  and other diagnostics more verbose. In SOAP output, does not have any impact.</td>
  <td>0 (unset)</td>
</tr>
<tr>
  <th>ss</th>
  <td> as <em>show source</em>. In the web interface, triggers the display of the source
  after the validation results. In SOAP output, does not have any impact.</td>
  <td>0 (unset)</td>
</tr>
<tr>
  <th>outline</th>
  <td>In the web interface, when set to 1, triggers the display of the document outline 
  after the validation results. In SOAP output, does not have any impact.</td>  
  <td>0 (unset)</td>
</tr>
<tr>
  <th>sp</th>
  <td>In the web interface, when set to 1, triggers the display of the parsing tree
  after the validation results. When used with the auxiliary parameter <code>noatt</code>
  set to 1, the parse tree will not display attributes. In SOAP output, does not have any impact.</td>
  <td>0 (unset)</td>
</tr>
</table>
<h3 id="soap12format">SOAP format description</h3>

<p>When called with parameter <code>output=soap12</code>, the validator will switch
to its SOAP 1.2 interface (experimental for now). Below is a sample response, as well as
a description of the most important elements of the response.</p>

<h4 id="soap12_sample">sample SOAP 1.2 validation response</h4>
<p>A SOAP response for the validation of a document (invalid) will look like this:</p>
<pre style="font-size: smaller"> 
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;env:Envelope xmlns:env=&quot;http://www.w3.org/2003/05/soap-envelope&quot;&gt;
&lt;env:Body&gt;
&lt;<a href="#soap12_markupvalidationresponse">m:markupvalidationresponse</a>
env:encodingStyle=&quot;http://www.w3.org/2003/05/soap-encoding&quot; 
xmlns:m=&quot;http://www.w3.org/2005/10/markup-validator&quot;&gt;
    &lt;<a href="#soap12_uri">m:uri</a>&gt;http://qa-dev.w3.org/wmvs/HEAD/dev/tests/xhtml1-bogus-element.html&lt;/m:uri&gt;
    &lt;<a href="#soap12eckedby">m:checkedby</a>&gt;http://validator.w3.org/&lt;/m:checkedby&gt;
    &lt;<a href="#soap12_doctype">m:doctype</a>&gt;-//W3C//DTD XHTML 1.0 Transitional//EN&lt;/m:doctype&gt;
    &lt;<a href="#soap12_charset">m:charset</a>&gt;utf-8&lt;/m:charset&gt;
    &lt;<a href="#soap12_validity">m:validity</a>&gt;false&lt;/m:validity&gt;
    &lt;<a href="#soap12_errors">m:errors</a>&gt;
        &lt;<a href="#soap12_errorcount">m:errorcount</a>&gt;1&lt;/m:errorcount&gt;
        &lt;<a href="#soap12_errorlist">m:errorlist</a>&gt;
          
            &lt;<a href="#soap12_error">m:error</a>&gt;
                &lt;<a href="#soap12_line">m:line</a>&gt;13&lt;/m:line&gt;
                &lt;<a href="#soap12_col">m:col</a>&gt;6&lt;/m:col&gt;                                           
                &lt;<a href="#soap12_message">m:message</a>&gt;element &quot;foo&quot; undefined&lt;/m:message&gt;
            &lt;/m:error&gt;
           
        &lt;/m:errorlist&gt;
    &lt;/m:errors&gt;
    &lt;m:warnings&gt;
        &lt;m:warningcount&gt;0&lt;/m:warningcount&gt;
        &lt;m:warninglist&gt;
        
        
        &lt;/m:warninglist&gt;
    &lt;/m:warnings&gt;
&lt;/m:markupvalidationresponse&gt;
&lt;/env:Body&gt;
&lt;/env:Envelope&gt;
</pre>
<h4 id="soap12response">SOAP1.2 response format reference</h4>

<table class="refdoc">
<tr><th>element</th><th>description</th></tr>
<tr>
  <th id="soap12_markupvalidationresponse">markupvalidationresponse</th>
  <td>The main element of the validation response. Encloses all other information about the validation results.</td>
</tr>
<tr>
  <th id="soap12_uri">uri</th>
  <td>the address of the document validated. Will (likely?) be <kbd>upload://Form Submission</kbd>
  if an uploaded document or fragment was validated.
  In <a href="http://www.w3.org/WAI/ER/">EARL</a> terms, this is the <kbd>TestSubject</kbd>.
  </td>
</tr>
<tr>
  <th id="soap12_checkedby">checkedby</th>
  <td>Location of the service which provided the validation result. 
  In <a href="http://www.w3.org/WAI/ER/">EARL</a> terms, this is the <kbd>Assertor</kbd>.
  </td>
</tr>
<tr>
  <th id="soap12_doctype">doctype</th>
  <td>Detected (or forced) Document Type for the validated document</td>
</tr>
<tr>
  <th id="soap12_charset">charset</th>
  <td>Detected (or forced) Character Encoding for the validated document</td>
</tr>
<tr>
  <th id="soap12_validity">validity</th>
  <td>Whether or not the document validated passed or not formal validation (true|false boolean)</td>
</tr>
<tr>
  <th id="soap12_errors">errors</th>
  <td>Encapsulates all data about errors encountered through the validation process</td>
</tr>
<tr>
  <th id="soap12_errorcount">errorcount</th>
  <td>a child of <a href="#soap12_errors">errors</a>, counts the number of errors listed</td>
</tr>
<tr>
  <th id="soap12_errorlist">errorlist</th>
  <td>a child of <a href="#soap12_errors">errors</a>, contains the list of errors (surprise!)</td>
</tr>
<tr>
  <th id="soap12_error">error</th>
  <td>a child of <a href="#soap12_errorlist">errorlist</a>, contains the information on a single 
  validation error. </td>
</tr>
</table>
<p><strong>Note</strong>: <code>warnings</code>, <code>warningcount</code>, 
<code>warninglist</code> and <code>warning</code> are similar to, respectively,
<code><a href="#soap12_errors">errors</a></code>, 
<code><a href="soap12_errorcount">errorcount</a></code>, 
<code><a href="soap12_errorlist">errorlist</a></code> and 
<code><a href="soap12_error">error</a></code>.
</p>
<h4 id="soap12message">SOAP1.2 atomic message (error or warning) format reference</h4>
<p>As seen as the example above, the children of the <code><a href="soap12_error">error</a></code>
element, but also the <code>warning</code> element are <code>line</code>, <code>col</code> and
<code>message</code>, defined below:</p>
<table class="refdoc">
<tr><th>element</th><th>description</th></tr>
<tr>
  <th id="soap12_line">line</th>
  <td>Within the source code of the validated document, refers to the line where the error was detected.</td>
</tr>
<tr>
  <th id="soap12_col">col</th>
  <td>Within the source code of the validated document, refers to the line where the column was detected.</td>
</tr>
<tr>
  <th id="soap12_message">message</th>
  <td>The actual error message</td>
</tr>
<tr>
  <th id="soap12_messageid">messageid</th>
  <td>@@ not implemented yet@@ - should be the number of the error, as addressed internally by the validator</td>
</tr>
</table>

</div>
<!--#include virtual="../footer.html" -->
  </body>
</html>

Index: users.html
===================================================================
RCS file: /sources/public/validator/htdocs/docs/users.html,v
retrieving revision 1.22.2.1
retrieving revision 1.22.2.2
diff -u -d -r1.22.2.1 -r1.22.2.2
--- users.html	6 Jan 2006 06:37:34 -0000	1.22.2.1
+++ users.html	13 Oct 2006 07:16:19 -0000	1.22.2.2
@@ -230,117 +230,22 @@
         </p>
         <p class="shout" id="api-warning">
 	  <strong>These options are experimental!</strong>
-	  The API and output format is subject to change without notice and
-	  may well be removed or disabled at any time. They are provided now
-	  to garner public feedback to determine how best to support this
-	  functionality in the future. One particularly likely option being
-	  considered is removing these features altogether in favor of a
-	  full-blown SOAP interface. <em>You have been warned!</em>
+	  The API and output formats are still subject to change without notice and
+	  may well be removed or disabled at any time. <em>You have been warned!</em>
 	</p>
         <dl>
-          <dt id="output-earl">EARL/RDF (<code>earl</code>)</dt>
-          <dd>Produces output in the EARL RDF syntax.</dd>
-	  <dt id="output-n3">Notation3 (<code>n3</code>)</dt>
-	  <dd>Produces output in the Notation3 RDF syntax</dd>
+      <dt id="output-soap12">Web Service API (<em>NEW</em> in version 0.7.3)</dt>
+      <dd>Using the SOAP1.2 language over HTTP, this defines a web service with an output similar to the API for
+	  the W3C CSS validator and Feed Validator. The <a href="api">Full documentation</a> for this API is available.
+	  Can be called by using parameter <code>output=soap12</code></dd>
+      <dt id="output-earl">EARL/RDF</dt>
+      <dd>Produces output in the EARL RDF syntax.
+	  		Can be called by using parameter <code>output=earl</code>.</dd>
+	  <dt id="output-n3">Notation3 </dt>
+	  <dd>Produces output in the Notation3 RDF syntax. 
+		Can be called by using parameter <code>output=n3</code>.</dd>
 	  <dt id="output-xml">XML (<code>xml</code>)</dt>
-	  <dd>
-            <p>Produces output in a homegrown XML format (yes, we know...).</p>
-            <p>The DTD for this format is as follows:</p>
-	    <pre>
-	      <code>
-&lt;!DOCTYPE result [
-  &lt;!ELEMENT result (meta, warnings?, messages?)&gt;
-  &lt;!ATTLIST result
-    version CDATA #FIXED '0.9'
-  &gt;
-
-  &lt;!ELEMENT meta (uri, modified, server, size, encoding, doctype)&gt;
-  &lt;!ELEMENT uri      (#PCDATA)&gt;
-  &lt;!ELEMENT modified (#PCDATA)&gt;
-  &lt;!ELEMENT server   (#PCDATA)&gt;
-  &lt;!ELEMENT size     (#PCDATA)&gt;
-  &lt;!ELEMENT encoding (#PCDATA)&gt;
-  &lt;!ELEMENT doctype  (#PCDATA)&gt;
-
-  &lt;!ELEMENT warnings (warning)+&gt;
-  &lt;!ELEMENT warning  (#PCDATA)&gt;
-
-  &lt;!ELEMENT messages (msg)*&gt;
-  &lt;!ELEMENT msg      (#PCDATA)&gt;
-  &lt;!ATTLIST msg
-    line   CDATA #IMPLIED
-    col    CDATA #IMPLIED
-    offset CDATA #IMPLIED
-  &gt;
-]&gt;
-              </code>
-            </pre>
-            <p>
-	      Each element except the containers (<code>result</code>,
-              <code>meta</code>, <code>warnings</code>, <code>messages</code>)
-              and the free-form text fields (<code>warning</code>,
-              <code>msg</code>) will take a single value of a specific type.
-            </p>
-            <p>
-              The base document element is <code>result</code>. The only
-              elements allowed to be directly contained at the first level are
-              <code>meta</code>, <code>warnings</code>, and
-              <code>messages</code>. <code>warnings</code>, and
-              <code>messages</code> may be omitted if empty, and no first-level
-              elements may appear more then once.
-            </p>
-            <div id="dtd-meta">
-	      <h5>The <code>meta</code> element</h5>
-	      <p>
-                The <code>meta</code> element contains various metadata about
-	        about the Validated document. It contains further elements
-	        describing each value.
-	      </p>
-	      <dl>
-	        <dt><code>uri</code></dt>
-	        <dd>The URL of the document validated.</dd>
-	        <dt><code>modified</code></dt>
-	        <dd>The Last-Modified header field of the document as free-form text.</dd>
-	        <dt><code>server</code></dt>
-	        <dd>The Server header field of the document as free-form text.</dd>
-	        <dt><code>size</code></dt>
-	        <dd>The size in bytes of the document.</dd>
-	        <dt><code>encoding</code></dt>
-	        <dd>The Character Encoding used for Validation.</dd>
-	        <dt><code>doctype</code></dt>
-	        <dd>A text string describing the DOCTYPE used for Validation.</dd>
-	      </dl>
-	      <p>
-	        Currently, the type of these fields is free-form text, but it
-                is intended that a future revision will switch to less opaque
-                data types so these values can be reliably machine-parsed.
-              </p>
-            </div>
-	    <div id="dtd-warnings">
-	      <h5>The <code>warnings</code> element</h5>
-	      <p>
-	        The <code>warnings</code> element can contain only one sub-element;
-	        the <code>warning</code> element. Multiple <code>warning</code>
-	        elements may appear and each one contains free-form text
-                corresponding to a warning of the type found in the "Warnings"
-	        section of the HTML output (e.g. "DOCTYPE override in effect!").
-	      </p>
-	    </div>
-	    <div id="dtd-messages">
-	      <h5>The <code>messages</code> element.</h5>
-	      <p>
-	        The <code>messages</code> element can contain only one sub-element;
-	        the <code>msg</code> element. Multiple <code>msg</code> elements
-	        may appear and each contains free-form text representing one
-	        detected error. The <code>msg</code> element has three attributes;
-	        <code>line</code>, <code>col</code>, <code>offset</code>.
-	        These contain a number representing the line and column on which
-	        the error was detected, and the offset in characters from the
-	        beginning of the document (as opposed to <code>col</code> which
-	        can be said to be the offset from the beginning of the line).
-	      </p>
-	    </div>
-	  </dd>
+	  <dd>This output option has been deprecated, and will be removed from subsequent versions of the validator. </dd>
 	</dl>
       </div>
 
Received on Friday, 13 October 2006 07:16:34 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 26 April 2012 12:54:54 GMT