Interface Guide creation
Getting started with Interface Guides
This page is intended to capture any questions regarding the creation and/or submission of the required ONVIF Interface Guide (IG).
The ONVIF Interface Guide must accompany any Declaration of Conformance submission to the ONVIF office as part of the ONVIF Conformance Process. The purpose of the ONVIF Interface Guide is to provide installers, system integrators, architects and engineers, as well as end users with the initial steps required to operate an ONVIF client or device using the ONVIF API.
Please see the ONVIF Interface Guide Specification here https://www.onvif.org/profiles/conformance/interface-guide/ for details.
To aid ONVIF members in the successful creation and validation of IGs TSC provides:
- the afore mentioned ONVIF Interface Guide Specification
- an updated xml-template file with the correct structure: can be downloaded from Member Portal/Test Tool Download under “Device Test Tool” (login required)
- the schematron file used in the member portal for validation of uploaded IGs: can be downloaded from Member Portal/Test Tool Download under “Device Test Tool” (login required)
If the IG is not correct according to ONVIF Interface Guide Specification, the member portal will reject the submission and display an error message pointing you to the relevant section in the ONVIF Interface Guide Specification.
It is highly recommended to use the latest available Interface Guide template file when creating IGs.
Frequently asked questions
Q1: How can I validate my XML document (verify that my document was created properly)?
A1: Use an XML editor that supports RelaxNG and Schematron, such as oXygenXML (http://oxygenxml.com) or use a validation tool like Probatron4J.
Here are some brief instructions for validating the XML file using Probatron4J and the schematron file.
- Install Java on your desktop system (https://java.com/en/download/) and add the path to the system environment variables.
- Download Probatron4J https://code.google.com/archive/p/probatron4j/.
- Copy the attached schematron file (check_onvif_interface_guide_vx_x_x.sch) to the same dir as Probatron4J.
- Open a terminal or command prompt and navigate to the above directory and run the below command (be sure to change <IG-to-be-verified.xml> to the IG file to be verified
- Command is java -jar probatron.jar <IG-to-be-verified.xlm> check_onvif_interface_guide_vx_x_x.sch. Example: C:\> java -jar probatron.jar interfaceGuideTemplate.xml check_onvif_interface_guide_v1_1_1.sch
Q2: What is DocBook and what kinds of information can I include in the document?
A2: DocBook is an open XML documentation standard from OASIS. The best resource to help with DocBook questions is http://docbook.org or https://tdg.docbook.org/tdg/5.0/docbook.html
Q3: Why aren’t my images showing up?
A3: You need to log into the Member Portal:
- Clicking “Interface Guide Images” will take you to the a page where there are two tabs, one for ONVIF images (handled by ONVIF) and the other one (your company name) is for uploading own graphical assets.
- Clicking on the tab with your company name will give you the option to upload your images and you will see the “File path” to be used in your interface guide for images to be show correctly.
Q4: I’m getting an error reported back. How do I fix this?
A4: Use a validating XML editor to fix any XML issues. The schematron file also checks to ensure that you have the appropriate sections in the proper sequence. Refer to the ONVIF Interface Guide Specification and the provided template for details. You can add additional sub-sections, but do not change the order of the primary sections or you will fail validation.
Q5: I got the following error: “Required namespace not found: http://www.w3.org/2001/XMLSchema-instance”. What do I need to do to fix this?
A5: The first article tag should include the three namespaces from the template: <article xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns=”http://docbook.org/ns/docbook” xmlns:xlink=”http://www.w3.org/1999/xlink” version=”5.0″>. Use the latest version of the template file for creating your interface guide.
Q6: I have made editorial changes to my IG that will make it look better/fit my company´s content better but I now fail the schematron check. I am sure it doesn’t violate the ONVIF Interface Guide Specification! What should I do?
A6: Use the support form on the ONVIF webpage to report the problem. Also attach the IG file that fails the validation. If the changes are according to the specification the TSC will issue an update to the schematron file.
Q7: I get one of the following 2 validation errors when I try to upload my product, what’s wrong?
Inconsistent FW/SW version in Interface guide compared to Feature List, approval is not possible.
Inconsistent product name in Interface guide compared to Feature List, approval is not possible.
A7: The fields <productname> and <productnumber> in the Interface Guide must exactly match the information from the fields <ProductName> and <FirmwareVersion> from the FeatureList.
Also note that these fields (<productname> and <productnumber>) appear in two separate locations in the Interface Guide document so make sure you change both locations.