[XGC]


Metanode Organized Prototype Hierarchy Specification (MORPH)

Version 0.9b, March 7, 2006

This Version:
http://www.gamexml.org/Specs/MORPH/
Editors:
Duncan Suttles, Magnetar Games
Reggie Chen, Magnetar Games
Miranda Paugh, Magnetar Games
Aleksandar Mandic, Magnetar Games

Abstract

MORPH (Metanode ORganized Prototype Hierarchy) is a modularized language for describing meta-programmable, hierarchically organized information models in XML. MORPH is an extension of the Object Model Template (OMT) defined as a component of the U.S. Department of Defense High Level Architecture (HLA) for Distributed Interactive Simulations (DIS).

Status of this Document

This is a working draft that is under review by Magnetar Games. It is currently being edited and all portions are subject to change.

Revision History:


Table of Contents

  1. 1. Overview
    1. 1.1. Scope
    2. 1.2. Purpose
    3. 1.3. Background
      1. 1.3.1. High Level Architecture
      2. 1.3.2. Domain Specific Language
      3. 1.3.3. Meta-Object Facility and Model Driven Architecture
      4. 1.3.4. Early-Bound Schema
      5. 1.3.5. Rationale
  2. 2. References
  3. 3. Definitions, Abbreviations, Acronyms, and Conventions
    1. 3.1. Abbreviations and Acronyms
  4. 4. MORPH Concepts
    1. 4.1. Domain Language
      1. 4.1.1. MORPH-DSL
    2. 4.2. Object Model
    3. 4.3. Prototype Pattern
    4. 4.4. Metanode Organization
    5. 4.5. MORPH Development Process
    6. 4.6. General Overview
    7. 4.7. Development Process Example: RTS DSL
  5. 5. MORPH Components
    1. 5.1. Conventions
      1. 5.1.1. hla: attributes
      2. 5.1.2. doc:nodetype
      3. 5.1.3. Names
      4. 5.1.4. Duplicate Names
      5. 5.1.5. Legend
    2. 5.2. Schema Root
    3. 5.3. Product Root
    4. 5.4. Redefine
    5. 5.5. Data Types
      1. 5.5.1. Basic Type
      2. 5.5.2. Simple Type
      3. 5.5.3. Enumerated Type
      4. 5.5.4. Array Type
      5. 5.5.5. Fixed Record Type
      6. 5.5.6. Variant Record Type
    6. 5.6. Tables
      1. 5.6.1. Dimensions
      2. 5.6.2. Time
      3. 5.6.3. Synchronization
      4. 5.6.4. Transportation
      5. 5.6.5. Switches
      6. 5.6.6. User-Supplied Tags
      7. 5.6.7. Notes
      8. 5.6.8. Lexicon
    7. 5.7. Object Classes
      1. 5.7.1. Category
      2. 5.7.2. Class
      3. 5.7.3. AttributeOverride
      4. 5.7.4. UserAttribute
      5. 5.7.5. Event
    8. 5.8. Attributes and Parameters
      1. 5.8.1. Simple Types
      2. 5.8.2. Complex Types
    9. 5.9. Events and Scripts
      1. 5.9.1. Event
      2. 5.9.2. Script
    10. 5.10. Prototypes
      1. 5.10.1. Category
      2. 5.10.2. Class
      3. 5.10.3. UserAttribute
      4. 5.10.4. Event
    11. 5.11. Hierarchies
      1. 5.11.1. Category
      2. 5.11.2. Reference
    12. 5.12. Interactions
      1. 5.12.1. Category
      2. 5.12.2. Interaction
    13. 5.13. Interface
      1. 5.13.1. Category
      2. 5.13.2. Interaction
      3. 5.13.3. Response
      4. 5.13.4. Error
    14. 5.14. Instances
      1. 5.14.1. Category
      2. 5.14.2. Instance
      3. 5.14.3. UserAttribute
      4. 5.14.4. Event
    15. 5.15. Keys
    16. 5.16. Documentation
    17. 5.17. Specification Documentation
      1. 5.17.1. Editors
      2. 5.17.2. Copyright
      3. 5.17.3. Abstract
      4. 5.17.4. Status
      5. 5.17.5. Keywords
      6. 5.17.6. Section
      7. 5.17.7. Appendix

Appendices

  1. A. Related Files

1. Overview

1.1. Scope

MORPH is an information modeling paradigm based on the IEEE 1516.2-2000 standard for the Object Model Template (OMT), the object modeling standard for High Level Architecture (HLA) proposed by the US Department of Defense.

MORPH methodology produces an information model, encapsulated as a Domain Specific Language (DSL), which describe a family of products in CEB (Containment Early Bound) XML format. It also uses Schema Adjunct, a form of XML Schema annotation proposed by TIBCO, to facilitate special applications for MORPH processors.

This document defines and includes:

1.2. Purpose

Metanode Organized Prototype Hierarchy (MORPH) is a language for defining Domain Specific Languages (DSL) in XML. The key benefits of MORPH are support for:

MORPH extends HLA Object Model Template (OMT) by adding:

1.3. Background

1.3.1. High Level Architecture

The foundation of MORPH is the High Level Architecture (HLA). HLA is a general-purpose architecture developed by the US Department of Defense (DoD) to promote interoperability of simulations and the re-use of simulation components. HLA has been accepted as both OMG and IEEE standards. Key components of HLA are:

The Object Model Template (OMT) provides a standardized framework for describing HLA object models. It defines the format and syntax (but not content) of HLA object models. OMT is a meta-model for all FOMs. Its main components are:

1.3.2. Domain Specific Language

A Domain Specific Language (DSL) is a programming language for a specific domain or a problem. A DSL provides abstractions, notations, and semantics to express and encapsulate a particular domain or a problem. The key characteristics of DSLs are domain-focused expressive power and specific abstractions. A good definition of DSLs can be found at http://compose.labri.fr/documentation/dsl/dsl_overview.php3#when.

The concept of a Domain Specific Language (DSL) is central to the evolution of XML standards promoted by the World Wide Web Consortium at http://www.w3.org. Specifications such as Scalable Vector Graphics (SVG) and Synchronized Multimedia Integration Language (SMIL) define engines which have the following generic characteristics:

MORPH extends OMT by organizing a DSL through mapping interactions to commands and events.

1.3.3. Meta-Object Facility and Model Driven Architecture

The Object Management Group (OMG) Meta-Object Facility (MOF) is a generic framework for representation of meta-information in technology neutral meta-models. Meta-information is information describing other information and a meta-model is a model that describes other models.

MOF, Unified Modeling Language (UML), and XML Metadata Interchange (XMI) form a foundation for OMG's Model Driven Architecture (MDA). MDA is a four-layer metadata architecture, with elements in one layer representing the elements in the next layer down. The layers are, from top down:

For example:

MORPH is contained at the meta-model layer of the classic Four Layer Metadata Architecture. MORPH is parallel to UML meta-model.

1.3.4. Early-Bound Schema

There are two well-known kinds of mapping between a model expressed in an instance document and a schema: late binding and early binding. The EXPRESS community defines an early-bound schema as a schema that can be used for only a particular domain or application. It exposes domain-specific constructs. The other, more generic schema binding, is the late-binding schema, which can be used for multiple domains. In such a case, the instances of such schemas use the MORPH metadata which is independent of domains to express runtime instances of a particular domain.

One example of a late-bound information model is HLA's Object Model Template (OMT). OMT treats domain concepts such as "Unit" and "Structure" as elements of "Object Class," rather than first-class concepts. Unlike MORPH, which is designed to create models for product-line application, OMT does not define the product specification. Tools like RTI directly consume the late-bound model. If OMT had a product document that derived from the late-bound model, it would resemble:

<objectClass name="Unit">
<objattr name="Tank"/>
(...)
</objectClass>
<objectClass name="Structure">
(...)
</objectClass>

MORPH presents the above scenario as a schema:

<xs:element name="Unit" minOccurs="0" maxOccurs="unbounded">
(...)
</xs:element>
<xs:element name="Structure" minOccurs="0" maxOccurs="unbounded">
(...)
</xs:element>

The instance would then be an early-bound model:

<Unit name="Tank" ... />
<Unit name="Fighter" ... />
<Structure name="Base" ... />

It is apparent that using a late-bound model results in instances that are very verbose and awkward. Yet a late-bound approach facilitates usage of the same schema for multiple domains. In MORPH, the late-bound model is an XML schema, which allows for early-bound XML instances. HLA OMT models can be automatically translated into MORPH domain schemas.

1.3.5. Rationale

The IEEE Standard for Object Model Template notes that OMT is narrowly focused on "requirements and capabilities for federate information exchange."

The rationale underlying MORPH is to extend the scope of OMT to support design and implementation of federates through addressing these important areas:

2. References

1. Scott Vorthmann, Lee Buck TIBCO Schema Adjunct Framework, Draft Specification 24 February 2000, http://www.extensibility.com/saf/spec/, www.extensibility.com

2. Step/EXPRESS, Technology Reports: STEP/EXPRESS and XML, March 29, 2002,http://xml.coverpages.org/stepExpressXML.html

3. OMG Model Driven Architecture, Object Managment Group, http://www.omg.org/mda/

4. High Level Architecture (HLA), U.S. Department of Defense, Defense Modeling and Simulations Office, https://www.dmso.mil/public/transition/hla/

5. Domain Engineering and Product Line, Carnegie Mellon Software Engineering Institute, http://www.sei.cmu.edu/domain-engineering/domain_engineering.html, Dec 16, 2002.

