Rules for Mapping Existing EDIFACT MIGs to XML DTDs

11th October 1999

The following rules should be applied when mapping an existing UN/EDIFACT Message Implementation Guide (MIG) to an XML Document Type Defintion (DTD).

The outermost element of the message should indicate the purpose of the message
- DTD developers are allowed to assign a locally meaningful name for the element.
  The UN-EDIFACT identifier for each element within the message will be indicated using the UN-EDIFACT namespace.
- The owner of the names used to identify elements and attributes within the DTD should be indicated by an xmlns namespace declaration.
  The URL specified in this namespace declaration should point either to the MIG forming the basis for the mapping, or to a separate document explaining the use of the XML version of the message.
- A pointer to the relevant UN-EDIFACT directory should be defined using an xmlns:UN-EDIFACT attribute.
  This pointer will be used to resolve all references to the directory made in attributes with this namespace.
- The set of identifiers (S009) used to identify the type of the message in the UNH segment of the message should be recorded in a namespaced property of the element with the name UN-EDIFACT:Id.
  As this information forms a unique identifier for the messsage it should be stored as one attribute value.
Example:
```
<!ELEMENT FirmBooking (MessageID, Date*, Requirements*, FreeText*,

                       TermsGroup*,  RefersTo*, GovernmentReqsGroup*,

                       ChargeRatesGroup*, TransportDetailsGroup*,

                       NameAndAddressGroup*, GoodsIdentityGroup*,

                       EquipmentDetailsGroup*)                              >

<!ATTLIST FirmBooking

          xmlns                 CDATA  #FIXED         "http://www.tieke.fi/transport/IFTMBF"

          xmlns:UN-EDIFACT      CDATA  #FIXED         "http://www.un.org/edifact/D96B/"

          xmlns:ISIS            CDATA  #FIXED         "http://www.tieke.fi/isis-xmledi"

          UN-EDIFACT:Id         CDATA  #FIXED         "IFTMBF:D:96B:UN:FI0076"

          UN-EDIFACT:Attributes CDATA  #FIXED         "0062 ReferenceNumber

                                                       0068 AccessReference"

          ReferenceNumber       CDATA                 #REQUIRED

          AccessReference       CDATA                 #IMPLIED              >
```
Note: The ISIS namespace is used to define the constraints that apply to elements. As there are no standards for defining such constraints at present this technique is currently project specific.
To be determined: Whether the S010 status identifiers need to be recorded in the message, or are part of the message transport protocol's handshake information.
Message headers and trailers should be ignored
Data elements associated with the message header should be assigned to the root element of the message.
Example: See ReferenceNumber and AccessReference attributes in example above.
Segment groups which contain a single segment should be ignored
Constraints relating to the repetition of the group should become constraints that apply to the segment that makes up the group's contents.
Example: The group referred to as GR3 in the Finnish subset of the IFTMBF message only contains a single, non-repeatable, RFF element. The group constraints can be expressed as constraints on the RefersTo element that represents the RFF element, without the addition of a specific ReferencesGroup element.
Segment groups which contain repeatable groups of elementsshould be represented by an XML element whose content model indicates the elements that form the group
- The name of the element should reflect the fact that the element defines a group.
  Normally this can be achieved by adding Group to the name.
- The name of the container element should include the name of the first compulsory element within the group.
  It is considered good practice for each group to have at least one compulsory item.
- If more than one group has the same compulsory element the name of the next element in the group should qualify the first name.
  This is only required if the group name would otherwise be ambiguous.
- Nested groups will be indicated by the presence of nested group elements within the content model of the group.
Example:
```
<!ELEMENT TransportDetailsGroup  (TransportDetails, Date*, Locations*)* >

<!ELEMENT DangerousGoodsGroup    (DangerousGoods, FreeText*,

                                  MeasurementsGroup*, SplitGoodsGroup*)* >
```

Where the structure of a segment depends on the value assigned to one of the data elements within it, the name of the segment should be replaced by the name of the value of the controlling data element

The EDIFACT name of the associated segment should be indicated by a namespaced property of the element with the name UN-EDIFACT:Segment.
The Segment qualifier allows the query to be directed to the part of the UN directory that lists segment details.
The UN-EDIFACT attributes of all elements based on a single type will be the same.
The relevant qualifier will have a fixed value indicating the name asssigned to the value of the qualifying data element.
Fixed attribute values do not need to be transmitted as part of the message as users are not permitted to override the default value.
The group element that references these element will contain the names of all elements with the same UN-EDIFACT attributes.
Not all elements with the same type need to be converted to named elements.

