Consider Martin, who is using a Web-based bug tracking system to investigate some software problems. He sees a bug report which says:

The bug tracking system is built to show examples just as they are entered into the system, so for http://example.org/bugdata/brokenfile.xml it returns a stream of (poorly formed) XML with Content-Type text/plain. That Content-Type should cause a properly configured browser to show Martin the erroneous text just as it was recorded:

<?xml version="1.0">
<PetList>
  <Dog>Rover</Dog>
  <Cat>Felix</Fish>
</PetList>

Unfortunately, Martin uses a browser that incorrectly attempts to infer the format of the returned data from the URI suffix. Keying on the ".xml" in the URI, it launches an XML renderer for what should have been plain text. When Martin attempts to view the faulty file, he sees instead a browser error saying that the erroneous XML could not be displayed.

Constraint: Web software MUST NOT depend on the correctness of metadata inferred from a URI, except when the encoding of such metadata is documented by applicable standards and specifications.

Such standards and specifications include pertinent Web and Internet RFCs and Recommendations such as , as well as documentation provided by the URI assignment authority.

Martin's browser is in error because its inference that the URI suffix provides file type metadata is not provided for by normative Web specifications or, we may assume, in documentation from the assignment authority. A correctly written browser would have shown the faulty XML as text, or might conceivably have shown a warning about the apparent mismatch between the type inferred from the URI and the returned Content-Type. (Martin's browser is also ignoring TAG finding "Authoritative Metadata" , which mandates that the Content-Type HTTP header takes precedence even if type information had somehow been reliably encoded in the URI.)

Note that the constraint refers to conclusions drawn by software, which must be trustworthy, as opposed to guesses made by people. As discussed in , guessing is something that people using the Web do quite often and for good reason. Software tends to be long lived and widely distributed. Thus software dependencies on undocumented URI metadata result not only in buggy systems, but in inappropriate expectations that authorities will constrain their URI assignment policies and representation types to match dependencies in the clients. For both of these reasons, the constraint above requires that software must not have such dependencies.

There is certain metadata that Martin or his browser can reliably determine from the URI. For example, the URI conveys that the http scheme has been used, and that attempts to access the resource should be directed to the IP address returned from the DNS resolution of the string "example.org". These conclusions are supported by normative specifications such as and .

Bob is walking down a street, and he sees an advertisement on the side of a bus:

Bob goes home and types the URI into his browser, which does indeed display for him a Chicago weather forecast. Bob then realizes that he'll be visiting Boston, and he guesses that a Boston weather page might be available at a similar URI:

He types that into his browser and reads the response that comes back.

Bob is using the original URI for more than its intended purpose, which is to identify the Chicago weather page. Instead, he's inferring from it information about the structure of a Web site that, he guesses, might use a uniform naming convention for the weather in lots of cities. So, when Bob tries the Boston URI, he has to be prepared for the possibility that his guess will prove wrong: Web architecture does not guarantee that the retrieved page, if there is one, has the weather for Boston, or indeed that it contains any weather report at all. Even if it does, there is no assurance that it is current weather, that it is intended for reliable use by consumers, etc. Bob has seen an advertisement listing just the Chicago URI, and that is the only one that the URI authority has warranted will be a useful weather report.

Still, the ability to explore the Web informally and experimentally is very valuable, and Web users act on such guesses about URIs all the time. Many authorities facilitate such flexible use of the Web by assigning URIs in an orderly and predictable manner. Nonetheless, in the example above, Bob is responsible for determining whether the information returned is indeed what he needs.

Bob would not have had to guess the Boston weather URI if the authority had documented its URI assignment policy. Assignment authorities have no obligation to provide such documentation, but it can be a useful way of advertising in bulk the URIs for a collection of related resources. For example, an advertisement might read:

Reading that advertisement, Bob can reasonably assume that weather reports are available by substituting specific city names into the URI pattern http://example.org/weather/your-city-name-here. Moreover, the advertisement claims that the weather information obtainable at those URIs is "the best", so Bob can assume that the weather reports are trustworthy and current.

HTML forms and now XForms each provide a means by which an authority can assert its support for a class of parameterized URIs, while simultaneously programming Web clients to prompt for the necessary parameters. For example, a Web site http://example.org/weatherfinder might offer a city lookup page containing the following HTML form fragment:

<FORM ACTION="http://example.org/cityweather" METHOD="GET">
  For what city would you like a weather report: 
  <INPUT TYPE="TEXT" NAME="city">?
  <INPUT TYPE="SUBMIT" VALUE="Get the weather">
