URIs and LumenVox

There are a variety of ways that LumenVox may take user-supplied URIs to point to external resources. These include:

As the location of a grammar or SSML document to use for a recognition or synthesis (passed into the Media Server or the API).
External grammars or lexicons referenced within a grammar file.
External audio or lexicon files referenced with an SSML document.

LumenVox supports URIs using the following prefixes:

http:// for documents served by an HTTP (web) server.
https:// for documents served by secure HTTP server.
builtin: for referencing built-in grammars.

Examples of acceptable URIs:

In a GrXML grammar file, using to reference an external grammar called yesno.grxml hosted on the web server called my-server in the grammars directory.
In an SSML document, using to reference the external lexicon called names.xml hosted on the web server called my-server in the lexicons directory.
As part of a DEFINE-GRAMMAR MRCP message, sending file:///c:/grammars/parts.abnf to reference the grammar called parts.abnf hosted on the local C: drive in the folder called grammars.

Users should not provide URIs that do not include a prefix which indicates the mechanism used for retrieving the document (the exception is for relative URIs when a base URI can be established; see more on that below). Examples of URIs that are not acceptable:

is unacceptable because it is a reference to a local file without the file:// prefix
is unacceptable because it references the local filesystem without the file:// prefix and uses the wrong sorts of slashes (URIs should not contain backslashes).

Using these sorts of unacceptable URIs will produce unexpected results. LumenVox will make an attempt to resolve them, but for instance you may find that while speech recognition works correctly, attempts to perform tuning on those grammars fail since the Tuner (on a remote machine) may not be able to correctly resolve them. LumenVox officially supports and tests URIs with the scheme:// prefix.

Relative URIs

Relative URIs are the only time that URIs are supported without the scheme:// prefix. The use of a relative URI implies that LumenVox has a base URI for the document. For instance, GrammarA might reference another grammar using which implies that GrammarB.grxml is in the same directory as GrammarA. In that case, LumenVox would use the same scheme for fetching GrammarB as was used with GrammarA, e.g. if GrammarA were loaded with http://my-server/grammars/GrammarA.grxml then we would attempt to resolve the reference to GrammarB as http://my-server/grammars/GrammarB.grxml.

There are several ways a base URI can be calculated:

Using the xml:base attribute in a GrXML grammar, SSML, or other XML document.
Using the base keyword in an ABNF grammar.
By explicitly setting a Base-URI over MRCP.
Implicitly as in the example above (GrammarB is considered to have the same base URI as GrammarA)

Using file://

There is sometimes some confusion about how to properly use the file:// prefix. The basic rules are as follows:

The URI must always begin with the file:// prefix
Following the prefix, there is an optional hostname. E.g. file://my-server
After the hostname, you must include a single slash and then the path, e.g. file://my-server/etc/grammars/parts.abnf or file://my-server/share/grammars/parts.abnf
If you are simply referencing the local system and not a networked location, you must omit the hostname entirely. However you must still include the slash before the path, giving three slashes before the path, e.g. file:///etc/grammars/parts.abnf or file:///c:/share/grammars/parts.abnf
Note that on Windows, if you are referencing a network share, you cannot include a drive letter followed by a colon (e.g. file://my-server/c:/share/ is illegal) as colons are not valid characters in UNC path names.

Here are some examples of how a file:// would be resolved:

file:///c:/foo.gram is equivalent to C:\foo.gram (on the local machine) on Windows
file://my-server/foo.gram is equivalent to \\my-server\foo.gram using UNC on Windows only.
file:///root/foo.gram is equivalent to /root/foo.gram on Linux.

Was this article helpful?