Example: When CustomStatus is chosen as the subject qualifier of a free text segment then, and only then, a text reference must be used.

<!ELEMENT GovernmetnReqsGroup (GovernmentRequirements, (CustomsStatus?, FreeText*)?) >

<!ELEMENT CustomsStatus (TextID) >

<!ATTLIST CustomsStatus

UN-EDIFACT:Segment    CDATA  #FIXED  "FTX"

UN-EDIFACT:Attributes CDATA  #FIXED  "4451 SubjectQualifier

                                      4453 FunctionCode

                                      3453 LanguageCode

                                      4447 FormatType"

SubjectQualifier      CDATA  #FIXED  "CustomsStatus"

FunctionCode          CDATA          #IMPLIED

LanguageCode          CDATA  #FIXED  "ISO 639"

FormatType            CDATA          #IMPLIED

ISIS:Constraints      ENTITY #FIXED  "CustomsStatus.constraints"  >

<!ELEMENT FreeText        (Line, (Line, (Line, (Line,Line?)?)?)?)    >

<!ATTLIST FreeText

UN-EDIFACT:Segment    CDATA  #FIXED  "FTX"

UN-EDIFACT:Attributes CDATA  #FIXED  "4451 SubjectQualifier

                                      4453 FunctionCode

                                      3453 LanguageCode

                                      4447 FormatType"

SubjectQualifier      (Order|Delivery|

                       Transportation|

                       CustomsDeclaration|

                       SpecialInstructions|

                       GoodsDescription|

                       DGS-AdditionalInformation|

                       DGS-TechnicalName)    #REQUIRED

FunctionCode          CDATA                  #IMPLIED

LanguageCode          CDATA  #FIXED          "ISO 639"

FormatType            CDATA                  #IMPLIED

ISIS:Constraints      ENTITY #FIXED          "FreeText.constraints"  >

Each segment should be represented by a single element
- DTD developers are allowed to assign a locally meaningful name for the element.
  The EDIFACT name of the associated segment should be indicated by a namespaced property of the element with the name UN-EDIFACT:Segment. (The Segment qualifier allows the query to be directed to the part of the UN directory that lists segment details.)
- Where the segment's contents are to be used to store the value of one of the data elements the element name should reflect the data element name..
  The name of any element containing data should indicate the role played by its contents. Where there is only one data element in the segment that is permitted to contain user-specified data this data element can be "promoted" to become the contents of the containing segment.
Example:
```
<!ELEMENT NumberOfUnits     (#PCDATA)                                        >

<!ATTLIST NumberOfUnits

          UN-EDIFACT:Segment    CDATA  #FIXED    "EQN"

          UnitsQualifier        CDATA            #IMPLIED

          ISIS:Constraints      ENTITY #FIXED    "NumberOfUnits.constraints" >
```
Where a segment contains multiple occurrences of the same composite a separate element should be declared for the composite, and the model of the containing element should indicate the number of times the composite can occur
- The model should repeat the element name once for each occurrence of the composite.
  The segment definition constrains the number of times the composite can occur within the segment.This mechanism allows that constraint to be recorded in the XML DTD.
- Where one of the composites is mandatory the first occurrence of the element listed should have no occurrence indicator.
- Conditional composites should be qualified by use of a ? optional element indicator.
  Nesting of conditional groups is encouragedfor accurate modelling of composite use constraints.
- Where the composite only contains data elements that record coded values the model of the element defined for the repeated composite can be declared to be EMPTY.
  Coded values should be recorded as attribute values - as explained below.
Example:
```
<!ELEMENT ProductIDs       (ItemID, (ItemID, (ItemID, (ItemID, ItemID?)?)?)?)   >

<!ATTLIST ProductIDs

          UN-EDIFACT:Segment    CDATA  #FIXED          "PIA"

          ISIS:Constraints      ENTITY #FIXED          "ProductIDs.constraints" >
```

Where a segment contains multiple different composites a separate element should be assigned to each composite that does not consist entirely of data elements whose values need to be assigned from coded lists

DTD developers are allowed to assign a locally meaningful name for the element.
The number of the associated composite should be indicated by a namespaced property of the element with the name UN-EDIFACT:Composite. (The Composite qualifier allows the query to be directed to the part of the UN directory that lists composite details.)