3. Definitions, Abbreviations, Acronyms, and Conventions

3.1. Abbreviations and Acronyms

The following abbreviations and acronyms pertain to this standard.

API
Application Programming Interface
DIS
Distributed Interactive Simulations
DSL
Domain Specific Language
DoD
U.S. Department of Defense
FOM
Federation Object Model
HLA
High Level Architecture
MDA
Model Driven Architecture
mod
An unofficial variant of the game created by fans
MOF
Meta-Object Facility
MORPH
Metanode Organized Prototype Hierarchy
OMG
Object Management Group
OMT
Object Model Template
OOP
object oriented programming
RTI
Run-Time Infrastructure
SOM
Simulation Object Model
XMI
XML Metadata Interchange
XML
Extensible Markup Language

4. MORPH Concepts

4.1. Domain Language

A Domain Specific Language (DSL) describes an information model and an interface of commands and events. A DSL is a means to describe and generate members of a family of programs in the domain. The World Wide Web Consortium promotes XML-based DSL specifications. A well-developed example is Scalable Vector Graphics (SVG), which has been implemented by many SVG "Engines."

4.1.1. MORPH-DSL

A MORPH-DSL extends the Object Model Template (OMT) information-modeling paradigm to cover creation of complete DSLs. The design of MORPH-DSL is encapsulated in five related specifications.

The following entity-relationship diagram shows the relationships among the specifications and documents mentioned above. The MORPH-DSL late-bound instance (myDSL.xml) is governed by the file HLA-MORPH.xsd. This instance document is the input for the MORPH-DSL generator. As with applying XSLT to generate HTML pages, a DSL specification in XML Schema format is produced by applying the MORPH specification template to the underlying product description.

4.2. Object Model

The MORPH object model is a refinement of the Object Model Template (OMT). The core components of that model are Datatypes, Objects, Interactions, and Dimensions.

4.3. Prototype Pattern

The idea behind the prototype pattern is to make use of specific instances of classes called "prototypes" to represent special categories of the classes. In an object-oriented programming language, one could simply use inheritance to create sub-classes with the correct properties. For a larger system, however, the number of these sub-classes and their interdependencies grows very rapidly. Such an object-oriented (OO) system tends to become resistant to change. For example, let us suppose that a Truck is a class in a system. If we need special types of the class, called "5-Ton-Truck" and "2-Ton-Truck," then we can extend them as sub-classes of the Truck. But doing so has the following drawbacks:

  1. The number of classes in the model hierarchy increases. For a large-scale system like a military simulation, this increase can be so dramatic as to retard the comprehensibility of the system.
  2. The model hierarchy itself is static. That is, it is not possible to introduce new variations of base classes at runtime.

The prototype pattern models objects based on their common properties. For example, all entities in a particular game may possess specific properties such as health, movement speed, and shields. In an object-oriented programming language, these properties would become members of a class with specific values. Using the prototype pattern, these values are then initialized based on a prototype whenever a new object instance is created.

MORPH models the object itself by declaring what properties it has. Then those properties are given values in various prototype declarations. The properties could be either "instance attributes" or "global attributes." Like class variables in C++, "global attributes" are the same for each instance of a prototype class, while instance attribute vary from instance to instance. Finally, an instance is created using a prototype, which may in turn have its own unique instance property values.

To make an analogy between MORPH and a typical object-oriented programming language, consider MORPH meta-models as classes, the MORPH prototypes as implicit sub-classes which initialize their values automatically when created, and the MORPH instances as object instances of these classes.

4.4. Metanode Organization

The metanode pattern is the organizational principle for MORPH models. The "metanode" we refer to here was introduced by RSD software to express the "nodes" property of their DBExplorer. DBExplorer is a tree-view GUI component created for navigating relational database tables. The value of DBExplorer's "nodes" property is a metanode structure that defines custom relationships among the tables for DBExplorer to navigate the data in a particular way. An example would be a simple master-detail relationship like Customers-Orders. Once the metanode structure is defined, DBExplorer creates a tree view that allows the user to navigate to the desired custom-order instance. MORPH adopts this concept and provides a declarative XML language expression for authors to define different useful metanode relations for the model. The metanode relationship can be considered like a "view" in a relational database.

The metanode pattern reflects a family of similar node relationships, rather than specifying a particular node relationship. The metanode expresses a relationship between types of objects, which may be organized in a directory-like structure.

MORPH uses metanodes to organize both the prototype classes and the execution instances of the model. The specific use of the metanode pattern in MORPH creates a namespace for objects in which each object has a unique name derived by concatenating the distinguished name of each node in the path.

Metanode relationships are expressed in both the Prototypes and Hierarchies sections.

4.5. MORPH Development Process

MORPH development process is subdivided into layers, based on the Four Layer Architecture. The main characteristics of MORPH development process are:

The MORPH process facilitates product development with a host of development tools that are used to abstract the process details from domain and product developers.

4.6. General Overview

MORPH Specification extends the HLA OMT, and it sits at the M2 (meta-model) layer. The MORPH Specification is used to produce a Domain Specific Language, which describes the product domain. DSLs specify product lines.

A product under MORPH is defined as a system involving a product specification, a collection of scenarios, and an engine that consumes them. Product specification documents declare prototypes and general game definitions. Prototypes are used by the various scenarios developed for the product.

The following UML use-case diagram captures the overview of MORPH information development. "Information Model Designer" creates the domain model and optional annotations. "Product Developer" uses the domain model and instantiate the "Product Description" with specific prototypes and scenarios. The engine process is a special system actor who consumes the "Product Description" alone with annotations to create the runtime execution instance for the user. The diagram also shows that an information model compliant to HLA could be imported and automatically translated into a MORPH domain model.

A series of XML documents is produced by the MORPH information modeling methodology. The DSL could be presented as an XML instance document which is an HLA object model with metanode and prototype extensions. This XML file is then translated into the form of an early-bound schema, MORPH-DSL schema, to validate a CEB (Containment Early Binding) instance document that encapsulates the "product" of the specified domain.

The following entity relationship diagram expands the diagram at 4.11 and shows the architectural boundaries among the documents.

Different from the traditional "Domain Engineering" model, we introduce a new intermediate architecture level between "Domain" and "Product" called "System." This layer will host the annotations, or adjuncts in TIBCO's term, to either extend or restrict the domain vocabulary and provide useful information for the engine processor. Product lines from a domain can be characterized as different systems. System concepts or vocabularies, expressed in the form of annotations to the underlying domain model, partition the "product space" into meaningful subgroups for different processors. It avoids creating new domain model and provides better extensibilities in a modular way.

Besides model-system-product, we can also describe the relationships of documents from MORPH methodology in a layering architecture like OMG's Model Driven Architecture (MDA). Using M2, M1, and M0 to present meta-model, model, and instance as proposed in OMG, the following table can be used to describe for MORPH information modeling paradigm.

Meta-model (M2) HLA-OMT (hla.xsd), MORPH schema (HLA-MORPH.xsd), DSL schema template
Model (M1) DSL in HLA-MORPH (myDSL.xml), MORPH-DSL schema (myDSL.xsd), annotations, product/variant description (myProduct.xml)
Instance (M0) Execution instance instantiated internally in processor/engine

A DSL schema template sits at the M2 layer because it is conceptually a schema made for all DSLs. The product description might be thought of as "M0.5" since it is expressed by the modeling component, MORPH-DSL schema (myDSL.xsd), and will be instantiated to M0 as runtime instance data by an engine or processor.

A set of MORPH tools will be created to help information model designers and product developers to produce MORPH-compliant documents. The following is a data-flow diagram which shows how MORPH documents are produced and used.

4.7. Development Process Example: RTS DSL

This fictional example deals with the development of a general DSL for real-time strategy (RTS) games. Two of the most popular product lines, Blizzard's Warcraft/Starcraft and Ensemble Studio's Age of Empires series, are used to illustrate the development process.

The design studios would utilize the APIs and engines (as specified by the MAGNETAR architecture; their specification is outside of the scope of this document) to create their own proprietary engines. These engines are used to run the product models created by studio's own game designers as well as the fan community (mod designers). A complete product would consist of the product specification, a collection of scenario specifications, and one or more engines to run the scenarios.

Under the MORPH development process, a DSL would be created to capture the knowledge of the RTS domain. A product line for this domain, such as the Age of Empires series or the StarCraft/WarCraft series, could be defined using the DSL. Products in the Age of Empire series would be games like Age of Empires, Age of Kings, and so forth. StarCraft, WarCraft II, and WarCraft III are all example products of the "Crafts" product line. As mentioned in 4.6, the architectural level "System" would be created to identify the different genres of the "Crafts" product line and the "AOE" product line.

5. MORPH Components

A MORPH document is known as a "DSL" which stands for "Domain Specific Language." MORPH-DSLs are XML Schema files. This allows for the development of "Product" files, which are early-bound XML instance documents. The use of XML Schema to model DSLs creates a powerful mechanism for creating early- and late-bound models. However, the use of XML Schema also creates some odd restrictions and constructs that are not obvious at first glance. This is because:

5.1. Conventions

5.1.1. hla: attributes

Using another namespace for the "hla:" attributes allows us to place attributes on XML Schema elements that would normally prohibit them. In this way we can annotate the model with all of the information required to reconstruct a valid OMT model. For consistency with OMT, these attributes use the capitalization as used in the IEEE 1516.2 specification and do not reflect the Best Practices capitalization which is used elsewhere in MORPH.

