federal xml naming and design rules and guidelines

Federal XML Naming and Design Rules and Guidelines

Mark Crawford

P A G E 2

Agenda

• Purpose• Scope• Audience• Sources• Terminology• Modularity• Namespaces• Versioning• Content• Next Steps

P A G E 3

The purpose of this document is to provide a set of rules and guidelines that will enable development of:

• a flexible federal modularity model that defines the structure for creating interoperable schema and schema modules

• a clearly defined namespace scheme that ensures consistency across Agencies

• a versioning scheme that will support consistency in versioning of government schema

• a Federal canonical schema for base Data Types • specific NDR’s by government agencies or communities of

practice that build on this document• a reference to use for a mapping of different agency NDR’s to

each other

P A G E 4

The purpose of this document is to provide a set of rules and guidelines that will enable development of: (cont’d)

• consistent, reusable XML components that may be made available for reuse such as:– Schema– Schema Modules such as reusable code lists and identifier lists– Simple and Complex Types– Elements– Attributes

• a set of tools to facilitate ease of development, validation, and interoperability

P A G E 5

Scope

This Federal XML Naming and Design Rules and Guidelines document is intended for use by all Executive Branch Departments and Agencies

(hereinafter referred to as Agency) that employ XML, including all commercial and government off-the-shelf

XML related product implementations. It should be used by all contractors and vendors doing XML

development work on behalf of Departments and Agencies. Agencies developing specific XML Naming

and Design Rules and Guidelines should use this document as the baseline for those efforts.

P A G E 6

Audience (not yet vetted)

• Developers of Federal Enterprise Schema• Government organizations looking for guidance• Agency level developers interested in fostering interoperability• Private sector organizations who wish to track government

efforts

P A G E 7

Sources

• Voluntary Consensus Standards Bodies– OASIS Universal Business Language Technical Committee– UN/CEFACT

• Government NDRs– Department of the Navy– Environmental Protection Agency– Global Justice

P A G E 8

Terminology

• The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in Internet Engineering Task Force (IETF) Request for Comments (RFC) 2119. Non-capitalized forms of these words are used in the regular English sense.

P A G E 9

Modularity is key to reuse

• Modularity Model Must Be:– Structured– Flexible– Consistent

P A G E 10

Modularity

• Three Approaches under consideration– Monolithic

• Single Namespace• One schema per process, idea, or information requirement• No imports

– Reuse• Root Schema with all content imported• Unique namespace for each schema• Common modules for reusables (data elements and generic data

elements), standard data types, code lists, identifier lists– Unique

• Root Schema with all content imported• Unique namespace for each schema• Unique schema modules for each data element i.e. an address would be a

stand alone schema in a unique namespace

P A G E 11

Modularity Model – Reuse Approach

Schema ModuleType

File

Namespace

W3C XML Schema

1

1

1

1 ..*

Root Schema Module

Internal Schema Module

Complex DataReusable Modules

Unqualified Data Type Module

Qualified Data Type Module

Identifier List Module

Code List Module

Other Standards Body Modules

Simple Data Module

P A G E 12

Modularity Model – Root Schema

• A Root Schema is a single concept like an Order, Invoice, OMB 300, SF12, Document, Book, or some other logical grouping of information.

Government and Source Standards Body Schema

Root Schema Module

Internal Schema Module(s)

Message Assembly –

Single Namespace 0..*

1

Include

Import

External Standards Body Reusable Entities Schema

Module

Other External Reusable Entities Schema Module

0..*

0..*

Import

Import

0..*

External Schema Modules – Individual Namespaces

P A G E 13

Modularity Model – Importing Data Types From Standards

• UBL and other standards bodies are converging on UN/CEFACT Data Type schema modules

• UBL and other standards bodies are converging on single approach to code lists

Root Schema Module

Internal Schema Module(s)

Message Assembly –

Single Namespace

External Schema Modules – Individual Namespaces

Source Standards Unqualified DataType

Schema Module

Code List (CL) Schema Module(s)

0..*

0..*Identifier List (IL) Schema Module(s)

1Source Standards Qualified DataType

Schema Module

1

1

Include

Import

External Standards Body Reusable Entities Schema

Module

Other External Reusable Entities Schema Module

0..*

0..*

Import

Import

0..* 0..*

0..*

0..*

1

P A G E 14

What Data Types

•Amount (xsd:decimal)

•Binary Object (xsd:base64Binary)– Graphic– Sound– Video

•Code (xsd:normalizedString)

•Date Time (xsd:dateTime)– Date (xsd:date)– Time (xsd:time)

•Identifier (xsd:normalizedString)

•Indicator (xsd:boolean)

•Measure (xsd:decimal)– Value– Rate– Percent

•Numeric (xsd:decimal)

•Quantity xsd:decimal)

•Text (xsd:string)– Name (xsd:string)

P A G E 15

A Data Type Example

<xsd:complexType name="AmountType"><xsd:annotation> <xsd:documentation>

<Component> <ComponentType>DT</ComponentType> <DictionaryEntryName>Amount. Type<:DictionaryEntryName> <Definition>A number of monetary units specified in a currency where the unit of the

currency is explicit or implied.<Definition> <RepresentationTerm>Amount</RepresentationTerm> </Component>

</xsd:documentation></xsd:annotation>

