e-Government Program (Yesser) YEsser Framework Interoperability (YEFI) XML Schema Naming and Design Rules Version 1.1 Date: 25/11/2007 e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 2 / 26 Versioning Version Date 0.1 1.0 1.1 01/01/2007 27/05/2007 25/11/2007 Description of changes made Document Creation Final Update with government agencies’ comments Document Validation Version Author Review by Date Status Table of Contents 1. Introduction ....................................................................................................................... 5 1.1. Purpose ........................................................................................................................ 5 1.2. Document Structure ..................................................................................................... 5 1.3. Terminology and Notations ........................................................................................... 5 1.3.1. 1.3.2. 2. 3. Rationale ............................................................................................................................................. 5 Classification of Rules ......................................................................................................................... 6 Relationship to Other Standards ...................................................................................... 9 Naming Rules .................................................................................................................. 10 3.1. Common Naming Rules ............................................................................................. 10 3.1.1. 3.1.2. 3.1.3. 3.1.4. 3.1.5. 3.2. Language Options ...................................................................................................... 11 3.2.1. 3.2.2. 3.2.3. 3.2.4. 3.2.5. 3.2.6. 3.2.7. 3.3. Unique Elements and Types Naming Rule ........................................................................................ 10 Elements, Attributes and Types Naming Structure ............................................................................ 10 Singular Form of Names.................................................................................................................... 11 Connecting Words ............................................................................................................................. 11 Characters Permitted in Names ........................................................................................................ 11 Arabic /English Naming Options ........................................................................................................ 11 XML Schema Language .................................................................................................................... 11 Declaring XML Schema Language .................................................................................................... 12 XML Schema Language Verification ................................................................................................. 12 XML Schema Cross References ....................................................................................................... 12 Reusing Types from Different Languages ......................................................................................... 12 Inheriting Types from Different Languages ........................................................................................ 12 Types (Simple and Complex) Naming ........................................................................ 13 3.3.1. 3.3.2. Version 1.1 Simple Type Suffix............................................................................................................................. 13 Complex Type Suffix ......................................................................................................................... 13 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 3 / 26 3.3.3. 3.4. 3.4.1. 3.4.2. 3.5. Naming of A YEFI XML Schema File................................................................................................. 14 Naming of Metadata File ................................................................................................................... 14 Design rules ..................................................................................................................... 15 4.1. General Schema Design Rules .................................................................................. 15 4.1.1. 4.1.2. 4.1.3. 4.1.4. 4.1.5. 4.1.6. 4.1.7. 4.1.8. 4.1.9. 4.2. 4.3. Construction of Complex Types ........................................................................................................ 21 Definition of Complex Types by Derivation ........................................................................................ 21 The Use of Restrictions in Complex Types ........................................................................................ 21 The Use of Empty Content Model...................................................................................................... 21 The Use of “Any” Construct ............................................................................................................... 22 The Use of anyAttribute ..................................................................................................................... 22 Element Declarations Rules ....................................................................................... 22 4.5.1. 4.5.2. 4.5.3. 4.5.4. 4.5.5. 4.6. The Use of List .................................................................................................................................. 20 The Use of Union............................................................................................................................... 20 The Length of Strings ........................................................................................................................ 20 Representation of Code Lists ............................................................................................................ 20 Values in Enumerations ..................................................................................................................... 20 The use of the Whitespace Facet and Related Types ....................................................................... 21 Complex Type Definition rules .................................................................................... 21 4.4.1. 4.4.2. 4.4.3. 4.4.4. 4.4.5. 4.4.6. 4.5. Strong Data Types............................................................................................................................. 17 Renaming of an Existing Type ........................................................................................................... 19 The Use of anyType and anySimpleType .......................................................................................... 19 Handling Binary Content.................................................................................................................... 19 Abstract Types................................................................................................................................... 19 Controlling Type Derivations ............................................................................................................. 19 Simple Type Definition Rules...................................................................................... 20 4.3.1. 4.3.2. 4.3.3. 4.3.4. 4.3.5. 4.3.6. 4.4. Choice of Schema Language ............................................................................................................ 15 XML Version ...................................................................................................................................... 15 Choice of Encoding Scheme ............................................................................................................. 15 Namespace Assignment.................................................................................................................... 16 Namespace Representation .............................................................................................................. 16 Sub-Schema Referencing ................................................................................................................. 16 The Use of “Redefine” in XML Schema’s Cross Referencing ............................................................ 17 The use of notation ............................................................................................................................ 17 The Use of schemaLocation .............................................................................................................. 17 Type Definition Rules ................................................................................................. 17 4.2.1. 4.2.2. 4.2.3. 4.2.4. 4.2.5. 4.2.6. Global Element Declarations ............................................................................................................. 22 Elements Namespace ....................................................................................................................... 22 The use of Substitution Groups ......................................................................................................... 22 Empty Elements ................................................................................................................................ 22 Default or Fixed Elements Values ..................................................................................................... 23 Rules for Attribute Declarations .................................................................................. 23 4.6.1. 4.6.2. 4.6.3. 4.6.4. 5. lowerCamelCase Use ........................................................................................................................ 14 Naming of YEFI XML Schema and Metadata Files ..................................................... 14 3.6.1. 3.6.2. 4. The Relation Between Element Names and Type Names ................................................................. 13 UpperCamelCase Use in Elements Naming ...................................................................................... 13 Attributes Naming ....................................................................................................... 14 3.5.1. 3.6. UpperCamelCase Use in Types Naming ........................................................................................... 13 Elements Naming ....................................................................................................... 13 The Use of Attributes ......................................................................................................................... 23 Attributes Reusability ......................................................................................................................... 23 Attributes Namespace ....................................................................................................................... 23 Default or Fixed Attributes Values ..................................................................................................... 24 Versioning Rules ............................................................................................................. 25 5.1. Namespace Versioning .............................................................................................. 25 5.2. Locking YEFI XML Schemas ...................................................................................... 25 5.3. Versioning Mechanism ............................................................................................... 25 5.3.1. 5.3.2. Version 1.1 Namespaces versioning .................................................................................................................... 25 XML Xchema Versioning ................................................................................................................... 26 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 4 / 26 Copyright Notice This document is a working draft or committee draft and is copyright-protected by MCIT. While the reproduction of working drafts or committee drafts in any form for use by participants in the YEFI standards development process is permitted without prior permission from MCIT, neither this document nor any extract from it may be reproduced, stored or transmitted in any form for any other purpose without prior written permission from MCIT. Reproduction for sales purposes may be subject to royalty payments or a licensing agreement. Violators may be prosecuted. List of Tables Table 1: Document Structure ...................................................................................................... 5 Table 2: Rational ........................................................................................................................ 6 Table 3: Rules categories ........................................................................................................... 6 Table 4: Rules descriptions ........................................................................................................ 8 Table 5: Elements and attributes naming examples.................................................................. 11 List of Figures Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 5 / 26 1. Introduction This document defines the naming, design rules and guidelines that were applied by YEFI when developing the XML Schema instantiation of the Saudi e-Government. Since the YEFI standard employs standards from other organizations this document defines how those standards are used and incorporated. 1.1. Purpose The purpose of this document is to provide guidance for data analyst in applying the best practices for the design of XML schema. The document is targeting the data analysts and developers as the main audience. 1.2. Document Structure Introduction This section talks about the purpose and background of this document. Relationship to other standards This section references and makes use of other international open standards Naming Rules This section defines rules for naming schemas, elements, and attributes Design rules This section defines rules for designing schemas Namespace rules This section defines rules for namespace specifications Versioning rules This section defines rules for schema version control classes, Table 1: Document Structure 1.3. Terminology and Notations 1.3.1. Rationale The key words "SHALL", "SHALL NOT", "SHOULD","SHOULD NOT", and "MAY" when used in the definition of the rules SHOULD be interpreted, as follows: SHALL SHALL NOT SHOULD Version 1.1 The word shall is used to indicate mandatory requirements strictly to be followed in order to conform to the standard and from which no deviation is permitted (shall equals is required to). This phrase means that the definition is an absolute prohibition of the specification. The word should is used to indicate that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others; or that a certain course of action is preferred but not necessarily required; or that (in the negative form) a certain course of action is deprecated but not prohibited (should equals is recommended that). Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 6 / 26 SHOULD NOT MAY CAN This phrase means that the definition is prohibited. Only under particular circumstances and if strong reasons exist (that SHALL be accepted as valid), the definition can be ignored, but the full implications SHALL be understood and carefully weighed before choosing a different course. The word may is used to indicate a course of action permissible within the limits of the standard (may equals is permitted to). The word can is used for statements of possibility and capability, whether material, physical, or causal (can equals is able to). Table 2: Rational 1.3.2. Classification of Rules The rules defined in this document are classified into 14 categories described in the following table: Rule Category Prefix [YNR] [YLR] [YTR] [YER] [YAR] [YMR] [YGDR] [YTDR] [YSDR] [YCDR] [YEDR] [YADR] [YNSR] [YVR] Rule Category YEFI Common Naming Rules YEFI Language Rules YEFI Types Naming Rules YEFI Elements Naming Rules YEFI Attributes Naming Rules YEFI Metadata Naming Rules YEFI General Design Rules YEFI Types Design Rules YEFI Simpletypes Design Rules YEFI Complextypes Design Rules YEFI Elements Design Rules YEFI Attributes Design Rules YEFI Namespace Naming Rules YEFI Version Control Rules Table 3: Rules categories The following table contains a list of all rules and their descriptions: Rule [YNR 1] [YNR 2] [YNR 3] [YNR 4] [YNR 5] [YLR 1] [YLR 2] [YLR 3] [YLR 4] [YLR 5] Version 1.1 Description All elements and types (complex and simple) names SHALL be unique within the same name space and across all name spaces All elements, attributes and types SHOULD comply with the ObjectPropertyRepresentation scheme. A name SHOULD be represented in the singular form, unless the name is a plural Connecting words such as "and", "or", "of", and "the" SHALL NOT be used Only alphanumeric characters SHALL be used in element, type, and attribute names. English language SHOULD be used to name elements, types, and attributes. Arabic language MAY be used in case English language is inadequate. Only one language SHALL be used in an XML schema. The language used in the XML SHALL be declared using xml:lang root element attribute. Naming in English SHOULD comply with Oxford English Dictionary or relevant specialist literature. English XML schemas SHALL NOT refer to (include or import) any Arabic XML schema, and Arabic XML schemas SHALL NOT include or import any English XML Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 7 / 26 [YLR 6] [YLR 7] [YTR 1] [YTR 2] [YTR 3] [YER 1] [YER 2] [YAR 1] [YMR 1] [YMR 2] [YGDR 1] [YGDR 2] [YGDR 3] [YGDR 4] [YGDR 5] [YGDR 6] [YGDR 7] [YGDR 8] [YTDR 1] [YTDR 2] [YTDR 3] [YTDR 4] [YTDR 5] [YTDR 6] [YSDR 1] [YSDR 2] [YSDR 3] [YSDR 4] [YSDR 5] [YSDR 6] [YCDR 1] Version 1.1 schema. English XML schemas SHALL NOT declare an element using an Arabic type (simple or complex) defined in any Arabic XML schema, and Arabic XML schemas SHALL NOT declare an element using an English type defined in any English XML schema. English XML schemas SHALL NOT inherit an Arabic type (simple or complex) defined in any Arabic XML schema, and Arabic XML schemas SHALL inherit an English type defined in any English XML schema. An XML schema SHALL end the name of a simple type with the "Type" suffix. An XML schema SHALL end the name of a complex type with the "Structure" suffix. An XML schema SHALL name its simple and complex types using UpperCamelCase. The element name of an XML schema SHOULD be the same as the name of the type with the "Type" or "Structure" suffix omitted, if the element declaration and the type definition occur in the same schema. An XML schema SHALL name its elements using UpperCamelCase. An XML schema SHALL name its attributes using lowerCamelCase. An XML schema SHALL name its file in compliance with the naming <rootElementName>+"-v"+<M-n>+".xsd", where Mis the major version number and n is the minor version number. An XML schema SHALL name its metadata file in compliance with the naming scheme: <elementName>+"-v"+<M-n>+".xml" . An XML schema SHALL be defined in accordance with the W3C XML Schema Recommendation (version 1.0) of 2 May 2001: XML Schema Part 1: Structures and XML Schema Part 2: Data types. An XML schema SHALL comply with version 1.0 of the W3C XML Recommendation of 4 February 2004 Extensible Markup Language (XML) 1.1 (Third Edition). An XML schema SHALL use UTF-8 as an encoding scheme. An XML schema SHALL be assigned a namespace. An XML schema SHALL NOT use the "import" construct when referring to a sub - XML schema. The "import" construct SHALL be used only when referencing an XML Schema in an other namespace An XML schema SHALL NOT use the redefine construct. An XML schema SHALL NOT use the "notation" construct. An XML schema SHALL specify all its schemaLocation attributes with an absolute and valid URL that identifies the location of the referred YEFI XML schema module in the repository base. An XML schema SHOULD define all its simple and complex types as strongly as possible. An XML schema SHALL NOT define a new simple or complex type identical with a simple or complex type from another existing YEFI XML schema. An XML schema SHALL NOT reuse the built-in ur-types anyType and anySimpleType. An XML schema SHOULD use the built-in simple types anyURI orbase64Binary for handling binary content. An XML schema MAY use the attribute abstract in simple and complex type definitions. An XML schema SHOULD NOT limit type derivations, i.e. the attributes finalDefault and blockDefault in the root element schema as well as the attributes block and final in simple and complex type definitions SHOULD NOT be used. An XML schema SHALL NOT use the list construct. An XML schema SHALL NOT use the union construct. An XML schema SHOULD NOT limit the length of the simple built-in type string, unless a specific length has been commonly agreed upon. An XML schema SHOULD express code lists using the enumeration An XML schema SHOULD only express the values of enumeration constructs in lower case letters. An XML schema MAY express the values of enumeration constructs in both Arabic and English. An XML schema SHALL NOT use the whitespace and the other built-in simple types token and normalizedString. An XML schema SHOULD define a complex type by using the sequence and choice Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 8 / 26 [YCDR 2] [YCDR 3] [YCDR 4] [YCDR 5] [YCDR 6] [YEDR 1] [YEDR 2] [YEDR 3] [YEDR 4] [YEDR 5] [YADR 1] [YADR 2] [YADR 3] [YEDR 4] [YNSR 1] [YVR 1] [YVR 2] constructs. An XML Schema SHALL NOT define a complex type by using the all construct An XML schema MAY define a complex type by using the extension construct. An XML schema SHALL NOT define a complex type by using the restriction construct. An XML schema SHALL NOT use the empty content model (empty content). An XML schema SHALL NOT use the any construct. An XML schema SHALL NOT use the anyAttribute construct in the content model for a complex type. All complex and simple types defined in the XML schemas SHOULD be declared globally. The attribute "elementFormDefault" in the root element schema SHALL have the value "qualified". Substitution groups SHALL NOT be used. Empty elements SHALL NOT be allowed Elements in XML schemas SHALL NOT have any default or fixed values. Attributes SHOULD be used to define element metadata Attributes SHALL be locally declared Attributes SHALL NOT be assigned to a namespace Attributes in an XML schema SHALL NOT have any default or fixed values. Namespace representation SHALL use the following format: http://yefi.gov.sa/<schema context >/xml/schemas/version<version number> An XML Schema SHALL declare its version using version" attribute in XML schema root element. Approved and issued YEFI XML schemas SHALL NOT be changed, any required changes SHALL be done on a new schema version. Table 4: Rules descriptions Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 9 / 26 2. Relationship to Other Standards YEFI XML schema naming and design rules refer and make use of the following international standards: W3C - URI/URL W3C - XML Schema 1.0 Part 1 ISO - ISO11179-5 Specification and standardization of data elements -- Part 5: Naming and identification principles for data elements ISO - ISO1500-5 Core Components Technical Specification – Also known as ISO - ISO4217 - Currency Codes ISO - ISO639 - Language Codes MIME Media Type Code UN/CEFACT ATG2 Naming and Design Rules – NDR CIQ TC Specifications InfoStructureBase - http://isb.oio.dk/ Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 10 / 26 3. Naming Rules 3.1. Common Naming Rules 3.1.1. Unique Elements and Types Naming Rule [YNR 1] All elements and types (complex and simple) names SHALL be unique within the same name space and across all name spaces Whenever a new element or type is declared, it should be named uniquely within its schema, name spaces and across all name spaces. 3.1.2. Elements, Attributes and Types Naming Structure [YNR 2] All elements, attributes and types SHOULD comply with the ObjectPropertyRepresentation scheme. This structure follows the ebXML recommendations for naming, which are base upon the ISO 11179 standard "Information technology — Specification and standardization of data elements". This naming convention is backed by a broad international consensus. The object term in the ObjectPropertyRepresentation scheme describes the data object represented by the element and its type. If the element and its type occur in the context of an object or the object is unknown, the object term MAY be omitted. The property term in the ObjectPropertyRepresentation scheme describes the elementdistinguishing characteristic. The representation term in the ObjectPropertyRepresentation scheme describes the element category. Synonymous phrases in the representation and property terms should be removed from the property term and only maintained in the representation term. The table below shows examples of names under this naming scheme: Object Property Representation Communication Mode Code Element name CommunicationModeCode Code CountryCode Country Currency Exchange Rate CurrencyExchangeRate Location Type Code LocationTypeCode Transport Method Code TransportMethodCode Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 11 / 26 Street Name OrganizationRegistration Address Type StreetName Date OrganizationRegistrationDate Code AddressTypeCode Table 5: Elements and attributes naming examples Example: GuardianEmployementStatus 3.1.3. Singular Form of Names [YNR 3] A name SHOULD be represented in the singular form, unless the name is a plural For example, “Premises” is a plural name so it is used as is in “PremisesArabicName”. 3.1.4. Connecting Words [YNR 4] Connecting words such as “and”, “or”, “of”, and “the”SHALL NOT be used Since we are not using full sentences as element names, connecting words SHALL NOT be used in the element names. 3.1.5. Characters Permitted in Names [YNR 5] Only alphanumeric characters SHALL be used in element, type, and attribute names. Alphanumeric characters are A to Z, a to z, and 0 to 9. 3.2. Language Options 3.2.1. Arabic /English Naming Options [YLR 1] English language SHOULD be used to name elements, types, and attributes. Arabic language MAY be used in case English language is inadequate. In general, English is language usage is recommended for naming elements, types, and attributes. In case English language is inconvenient, Arabic language may be used. 3.2.2. XML Schema Language [YLR 2] Only one language SHALL be used in an XML schema. Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 12 / 26 For consistency reasons mixed language SHALL NOT be used in one XML schema. So the whole XML schema SHALL be in either Arabic or English language. 3.2.3. Declaring XML Schema Language [YLR 3] The language used in the XML SHALL be declared using xml:lang root element attribute. “xml:lang” root element attribute SHALL be given “ar” value in case XML schema elements names are in, and “en” SHALL be given to the attribute in case XML schema elements names are in English 3.2.4. XML Schema Language Verification [YLR 4] Naming in English SHOULD comply with Oxford English Dictionary or relevant specialist literature. Naming in a specific language SHOULD follow the syntactic and orthographical rules of that language, as specified in the relevant dictionaries and specialist literature. 3.2.5. XML Schema Cross References [YLR 5] English XML schemas SHALL NOT refer to (include or import) any Arabic XML schema, and Arabic XML schemas SHALL NOT include or import any English XML schema. In order to secure consistency between XML schemas, an XML schema SHALL NOT refer to (include or import) schemas in different language. 3.2.6. Reusing Types from Different Languages [YLR 6] English XML schemas SHALL NOT declare an element using an Arabic type (simple or complex) defined in any Arabic XML schema, and Arabic XML schemas SHALL NOT declare an element using an English type defined in any English XML schema. In order to secure consistency between XML schemas, an XML schema SHALL NOT reuse a type (simple or complex) defined in a different language. 3.2.7. Inheriting Types from Different Languages [YLR 7] English XML schemas SHALL NOT inherit an Arabic type (simple or complex) defined in any Arabic XML schema, and Arabic XML schemas SHALL inherit an English type defined in any English XML schema. Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 13 / 26 In order to secure consistency between XML schemas, an XML schema SHALL NOT iherit a type (simple or complex) defined in a different language. 3.3. Types (Simple and Complex) Naming 3.3.1. Simple Type Suffix [YTR 1] An XML schema SHALL end the name of a simple type with the “Type” suffix. The names of simple data types SHALL end with the text string “Type”. In the element name, this suffix is omitted. This way it is always possible to distinguish types from elements. 3.3.2. Complex Type Suffix [YTR 2] An XML schema SHALL end the name of a complex type with the “Structure” suffix. The names of complex data types SHALL end with the text string “Structure”. In the element name, this suffix is omitted. This way it is always possible to distinguish types from elements. 3.3.3. UpperCamelCase Use in Types Naming [YTR 3] An XML schema SHALL name its simple and complex types using UpperCamelCase. UpperCamelCase means that the name SHALL begin with an upper case letter, and the following new words SHALL begin with upper case letters as well, example: <element name="StreetBuildingIdentifier" type="cc:StreetBuildingIdentifierType"> 3.4. Elements Naming 3.4.1. The Relation Between Element Names and Type Names [YER 1] The element name of an XML schema SHOULD be the same as the name of the type with the “Type” or “Structure” suffix omitted, if the element declaration and the type definition occur in the same schema. The name of the element SHOULD directly reflect the name of the type used. This is done by deleting the “Type”/”Structure” suffix from the type name. This rule only applies to elements that have their type defined in the same schema. 3.4.2. UpperCamelCase Use in Elements Naming [YER 2] An XML schema SHALL name its elements using UpperCamelCase. Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 14 / 26 UpperCamelCase means that the name SHALL begin with an upper case letter, and the following new words SHALL begin with upper case letters as well, example: <xsd:element name="StreetBuildingIdentifier" type="cc:StreetBuildingIdentifierType"/> 3.5. Attributes Naming 3.5.1. lowerCamelCase Use [YAR 1] An XML schema SHALL name its attributes using lowerCamelCase. lowerCamelCase begins with a lower case letter, and every following word SHOULD begin with a capital letter. <xsd:complexType name="CustomerType"> <xsd:sequence> <xsd:element name="GivenName" type="prefix:GivenNameType"/> ... </xsd:sequence> <xsd:attribute name="customerIdentifier" type="prefix:CustomerIdentifierType"/> </xsd:complexType> 3.6. Naming of YEFI XML Schema and Metadata Files 3.6.1. Naming of A YEFI XML Schema File [YMR 1] An XML schema SHALL name its file in compliance with the naming <rootElementName>+”-v”+<M-n>+“.xsd”, where Mis the major version number and n is the minor version number. It is important to follow a specific naming pattern for the schemas and metadata files. This will enable users to identify the purpose and version of the file by looking at the name. Version format is “-vM-N”, where M is the major version and N is the minor version. Example: PersonProfileTypes-v1-0.xsd 3.6.2. Naming of Metadata File [YMR 2] An XML schema SHALL name its metadata file in compliance with the naming scheme: <elementName>+” – v ”+<M_n>+”_DSC”+“.xml” . This ensures that the metadata of an element can be identified by its file name. Example: ActivityDescription - v 1_0_DSC.xml Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 15 / 26 4. Design rules 4.1. General Schema Design Rules 4.1.1. Choice of Schema Language [YGDR 1] An XML schema SHALL be defined in accordance with the W3C XML Schema Recommendation (version 1.0) of 2 May 2001: XML Schema Part 1: Structures and XML Schema Part 2: Data types. It is important that interoperability is secured by ensuring that all public systems use one schema language. Otherwise syntax specific definitions of common components might not be reusable. 4.1.2. XML Version [YGDR 2] An XML schema SHALL comply with version 1.0 of the W3C XML Recommendation of 4 February 2004 Extensible Markup Language (XML) 1.1 (Third Edition). All XML schemas SHALL comply with XML version 1.0. It is not allowed to use the more recent XML version 1.1 for YEFI XML schemas, as there is a risk of lacking tool support. The XML version is stated in the XML declaration at the beginning of the schema: <?xml version="1.0" ... ?> </xsd:schema> ... </xsd:schema> 4.1.3. Choice of Encoding Scheme [YGDR 3] An XML schema SHALL use UTF-8 as an encoding scheme. All XML schemas SHALL use UTF-8 as encoding scheme. UTF-8 was chosen because it is broadly accepted and used in existing XML tools. UTF-8 supports both Arabic and English language character set. Please note that ISO Latin 1 (ISO-8859-6), which also supports Arabic special characters, SHALL not be used. UTF-8 encoding scheme is stated in the XML declaration at the beginning of the schema: <?xml version="1.0" encoding="UTF-8"?> </xsd:schema> ... </xsd:schema> Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 16 / 26 4.1.4. Namespace Assignment [YGDR 4] An XML schema SHALL be assigned a namespace. Namespaces form the backbone of the XML versioning strategy and are used both for versioning each XML schema as well as for dividing entire schema deliveries into separate domains. This use of namespaces clarifies the affiliation of the namespaces, and prevents unwanted name collisions. An XML schema is assigned a namespace by entering the targetNamespace attribute in the schema’s <xsd:schema …> root element. Example: <!-- edited with XMLSpy v2007 sp1 (http://www.altova.com) by Nassir Hassouneh (Devoteam ME) --> <xsd:schema xmlns="http://yefi.gov.sa/commercial/xml/schemas/version1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:cst="http://yefi.gov.sa/xml/schemas/version1.0" xmlns:prs="http://yefi.gov.sa/person/xml/schemas/version1.0" targetNamespace="http://yefi.gov.sa/commercial/xml/schemas/version1.0" elementFormDefault="qualified" attributeFormDefault="unqualified" version="0.1" id="CocType"> 4.1.5. Namespace Representation [YNSR 1] Namespace representation SHALL use the following format: http://yefi.gov.sa/<schema context >/xml/schemas/version<version number> Schema contexts can be: Commercial: which commercial related schemas belong to, such as commercial entity schema, GOSI schema, and MOMRA schema. Person: which person related schemas belong to, such as PersonProfile schema, PersonaContractTypes schema. Address: which address related schemas belong to. Financial: which financial related schemas such as ZakatCertificate belong to. Education: which education related schemas such as HighSchoolCertificate belong to. 4.1.6. Sub-Schema Referencing [YGDR 5] An XML schema SHALL NOT use the “import” construct when referring to a sub - XML schema. The “import” construct SHALL be used only when referencing an XML Schema in an other namespace When referring to a sub-schema under the same namespace as the schema from which is being referred, the include construct SHALL be used. If the sub-schema is under a different namespace, the import construct SHALL be used. Example: <xsd:import namespace="http://yefi.gov.sa/person/xml/schemas/version1.0" schemaLocation="PersonProfile-v1-0.xsd"/> <xsd:include schemaLocation="Gosi-v1-0.xsd"/> Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 17 / 26 <xsd:include schemaLocation="Coc-v1-0.xsd"/> The Use of “Redefine” in XML Schema’s Cross Referencing 4.1.7. [YGDR 6] An XML schema SHALL NOT use the redefine construct. The redefine construct includes a sub-schema in the same way as include, but unlike include it always makes it possible to redefine the content model of any type that already exists in the subschema without changing the name of the type. As the type name remains unchanged, schemas with a redefined version of this type can exist. This MAY have unwanted side effects in terms of ambiguity and inconsistency. 4.1.8. The use of notation [YGDR 7] An XML schema SHALL NOT use the “notation” construct. As this construct creates application specific constraints with instances, it SHALL NOT be used. The use of notations is a remnant from DTDs, which was tentatively transferred to XML Schema to achieve reverse compatibility, but failed to do so. 4.1.9. The Use of schemaLocation [YGDR 8] An XML schema SHALL specify all its schemaLocation attributes with an absolute and valid URL that identifies the location of the referred YEFI XML schema module in the repository base. This rule secures that the XML schema repository-base maintains the correct display of interdependence between XML schemas, and that the XML schema relations/validity is kept intact after transferring or copying the XML schemas from the repository base to an alternative location (e.g. a local development platform). The advantage of the absolute URL is that even the XML schemas that are localized outside a repository base will keep the correct references. 4.2. Type Definition Rules 4.2.1. Strong Data Types [YTDR 1] An XML schema SHOULD define all its simple and complex types as strongly as possible. One of the reasons to recommend the XML Schema approach is that it enables the use of strong data types, i.e. its is possible to describe the precise sample space of allowed values. This also enables validation of instances prior to further processing, which reduces the efforts for data validation in applications. Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 18 / 26 Whenever there are multiple ways of defining the same construct; the most simple and logical form SHOULD be chosen. The example below shows a “too loose” and presentation-oriented definition of the temperature scale “Celsius”. The sample space for Celsius has a 7 digit maximum, which MAY be inconvenient. <simpleType name="CelsiusType"> <restriction base="string"> <pattern value="[+-][0-9]{1,7}"/> </restriction> </simpleType> Celsius could be defined in a stronger and simpler way when based on a type with a logical background “Decimal”. There is a clear definition of the minimum value of Celsius “-273”, and that there is no maximum value. <simpleType name="CelsiusType"> <restriction base="decimal"> <minExclusive value="-273"/> </restriction> <simpleType> In the next example CivilRegistrationNumberType is defined as 10 digits from 0 to 9. <simpleType name="CivilRegistrationNumberType"> <restriction base="string"> <pattern value="[0-9]{10}"/> </restriction> </simpleType> This means that CivilRegistrationNumberType MAY have the value 1313131313. Since the four first digits represent DDMM as day and month of the birth date of the client. The value shows that the person to whom the civil registration number belongs is born in the 13th day of the 13th month. This is of course not possible since there is 12 months only, but the XML schema parser will not detect the error. The data type is too weak. Following is an attempt to make CivilRegistrationNumberType a stronger data type. <simpleType name="CivilRegistrationNumberType"> <restriction base="string"> <pattern value="(((0[1-9]|1[0-9]|2[0-9]|3[0-1])(01|03|05|07|08|10|12))| ((0[1-9]|1[0-9]|2[0-9]|30)(04|06|09|11))| ((0[1-9]|1[0-9]|2[0-9])(02)))[0-9]{6}"/> </restriction> </simpleType> By using the new regular term for CivilRegistrationNumberType only valid civil registration numbers will pass the parser, except for those containing the date 29.02 for non-leap years. In this case the type was made more complex, because there was no alternative. Making the type strong is more important than making it easy to read. Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 19 / 26 4.2.2. Renaming of an Existing Type [YTDR 2] An XML schema SHALL NOT define a new simple or complex type identical with a simple or complex type from another existing YEFI XML schema. In order to limit redundancy and to encourage reusing, XML schema SHALL NOT define a new type identical to an existing type. 4.2.3. The Use of anyType and anySimpleType [YTDR 3] An XML schema SHALL NOT reuse the built-in ur-types anyType and anySimpleType. As these types are the weakest data types available, they SHALL NOT be used. 4.2.4. Handling Binary Content [YTDR 4] An XML schema SHOULD use the built-in simple types anyURI orbase64Binary for handling binary content. As XML is character based, it is not possible to imbed unprocessed binary data in XML. This is helped by either referring to the document which is to be forwarded, or by formatting the document to the base64 format. <element name="ImageURI" type="xsd:anyURI"/> <element name="Image" type="xsd:base64Binary"/> An element or attribute SHOULD be defined to state the document type based on MimeType. 4.2.5. Abstract Types [YTDR 5] An XML schema MAY use the attribute abstract in simple and complex type definitions. If the modeling states a derivative structure, e.g. with a common data type that can not be instanced, the attribute abstract MAY be used. 4.2.6. Controlling Type Derivations [YTDR 6] An XML schema SHOULD NOT limit type derivations, i.e. the attributes finalDefault and blockDefault in the root element schema as well as the attributes block and final in simple and complex type definitions SHOULD NOT be used. As reusing is central in XML Schema, the possibilities for type derivations SHOULD NOT be limited. Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 20 / 26 4.3. Simple Type Definition Rules 4.3.1. The Use of List [YSDR 1] An XML schema SHALL NOT use the list construct. The use of list makes it possible to represent multiple values of a specific type within the textual value of one element or one attribute. i.e. an element or attribute is not linked to one unambiguous value, but to several possible values. As clarity is an important principle in XML schema definition, the list construct SHALL NOT be used. 4.3.2. The Use of Union [YSDR 2] An XML schema SHALL NOT use the union construct. union constitutes the combination of two or more data types within the same element. This makes it unclear which type is being used, and is therefore not allowed. 4.3.3. The Length of Strings [YSDR 3] An XML schema SHOULD NOT limit the length of the simple builtin type string, unless a specific length has been commonly agreed upon. This rule only allows limitation of the length of string for specific textual information, if a valid reason exists, such as statutes, directives or circulars, or if a specific string length has been agreed upon for this piece of information within a specific domain (the length of string can be limited by using the Length and maxLength facets). 4.3.4. Representation of Code Lists [YSDR 4] An XML schema SHOULD express code lists using the enumeration construct. If natural name token values exist, the enumeration construct SHOULD be used. An alternative solution is the limitation of typically positive, integers. Otherwise, and less frequently, pattern MAY be used. It is supposed to remain a code as well as a full textual representation. 4.3.5. Values in Enumerations [YSDR 5] An XML schema SHOULD only express the values of enumeration constructs in lower case letters. An XML schema MAY express the values of enumeration constructs in both Arabic and English. The values of enumeration SHOULD be un-spaced lower case letters, unless it expresses a value that is spelt with a capital letter (e.g. proper nouns). Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 21 / 26 If the type represents real data values, Arabic language SHOULD be used. More abstract codes SHOULD use English language. 4.3.6. The use of the Whitespace Facet and Related Types [YSDR 6] An XML schema SHALL NOT use the whitespace and the other built-in simple types token and normalizedString. One consequence of using whitespace, token and normalizedString is that the content of an XML instance is not clear by itself, but requires the presence of a schema to establish its full-canonized content. For this reason these constructions SHALL NOT be used. The content of an XML instance SHALL be unambiguous by itself. 4.4. Complex Type Definition rules 4.4.1. Construction of Complex Types [YCDR 1] An XML schema SHOULD define a complex type by using the sequence and choice constructs. An XML Schema SHALL NOT define a complex type by using the all construct New complex types SHOULD be defined by using sequence and choice, as these give a predictable structure. 4.4.2. Definition of Complex Types by Derivation [YCDR 2] An XML schema MAY define a complex type by using the extension construct. Based on the design principle that encourages simplicity, aggregation SHOULD be implemented using extension construct. 4.4.3. The Use of Restrictions in Complex Types [YCDR 3] An XML schema SHALL NOT define a complex type by using the restriction construct. The use of restriction construct in complex types is not allowed, because of the complications that MAY occur. Combining restriction with extension can easily create incomprehensible content models, which is contrary to the XML Schema principle that the definition of schemas SHALL be as simple and clear as possible. 4.4.4. The Use of Empty Content Model [YCDR 4] An XML schema SHALL NOT use the empty content model (empty content). Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 22 / 26 The empty content model complicates the verification of schemas. The Use of “Any” Construct 4.4.5. [YCDR 5] An XML schema SHALL NOT use the any construct. The use of “any” construct leads to ambiguous structure. 4.4.6. The Use of anyAttribute [YCDR 6] An XML schema SHALL NOT use the anyAttribute construct in the content model for a complex type. As content model SHOULD be clear, anyAttribute SHOULD not be used. 4.5. Element Declarations Rules 4.5.1. Global Element Declarations [YEDR 1] All complex and simple types defined in the XML schemas SHOULD be declared globally. In order to avoid duplication and to secure the highest possible level of reusability, all complex and simple types SHOULD be declared globally so that other XML schemas can use them to define their own elements or types. 4.5.2. Elements Namespace [YEDR 2] The attribute “elementFormDefault” in the root element schema SHALL have the value “qualified”. This attribute is set to “qualified” so that each element does not have to be prefixed with the XML schema NameSpace. 4.5.3. The use of Substitution Groups [YEDR 3] Substution groups SHALL NOT be used. In order to maintain consistency in using elements, “xsi:type” which allows substitution during the instantiation of an XML document SHALL NOT be used 4.5.4. Empty Elements [YEDR 4]Empty elements SHALL NOT be allowed Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 23 / 26 In order to maintain consistency and simplicity in the XML schemas, all elements that appear in an XML file should have a value, ether direct text in case of simple types and sub-elements in case of complex types. Hence the “xsd:nill” attribute which allows the element to have null value SHALL NOT be allowed. If it appeared that the element may not always have value during the element definition in an XML schema; the attribute “minoccur=0” SHALL be used, so that when there is no value for the element in the XML file, the whole element will be omitted. 4.5.5. Default or Fixed Elements Values [YEDR 5]Elements in XML schemas SHALL NOT have any default or fixed values. In order to avoid ambiguity, elements SHALL NOT have default values. So that the resulted XML file will not contain any pre-populated elements which might be difficulty to understand. 4.6. Rules for Attribute Declarations 4.6.1. The Use of Attributes [YADR 1] Attributes SHOULD be used to define element metadata In order to give a better understanding of what element value represents, element attributes SHOULD be used to describe an element value. For example an attribute can define the measurement unit for a weight element, as the following <weight measureUnit="kg">230</weight> 4.6.2. Attributes Reusability [YADR 2] Attributes SHALL be locally declared Attributes SHALL NOT be reused, as they are solely used for metadata that qualifies an element and its content. This corresponds to the regular use of attributes, and follows the general international recommendations. Therefore, all elements’ attributes SHALL be locally declared. 4.6.3. Attributes Namespace [YADR 3] Attributes SHALL NOT be assigned to a namespace Attributes SHALL NOT be assigned a namespace as they are defined locally in the element context, so the attribute “attributeFormDefault” SHALL be specified with the value “unqualified” in the schema root element definition. Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 24 / 26 4.6.4. Default or Fixed Attributes Values [YEDR 4]Attributes in an XML schema SHALL NOT have any default or fixed values. In order to avoid ambiguity, attributes SHALL NOT have default values so that the resulted XML file will not contain any pre-populated attributes which might be difficult to understand. Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 25 / 26 5. Versioning Rules 5.1. Namespace Versioning [YVR 1] An XML Schema SHALL declare its version using “version” attribute in XML schema root element. XML schema version SHALL be declared in the root element attribute “version”. This value should be updated whenever a new XML schema version is issued. 5.2. Locking YEFI XML Schemas [YVR 2] Approved and issued YEFI XML schemas SHALL NOT be changed, any required changes SHALL be done on a new schema version. In order to prevent ambiguity or doubts over versions, it is not allowed to change an approved schema in the DSC. This is a merely practical rule, as it secures identical content every time an approved schema is used. 5.3. Versioning Mechanism A new XML schema version is created as result of either major or minor change in the previous XML schema. Major and minor changes are defined as: Major change: a change in the XML schema structure or semantics that stops it from being backward compatible, so applications reference to this XML schema should be updated. Example: Updating XML schema elements, types (complex or simple type) or attributes structure. Deleting elements, types, or attributes. Minor change: which is adding new features to the XML schema without removing or changing the semantics of the existing schema structure, this change doesn’t require applications reference to this XML schema to be updated. Example: Defining new types which do not exist in any other schemas. 5.3.1. Namespaces versioning Schemas namespace SHALL have its version number concatenated to its definition. Example: http://yefi.gov.sa/<schema context >/xml/schemas/version<version number> where <version number> is the major namespace version number, this number is only updated as result of a MAJOR change to the XML schema. Example: http://yefi.gov.sa/commercial/xml/schemas/version1.0 Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER) e-Government Program (Yesser) XML Schema Naming and Design Rules Version 1.1- Page 26 / 26 The XML schema header attributes “targetnamespace”, which describes the namespace to which elements defined in the XML schema belong, and “xmlns”, which describes the default namespace to which the XML schema belongs, SHALL have the same value in all YEFI XML schemas. 5.3.2. XML Xchema Versioning XML schemas version number SHALL be maintained in the following positions: The “Version” XML schema header attribute Example: <xsd:schema xmlns="http://yefi.gov.sa/person/xml/schemas/version1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://yefi.gov.sa/person/xml/schemas/version1.0" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0" id="PersonProfileType"> In the XML schema physical file name in the form of <filename> + “v”+ <M-n> + “”.xml Where M is the MAJOR version number which should match the namespace version number and n is the MINOR version number which is incremented when minor changes are done to the XML schema. How XML Instances may Reference XML schemas? For XML instances to reference XML schemas the attribute “xsi:schemaLocation” can be used, Example: <ord:order xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation=" http://yefi.gov.sa/person/xml/schemas/version1.0/PersonProfile-v10.xsd"> <personname> …………………….. </personname> </ord:order> Version 1.1 Confidential e-Government Program (YESSER) This document (either in whole or in part) cannot be modified or reproduced without the prior written permission of the e-Government Program (YESSER)