</FORM>

A browser receiving this form, or Bob if he views the source of the form, is assured that the assigning authority is supporting an entire class of URIs of the form:

http://example.org/cityweather?city=CityName

The same HTML Form is also a computer program, executable by the browser, that prompts for and retrieves representations for all such URIs, and the English text in the form assures Bob that these are indeed for weather reports. Bob is not guessing the encoding of the URI or the nature of the resources referenced — he is acting on authoritative information provided by the assignor of the URIs. He can assume not just that he will get weather reports for certain cities, but that no URIs in the class correspond to anything other than weather reports (though some may correspond to no resource at all). Bob could, with this assurance, write his own software to construct and use such URIs to retrieve weather reports. Of course, the typical Web user would neither directly inspect the URIs nor write software to build them, but would instead type in city names and push the handy "Get the weather" button on his or her browser screen.

Note that the example carefully specifies that the HTML form is sourced from the same authority as the individual weather URIs that the form queries. In fact, it is also common for the ACTION attributes in HTML forms to refer to URIs from other authorities. In such cases, it is the provider of the form rather than the assigning authority for the queried URIs who is responsible for the claims made in the form. In particular, users (and software) should check the origin of HTML forms before depending on the URI assignment patterns that they appear to imply. Of course, you can always use such a form to perform a query and see what comes back; what you can't do is blame the assignment authority if the generated URIs either don't resolve (status code 404) or return representations that don't match the expectations established when reading the form (you got a football score instead of a weather report).

In the examples in above, resource metadata (I.e. the city associated with each resource) was encoded into URIs primarily for the benefit of users such as Bob, or to facilitate use of the HTML Forms or XForms acting on those users' behalf.

Often, metadata is encoded into a URI not primarily for the benefit of users, but to facilitate management of the resources themselves. For example, assume that the administrators at example.org have established a policy of assigning URIs based on the media types of representations: all GIF images are named with URIs ending in ".gif", and all JPEG images are named with URIs ending in ".jpeg", and so on. Although warned that users of a resource cannot rely on undocumented naming conventions to determine media types and other information about a resource, the owner of a resource controls such naming and can depend on it. Example.org may therefore rely on their policy in an Apache Web Server .htaccess file, which causes the correct media type to be served automatically for each resource:

<Files ~ ".*\.gif">
  ForceType 'image/gif'
</Files>
<Files ~ ".*\.jpg">
  ForceType 'image/jpeg'
</Files>

Even if it does not document this policy publicly, example.org's own Web servers can safely depend on it.

Good Practice: URI assignment authorities and the Web servers deployed for them may benefit from an orderly mapping from resource metadata into URIs.

In addition to filename-based conventions, authorities may choose to base URIs on database keys, customer identifiers, or other information that makes it easy to associate a URI with information pertinent to the corresponding resource. Such encodings are both useful and common on the Web, but there can also be drawbacks to including such information in URIs. Some of those problems are discussed in the three sections immediately below.

URIs optimized for use by the assignment authority may sometimes be inconvenient for resource users. Consider Mary who is walking down the street, and who sees the same weather advertisement as Bob:

Like Bob, Mary is pleased to learn about a valuable Web site, and she finds that the URI itself is quite easy both to remember and to type into her browser. This is because, in addition to the required scheme and authority components, the URI is based on the word weather and the city name Chicago, both of which fit her expectations for this resource.

The next day, Mary sees another advertisement reading:

Mary is annoyed, because the URI is both difficult to remember and hard to transcribe accurately. She guesses that the authority has assigned this URI for its own convenience (see ) rather than for hers. Although Web architecture does not require that URIs be easy to understand or suggestive of the resource named, it's handy if those intended for direct use by people are.

Good Practice: URIs intended for direct use by people should be easy to understand, and should be suggestive of the resource actually named.

Note that the second URI might be based on a database key that facilitates efficient access to the weather data at the server (see ); such a URI might have been a good choice if it were intended only for use in HTML hyperlinks, rather than in an advertisement on the side of a bus.

URIs should generally not encode metadata that will change, regardless of whether the encoding policy is established to benefit URI assignment authorities, resource users, or both. Consider a web site that organizes document URIs according to the documents' lead author or editor. Thus, the documents:

http://example.org/documents/editor/BobSmith/document1
http://example.org/documents/editor/BobSmith/document2

are named for their editor, Bob Smith. Bob retires, and Mary Jones takes over as editor for document1. If the URI is changed to encode her name, then existing links break, but if the URI is not changed, the naming policy is violated. By encoding into the URI metadata that will change, the authority has put itself in a difficult position.

