2005-05-02 diff-marked version: Assigning Describing Media Types to Content of Binary Data in XML

1.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [IETF RFC 2119] .

This specification uses properties from the XML Information Set, see Set (see [XML Information Set] </a>. ). Such properties are denoted by square brackets, e.g. [namespace name].

This specification uses namespace prefixes that are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Information Set] ).

Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs <a href="#rfc2396"> (see [IETF RFC 2396] </a>. 3986] ).

All parts of this specification are normative, with the exception of examples and sections explicitly marked as "Non-Normative".

1.2 Requirements

This section describes the set of requirements that this document addresses.

1. Define how to indicate the media type content-type of an XML element content whose type is xs:base64Binary or xs:hexBinary . This is meta-data that may be, but not required to, used by tools to infer the specific media type content-type of binary data.

2. Define how to indicate the expected media type(s) content-type(s) of XML element content whose type is xs:base64Binary or xs:hexBinary in XML Schema. This information is needed to define the set of media types content-type that a binary data may have. For example, a Web services application may be willing to indicate that the binary data represents an image, but leaves it to a document instance to further specify whether it is "jpeg", "gif", etc. or "gif". This meta-data is not required to be present.

3. Define the acceptable format of media type content-type values.

4. Define the relationship between the expected and the actual value of the media types content-type declared for binary data in XML documents.

2.1 contentType attribute xmime:contentType Attribute

The contentType xmime:contentType attribute information item has the following Infoset properties:

• A [local name] of contentType .

• A [namespace name] of "http://www.w3.org/2004/11/xmlmime". "http://www.w3.org/2005/05/xmlmime".

The type of the contentType xmime:contentType attribute information item is xs:string </em>. with a minimum length of three and all leading and trailing white space characters are ignored.

The [normalized value] of the xmime:contentType attribute information item MUST be a valid Content-Type string, e.g., "image/png", "text/xml; charset=utf-16" as defined by [IETF RFC 2045] and indicates the content-type of the [owner element]. Note that [normalized value] consists of normalized attribute value as defined by [XML Information Set] and does not mean that two equivalent values of xmime:contentType will necessarily be equal.

The xmime:contentType attribute information item allows Web services applications to optimize the handling of the binary data defined by a binary element information item and should be considered as meta-data. The presence of the xmime:contentType attribute does not changes the value of the element content.

<a name="expectedMediaType" id="expectedMediaType"> 2.2 expectedMediaType attribute xmime:expectedContentTypes Attribute

The expectedMediaType xmime:expectedContentTypes attribute information item has the following Infoset properties:

• A [local name] of expectedMediaType expectedContentTypes .

• A [namespace name] of http://www.w3.org/2004/11/xmlmime http://www.w3.org/2005/05/xmlmime .

The type of the expectedMediaType xmime:expectedContentTypes attribute information item is xs:string .

The value and the meaning of the expectedMediaType xmime:expectedContentTypes attribute is similar to the value allowed for the 'Accept' HTTP header defined by HTTP 1.1 specification, Section 14.1 <a href= "#rfc2616"> (see [IETF RFC 2616] ) and MUST follow the production rules defined in that section. The 'q' parameter defined by HTTP 1.1 specification, Section 3.9 <a href="#rfc2616"> [IETF RFC 2616] </a> is allowed, but other accept-extensions are not allowed. section except for the following:

1. The 'accept-extensions' of the HTTP 'Accept' header are not allowed in the 'expectedMediaType' attribute value. prefix "Accept:" MUST NOT be used.

2. The WSD WG would like rule qdtext is changed from: qdtext = <any TEXT except<">> to: qdtext = <any CHAR except<">> This change is made to solicit feedback on this. </td> </tr> </table> disallow non-US-ASCII OCTETs.

