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)