5.1.2. doc:nodetype

The "nodetype" attribute is required for automatic processing of the XML Schema file. Without these attributes, the schema may be used to validate Product instances, but a processor will be unable to identify certain aspects of the DSL. Additionally the documentation XSLT relies on "nodetype" attributes to operate correctly.

5.1.3. Names

Identifying names use the "MORPHnameToken" type declared in HLAdatatypes. This datatype shall identify those names which must conform to the HLA naming conventions. Briefly, these are:

Early-bound XML element and attribute names of items in the model should also follow these restrictions.

5.1.4. Duplicate Names

HLA allows for classes and interactions to share duplicate names, as long as their hierarchy is different. If this is used in MORPH, "dot notation" must be used to identify classes/interactions in all places where a class/interaction is referenced. Dot notation is not used to name the classes in the Object Classes and Interactions sections. However, it would be used in Attributes/Parameters and a few other places where the object is referenced. These are described below.

Dot notation begins with the root and concatenates the name of each class/interaction in the object hierarchy. For example: HLAobjectRoot.Class1.Class2.

5.1.5. Legend

The following diagrams illustrate how the nodes are arranged in a MORPH DSL, and, by extension, the MORPH Product XML instance file. The boxes in the document represent specific chunks of XML Schema code in the DSL file. They also serve as hyperlinks to the corresponding node section of this document.

Prototypes
A solid outline with a normal font indicates a specific element with that name in the tree of the XML instance file.
Prototypes
A double outline indicates that an element with the same name may appear more than once in its shown location (its maxOccurs is greater than 1).
(Prototypes)
A faded outline indicates a node which does not actually represent an element in the instance XML document.
Prototypes
Italic text indicates an element in the XML document which has an early-bound name. The name shown is simply a placeholder. Also such nodes may appear more than once in this location, as long as they each have a different element name.
A solid horizontal line indicates an inheritance model for the element tree.
An ellipsis indicates missing nodes, usually due to variable repetition.
Vertical lines connect sibling nodes.
Prototypes Text with this style indicates optional items which may (or, in some situations as described in the text, must) be omitted as desired by the DSL.
#Prototypes# Hash marks indicate placeholder text which must be edited by the DSL, and should not be copied as-is.
(...) A text ellipsis indicates omitted data, either DSL-defined or repetition of items above it.

5.2. Schema Root

xs:schema (Redefine)
(Specification)
(Datatypes)
(Tables)
(Events)
(Attributes)
Product

The above node tree illustrates the schema root of a MORPH-DSL. A DSL's root element is <xs:schema>, whereas an XML instance file's root element is the Product element, shown last in the above tree.

The following metadata is found on the <xs:schema> element in the DSL, in the form of XML attributes in another namespace:

Each also has a "Notes" variation.

The <xs:schema> element also contains several namespace declarations. Note that namespace prefixes given here are the ones used throughout this document. However, XML allows the prefix to be anything the DSL desires, as long as the namespace path is the same.

Finally, a DSL may use a processing instruction "xml-stylesheet" to reference an XSLT stylesheet for automatically generating specification documentation on the model.

Schema Root Node
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="MORPHdoc.xslt"?>
<xs:schema elementFormDefault="qualified" attributeFormDefault="unqualified" xmlns:xs=" http://www.w3.org/2001/XMLSchema" xmlns:hla="http://www.gamexml.org/Specs/HLAsupplement.xsd" xmlns:doc="http://www.gamexml.org/Specs/MORPHdoc.xsd" hla:name="#Name#" doc:Title="#Title#" doc:ThisVersion="#URL#" doc:PreviousVersion="#URL#" doc:LatestVersion="#URL#" hla:nameNotes="#NameNotes#" hla:type="#Type#" hla:typeNotes="#TypeNotes#" hla:version="#Version#" hla:versionNotes="#VersionNotes#" hla:date="#Date#" hla:dateNotes="#DateNotes#" hla:purpose="#Purpose#" hla:purposeNotes="#PurposeNotes#" hla:appDomain="#AppDomain#" hla:appDomainNotes="#AppDomainNotes#" hla:sponsor="#Sponsor#" hla:sponsorNotes="#SponsorNotes#" hla:pocName="#pocName#" hla:pocNameNotes="#POCNameNotes#" hla:pocOrg="#pocOrg#" hla:pocOrgNotes="#pocOrgNotes#" hla:pocPhone="#pocPhone#" hla:pocPhoneNotes="#pocPhoneNotes#" hla:pocEmail="#pocEmail#" hla:pocEmailNotes="#pocEmailNotes#" hla:references="#References#" hla:referencesNotes="#ReferencesNotes#" hla:other="#Other#" hla:otherNotes="#OtherNotes#">
<xs:import schemaLocation="http://www.gamexml.org/Specs/HLAdatatypes.xsd"/>
(Redefine)
(Specification)
(Datatypes)
(Tables)
(Attributes)
Product
</xs:schema>

5.3. Product Root

Product ObjectClasses
Prototypes
Hierarchies
Interactions
Interface
Instances
(Keys)

Every XML document must have a single root element. In MORPH, this is known as the "Product root." The name of this element is not significant. By convention, the name "Product" is used, but any name may be substituted.

Note that each of the child elements of the Product root are marked optional (minOccurs is "0") in the XML Schema. This is to allow for multiple types of XML instance documents (such as Product definitions, scenario files, and so forth) without needing to create multiple schema files and re-declaring in each DSL-specific items such as datatypes and Keys. Thus, an XML instance file may omit any section which does not apply to its needs.

MORPH declares metadata which is applied to an instance document. This metadata provides a method of classifying and organizing MORPH models and scenarios which can be used as directory service content for MORPH repositories. The following metadata is found on the Product element of the early-bound instance:

In a MORPH-DSL, the attribute declarations for this data must appear at the bottom of the file, even though the attributes appear at the top of the file in the early-bound instance, as attributes must be declared after elements in XML Schema.

Product Root Node
<xs:element name="#Product#">
<xs:complexType>
<xs:sequence>
</xs:sequence>
<xs:attribute name="Name" type="MORPHnameToken" use="required"/>
<xs:attribute name="DisplayName" type="xs:string"/>
<xs:attribute name="Owner" type="MORPHnameToken"/>
<xs:attribute name="Version" type="xs:string"/>
<xs:attribute name="Copyright" type="xs:string"/>
<xs:attribute name="#Attribute#" type="#Type#" use="#Use#"/>
</xs:complexType>
(Keys)
</xs:element>

5.4. Redefine

A DSL defines a generic, abstract System for a domain. Any number of Engines may then be created which customize this domain further. This is accomplished via an XML Schema redefine. Datatypes and attributes may be redefined within the <xs:redefine> element. This must occur at the top of the file.

Redefine Node
<xs:redefine schemaLocation="#DSL#.xsd">
(...)
</xs:redefine>

5.5. Data Types

MORPH adopts the OMT specifications for datatypes while providing an XML instance format for declaring new datatypes and their values. MORPH has defined the OMT datatypes using XML Schema, which enables their validation and use in MORPH documents (which themselves are XML instances). Datatypes are integral to the rest of the model.

XML Schema has an extensive method of creating new datatypes. However MORPH restricts the XML Schema datatypes in the following manners:

Documentation may optionally be provided for each datatype. The <xs:annotation> must appear as a direct child of the <xs:simpleType> or <xs:complexType> element of the type, as shown in the examples.

Datatypes Node

5.5.1. Basic Type

Basic data types are those which are atomic and are not built from other datatypes. In XML Schema, they are represented using a <xs:simpleType> element. All basic types must use <xs:restriction>, and the "base" attribute of the restriction must not reference an "HLA" datatype or a DSL-defined type. That is, the base must be one of XML Schema's built-in types, usually "xs:integer." The content of the <xs:restriction> is left open to the DSL developer. The construct used should be one which allows the XML Schema type to closely model the restrictions listed in the attributes "hla:size," "hla:interpretation," and "hla:encoding." This can usually can be accomplished using "minInclusive" (or "minExclusive") and "maxInclusive" (or "maxExclusive").

Within an included HLAdatatypes.xsd file are all of the datatypes defined in HLA, translated into XML Schema form. This file should be imported into every MORPH-DSL in place of manually duplicating the data. These datatypes can be extended further by the DSL developer using simple datatypes. There is no requirement that they be used.

Basic Type Node
<xs:simpleType name="#BasicType#" doc:nodetype="basic" hla:nameNotes="#NameNotes#" hla:size="#Size#" hla:sizeNotes="#SizeNotes#" hla:interpretation="#Interpretation#" hla:interpretationNotes="#InterpretationNotes#" hla:endian="#Endian#" hla:endianNotes="#EndianNotes#" hla:encoding="#Encoding#" hla:encodingNotes="#EncodingNotes#">
(Documentation)
<xs:restriction base="xs:integer">
(...)
</xs:restriction>
</xs:simpleType>

5.5.2. Simple Type

Simple datatypes are scalar data items. They are declared in the DSL using XML Schema <xs:simpleType> elements. The "base" attribute must be the name of a basic datatype (either HLA or DSL defined). A simple type must be declared using <xs:restriction>. The "base" attribute is the type's HLA "Representation."