The expectedMediaType xmime:expectedContentTypes attribute information item is intended to be used as part of XML Schema annotation for a binary element information item declaration (see 3 Declaring media types Content-Type for binary data Binary Data ). This attribute information item is meant to allow XML Schema authors to indicate the range of media types and/or associated parameters that are acceptable for the binary data. It serves as a static constrain on the xmime:contentType .Users of this attribute information item are urged to avoid using wild cards (for example, "image/*") as it may lead to interoperability problems. If the set of expected media types is not known, the use of xmime:expectedContentTypes is NOT RECOMMENDED.

3.1 Role of expectedMediaType xmime:expectedContentTypes Schema annotation attribute Annotation Attribute

The expectedMediaType xmime:expectedContentTypes attribute is used for annotating XML Schema to indicate the expected range of media types content-type of the binary element content and the expected range of values for contentType xmime:contentType attribute.

The value of the contentType xmime:contentType attribute, if present, SHOULD be within the range specified by the expectedMediaType xmime:expectedContentTypes annotation attribute, if specified in the schema. See Section 14.1 of [IETF RFC 2616] on how to interpret content-type ranges that may be defined with respect to actual content. When the expectedMediaType xmime:expectedContentTypes annotation attribute has contains a wildcard wild card ("*") or a list of acceptable media types, content-type separated by commas (","), the schema SHOULD require the contentType xmime:contentType attribute to be present.

Applications that need to specify expected media types content-type SHOULD use the schema annotation to declare the range of expected values. expectedMediaType xmime:expectedContentTypes annotation attribute MAY be used in conjunction with the declaration of binary element information item s or with complex type definitions that are derived from xs:base64Binary or xs:hexBinary in XML Schema. If the expectedMediaType xmime:expectedContentTypes annotation attribute is used in both the binary element information item declaration as well as definition of the complex type which the binary element information item belongs to, then the expected range of values defined for the binary element information item MUST be a subset of the expected range of values defined for the complex type.

The xmime:expectedContentTypes annotation can be used in conjunction with either type or element declarations. Certain data-binding frameworks which use static type mappings can be more specific if the xmime:expectedContentTypes annotation is applied to the complexType declarations instead of the element declarations using those types. For this reason, the use of expectedContentTypes on element declarations using named complex types is not recommended. An example is provided in Example 6.

The example below consists of a type definition, PictureType , and an element declaration, Picture . The xmlmime:contentType xmime:contentType attribute is required to be present and specifies the media type content-type of the binary content. The schema annotation attribute xmlmime:expectedMediaType xmime:expectedContentTypes specifies that the media type of the binary content is 'image', but and the subtype name is unknown. either 'jpeg' or 'png'.

<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:tns="http://example.com/wildcard"


           xmlns:xmlmime="http://www.w3.org/2004/11/xmlmime"



           xmlns:xmime="http://www.w3.org/2005/05/xmlmime"


           targetNamespace="http://example.com/wildcard">



    <xs:import namespace="http://www.w3.org/2004/11/xmlmime"
            schemaLocation="http://www.w3.org/2004/11/xmlmime"/>



    <xs:import namespace="http://www.w3.org/2005/05/xmlmime"
                schemaLocation="http://www.w3.org/2005/05/xmlmime"/>




    <xs:complexType name="PictureType">
       <xs:simpleContent>


           <xs:restriction base="xmlmime:base64Binary" >
               <xs:attribute ref="xmlmime:contentType" use="required" />



           <xs:restriction base="xmime:base64Binary" >
               <xs:attribute ref="xmime:contentType" use="required" />


           </xs:restriction>
       </xs:simpleContent>
    </xs:complexType>

    <!-- This element designates the range of values 
         that the element definition will accept    -->
    <xs:element name="Picture" type="tns:PictureType" 


            xmlmime:expectedMediaType="image/*"/> 
    </xs:element>



                xmime:expectedContentTypes="image/jpeg, image/png"/>



</xs:schema>
deleted text: 

        

The example document instance below conforms to the element declaration of Picture and specifies that the binary content is of type "image/png".

