XML Schema Naming and Design Rules
XML Schema Naming and design rules
Version 1.1- Page 1 / 26
Versioning
Version / Date / Description of changes made0.1 / 01/01/2007 / Document Creation
1.0 / 27/05/2007 / Final
1.1 / 25/11/2007 / Update with government agencies’ comments
Document Validation
Version / Author / Review by / Date / StatusTable of Contents
1.Introduction......
1.1.Purpose......
1.2.Document Structure......
1.3.Terminology and Notations......
1.3.1.Rationale......
1.3.2.Classification of Rules......
2.Relationship to Other Standards......
3.Naming Rules......
3.1.Common Naming Rules......
3.1.1.Unique Elements and Types Naming Rule......
3.1.2.Elements, Attributes and Types Naming Structure......
3.1.3.Singular Form of Names......
3.1.4.Connecting Words......
3.1.5.Characters Permitted in Names......
3.2.Language Options......
3.2.1.Arabic /English Naming Options......
3.2.2.XML Schema Language......
3.2.3.Declaring XML Schema Language......
3.2.4.XML Schema Language Verification......
3.2.5.XML Schema Cross References......
3.2.6.Reusing Types from Different Languages......
3.2.7.Inheriting Types from Different Languages......
3.3.Types (Simple and Complex) Naming......
3.3.1.Simple Type Suffix......
3.3.2.Complex Type Suffix......
3.3.3.UpperCamelCase Use in Types Naming......
3.4.Elements Naming......
3.4.1.The Relation Between Element Names and Type Names......
3.4.2.UpperCamelCase Use in Elements Naming......
3.5.Attributes Naming......
3.5.1.lowerCamelCase Use......
3.6.Naming of YEFI XML Schema and Metadata Files......
3.6.1.Naming of A YEFI XML Schema File......
3.6.2.Naming of Metadata File......
4.Design rules......
4.1.General Schema Design Rules......
4.1.1.Choice of Schema Language......
4.1.2.XML Version......
4.1.3.Choice of Encoding Scheme......
4.1.4.Namespace Assignment......
4.1.5.Namespace Representation......
4.1.6.Sub-Schema Referencing......
4.1.7.The Use of “Redefine” in XML Schema’s Cross Referencing......
4.1.8.The use of notation
4.1.9.The Use of schemaLocation......
4.2.Type Definition Rules......
4.2.1.Strong Data Types......
4.2.2.Renaming of an Existing Type......
4.2.3.The Use of anyType and anySimpleType......
4.2.4.Handling Binary Content......
4.2.5.Abstract Types......
4.2.6.Controlling Type Derivations......
4.3.Simple Type Definition Rules......
4.3.1.The Use of List
4.3.2.The Use of Union
4.3.3.The Length of Strings
4.3.4.Representation of Code Lists......
4.3.5.Values in Enumerations......
4.3.6.The use of the Whitespace Facet and Related Types......
4.4.Complex Type Definition rules......
4.4.1.Construction of Complex Types......
4.4.2.Definition of Complex Types by Derivation......
4.4.3.The Use of Restrictions in Complex Types......
4.4.4.The Use of Empty Content Model......
4.4.5.The Use of “Any” Construct......
4.4.6.The Use of anyAttribute......
4.5.Element Declarations Rules......
4.5.1.Global Element Declarations......
4.5.2.Elements Namespace......
4.5.3.The use of Substitution Groups......
4.5.4.Empty Elements......
4.5.5.Default or Fixed Elements Values......
4.6.Rules for Attribute Declarations......
4.6.1.The Use of Attributes......
4.6.2.Attributes Reusability......
4.6.3.Attributes Namespace......
4.6.4.Default or Fixed Attributes Values......
5.Versioning Rules......
5.1.Namespace Versioning......
5.2.Locking YEFI XML Schemas......
5.3.Versioning Mechanism......
5.3.1.Namespaces versioning......
5.3.2.XML Xchema Versioning......
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
Table 2: Rational
Table 3: Rules categories
Table 4: Rules descriptions
Table 5: Elements and attributes naming examples
List of Figures
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 classes, 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
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 / 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).SHALL NOT / This phrase means that the definition is an absolute prohibition of thespecification.
SHOULD / 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).
SHOULD NOT / This phrase means that the definition is prohibited. Only under particularcircumstances 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.
MAY / The word may is used to indicate a course of action permissible within the limits of the standard (may equals is permitted to).
CAN / 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 / Rule Category[YNR] / YEFI Common Naming Rules
[YLR] / YEFI Language Rules
[YTR] / YEFI Types Naming Rules
[YER] / YEFI Elements Naming Rules
[YAR] / YEFI Attributes Naming Rules
[YMR] / YEFI Metadata Naming Rules
[YGDR] / YEFI General Design Rules
[YTDR] / YEFI Types Design Rules
[YSDR] / YEFI Simpletypes Design Rules
[YCDR] / YEFI Complextypes Design Rules
[YEDR] / YEFI Elements Design Rules
[YADR] / YEFI Attributes Design Rules
[YNSR] / YEFI Namespace Naming Rules
[YVR] / YEFI Version Control Rules
Table 3: Rules categories
The following table contains a list of all rules and their descriptions:
Rule / Description[YNR 1] / All elements and types (complex and simple) names SHALL be unique within the same name space and across all name spaces
[YNR 2] / All elements, attributes and types SHOULD comply with the ObjectPropertyRepresentation scheme.
[YNR 3] / A name SHOULD be represented in the singular form, unless the name is a plural
[YNR 4] / Connecting words such as "and", "or", "of", and "the"SHALL NOT be used
[YNR 5] / Only alphanumeric characters SHALL be used in element, type, and attribute names.
[YLR 1] / English language SHOULD be used to name elements, types, and attributes. Arabic language MAY be used in case English language is inadequate.
[YLR 2] / Only one language SHALL be used in an XML schema.
[YLR 3] / The language used in the XML SHALL be declared using xml:lang root element attribute.
[YLR 4] / Naming in English SHOULD comply with Oxford English Dictionary or relevant specialist literature.
[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.
[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.
[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.
[YTR 1] / An XML schema SHALL end the name of a simple type with the "Type" suffix.
[YTR 2] / An XML schema SHALL end the name of a complex type with the "Structure" suffix.
[YTR 3] / An XML schema SHALL name its simple and complex types using UpperCamelCase.
[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.
[YER 2] / An XML schema SHALL name its elements using UpperCamelCase.
[YAR 1] / An XML schema SHALL name its attributes using lowerCamelCase.
[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.
[YMR 2] / An XML schema SHALL name its metadata file in compliance with the naming scheme: <elementName>+"-v"+<M-n>+".xml" .
[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.
[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).
[YGDR 3] / An XML schema SHALL use UTF-8 as an encoding scheme.
[YGDR 4] / An XML schema SHALL be assigned a namespace.
[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
[YGDR 6] / An XML schema SHALL NOT use the redefine construct.
[YGDR 7] / An XML schema SHALL NOT use the "notation" construct.
[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.
[YTDR 1] / An XML schema SHOULD define all its simple and complex types as strongly as possible.
[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.
[YTDR 3] / An XML schema SHALL NOT reuse the built-in ur-types anyType and anySimpleType.
[YTDR 4] / An XML schema SHOULD use the built-in simple types anyURI orbase64Binary for handling binary content.
[YTDR 5] / An XML schema MAY use the attribute abstract in simple and complex type definitions.
[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.
[YSDR 1] / An XML schema SHALL NOT use the list construct.
[YSDR 2] / An XML schema SHALL NOT use the union construct.
[YSDR 3] / An XML schema SHOULD NOT limit the length of the simple built-in type string, unless a specific length has been commonly agreed upon.
[YSDR 4] / An XML schema SHOULD express code lists using the enumeration
[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.
[YSDR 6] / An XML schema SHALL NOT use the whitespace and the other built-in simple types token and normalizedString.
[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
[YCDR 2] / An XML schema MAY define a complex type by using the extension construct.
[YCDR 3] / An XML schema SHALL NOT define a complex type by using the restriction construct.
[YCDR 4] / An XML schema SHALL NOT use the empty content model (empty content).
[YCDR 5] / An XML schema SHALL NOT use the any construct.
[YCDR 6] / An XML schema SHALL NOT use the anyAttribute construct in the content model for a complex type.
[YEDR 1] / All complex and simple types defined in the XML schemas SHOULD be declared globally.
[YEDR 2] / The attribute "elementFormDefault" in the root element schema SHALL have the value "qualified".
[YEDR 3] / Substitution groups SHALL NOT be used.
[YEDR 4] / Empty elements SHALL NOT be allowed
[YEDR 5] / Elements in XML schemas SHALL NOT have any default or fixed values.
[YADR 1] / Attributes SHOULD be used to define element metadata
[YADR 2] / Attributes SHALL be locally declared
[YADR 3] / Attributes SHALL NOT be assigned to a namespace
[YEDR 4] / Attributes in an XML schema SHALL NOT have any default or fixed values.
[YNSR 1] / Namespace representation SHALL use the following format: context >/xml/schemas/version<version number>
[YVR 1] / An XML Schema SHALL declare its version using version" attribute in XML schema root element.
[YVR 2] / 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
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 -
3.Naming Rules
3.1.CommonNaming 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 element-distinguishing 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 / Element nameCommunication / Mode / Code / CommunicationModeCode
Country / Code / CountryCode
Currency / Exchange / Rate / CurrencyExchangeRate
Location / Type / Code / LocationTypeCode
Transport / Method / Code / TransportMethodCode
Street / Name / StreetName
OrganizationRegistration / Date / OrganizationRegistrationDate
Address / Type / 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.
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.