Simple Type Node
<xs:simpleType name="#SimpleType#" doc:nodetype="simple" hla:nameNotes="#NameNotes#" hla:representationNotes="#RepresentationNotes#" hla:units="#Units#" hla:unitsNotes="#UnitsNotes#" hla:resolution="#Resolution#" hla:resolutionNotes="#ResolutionNotes#" hla:accuracy="#Accuracy#" hla:accuracyNotes="#AccuracyNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:restriction base="#Representation#">
(...)
</xs:restriction>
</xs:simpleType>

5.5.3. Enumerated Type

Enumerated types are datatypes that can take a finite set of discrete values. The template for a MORPH enumerated datatype declaration uses the XML Schema method of declaring enumerated types. The "hla:value" is used when it is necessary to specify a specific value or values for the enumerator (which XML Schema does not directly support). If multiple values are specified, they should be separated using white space, not commas. If "hla:value" is not specified, the actual value of the enumerator is insignificant, and only the enumerator name has significance.

Note that enumerated types are always restrictions of type "xs:NMTOKEN." This is not the same as the HLA "Representation" value. The types must be restrictions of a string type in XML Schema in order to allow for the enumerators to have textual names. Even though XML Schema calls the attribute "value," the content of that attribute is in fact the HLA "Enumerator" name.

Enumerated Type Node
<xs:simpleType name="#EnumeratedType#" doc:nodetype="enumeration" hla:nameNotes="#NameNotes#" hla:representation="#Representation#" hla:representationNotes="#RepresentationNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="#Enumerator#" hla:value="#Value#" hla:nameNotes="#ValueNameNotes#" hla:valueNotes="#ValueNotes#">
</xs:enumeration>
(...)
</xs:restriction>
</xs:simpleType>

5.5.4. Array Type

ArrayType Value Index
Item

Arrays are sequences of items of the same underlying datatype. Arrays (or sequences) are defined as indexed homogenous collections of datatypes. In XML, an array of characters is a string and is easily utilized. More complicated arrays make use of repeated groups of nested elements.

Arrays are represented using elements in XML. In HLA and most programming languages, array items are not named. However, the elements in XML may have names. This is an extension and has no significant impact on the model. By default, these elements are named simply "Item" and "Value."

The construction of the array type depends on whether it is an array of simple types or complex types. Only one of Value or Item should be used, not both at once.

Multidimensional arrays are created by simply referencing another array as the "type" attribute. Because arrays are in themselves complex types, the element form of the array declaration must be used, rather than the attribute form.

Array Type Node
<xs:complexType name="#ArrayType#" doc:nodetype="array" hla:nameNotes="#NameNotes#" hla:dataTypeNotes="#DataTypeNotes#" hla:cardinalityNotes="#CardinalityNotes#" hla:encoding="#Encoding#" hla:encodingNotes="#EncodingNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:sequence>
</xs:sequence>
</xs:complexType>

The following is an example of a multidimensional array declaration, with customized element and attribute names:

Array Datatype Example
<xs:complexType name="MapY" doc:nodetype="array">
  <xs:sequence>
    <xs:element name="Y" type="MapX" minOccurs="0" maxOccurs="10"/>
  </xs:sequence>
</xs:complexType>

<xs:complexType name="MapX" doc:nodetype="array">
  <xs:sequence>
    <xs:element name="X" minOccurs="0" maxOccurs="10">
      <xs:complexType>
        <xs:attribute name="Tile" type="xs:integer"/>
      </xs:complexType>
    </xs:element>
  </xs:sequence>
</xs:complexType>

5.5.4.1. Array Value

The value node is used when the array is made up of complex types. The index node is optional. If the index is used, the "type" attribute (marked here as optional) must be removed.

Array Value Node
<xs:element name="#Value#" type="#ElementType#" minOccurs="0" maxOccurs="#Cardinality#">
</xs:element>

5.5.4.2. Array Index

The index node allows for an instance document to specify which index into the array to assign a value. Otherwise, the order of the elements implies the index. Therefore, the index node is optional.

Array Index Node
<xs:complexType>
<xs:complexContent>
<xs:extension base="#ElementType#">
<xs:attribute name="Index" type="xs:integer" use="optional"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>

5.5.4.3. Array Item

The item node is used when the array is made up of a simple type. This allows for a more compact instance document.

Array Item Node
<xs:element name="#Item#" minOccurs="0" maxOccurs="#Cardinality#">
<xs:complexType>
<xs:attribute name="Value" type="#ElementType#" use="required"/>
<xs:attribute name="Index" type="xs:integer" use="optional"/>
</xs:complexType>
</xs:element>

5.5.5. Fixed Record Type

Records consist of a variable number of fields that are of different types, simple or complex. In XML, these are represented using nested elements. The leaf node's data is always represented using attributes.

In MORPH, record types are declared using a <xs:complexType> which contains only <xs:attribute> nodes, or <xs:element> nodes which have a "type" attribute pointing to another complex type. No other construct is valid. There may be no nested <xs:element> nodes, and no <xs:element> should have a "type" attribute which references a simple type (<xs:attribute> nodes are used for simple types). If <xs:element> nodes are required, they must be contained within an <xs:all> construct.

The following template includes the code required for both complex and simple fields. The Complex section (and its surrounding <xs:all> elements) is eliminated if all field types are simple types. Conversely, if all of the types are complex types, the SimpleField node is eliminated.

Fixed Record Type Node
<xs:complexType name="#FixedRecordType#" doc:nodetype="record" hla:nameNotes="#NameNotes#" hla:encoding="#Encoding#" hla:encodingNotes="#EncodingNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
</xs:complexType>

5.5.5.1. Complex Field

In the following declaration, "minOccurs" can be either 0 or 1, which denotes whether or not it is optional in an XML instance document. The "maxOccurs" should always be "1" since it is undefined to give a value to the same field more than once.

Complex Field Node
<xs:element name="#ComplexField#" type="#DataType#" minOccurs="#0#" maxOccurs="1" hla:nameNotes="#NameNotes#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>

5.5.5.2. Simple Field

The "use" attribute can be either "optional" or "required" as desired by the DSL.

Simple Field Node
<xs:attribute name="#SimpleField#" type="#DataType#" use="#Use#" hla:nameNotes="#NameNotes#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>

5.5.6. Variant Record Type

Variant record types define unions of types. All variant records have a discriminant value which determines which one of its alternatives is used in an instance document. Because of XML constraints, there is no way to link the value of the discriminant to its alternative name. That is, each discriminant should have only one possible type of content, but there is no way using XML Schema alone to force this constraint.

The <xs:choice> element is used as it allows for one of its children to appear, but only one. This constraint works only for elements; thus all alternatives must be declared using elements rather than attributes, even if they are simple types.

There should only be one <xs:attribute> as a direct child of the complex type. This attribute specifies the discriminant of the record.

Variant Record Type Node
<xs:complexType name="#VariantRecordType#" doc:nodetype="variant" hla:encoding="#Encoding#" hla:encodingNotes="#EncodingNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:choice>
<xs:element name="#AlternativeName#" type="#AlternativeType#" hla:enumerator="#DiscriminantEnumerator#" hla:enumeratorNotes="#EnumeratorNotes#" hla:nameNotes="#AlternateNameNotes#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
(...)
</xs:choice>
<xs:attribute name="#DiscriminantName#" type="#DiscriminantType#" hla:discriminantNotes="#DiscriminantNotes#" hla:dataTypeNotes="#DataTypeNotes"/>
</xs:complexType>

An example of a variant type:

Array Datatype Example
<xs:complexType name="WaiterValue" doc:nodetype="variant" hla:encoding="HLAvariantRecord"
hla:semantics="Datatype for waiter performance rating value">
  <xs:choice>
    <xs:element name="CoursePassed" type="HLAboolean" hla:enumerator="Trainee"
    hla:semantics="Ratings scale for employees under training"/>
    <xs:element name="Rating" type="RateScale" hla:enumerator="[Apprentice..Senior], Master"
    hla:semantics="Ratings scale for permanent employees"/>
    <xs:element name="NA" type="NA" hla:enumerator="HLAother" hla:semantics="All others"/>
  </xs:choice>
  <xs:attribute name="ValIndex" type="ExperienceLevel"/>
</xs:complexType>

5.6. Tables

The MORPH early-bound instance excludes some OMT data unnecessary to the purpose of the early-bound model. Such data generally does not change from one System to the next, and thus can be set at the DSL level. To prevent these tables from showing up in resulting instance documents, the data is recorded in the schema using either <xs:annotation> or encoded as XML Schema datatypes.

The following items must appear as direct children of the <xs:schema> element. Aside from this, there is no other restriction on their placement. All of the tables which are placed within <xs:annotation> may appear within a single annotation element, or they may each be given separate <xs:annotation> sections if desired, or any combination thereof.

All such tables of information use the "hla:" namespace in the following examples. A DSL may use any namespace desired, but the namespace should reference http://www.gamexml.org/Specs/HLAsupplement.xsd.

5.6.1. Dimensions

Dimensions are used to limit the flow of data between federates to only what is necessary for the simulation. This can result in saved bandwidth and execution time. The dimensions table provides a common framework for this distribution data model.

In MORPH, dimensions are specified as a list of possible values, to be used in "hla:dimensions" attributes.

Dimensions Node
<xs:simpleType name="Dimensions">
(Documentation)
<xs:list>
<xs:simpleType>
<xs:restriction base="MORPHnameToken">
<xs:enumeration value="#DimensionName#" hla:nameNotes="#NameNotes#" hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:upperBound="#UpperBound#" hla:upperBoundNotes="#UpperBoundNotes#" hla:normalization="#Normalization#" hla:normalizationNotes="#NormalizationNotes#" hla:default="#Default#" hla:defaultNotes="#DefaultNotes#">
</xs:enumeration>
(...)
</xs:restriction>
</xs:simpleType>
</xs:list>
</xs:simpleType>

5.6.2. Time

The time table allows a model to specify values for the following two properties for TimeStamp and Lookahead:

Time Node
<xs:annotation>
<xs:appinfo>
<hla:Time>
(Documentation)
<TimeStamp hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
</TimeStamp>
<Lookahead hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
</Lookahead>
</hla:Time>
</xs:appinfo>
</xs:annotation>

5.6.3. Synchronization

This table allows a model to describe the synchronization points to be used in the simulation. In MORPH, this is recorded using an enumerated type.

Synchronization Node
<xs:simpleType name="Synchronizations">
(Documentation)
<xs:list>
<xs:simpleType>
<xs:restriction base="MORPHnameToken">
<xs:enumeration value="#SynchronizationLabel#" hla:nameNotes="#NameNotes#" hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:capability="#Capability#" hla:capabilityNotes="#CapabilityNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
</xs:enumeration>
(...)
</xs:restriction>
</xs:simpleType>
</xs:list>
</xs:simpleType>

5.6.4. Transportation

HLA provides different methods for transporting data among federates. This table allows the model to describe the types of transportation that can be supported. In MORPH, transportation methods are defined using an enumeration to aid in validation. HLA supplies two transportation types, "HLAreliable" and "HLAbestEffort," and others may be added.

Transportations Node
<xs:simpleType name="Transportations">
(Documentation)
<xs:restriction base="MORPHnameToken">
<xs:enumeration value="HLAreliable" hla:description="Provide reliable delivery of data in the sense that TCP/IP delivers its data reliably"/>
<xs:enumeration value="HLAbestEffort" hla:description="Make an effort to deliver data in the sense that UDP provides best-effort delivery"/>
<xs:enumeration value="#TransportationName#" hla:nameNotes="#NameNotes#" hla:description="#Description#" hla:descriptionNotes="#DescriptionNotes#">
</xs:enumeration>
(...)
</xs:restriction>
</xs:simpleType>

5.6.5. Switches

The switches table allows a model to enable or disable certain actions which the RTI performs. The setting of each of the following must be either "Enabled," "Disabled," or "NA." The value "NA" is allowed only for SOMs.

Switches Node
<xs:annotation>
<xs:appinfo>
<hla:Switches AutoProvide="#Setting#" ConveyRegion="#Setting#" AttributeScope="#Setting#" AttributeRelevance="#Setting#" ObjectClassRelevance="#Setting#" InteractionRelevance="#Setting#" ServiceReporting="#Setting#">
</hla:Switches>
</xs:appinfo>
</xs:annotation>

5.6.6. User-Supplied Tags

This section allows a model to modify the HLA services as needed for the simulation.

Tags Node
<xs:annotation>
<xs:appinfo>
<hla:Tags>
(Documentation)
<UpdateReflect hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
<SendReceive hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
<DeleteRemove hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
<DivestRequest hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
<DivestComplete hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
<AcquisitionRequest hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
<RequestUpdate hla:dataType="#DataType#" hla:dataTypeNotes="#DataTypeNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
</hla:Tags>
</xs:appinfo>
</xs:annotation>

5.6.7. Notes

The notes table allows the author to add annotations to the model. Notes are referenced from elsewhere in the model by label number. A single note may be referenced multiple times, and a single OMT entry may reference more than one note. All "Notes" attributes may supply a list, delimited by white space, of valid note labels as specified in the table below. For example: "1 2 5" would specify notes 1, 2, and 5. This is why label names cannot have white space.

Notes Node
<xs:annotation>
<xs:appinfo>
<hla:Notes>
<Note hla:label="#Label#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"/>
(...)
</hla:Notes>
</xs:appinfo>
</xs:annotation>

5.6.8. Lexicon

The lexicon table allows a federation to describe the semantics of the data in the model. MORPH uses a nested view which allows objects, attributes, and parameters to be documented in a concise manner. All elements have the following attributes in common:

Lexicon Node
<xs:annotation>
<xs:appinfo>
<hla:Lexicon>
<Class Ref="#ClassName#" Definition="#Definition#">
<Attribute Ref="#AttributeName#" Definition="#Definition#"/>
(...)
<Parameter Ref="#ParameterName#" Definition="#Definition#"/>
(...)
</Class>
(...)
</hla:Lexicon>
</xs:appinfo>
</xs:annotation>

5.7. Object Classes

ObjectClasses Category Class AttributeOverride
UserAttribute
Event
Class

The <ObjectClasses> element is designed to allow the Product XML instance document to modify object classes in specific, restricted ways. Its entire purpose in the schema is simply to surface such information for use by the Product. The <ObjectClasses> element does not directly declare object classes, and it does not declare attributes or inheritance. A processor uses the Attributes section to determine class hierarchy and attributes.

Classes may be nested; this nesting however reflects a metanode model, not the inheritance model. The inheritance model is reflected by the attribute declarations. Please see Attributes.

In short, the <ObjectClasses> element does:

The <ObjectClasses> element does not:

ObjectClasses Node
<xs:element name="ObjectClasses" minOccurs="0">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded"> </xs:choice>
</xs:complexType>
</xs:element>

5.7.1. Category

Categories are optional. A category is simply for metanode organization and has no other impact on the model.

Category Node
<xs:element name="#Category#" minOccurs="0" doc:nodetype="category">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded"> </xs:choice>
</xs:complexType>
</xs:element>

5.7.2. Class

Class Node
<xs:element name="#Class#" minOccurs="0" doc:nodetype="class" hla:sharing="#Sharing#" hla:sharingNotes="#SharingNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
</xs:choice>
<xs:attribute name="DisplayName" type="xs:string" use="optional"/>
<xs:attribute name="PluralName" type="xs:string" use="optional"/>
</xs:complexType>
</xs:element>

5.7.3. AttributeOverride

The AttributeOverride node allows a DSL to permit a Product to modify certain aspects of an object's attributes. Generally the attribute's data type cannot be altered, as that might impact the RTI, but its display name, default value, and whatever else the DSL desires can be modified. By adding additional attributes to the AttributeOverride element, the DSL may declare which aspects of the attribute a product may redefine.

The type of the "Ref" attribute can be an XML Schema enumeration of all of the attributes that the DSL wishes to allow to be modified by a Product. However, this is not required for the model to be complete; it merely aids in validation for the end user. If an enumeration is not used, the "Ref" attribute should be simply the "MORPHnameToken" type.

AttributeOverride Node
<xs:element name="AttributeOverride" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="Ref" type="#AttrsEnum#" use="required"/>
<xs:attribute name="DisplayName" type="xs:string" use="optional"/>
<xs:attribute name="Default" type="xs:string" use="optional"/>
<xs:attribute name="#Name#" type="#Type#" use="#Use#"/>
</xs:complexType>
</xs:element>

5.7.4. UserAttribute

User attributes (declared in the Product instance file using UserAttribute) allow a Product to attach an arbitrary number of additional attributes to an object class. They are implemented internally using an array of variants and are not in fact actual HLA object class attributes; thus they are restricted to simple types that can be represented with a variant. They also do not need HLA attributes such as "transportation" and "updateType."

In the Product file, the UserAttribute element here in the Object Classes section allows the Product to declare which attributes it wishes to define. The attributes are actually given values in the Prototypes and Instances sections.

UserAttribute Node
<xs:element name="UserAttribute" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="Name" type="MORPHnameToken" use="required"/>
<xs:attribute name="DataType" type="MORPHnameToken" use="required"/>
<xs:attribute name="DisplayName" type="xs:string" use="optional"/>
<xs:attribute name="Default" type="xs:string" use="optional"/>
<xs:attribute name="Instance" type="xs:boolean" use="optional" default="false"/>
<xs:attribute name="#Name#" type="#Type#" use="#Use#" default="#Default#"/>
</xs:complexType>
</xs:element>

5.7.5. Event

The event node is an element which references an event command. See the Events section.

Event Node
<xs:element name="#Event#" type="#EventType#" minOccurs="0" maxOccurs="#unbounded#" doc:nodetype="event"/>

5.8. Attributes and Parameters

Attributes are not declared in the <ObjectClasses> section. If they were, they would show up in the instance document, which is an undesired side-effect. Furthermore, the same attribute declarations may appear in two places: the Prototypes section, and the Instances section. To prevent the need for copy-and-paste (and the potential errors that may result), it was decided to pre-declare attributes in groups, using two XML Schema constructs known as <xs:attributeGroup> and <xs:group>.

These groups have the additional advantage that they may reflect the inheritance tree of the model. This not only provides valuable information to a processor, but also allows for attributes to be inherited in the schema itself, thus removing the necessity of manually re-declaring them in each descendant class.

Additionally, this construct allows for the <ObjectClasses> section to be flat, or to be organized in metanode categories, rather than being forced to be organized according to the inheritance tree.

Parameters are only used once in a schema document. However, interactions can have an inheritance tree just like object classes. Furthermore, because of metanode categorization, it is not possible to reflect the inheritance tree using the <Interactions> section. For these reasons, parameters are declared in an identical manner as attributes.