<?xml version="1.0" ?>
<Picture xmlns="http://example.com/wildcard"


           xmlns:xmlmime="http://www.w3.org/2004/11/xmlmime"
           xmlmime:contentType="image/png">/aWKKapGGyQ=</Picture>



           xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
           xmime:contentType="image/png">/aWKKapGGyQ=</Picture>


        

4.1 Binary data Data with known media type Known Media Type

The example below examples in this section consists of a binary element elements whose media type is known in advance to be "image/jpeg".

In this example, the application fixes the Example 4, a fixed media type is specified by declaring it with an annotation in conjunction with the complex type definition. The attribute xmime:contentType is not used as the media type of the binary data is know in advance.

<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:tns="http://example.com/know-type"


           xmlns:xmlmime="http://www.w3.org/2004/11/xmlmime"



           xmlns:xmime="http://www.w3.org/2005/05/xmlmime"


           targetNamespace="http://example.com/know-type">



    <xs:import namespace="http://www.w3.org/2004/11/xmlmime"
            schemaLocation="http://www.w3.org/2004/11/xmlmime"/>




    <xs:import namespace="http://www.w3.org/2005/05/xmlmime"
            schemaLocation="http://www.w3.org/2005/05/xmlmime"/>





    <xs:complexType name="JPEGPictureType" 
            type="xs:base64Binary"
            xmlmime:expectedMediaType="image/jpeg"/> 



    <xs:simpleType name="JPEGPictureType" 
            xmime:expectedContentTypes="image/jpeg"> 
        <xs:restriction base="xs:base64Binary"/>
    </xs:simpleType>





    <xs:element name="JPEGPicture" type="tns:JpegPictureType"/>



    <xs:element name="JPEGPicture" type="tns:JPEGPictureType"/>



</xs:schema>


        

In Example 5, a fixed media type is specified by declaring it with an annotation in conjunction with the element declaration. The attribute xmime:contentType is optionally used in document instances to indicate the media type of the binary data.

<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:tns="http://example.com/know-type"
           xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
           targetNamespace="http://example.com/know-type">

    <xs:import namespace="http://www.w3.org/2005/05/xmlmime"
            schemaLocation="http://www.w3.org/2005/05/xmlmime"/>

    <xs:element name="JPEGPicture" type="xmime:base64Binary"
            xmime:expectedContentTypes="image/jpeg" />

</xs:schema>


        

4.2 Binary data Data with preferred media type Preferred Media Type

This example illustrates that binary data with media type 'image/jpeg' is preferred but binary data with media type of 'image/tiff' is also allowed (with a lower preference).

<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:tns="http://example.com/preferred-type"


           xmlns:xmlmime="http://www.w3.org/2004/11/xmlmime"



           xmlns:xmime="http://www.w3.org/2005/05/xmlmime"


           targetNamespace="http://example.com/preferred-type">



    <xs:import namespace="http://www.w3.org/2004/11/xmlmime"
        schemaLocation="http://www.w3.org/2004/11/xmlmime"/>



    <xs:import namespace="http://www.w3.org/2005/05/xmlmime"
            schemaLocation="http://www.w3.org/2005/05/xmlmime"/>






    <xs:complexType name="JPEGPreferredPictureType">



    <xs:complexType name="JPEGPreferredPictureType"
            xmime:expectedContentTypes="image/jpeg;q=1.0, image/tiff;q=0.8"> 


        <xs:simpleContent>


            <xs:restriction base="xmlmime:base64Binary" >
                <xs:attribute ref="xmlmime:contentType" use="required" />



            <xs:restriction base="xmime:base64Binary" >
                <xs:attribute ref="xmime:contentType" use="required" />


            </xs:restriction>
        </xs:simpleContent>
    </xs:complexType>



    <xs:element name="JPEGPeferredPicture" type="tns:JPEGPreferredPictureType"
            xmlmime:expectedMediaType="image/jpeg;q=1.0, image/tiff;q=0.8"/> 



    <xs:element name="JPEGPeferredPicture" 
            type="tns:JPEGPreferredPictureType"/> 



</xs:schema>
deleted text: