1. 1 Hide (Localize) Namespaces versus Expose Namespaces XML Schemas: Best Practices A set of guidelines for designing XML Schemas Created by discussions on xml-dev

2. 2 <xsd:schema … targetNamespace=“A”> A.xsd <xsd:schema … targetNamespace=“B”> B.xsd <xsd:schema … targetNamespace="C"> <xsd:import namespace="A" schemaLocation="A.xsd"/> <xsd:import namespace="B" schemaLocation="B.xsd"/> … C.xsd Typical Scenario: Multiple Schemas, each with a Different Namespace

3. 3 Hide (Localize) Namespaces The namespaces of the components are not visible in the instance documents. <myDoc … schemaLocation=“C C.xsd”> Instance Document

4. 4 Expose Namespaces <myDoc … schemaLocation=“C C.xsd”> The namespaces of the components are visible in the instance documents. Instance Document

5. 5 Hide (Localize) Namespaces The namespaces of the elements used in an instance document are hidden within the schema. –That is, the namespace complexities are localized to the schemas. The complexities are not propagated to instance documents.

6. 6 Expose Namespaces The namespaces of the elements used in an instance document are made visible in instance documents.

7. 7 elementFormDefault - the Exposure “Switch” hide expose elementFormDefault <xsd:schema … elementFormDefault=“qualified”> <xsd:schema … elementFormDefault=“unqualified”> vs Schema

8. 8 How do we Design the below Schemas to Hide (Localize) Namespaces? versus How do we Design them to Expose Namespaces? Camera.xsd Nikon.xsd Olympus.xsd Pentax.xsd

9. 9 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.camera.org" xmlns:nikon="http://www.nikon.com" xmlns:olympus="http://www.olympus.com" xmlns:pentax="http://www.pentax.com" elementFormDefault="unqualified"> <xsd:import namespace="http://www.nikon.com" schemaLocation="Nikon.xsd"/> <xsd:import namespace="http://www.olympus.com" schemaLocation="Olympus.xsd"/> <xsd:import namespace="http://www.pentax.com" schemaLocation="Pentax.xsd"/> <xsd:element name="manual_adapter" type="pentax:manual_adapter_type"/> This schema is designed to hide namespaces

10. 10 <my:camera xmlns:my="http://www.camera.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.camera.org Camera.xsd"> Ergonomically designed casing for easy handling</descriptio 300mm 1.2 1/10,000 sec to 100 sec Instance document with namespaces hidden (localized) within the schema Ergonomically designed casing for easy handling 300mm 1.2 1/10,000 sec to 100 sec Instance document with namespaces hidden (localized) in the schema. --> The fact that the element comes from the Nikon schema, the and elements come from the Olympus schema, and the element comes from the Pentax schema is totally transparent to the instance document. Instance Document

11. 11 Technical Requirements for Hiding (Localizing) Namespaces The schema must be designed as follows: –elementFormDefault must be set to unqualified –The elements whose namespaces are to be localized to the schema must be declared locally (recall that global elements must always be qualified) elementFormDefault only behaves as a “switch” when this requirement is met!

12. 12 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.camera.org" xmlns:nikon="http://www.nikon.com" xmlns:olympus="http://www.olympus.com" xmlns:pentax="http://www.pentax.com" elementFormDefault="qualified"> <xsd:import namespace="http://www.nikon.com" schemaLocation="Nikon.xsd"/> <xsd:import namespace="http://www.olympus.com" schemaLocation="Olympus.xsd"/> <xsd:import namespace="http://www.pentax.com" schemaLocation="Pentax.xsd"/> <xsd:element name="manual_adapter" type="pentax:manual_adapter_type"/> This schema is designed to expose namespaces

13. 13 <c:camera xmlns:c="http://www.camera.org" xmlns:nikon="http://www.nikon.com" xmlns:olympus="http://www.olympus.com" xmlns:pentax="http://www.pentax.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.camera.org Camera.xsd> Ergonomically designed casing for easy handling 300mm 1.2 1/10,000 sec to 100 sec Instance document with namespaces exposed Ergonomically designed casing for easy handling 300mm 1.2 1/10,000 sec to 100 sec Instance Document

14. 14 Technical Requirements for either Hiding or Exposing Namespaces elementFormDefault applies just to the schema that it is in. It does not apply to schemas that it includes or imports. Consequently, if you want to hide namespaces then all schemas involved must have set elementFormDefault="unqualified". Likewise, if you want to expose namespaces then all schemas involved must have set elementFormDefault="qualified". The next couple of slides shows what happens when a mix of elementFormDefault values is used.

15. 15 Nikon.xsd elementFormDefault="qualified" Olympus.xsd elementFormDefault="unqualified" Pentax.xsd elementFormDefault="qualified" Camera.xsd elementFormDefault="unqualified"

16. 16 Hiding/exposure mix: This instance document has the Nikon and Pentax namespaces exposed, while the Camera and Olympus namespaces are hidden. Instance Document <my:camera xmlns:my="http://www.camera.org" xmlns:nikon="http://www.nikon.com" xmlns:pentax="http://www.pentax.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.camera.org Camera.xsd> Ergonomically designed casing for easy handling 300mm 1.2 1/10,000 sec to 100 sec 300mm 1.2 Instance document with namespaces hidden (localized) within the schema Ergonomically designed casing for easy handling 300mm 1.2 1/10,000 sec to 100 sec Ergonomically designed casing for easy handling 1/10,000 sec to 100 sec

17. 17 Guidelines: When to Hide (Localize) Namespaces within the Schema When simplicity, readability, and understandability of instance documents is of utmost importance. In many scenarios the users of the instance documents are not XML-experts. Namespaces would distract and confuse such users, where they are just concerned about structure and content. When namespaces in the instance provide no necessary additional information. When you need the flexibility of being able to change the inner components without impact to instance documents –Example. Changing from using the Olympus schema to declare the and elements to another vendor’s schema is transparent

18. 18 Guidelines: When to Expose Namespaces in Instance Documents When lineage (ownership) of the elements are important, e.g., for copyright purposes When there are multiple elements with the same name then it may be necessary to qualify those elements to make clear their semantics. –Example. versus When processing (by an application) of the instance document elements is dependent upon knowledge of the namespaces of the elements –Forcing applications to go to the schema for such information may be costly in terms of speed. This cost may be negated as XML API’s (DOM, SAX) provide namespace information for each element.

19. 19 Best Practice Make two versions of all your schemas - one with elementFormDefault="qualified" and the other with elementFormDefault="unqualified". –If every schema designer adopts this practice then each schema designer will be able to make a choice on whether to hide or expose namespaces. Minimize the use of global elements and attributes so that elementFormDefault may be used as an “exposure switch”. Do Labs 1,2,3,4