All attribute and parameter declarations must appear as direct children of the <xs:schema> element. By convention, they appear at the top of the file, before the root node. Their order does not directly matter as long as they are declared as "global" XML groups, and the schema validates. The names used for each of the groups also is not significant. The groups are identified by their "doc:class" attributes rather than by their names.

To reflect the inheritance model, nest attribute group declarations within each other using the XML Schema "ref" attribute within a nested <xs:attributeGroup> or <xs:group> element. The root classes, HLAobjectRoot and HLAinteractionRoot, must not include this reference. Do not manually re-declare each attribute from a parent class within a child class's group. XML Schema will do this automatically when the "Ref" attribute is used.

Every class and interaction (with the exception of HLAobjectRoot and HLAinteractionRoot) must have at least one attribute group declaration (either an <xs:attributeGroup> or <xs:group>), even if it is empty. Classes and interactions are declared and placed into the object hiarachy by their attribute groups. All such groups (except for HLAobjectRoot and HLAinteractionRoot) should include the "Ref" to their object parent, even if otherwise empty.

Instance attributes should be declared in separate groups from global attributes so that they may be applied correctly to Prototypes and Instances. This may mean there could be four or more attribute groups per class (global simple types, instance simple types, global complex types, and instance complex types). Further subdivision can be done as desired by the DSL.

Every object class should have, at the very minimum, a "Name" attribute which follows the HLA naming conventions (MORPHnameToken). This is used for identifying Prototypes.

The "use" attribute on simple types, or the "minOccurs" for complex types, may be assigned as desired by the DSL to either force a Product to include a value for that attribute, or to allow the Product to omit the value, in which case the default value is assumed.

Attributes themselves contain attributes. These attributes are:

Parameters contain only a subset of the above attributes, which are:

5.8.1. Simple Types

This construct is used when the type of the attribute or parameter is a simple type.

The name of the attribute or parameter group element is insignificant; the only requirement is that it is unique throughout the model, as it is referenced in several other places.

AttributeGroup Node
<xs:attributeGroup name="#ClassAttrs#" doc:nodetype="attributes" doc:class="#Class#">
<xs:attributeGroup ref="#ParentClassAttrs#"/>
<xs:attribute name="#Attribute#" type="#DataType#" use="#Use#" default="#Default#" doc:DisplayName="#DisplayName#" doc:Instance="#True|False#" hla:nameNotes="#NameNotes#" hla:dataTypeNotes="#DataTypeNotes#" hla:updateType="#UpdateType#" hla:updateTypeNotes="#UpdateTypeNotes#" hla:updateCondition="#UpdateCondition#" hla:updateConditionNotes="#UpdateConditionNotes#" hla:ownership="#Ownership#" hla:ownershipNotes="#OwnershipNotes#" hla:sharing="#Sharing#" hla:sharingNotes="#SharingNotes#" hla:dimensions="#Dimensions#" hla:dimensionsNotes="#DimensionsNotes#" hla:transportation="#Transportation#" hla:transportationNotes="#TransportationNotes#" hla:order="#Order#" hla:orderNotes="#OrderNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#"> </xs:attribute>
</xs:attributeGroup>

5.8.2. Complex Types

This construct is used when the type of the attribute or parameter is a complex type.

The name of the attribute or parameter group element is insignificant; the only requirement is that it is unique throughout the model, as it is referenced several other places.

Note: Normally, "doc:" attributes would be placed on the <xs:group> element. However, the W3 working group neglected to add "any attributes with non-schema namespace" for <xs:group> in the XML Schema specification. This omission has been corrected in the errata, but MORPH nevertheless allows the "doc:" attributes to be placed on the <xs:choice> instead if the desire is to validate in older processors that have not yet updated to the errata. The code below shows the "doc:" attributes in both locations; a DSL should choose one or the other, rather than both.

Group Node
<xs:group name="#ClassGroupAttrs#" doc:nodetype="attributes" doc:class="#Class#">
<xs:sequence>
<xs:choice minOccurs="0" maxOccurs="unbounded" doc:nodetype="attributes" doc:class="#Class#">
<xs:group ref="#ParentClassGroupAttrs#"/>
<xs:element name="#Attribute#" type="#DataType#" minOccurs="#0#" maxOccurs="1" doc:Default="#Default#" doc:DisplayName="#DisplayName#" doc:Instance="#True|False#" hla:nameNotes="#NameNotes#" hla:dataTypeNotes="#DataTypeNotes#" hla:updateType="#UpdateType#" hla:updateTypeNotes="#UpdateTypeNotes#" hla:updateCondition="#UpdateCondition#" hla:updateConditionNotes="#UpdateConditionNotes#" hla:ownership="#Ownership#" hla:ownershipNotes="#OwnershipNotes#" hla:sharing="#Sharing#" hla:sharingNotes="#SharingNotes#" hla:dimensions="#Dimensions#" hla:dimensionsNotes="#DimensionsNotes#" hla:transportation="#Transportation#" hla:transportationNotes="#TransportationNotes#" hla:order="#Order#" hla:orderNotes="#OrderNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
</xs:element>
</xs:choice>
</xs:sequence>
</xs:group>

5.9. Events and Scripts

Events allow a way of embedding XML-based "scripts" into the Product instance XML. Events may be implemented as Interactions; in this case, the early-bound name should match an interaction name as declared elsewhere in the DSL. (There is no way in XML Schema itself to force this association; it will have to be enforced via special tools.)

An event may be applied to both an object class itself, one of its prototypes, or even onto an instance directly. When applied to the object class, it affects all prototypes of that class. When applied to a prototype, it affects all instances of that prototype. Because events may be referenced in more than one place within the document, they are declared separately as complex types. Event declarations must appear as direct children of the <xs:schema> element.

It should be noted that while MORPH creates a template for using an event model, it does not define the events nor the script elements to be used. These must be modeled by the engineer. Like everything in MORPH, the events and scripts chosen are domain-specific. The following gives some examples of how the system may be used, but does not denote a standard use.

In the example below, a class "Weapon" needs an event "OnHitTarget" which will be fired by the game engine when the weapon's shot strikes a target. Implicitly, this event passes three parameters: "Self" which represents the weapon itself, "Target" which represents the object that was struck, and "User" which represents the unit which fired the weapon. These may be referenced in commands to perform actions.

The command "If" is evaluated by the game engine as a conditional test. The commands nested within it are those which are able to be performed when the conditional test evaluates to "true." Likewise, the "Else" statement is provided and is expected to immediately follow a closing "If" element. Finally, a "FindObject" is declared which locates another object in the game field. The objects located through "FindObject" may be operated upon by referencing "Target" within child commands.

Event Example
<!-- Simple Datatypes -->

<xs:simpleType name="ObjectType">
  <xs:restriction base="xs:string">
    <xs:enumeration value="Self"/>
    <xs:enumeration value="User"/>
    <xs:enumeration value="Target"/>
  </xs:restriction>
</xs:simpleType>

<!-- Parameters -->
 
<xs:attributeGroup name="IfParams">
  <xs:attribute name="Object" type="ObjectType" use="required"/>
  <xs:attribute name="Attribute" type="xs:string" use="required"/>
  <xs:attribute name="Value" type="xs:string" use="optional"/>
</xs:attributeGroup>

<xs:attributeGroup name="SetAttributeParams">
  <xs:attribute name="Object" type="ObjectType" use="required"/>
  <xs:attribute name="Attribute" type="xs:string" use="required"/>
  <xs:attribute name="Value" type="xs:string" use="required"/>
</xs:attributeGroup>

<xs:attributeGroup name="FindObjectParams">
  <xs:attribute name="Searcher" type="ObjectType" use="required"/>
  <xs:attribute name="ObjectKind" type="xs:string" use="required"/>
  <xs:attribute name="Alliance" type="xs:string" use="required"/>
  <xs:attribute name="Type" type="xs:string" use="required"/>
  <xs:attribute name="Distance" type="xs:integer" use="required"/>
</xs:attributeGroup>

 <!-- Events -->

<xs:complexType name="OnHitTargetType">
  <xs:annotation>
   <xs:documentation>
     <p>Supplied parameters: User (user of weapon), Target (the object hit), Self
     (the weapon itself)</p>
   </xs:documentation>
  </xs:annotation>
  <xs:choice minOccurs="0" maxOccurs="unbounded">
    <xs:element name="If" type="IfType"/>
    <xs:element name="Else" type="ElseType"/>
    <xs:element name="SetAttribute" type="SetAttributeType"/>
    <xs:element name="FindObject" type="FindObjectType"/>
  </xs:choice>
</xs:complexType>

 <!-- Scripts -->

<xs:complexType name="IfType">
  <xs:choice minOccurs="0" maxOccurs="unbounded">
    <xs:element name="If" type="IfType"/>
    <xs:element name="Else" type="ElseType"/>
    <xs:element name="SetAttribute" type="SetAttributeType"/>
    <xs:element name="FindObject" type="FindObjectType"/>
  </xs:choice>
  <xs:attributeGroup ref="IfParams"/>
</xs:complexType>

<xs:complexType name="ElseType">
  <xs:choice minOccurs="0" maxOccurs="unbounded">
    <xs:element name="If" type="IfType"/>
    <xs:element name="Else" type="ElseType"/>
    <xs:element name="SetAttribute" type="SetAttributeType"/>
    <xs:element name="FindObject" type="FindObjectType"/>
  </xs:choice>
</xs:complexType>

<xs:complexType name="SetAttributeType">
  <xs:attributeGroup ref="SetAttributeParams"/>