Good Practice: Resource metadata that will change SHOULD NOT be encoded in a URI.

Indeed, RDF statements about the resource, headers returned with representations (e.g. Content-Type) or metadata embedded in the representations themselves (e.g. HTML <META> tags) are all better alternatives for conveying such volatile metadata about the resource.

A bank establishes a URI assignment policy in which account numbers are encoded directly in the URI. For example, the URI http://example.org/customeraccounts/456123 accesses information for account number 456123. A malicious worker at an Internet Service Provider notices these URIs in his traffic logs, and determines the bank account numbers for his Internet customers. Furthermore, if access controls are not properly in place, he might be able to guess the URIs for other accounts, and to attempt to access them.

Good Practice: URI assignment authorities SHOULD NOT put into URIs metadata that is to be kept confidential.

Confusing or malicious metadata

Although a URI suffix such as .jpeg or .exe plays no role in establishing the media type of a Web resource, such suffixes are often significant in operating system filenames and to users. This situation can be confusing to users, and may in some cases be exploited by malicious web sites to cause harm.

First, there is the question of how content is rendered. As discussed in , the Content-Type is the authoritative source of information on representation typing and so should be used as the basis for rendering. Still, users may be confused to see a file rendered in a manner that seems inconsistent with the suffix in the URI. The situation for users is further complicated if media types are misapplied by the server. For example, video files are too often served as text/plain, PNG images may be mis-typed as image/jpeg, and so on. In part to deal with such mislabeled content, or perhaps for other reasons, browsers sometimes use heuristics to guess type information from the the suffix of the URI. Unless done with permission from the user, such inferences violate the constraints set out in TAG finding "Authoritative Metadata" , but with the user's permission such inferences may be necessary for correct rendering of mislabeled content.

Users may also call upon their browsers to save content to a local filesystem, and often the filename suggested is derived from the URI. However, in the many operating systems that encode typing information in the filename suffix, the mapping from served representation to default saved filename must be made with care. If the URI suffix (such as .jpeg) is significant to the local filesystem, and especially if the type inferred from it is inconsistent with the authoritative media type, users may inadvertently save files that the local operating system considers to be mis-typed.

Good Practice: When saving files from the Web, user agents SHOULD suggest filenames that represent appropriate mappings of the authoritative media type to local file naming conventions. User agents MAY suggest filenames based on the URI suffix or other metadata, but SHOULD do so only if those names are consistent with the authoritative media type. In cases where such consistent mappings are not offered, or where the data saved may be harmful (e.g. an untrusted executable file), user agents SHOULD warn users of the associated risks.

Malicious use media types and URI metadata is never acceptable. Consider Bob who is looking on the Web for pictures of his favorite movie star. He views in his browser an image that has been served with media type image/jpeg. Underneath the picture is a label that says: "Right click on this picture and select 'Save Link As...' or 'Save Target As...' to save a copy of this picture on your hard drive." The HTML is:

<a href="./malicious.exe">
  <img src="./moviestar.jpg"/>
</a>

<p>
Right click on the picture above and select 
'Save Link As...' or 'Save Target As...'
to save a copy on your hard drive.
</p>

The linked executable is served with a media type of application/octet-stream, but the web site is counting on the common practice in which user agents carry the ".exe" suffix from the served URI to the saved filename.

Bob has heard that some sites with movie star pictures have been untrustworthy, but knowing a bit about computers, he believes that saving a picture file should be relatively safe. Bob doesn't notice that the link is to a URI ending in .exe, and that his browser will likely save a malicious executable to his hard drive. One can imagine circumstances in which linking to an executable from an image would be legitimate (e.g. linking from the image of a box of packaged software to an associated executable download), but this web site is malicious. It carefully mislabels the link, by erroneously claiming that its instructions will to saving of a picture rather than an executable.

Some of the confusion in the examples may arise from metadata inferred from URIs, but some traces to the fact that the example involves two separate URIs. Bob probably doesn't realize that on the Web, the resource used to render the picture is not in general the one that would be linked by clicking on the picture. The confusion in such situations is compounded by the tendency of users, browsers, and operating systems, each in their own way, to infer type information from URI and/or filename suffixes. Of course, the inclusion of instructions that are intended to mislead users such as Bob is always unacceptable.

Good Practice: Web sites SHOULD use hyperlinks and URI metadata in a manner that minimizes confusion for users, and SHOULD NOT misleadingly apply common conventions for encoding type information into filenames and URIs.