<xsd:simpleContent><xsd:restriction base="cct:AmountType"><xsd:attribute name="amountCurrencyID" type="xsd:normalizedString" use="required"/><xsd:attribute name="amountCurrencyCodeListVersionID" type="xsd:normalizedString"

use="optional"/></xsd:restriction>

</xsd:simpleContent></xsd:complexType>

P A G E 16

Modularity Model – Introducing the Federal Common Schema

• Reusing the Standards Body Schema

• Creating 4 Federal Enterprise Schema– Unqualified DataTypes

– Qualified DataTypes

– Complex Data Element Reusables

• Address

• Person

• Organization

– Simple Data Element Reusables

• First Name

• Last Name

• Birthdate

• Code and Identifier Lists

Root Schema Module

Internal Schema Module(s)

Message Assembly –

Single Namespace

External Schema Modules – Individual Namespaces

Federal Simple Data Elements

Schema Module

FederalComplex Data

Elements Schema Module

Federal Unqualified DataTypes (FUDT) Schema Module

Federal Qualified DataTypes (FQDT)

Schema Module

Source Standards Unqualified DataType

Schema Module

Code List (CL) Schema

Module(s)

0..*

0..*

0..*

1

0..*

1

1

Identifier List (IL) Schema

Module(s)

1

1

0..*

0..* 0..*

1 1

1

4..*

1

Source Standards Qualified DataType

Schema Module1

0..*

0..* 0..*0..*

0..*

1

Include

Import

External Standards Body Reusable Entities Schema

Module

Other External Reusable Entities Schema Module

0..*

0..*

Import

Import

P A G E 17

Flexibility for Everyone

• Government organizations and initiatives can leverage standards body and federal schema

• Organizations can create organizationally unique– Qualified and unqualified

Data Types– Complex Data Element

reusables– Simple data element

reusables– Code Lists– Identifier Lists

Root Schema Module

Internal Schema Module(s)

Message Assembly –

Single Namespace

External Schema Modules – Individual Namespaces

Federal Simple Data Elements

Schema Module

FederalComplex Data

Elements Schema Module

Federal Unqualified DataTypes (FUDT) Schema Module

Federal Qualified DataTypes (FQDT)

Schema Module

Source Standards Unqualified DataType

Schema Module

Code List (CL) Schema

Module(s)

0..1

0..*

0..*

0..*

1

0..*

1

1

1Agency Supplemental Unqualified DataTypes

(ASUDT) Schema Module

Agency Supplemental Qualified DataTypes (ASQDT) Schema

Module

Identifier List (IL) Schema

Module(s)

AgencyComplex Data

Elements Schema Module

Agency Simple Data Elements

Schema Module

1

1

1

0..*

0..*

0..*

0..*

1

11

0..*

1

0..1

0..10..1

0..1

1

0..1

4..*

1 1

1

1

Source Standards Qualified DataType

Schema Module1

0..*

0..* 0..*0..*

0..*

1

Include

Import

External Standards Body Reusable Entities Schema

Module

Other External Reusable Entities Schema Module

0..*

0..*

Import

Import

Note: relationships between shcema modules in different namespaces

are xsd:import

P A G E 18

Namespaces

• Initial Recommendation –Mandate hierarchical URN scheme• Consensus – SHOULD use URN and hierarchy scheme. MAY

use URL hierarchy scheme

P A G E 19

Namespaces

• 1st Level Domain – NID of US• Second Level Domain – Organization Hierarchy. In this case

GOV• Third Level Domain – Specific Government Hierarchy – EPA,

OMB, DoD, Treasury• Fourth Level Domain – Agency Level Hierarchy – USN, USAF,

IRS, FMS• Fifth Level Domain – Resource Type – Schema or Other as

Identified• Sixth Level Domain – Resource Status• Seventh Level Domain – Resource Name

P A G E 20

Versioning

• Consensus on:– <name>-<major >.<non-zero>[.<revision>]

• To be determined:– Minor versioning of namespaces– Use of namespaces for schema location– URN or URL for schema location

P A G E 21

Schema Content

• Modularity, Namespaces and Version is important, But:

What about the Schema Content?

P A G E 22

Source: ISO 11179

Schema is All About Data

Data Element (Type)

Object Class

Property

Representation

Attribute(Type)

Entity(Type)

Generic Data Element

Data ElementConcept

Entity Relationship Diagram

Data Model

ISO 11179 Data Element

Classification Structure

Source: ISO 11179

Data Concept

P A G E 23

Transforming Data to XML

Object Class

Property

Representation

Attribute(Type)

Entity(Type)

Entity Relationship Diagram

Data Model

ISO 11179 Data Element

Classification Structure

Global Element/xsd:complexType

Global Element/xsd:complexType

xsd:complexType or

xsd:simpleType

Simple XSD Transformation

P A G E 24

Handling Class Associations

-Person. First Name. Text-Person. Middle Name. Text-Person. Last Name. Text-Person. Birth Date. Date-Person. Mailing. Address

Person Complex Data Element-Address. Number. Text-Address. Street Name. Text-Address. City. Text-Address. State. Text-Address. Country Identification. Identiifier-Address. Postal Code. Code

Address Complex Data Element

• An associated class is treated as a simple data element with a global element declaration and complex type definition

P A G E 25

Next Steps

• Continue to work through comments to first draft– Finalize modularity– Finalize versioning– Finalize namespace

• Flesh out content