WADL, IDL, WSDL

notes from the rabbit hole of figuring out these three "languages"/"describers"/"not-specs"

WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate, however, the only bindings described in this document describe how to use WSDL in conjunction with SOAP 1.1, HTTP GET/POST, and MIME.

or

This specification defines an abstract language for describing documents and applications, and some APIs for interacting with in-memory representations of resources that use this language. The in-memory representation is known as "DOM HTML", or "the DOM" for short.

The WSDL describes services as collections of network endpoints, or ports.

A port is defined by associating a network address with a reusable binding, and a collection of ports defines a service.

Messages are abstract descriptions of the data being exchanged, and The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services.[1] WADL models the resources provided by a service and the relationships between them.[1] WADL is intended to simplify the reuse of web services that are based on the existing HTTP architecture of the Web.1 It is platform and language independent and aims to promote reuse of applications beyond the basic use in a web browser.[1]

WADL was submitted to the World Wide Web Consortium by Sun Microsystems on 31 August 2009[1], but the consortium has no current plans to standardize it[2]. WADL is the REST equivalent of SOAP's Web Services Description Language (WSDL), which can also be used to describe REST web services.[3] RESTful (representational state transfer) API (application programming interface) DLs (description languages) are formal languages designed to provide a structured description of a RESTful web API that is useful both to a human and for automated machine processing. API Description Languages are sometimes called interface description languages (IDLs). The structured description might be used to generate documentation for human programmers; such documentation may be easier to read than free-form documentation, since all documentation generated by the same tool follows the same formatting conventions. Additionally, the description language is usually precise enough to allow automated generation of various software artifacts, like libraries, to access the API from various programming languages, which takes the burden of manually creating them off the programmers.

<!-- empty attributes -->
<input name=address disabled>
<input name=address disabled="">

<!-- attributes with a value -->
<input name=address maxlength=200>
<input name=address maxlength='200'>
<input name=address maxlength="200">

HTML user agents (e.g. Web browsers) then parse this markup, turning it into a DOM (Document Object Model) tree. A DOM tree is an in-memory representation of a document.

DOM trees contain several kinds of nodes, in particular a DocumentType node, Element nodes, Text nodes, Comment nodes, and in some cases ProcessingInstruction nodes.

The markup snippet at the top of this section would be turned into the following DOM tree:

DOCTYPE: html
  html lang="en"
    head
      #text: ⏎␣␣
        title
          #text: Sample page
        #text: ⏎␣
      #text: ⏎␣
    body
      #text: ⏎␣␣
        h1
            #text: Sample page
        #text: ⏎␣␣
        //etc

VOCAB

The head element contains a title element, which itself contains a Text node with the text "Sample page". Similarly, the body element contains an h1 element, a p element, and a comment.

MISC

HTML HINT

HTMLHint is:

  1. bon
  2. a reminder of what it means to be a scripting language if pasted wholesale into devtools console
<script type="text/javascript" src="htmlhint.js"></script>

var messages = HTMLHint.verify(
    '<ul><li></ul>',
    {'tag-pair': true}
    );

/*
 *  {
 *    "type":"error",
 *    "message":"Tag must be paired, missing: [ </li>  ], start tag match failed [ <li>  ] on line 1.",
 *    "raw":"</ul>","evidence":"<ul><li></ul>",
 *    "line":1,
 *    "col":9,
 *    "rule": {
 *      "id":"tag-pair",
 *      "description":"Tag must be paired.",
 *      "link":"https://github.com/yaniswang/HTMLHint/wiki/tag-pair"
 *    }
 *  }
 */

// or

var docHTML = document.querySelectorAll('html')[0].outerHTML
var hintResults = HTMLHint.verify(docHTML);

make an htmlhintrc on htmlhint.com

{
  "tagname-lowercase": true,
    "attr-lowercase": true,
    "attr-value-double-quotes": true,
    "doctype-first": true,
    "tag-pair": true,
    "spec-char-escape": true,
    "id-unique": true,
    "src-not-empty": true,
    "title-require": true,
    "attr-value-not-empty": true,
    "tag-self-close": true,
    "doctype-html5": true,
    "csslint": {
      "display-property-grouping": true,
      "known-properties": true,
      "errors": 2
    },
    "attr-no-duplication": true,
    "attr-unsafe-chars": true,
    "href-abs-or-rel": "abs",
    "id-class-ad-disabled": true,
    "space-tab-mixed-disabled": "true",
    "inline-script-disabled": true,
    "inline-style-disabled": true,
    "style-disabled": true,
    "id-class-value": "underline",
    "jshint": {},
    "alt-require": true
}

the difference between specifying the above with --config ./.htmlhintrc:

  • with no rc file:

Scanned 236 files, found 1269 errors in 34 files (480 ms)

  • with the above rc file:

Scanned 236 files, found 11394 errors in 236 files (2342 ms)