</xs:complexType>

<xs:complexType name="FindObjectType">
  <xs:annotation>
    <xs:documentation>
      <p>Supplied parameters: Target (the object found)</p>
    </xs:documentation>
  </xs:annotation>
  <xs:choice minOccurs="0" maxOccurs="unbounded">
    <xs:element name="If" type="IfType"/>
    <xs:element name="Else" type="ElseType"/>
    <xs:element name="SetAttribute" type="SetAttributeType"/>
    <xs:element name="FindObject" type="FindObjectType"/>
  </xs:choice>
  <xs:attributeGroup ref="FindObjectParams"/>
</xs:complexType>

Here is an example of the above code in use within a Product instance document. In this example, when the weapon hits a target, the weapon user's "Health" value is examined to determine the power of the resulting blast. If the user is at 10% health or below, the damage is doubled. Furthermore, this weapon has splash damage that affects all enemies within five cells of ground zero of the blast.

Event Instance Example
<Product>
  (...)
  <Prototypes>
    <Weapons>
      <Weapon Name="Bomb" Power="50">
        <OnHitTarget>
          <If Object="User" Attribute="Health" Value="&lt;10%">
            <SetAttribute Object="Target" Attribute="Health" Value="-(Self.Power*2)"/>
          </If>
          <Else>
            <SetAttribute Object="Target" Attribute="Health" Value="-Self.Power"/>
          </Else>
          <FindObject Searcher="User" ObjectKind="Unit" Alliance="Enemy"
          Type="Ground" Distance="5">
            <SetAttribute Object="Target" Attribute="Health" Value="-10"/>
          </FindObject>
        </OnHitTarget>
      </Weapon>
    </Weapons>
  </Prototypes>
  (...)
</Product>

5.9.1. Event

Events have no attributes visible in the Product instance, and thus none need to be declared in the XML Schema. An event may carry parameters which may be utilized by the command script, but those do not need to be in the instance document. If an event is modeled using an interaction, the parameters may be determined by looking at that interaction. Otherwise, they could be specified in documentation, but do not actually exist as data in the MORPH model.

An event has one or more script commands as children which allow the instance document to essentially script actions in response to the event.

Event Node
<xs:complexType name="#EventType#" doc:nodetype="event">
(Documentation)
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="#CommandName#" type="#ScriptType#" minOccurs="0" maxOccurs="#unbounded#"/>
(...)
</xs:choice>
</xs:complexType>

5.9.2. Script

A script command represents a single action or condition check that can take place. Each script command may also have children commands, which represent either:

If commands are Interactions, their parameters are handled in the same manner as other interaction parameters, and are not declared here. Otherwise, they can be declared on the script command node directly.

Script Node
<xs:complexType name="#ScriptType#" doc:nodetype="script">
(Documentation)
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="#CommandName#" type="#ScriptType#" minOccurs="0" maxOccurs="#unbounded#"/>
(...)
<xs:group ref="#GroupParams#"/>
<xs:element name="#Param#" type="#Type#" minOccurs="#0#" maxOccurs="1"/>
(...)
</xs:choice>
<xs:attributeGroup ref="#Params#"/>
<xs:attribute name="#Name#" type="#Type#" use="#Use#"/>
(...)
</xs:complexType>

5.10. Prototypes

Prototypes Category Prototype UserAttribute
Category
Prototype
Event

The <Prototypes> section is a template to allow the Product to declare its prototypes. Any object class which is "prototypeable" should have an entry in this section. Conversely, objects which cannot be prototyped should be omitted from this section. In some models, some or all prototypes may be singletons, but they still need to be included in the <Prototypes> section so that a Product can declare their attribute values. The organization of the <Prototypes> section is up to the DSL. Metanode categories may be added at any level of nesting. In some cases, prototypes are nested within other prototypes.

Prototypes Node
<xs:element name="Prototypes" minOccurs="0">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
</xs:choice>
</xs:complexType>
</xs:element>

5.10.1. Category

Categories are optional. Categories and prototypes may be nested together at any level. A category is simply for metanode organization and has no other impact on the model. Any number of categories and prototypes may be nested within a category or prototype, but categories with the same name are not repeated as are the prototype nodes. Only prototype declarations have attributes (both global class attributes, and instance attributes), Scripts, and a UserAttribute element.

Category Node
<xs:element name="#Category#" minOccurs="0" doc:nodetype="category">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded"> </xs:choice>
</xs:complexType>
</xs:element>

5.10.2. Class

It should be noted that every Prototype should have, at the very minimum, a "Name" attribute which follows the HLA naming conventions (MORPHnameToken).

Prototype Node
<xs:element name="#Class#" minOccurs="0" maxOccurs="unbounded" doc:nodetype="prototype">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
UserAttribute
Category
Prototype
Event
<xs:group ref="#ClassGroupAttrs#"/>
<xs:group ref="#ClassGroupInstanceAttrs#"/>
</xs:choice>
<xs:attributeGroup ref="#ClassAttrs#"/>
<xs:attributeGroup ref="#ClassInstanceAttrs#"/>
</xs:complexType>
</xs:element>

5.10.3. UserAttribute

The UserAttribute element contains a reference ("Ref") to a UserAttribute declared in the ObjectClasses section, and a "Value" attribute. Because user attributes cannot be complex types, there is no need to support children elements on the UserAttribute element. The Value is assumed to be a variant, although it is represented as a string in XML Schema.

UserAttribute Node
<xs:element name="UserAttribute" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="Ref" type="MORPHnameToken" use="required"/>
<xs:attribute name="Value" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>

5.10.4. Event

The event node is an element which references an event command. See the Events section.

Event Node
<xs:element name="#Event#" type="#EventType#" minOccurs="0" maxOccurs="#unbounded#" doc:nodetype="event"/>

5.11. Hierarchies

Hierarchies Category Reference

The purpose of the hierarchies branch of the DSL is to specify many-to-many metanode relationships that cannot be represented with the ObjectClasses, Prototypes, and Instances sections alone. All objects mentioned in the hierarchies are references to prototypes declared above.

The <Hierarchies> section is not needed in all cases. In many situations, the desired metanode organization may be declared in elsewhere. In many DSLs, the <Hierarchies> section will be totally absent.

Hierarchies Node
<xs:element name="Hierarchies" minOccurs="0">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
</xs:choice>
</xs:complexType>
</xs:element>

Hierarchies Instance Example
<Hierarchies>
  <Faction Ref="Human">
    <Units>
      <Unit Ref="Knight"/>
      <Unit Ref="Archer"/>
      <Unit Ref="Warrior"/>
    </Units>
  </Faction>
  <Faction Ref="Elf">
    <Units>
      <Unit Ref="Archer"/>
      <Unit Ref="Ranger"/>
    </Units>
  </Faction>
</Hierarchies>

5.11.1. Category

Categories are optional. In many cases, they are the plural name of the object class and serve as a simple container for prototypes of that class.

Category Node
<xs:element name="#Category#" minOccurs="0" doc:nodetype="category">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded"> </xs:choice>
</xs:complexType>
</xs:element>

5.11.2. Reference

A reference node should have the same early-bound name as the object class to which it references, and in the instance document, the "Ref" attribute should match one of the prototypes as declared in the Product.

Dot notation may be required for the node's name to differenciate between classes that have identical names; however, by convention, classes are not given duplicate names in MORPH, and thus dot notation is not usually needed here.

Reference Node
<xs:element name="#Reference#" minOccurs="0" maxOccurs="unbounded">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded"> </xs:choice>
<xs:attribute name="Ref" type="MORPHnameToken" use="required"/>
</xs:complexType>
</xs:element>

5.12. Interactions

Interactions Category Interaction

Unlike object classes, interactions are referenced only in one place in the file. In the DSL file, the purpose of the <Interactions> section is to declare the interaction classes that exist in the model. In the Product instance document, the purpose of the <Interactions> section is to record instances of interaction objects. That is, the <Interactions> section is scenario instance data, just like the Instances section itself. It should be noted that, unlike object classes, interaction objects may not be modified by the Product. This is the reason interactions are referenced in only one place.

Interaction parameters are declared in the same manner as object class attributes.

Interactions Node
<xs:element name="Interactions" minOccurs="0">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
</xs:choice>
</xs:complexType>
</xs:element>

5.12.1. Category

Categories are optional.

Category Node
<xs:element name="#Category#" minOccurs="0" maxOccurs="unbounded" doc:nodetype="category">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded"> </xs:choice>
</xs:complexType>
<xs:element>

5.12.2. Interaction

Interactions have the following attributes:

Interaction Node
<xs:element name="#Interaction#" minOccurs="0" maxOccurs="unbounded" doc:nodetype="interaction" hla:sharing="#Sharing#" hla:sharingNotes="#SharingNotes#" hla:dimensions="#Dimensions#" hla:dimensionsNotes="#DimensionsNotes#" hla:transportation="#Transportation#" hla:transportationNotes="#TransportationNotes#" hla:order="#Order#" hla:orderNotes="#OrderNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
Category
Interaction
<xs:group ref="#InteractionGroupAttrs#"/>
</xs:choice>
<xs:attributeGroup ref="#InteractionParams#"/>
</xs:complexType>
</xs:element>

5.13. Interface

Interface Category Interaction Response
Error

The interface section is specifically geared toward mapping out the function interface of a System or Engine. An interface is made up of a named command, which may optionally return a result, and may optionally return an error upon failure. Each of these three are represented using elements, as they could be implemented using interactions in the RTI.

