CIDM Information Management News March 2015: Standards within a Standard
Standards within a Standard
Scott Hudson, Comtech Services, Inc.
How do you solve the problem of consistency and reliability of information across 500+ member companies and over 4,300 different products? Standards, of course! The ONVIF standard was first created in 2008 by Axis Communications, Bosch Security Systems, and Sony Corporation for the video surveillance industry as a common API for IP video cameras and Video Management Systems to communicate. Initially, fewer manufacturers were involved and the specifications were just starting to develop, so it was easy to define how their products should interoperate. Once the standard started gaining widespread adoption, however, it was difficult to provide a consistent experience for installers and integration partners. The leaders in the standard started receiving complaints that it was difficult to find information on how to use the ONVIF API to communicate between the various members’ products. Some products required special configuration, but the details were buried in various web sites or technical manuals.
The ONVIF Technical Services Committee (TSC) solved that problem by coming up with a common, consistently structured document called the ONVIF Interface Guide. The purpose of the ONVIF Interface Guide is to provide the initial steps required to operate an ONVIF client or device using the ONVIF API. The intended audiences for the Interface Guides are installers, system integrators, architects and engineers, and end users. ONVIF hosts the Interface Guides provided by the members available as part of the product information on the ONVIF conformant product homepage.
To guarantee that all 500+ member companies provided a consistent experience for ONVIF product users, ONVIF required that ALL manufacturers submit this Guide along with their Declarations of Conformance to the ONVIF standard. Since each manufacturer was required to provide an ONVIF Interface Guide for each of their products, installers and integrators in the industry would have access to these documents in a consistent location and with a consistent structure so they would know exactly where to go to get exactly the information they needed, no matter what product they chose.
Enter DocBook. As a member of the OASIS DocBook Technical Committee (TC) for almost 20 years, I was quite familiar with the types of information that could be tagged and presented to readers. I am also a member of the OASIS DITA TC, but the ONVIF TSC chose not to use DITA for the specific reason that we wanted all of the information in a single document that could be strictly controlled. The ONVIF TSC did not want a multitude of topics that would have to be managed. Since ONVIF is a worldwide standard, many of the member companies have limited staff and may not have English as their primary language. We needed a standard that was well documented, widely adopted, and required little technical support.
Of the 4,300 products (IP cameras or video management systems) that were submitted for ONVIF conformance, only 22 documents required some level of XML troubleshooting support. Of those 22, at least 20 had simple XML validation errors that could have been easily resolved by referring to the DocBook spec or DocBook: The Definitive Guide by Norm Walsh. For example, many of the invalid documents used plain text within a <section>, when the text should be wrapped in a element.
By choosing DocBook and using the <article> structure, all of the key information for an ONVIF implementer could be easily created and displayed, including:
The structured markup itself was not enough to guarantee that the document structure would be adhered to and displayed consistently. For this, we added Schematron. Each section of the document requires a specific ID, and those sections have to be in a specific sequence. The Schematron rules referenced in the Interface Guide XML file enforces those rules.
The consistent markup structure and an enforced sequence of information also allows for the ONVIF Interface Guides, themselves, to be dynamically rendered in a web browser. You can view this dynamic rendering yourself by visitinghttp://www.onvif.org/FindaProduct/ProfileProducts.aspx and searching for any conformant product. If you View… Source… on any Interface Guide, you will see the actual DocBook XML.
By adopting the DocBook standard for its documentation, the ONVIF standard can now provide consistent, reliable information to its manufacturer members and installation and integration partners, and to end users!