URIs and Capacity

Capacity Private Cloud accepts user-supplied URIs to point to external resources in a variety of places. 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 within an SSML document.

The platform supports URIs using the following prefixes:

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

Examples of acceptable URIs:

  • In a GrXML grammar file, <ruleref uri="http://my-server/grammars/yesno.grxml"/> references an external grammar called yesno.grxml hosted on the web server my-server in the grammars directory.
  • In an SSML document, <lexicon uri="http://my-server/lexicons/names.xml"/> references an external lexicon called names.xml hosted on the web server my-server in the lexicons directory.
  • As part of a DEFINE-GRAMMAR MRCP message, sending file:///c:/grammars/parts.abnf references the grammar called parts.abnf hosted on the local C: drive in the folder called grammars.

You should not provide URIs that omit a prefix indicating the mechanism used to retrieve the document (the exception is relative URIs, where a base URI can be established — see below). Examples of URIs that are not acceptable:

  • c:/grammars/parts.abnf is unacceptable because it references a local file without the file:// prefix.
  • c:\grammars\parts.abnf is unacceptable because it references the local filesystem without the file:// prefix and uses the wrong kind of slashes (URIs must not contain backslashes).

Using these unacceptable URIs produces unexpected results. The platform attempts to resolve them, but you may find, for example, that while speech recognition works correctly, attempts to tune or test those grammars from a different machine fail, because a remote tool may not be able to resolve a local-file URI. The platform officially supports and tests URIs that include the scheme:// prefix.

Relative URIs

Relative URIs are the only case where a URI is supported without the scheme:// prefix. A relative URI implies that the platform has a base URI for the document. For instance, GrammarA might reference another grammar using <ruleref uri="GrammarB.grxml"/>, which implies that GrammarB.grxml is in the same directory as GrammarA. In that case, the platform uses the same scheme to fetch GrammarB as was used for GrammarA — for example, if GrammarA was loaded with http://my-server/grammars/GrammarA.grxml, the reference to GrammarB resolves as http://my-server/grammars/GrammarB.grxml.

A base URI can be established in several ways:

  • 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).

For more detail, see the Base URI article.

Using file://

There is sometimes 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 — for example, file://my-server.
  • After the hostname, you must include a single slash and then the path — for example, file://my-server/etc/grammars/parts.abnf or file://my-server/share/grammars/parts.abnf.
  • If you are referencing the local system rather than a networked location, you must omit the hostname entirely. You must still include the slash before the path, giving three slashes before the path — for example, file:///etc/grammars/parts.abnf or file:///c:/share/grammars/parts.abnf.
  • On Windows, if you are referencing a network share, you cannot include a drive letter followed by a colon (for example, file://my-server/c:/share/ is illegal), because colons are not valid characters in UNC path names.

Examples of how a file:// URI resolves:

  • 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.

Related articles

Was this article helpful?