Interface Node
<xs:element name="Interface" minOccurs="0">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
</xs:choice>
</xs:complexType>
</xs:element>

5.13.1. Category

Category Node
<xs:element name="#Category#" doc:nodetype="category">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
</xs:choice>
</xs:complexType>
</xs:element>

5.13.2. Interaction

There are two ways to declare parameters for the interface section. If the interface is meant to be implemented using interactions, the parameters are referenced using XML Schema "ref" attributes on <xs:attributeGroup> and <xs:group> elements. Otherwise, they are simply declared in place. Note that a DSL should choose only one method or the other.

Interaction Node
<xs:element name="#CommandName#" minOccurs="0" doc:nodetype="interface" hla:callback="#boolean#" hla:sharing="#Sharing#" hla:sharingNotes="#SharingNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:complexType>
<xs:sequence>
Response
Error
<xs:group ref="#GroupParams#"/>
<xs:element name="#ComplexParameterName#" type="#ComplexParameterType#"/>
(...)
</xs:sequence>
<xs:attributeGroup ref="#Params#"/>
<xs:attribute name="#SimpleParameterName#" type="#SimpleParameterType#"/>
(...)
</xs:complexType>
</xs:element>

5.13.3. Response

Response Node
<xs:element name="#CommandResponse#" minOccurs="0" doc:nodetype="response" hla:sharing="#Sharing#" hla:sharingNotes="#SharingNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:group ref="#GroupParams#"/>
<xs:element name="#ComplexParameterName#" type="#ComplexParameterType#"/>
(...)
</xs:choice>
<xs:attributeGroup ref="#Params#"/>
<xs:attribute name="#SimpleParameterName#" type="#SimpleParameterType#"/>
(...)
</xs:complexType>
</xs:element>

5.13.4. Error

It is possible, although not required, to include within the declaration an enumeration of possible exceptions that a command may raise, as shown below. This has the dual effect of identifying in the DSL which exceptions a routine may throw, and allowing an instance document to specify which exception in particular was raised.

Error Node
<xs:element name="#CommandError#" minOccurs="0" doc:nodetype="error" hla:sharing="#Sharing#" hla:sharingNotes="#SharingNotes#" hla:semantics="#Semantics#" hla:semanticsNotes="#SemanticsNotes#">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:group ref="#GroupParams#"/>
<xs:element name="#ComplexParameterName#" type="#ComplexParameterType#"/>
(...)
</xs:choice>
<xs:attribute name="Exception">
<xs:simpleType>
<xs:restriction base="MORPHnameToken">
<xs:enumeration value="#ExceptionName#" hla:semantics="#Semantics#"/>
(...)
</xs:restriction>
</xs:simpleType>
</xs:attribute>

<xs:attributeGroup ref="#Params#"/>
<xs:attribute name="#SimpleParameterName#" type="#SimpleParameterType#"/>
(...)
</xs:complexType>
</xs:element>

5.14. Instances

Instances Category Instance UserAttribute
Event

The <Instances> section is scenario data. Its purpose is to declare actual instances of object classes (which, in MORPH, are typically clones of prototypes). Instances may be organized in a metanode tree as determined by the DSL. The metanode categories sometimes themselves reference other object classes or prototypes in the system, and other times they are merely placeholders.

Sometimes the <Instances> section is used within a Product file. In this case, the section is declaring the objects which should be created during initialization and startup. This is useful when certain object instances should always exist at the start of the simulation.

Instances Node
<xs:element name="Instances" minOccurs="0">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
</xs:choice>
</xs:complexType>
</xs:element>

5.14.1. Category

Category Node
<xs:element name="#Category#" minOccurs="0" doc:nodetype="category">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
</xs:choice>
</xs:complexType>
</xs:element>

5.14.2. Instance

Notice that instances make use only of the instance attributes, whereas prototypes make use of both global attributes and instance attributes.

The "Prototype" attribute indicates of which prototype this instance is a clone. In some cases, a DSL may allow instances to be direct instances of object classes without belonging to a prototype family, in which case the DSL should use the "Class" attribute instead of the "Prototype" attribute.

The "ID" attribute is optional because it may be inferred from the document by internally numbering all leaf nodes. It is up to the DSL to decide whether it is necessary to provide an explicit ID to each instance, and whether those ID numbers are reused with future instances, or if the number is always reserved even if the instance ceases to exist in the scenario.

Instance Node
<xs:element name="#Instance#" minOccurs="0" maxOccurs="unbounded" doc:class="#ClassName#">
(Documentation)
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
UserAttribute
Category
Instance
Event
<xs:group ref="#ClassGroupInstanceAttrs#"/>
</xs:choice>
<xs:attribute name="Prototype" type="MORPHnameToken" use="required"/>
<xs:attribute name="Class" type="MORPHnameToken" use="required"/>
<xs:attribute name="ID" type="xs:string" use="optional"/>
<xs:attributeGroup ref="#ClassInstanceAttrs#"/>
</xs:complexType>
</xs:element>

5.14.3. UserAttribute

The UserAttribute node is needed to allow the XML instance document to give values to user attributes declared in the ObjectClasses section.

UserAttribute Node
<xs:element name="UserAttribute" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="Ref" type="MORPHnameToken" use="required"/>
<xs:attribute name="Value" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>

5.14.4. Event

The event node is an element which references an event command. See the Events section. Note that placing events on instances is optional; if a particular DSL does not wish to support this, it may omit this block entirely in the XML Schema.

Event Node
<xs:element name="#Event#" type="#EventType#" minOccurs="0" maxOccurs="#unbounded#" doc:nodetype="event"/>

5.15. Keys

To aid in validation, XML Schema <xs:key> elements may be declared for user attributes. Such keys are not required for the model to be complete.

Keys are used to link object class names with their references, such as in the Prototypes and Hierarchies sections. They are also used to link user-defined attribute names with their references in Prototypes and Instances.

Basically, any time one aspect of the model references a name declared elsewhere in the same model, keys can be used.

Below is an example of a key. Consult a reference for XML Schema for more information on how to use keys.

Keys Node
<xs:key name="#KeyName#">
<xs:selector xpath="Prototypes/#Category#/#Class#"/>
<xs:field xpath="@Name"/>
</xs:key>
<xs:keyref name="#KeyRefName#" refer="#KeyName#">
<xs:selector xpath="Hierarchies/#Category#/#Class#"/>
<xs:field xpath="@Ref"/>
</xs:keyref>

5.16. Documentation

A documentation placeholder node is a simple annotation on the model. It must appear as a direct child of the object it is documenting, unless otherwise specified. Documentation may contain XHTML markup.

Documentation Node
<xs:annotation>
<xs:documentation>
<p>Documentation.</p>
</xs:documentation>
</xs:annotation>

5.17. Specification Documentation

xs:annotation xs:documentation doc:Editors
doc:Copyright
doc:Abstract
doc:Status
doc:Keywords
doc:Section
doc:Appendix

MORPH supports inline documentation which allows a processor to generate a specification document with only the source XML Schema file. Documentation uses the namespace http://www.gamexml.org/Specs/MORPHdoc.xsd which in this document is given the prefix "doc." All documentation appears within <xs:annotation>/<xs:documentation> elements as direct children of the <xs:schema> element, and may contain XHTML markup.

Specification Documentation Node
<xs:annotation> </xs:annotation>

5.17.1. Editors

The Editors element allows the DSL author to specify one or more editors for the DSL. The element has one or more Editor elements as children, one for each editor, and each has the following attributes:

doc:Editors Node
<doc:Editors>
<Editor Name="#Editor#" Org="#Organization#" Href="#URI#"/>
(...)
</doc:Editors>

5.17.2. Copyright

The Copyright element allows the DSL to specify copyright information as printed in the specification document. The element has the following attributes:

doc:Copyright Node
<doc:Copyright Name="#CompanyName#" Year="#Year#" Href="#CompanyURI#"/>

5.17.3. Abstract

The Abstract section contains a short paragraph or two which summarizes the DSL. The abstract's content must be contained within the Content element and may contain XHTML markup.

doc:Abstract Node
<doc:Abstract>
<Content>
<p>This is the abstract.</p>
</Content>
</doc:Abstract>

5.17.4. Status

The Status section is used to indicate the current status of the specification. The content must be contained within the Content element and may contain XHTML markup.

doc:Status Node
<doc:Status>
<Content>
<p>This is the status.</p>
</Content>
</doc:Status>

5.17.5. Keywords

The Keywords section is used to provide keywords for the document. The content must be contained within the Content element and may contain XHTML markup.

doc:Keywords Node
<doc:Keywords>
<Content>
<p>Keywords</p>
</Content>
</doc:Keywords>

5.17.6. Section

The Section element allows the DSL to provide structured documentation about the DSL in general. Sections may be nested within one another to provide a hierarchical table of contents. All sections will appear at the top of the document, before the generated content.

doc:Section Node
<doc:Section Title="#Section Title#" Href="#SectionHref#">
<Content>
<p>Section content</p>
</Content>
doc:Section
</doc:Section>

5.17.7. Appendix

There may be one or more appendix elements which are always output at the end of the specification document. The Appendix section works much like a Section except that appendices may not be nested within one another.

doc:Appendix Node
<doc:Appendix Title="#Appendix Title#" Href="#AppendixHref#">
<Content>
<p>Appendix content</p>
</Content>
</doc:Appendix>


A. Related Files