Example:


<!ELEMENT Requirements    (ContractType?, (Service, Service?)?,

                           Priority?, NatureOfCargo?)                                >

<!ATTLIST Requirements

          UN-EDIFACT:Segment    CDATA  #FIXED          "TSR"

          ISIS:Constraints      ENTITY #FIXED          "Requirements.constraints" >

<!ELEMENT ContractType   (#PCDATA)                                                >

<!ATTLIST ContractType

          UN-EDIFACT:Composite  CDATA  #FIXED          "C536"

          Qualifier             CDATA                  #IMPLIED

          Agency                (AssignedByOriginator|

                                 AssignedByCarrier)    #IMPLIED

          ISIS:Constraints      ENTITY #FIXED          "ContractType.constraints" >

Where a segment, or a composite, contains multiple uncoded data elements a separate element should be assigned to each data element
- DTD developers are allowed to assign a locally meaningful name for the element.
  The number of the associated data element should be indicated by a namespaced property of the element with the name UN-EDIFACT:Element. (The Element qualifier allows the query to be directed to the part of the UN directory that lists data element details.)
Example:
```
<!ELEMENT Service        (#PCDATA)                                            >

<!ATTLIST Service

          UN-EDIFACT:Element    CDATA  #FIXED          "7273"

          Qualifier             CDATA                  #IMPLIED

          Agency                (AssignedByOriginator|

                                 AssignedByCarrier)    #IMPLIED

          ISIS:Constraints      ENTITY #FIXED          "Service.constraints"  >
```

Each data element within a segment or composite whose value must conform to a predefined list of codes should be represented as an attribute of the element representing its containing segment

DTD developers are allowed to assign a locally meaningful name for the attribute.
The number of the associated data element can optionally be recorded in a namespaced property of the element with the name UN-EDIFACT:Attributes whose value consists of pairs of tokens in which the first member is the UN-assigned number of the data element and the second is the name of the attribute used (within this element) to record the value assigned to that data element.

Example:


<!ELEMENT MessageID       (#PCDATA)                                           >

<!ATTLIST MessageID

          UN-EDIFACT:Segment    CDATA  #FIXED      "BGM"

          UN-EDIFACT:Attributes CDATA  #FIXED      "1001 MessageTypeCode

                                                    1131 Qualifier

                                                    3055 Agency

                                                    1000 MessageTypeName

                                                    1225 MessageFunction

                                                    1056 Version

                                                    1060 RevisionNo

                                                    4343 ResponseType"

          MessageTypeCode       CDATA              #IMPLIED

          Qualifier             CDATA              #IMPLIED

          Agency                CDATA              #IMPLIED

          MessageTypeName       CDATA              #IMPLIED

          MessageFunction       CDATA              #IMPLIED

          Version               CDATA              #IMPLIED

          RevisionNo            CDATA              #IMPLIED

          ResponseType          CDATA              #IMPLIED

          ISIS:Constraints      ENTITY #FIXED      "MessageID.constraints"    >

Where the MIG limits the permitted set of attribute values a list of permitted values should be defined as part of the attribute declaration
- DTD developers are allowed to assign a locally meaningful name for the attribute value in place of the EDIFACT coded value.
  The relationship between the name of the attribute value and the equivalent coded value should be recorded in the constraints file associated with the element type.
  Note: Where the list of options is large the options should be listed in a parameter entity, which could be an external parameter entity that references a list maintained as a separate file. (See example below.)
Example:
```
<!ELEMENT Temperature      (#PCDATA)                                          >

<!ATTLIST Temperature

          UN-EDIFACT:Segment    CDATA  #FIXED          "TMP"

          UN-EDIFACT:Attributes CDATA  #FIXED          "6245 TemperatureQualifier

                                                        6411 MeasurementUnit"

          TemperatureQualifier  CDATA  #FIXED          "TransportTemperature"

          MeasurementUnit       (Celsius|Kelvin|

                                 Fahrenheit)           #IMPLIED

          ISIS:Constraints      ENTITY #FIXED          "Temperature.constraints"  >
```

Where there is no constraint on which set of values is permitted from a coded list a parameter entity definition should be used to indicate the code list from which the value should be selected
The contents of the referenced parameter entity may either be "CDATA" or "NMTOKEN", or it can be a reference to the system identifier of an external entity that contains the definition of the permitted values for the code list.

Example:


<!ENTITY % Stages "(PreCarriage|MainCarriage|FirstCarrier|

                    SecondCarrier|ThirdCarrier|OnCarriage)"  >

<!ENTITY % Directions SYSTEM "direction.txt" >

<!ENTITY % Owners     "CDATA" >



<!ELEMENT TransportDetails (ConveyanceNumber?, Mode?, Means?,

                            Carrier?, Excess?, Identification?)              >

<!ATTLIST TransportDetails

          UN-EDIFACT:Segment    CDATA  #FIXED  "TDT"

          UN-EDIFACT:Attributes CDATA  #FIXED  "8051 StageQualifier

                                                8101 DirectionCode

                                                8281 OwnershipCode"

          StageQualifier        %Stages;       #REQUIRED

          DirectionCode         %Directions;   #IMPLIED

          OwnershipCode         %Owners;       #IMPLIED

          ISIS:Constraints      ENTITY #FIXED  "TransportDetails.constraints" >

Where only one value is permitted from a code list that value should be assigned as a fixed default value for the attribute
Fixed values do not have to be transmitted with the XML message: they can be inferred from the XML document type definition (DTD).
Example: See TemperatureQualifier in Temperature example above.

Where one of the attribute values is more likely to be used than the others that value should be declared as the default value
Default values do not need to be transmitted with the message: they can be inferred from the DTDs. Attributes assigned default values only need to be specified for those occurrences for which an abnormal value is required.

Example:


<!ELEMENT Date            (#PCDATA)                                           >

<!ATTLIST Date

          UN-EDIFACT:Segment    CDATA  #FIXED          "DTM"

          UN-EDIFACT:Attributes CDATA  #FIXED          "2005 Of

                                                        2379 Format"

          Of                    (Document|Departure|

                                 Arrival)              "Document"

          Format                (Date|Period)          "Date"

          ISIS:Constraints      ENTITY #FIXED          "Date.constraints"     >

The constraints that apply to elements that contain contents should be recorded in an attribute called ISIS:Constraints that references an entity declared in the DTD that identifies an XML file containing details of the constraints to be applied
This attribute name is qualified by the ISIS name space to indicate that the structure of this XML file has been defined by the ISIS XML/EDI Pilot Project consortium rather than a recognized standards body. It is anticipated that more detailed constraints will be needed at a later stage, and that these will probably be provided by referencing XML Schemas containing relevant datatype specifications.
Note: The referenced entity must be an unparsed XML entity, not a parameter entity. The notation used for the unparsed entity will need to be defined within the DTD, but otherwise is applicaiton dependent. The exact format of the XML-encoded constraints file used within the ISIS project is still to be determined.
Example:
```
<!ENTITY   ConveyanceNumber.constraints

  SYSTEM   "../Constraints/ConveyanceNumber.xml"

  NOTATION "ISIS-Constraints"                       >

<!ELEMENT ConveyanceNumber (#PCDATA)                                        >

<!ATTLIST ConveyanceNumber

          UN-EDIFACT:Element    CDATA  #FIXED "8028"

          ISIS:Constraints      ENTITY #FIXED "ConveyanceNumber.constraints" >
```

References to parts of other messages, or other parts of the same message, should be represented as XML Simple Links using XPath locators
Where the element being referenced has a unique identifier the path should reference that identifier, e.g. xlink:href='messages/message1234//id("item2345")'. Alternatively the reference can be to an element with specific contents, e.g. xlink:href='[ReferenceNumber="Message1234"]'

Example:


<!ELEMENT RefersTo    EMPTY >

<!ATTLIST RefersTo

          UN-EDIFACT:Segment CDATA  #FIXED "RFF"

          DocType            CDATA  #REQUIRED

          DocID              CDATA  #IMPLIED

          Line               CDATA  #IMPLIED

          Version            CDATA  #IMPLIED

          RevisionNo         CDATA  #IMPLIED

          xlink:href         CDATA  #REQUIRED

          xmlns:xlink        CDATA  #FIXED "http://www.w3.org/XML/XLink/0.9"

          xlink:type         CDATA  #FIXED "simple"

          xlink:role         CDATA  #FIXED "reference"

          xlink:show         CDATA  #FIXED "new"

          xlink:actuate      CDATA  #FIXED "user"

          ISIS:Constraints   ENTITY #FIXED "RefersTo.constraints"          >