Traceable Resource Definitions (TRD)

The Traceable Resource Definitions (TRD) define the names and concepts to be used in a specific value chain. The names relate to a specific industry, a specific customer and his business objectives.These names are mapped to TraceTrackers generic concepts in the TRD. It defines the type of objects a specific value chain contains and what sort of properties these objects have.

The TRD may also be used to provide context for external input applications.

The TRD data provides an alternate view of the EPCIS event data, where the historic changes and current state of an EPC-tagged object is more important.

This section describes the TRD XML format in detail.

Changes since TIX 5

The TRD format is virtually unchanged except for a reduction of the number of data types. The different CHAR types have been merged into the TEXT type. TRACE-REF is now called EPC-REF, and a GAN-REF type to complement the ORG-REF. The old TRD format is still accepted, but only the newer format will be exported by the TIX.

Note that while TIX 5 allowed users to upload multiple TRD's and use them to segment data, TIX 6 uses only one TRD per TIX node. The TRD name is ignored except for presentation, and uploading multiple TRD's will cause them to be merged.

TRD XML Format

Document root

Example of the document root:

<?xml version="1.0" encoding="UTF-8"?>
<TRDef id="ID" version="1.0A" xmlns="http://www.tracetracker.com/trd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.tracetracker.com/trd
http://schema.tracetracker.com/ttTRD_5_0_1.xsd">
...
</TRDef>

This example declares that it is encoded using UTF-8. TIX applications use this encoding by default and everything will be converted to UTF-8 when persisted.
This XML document is declared as belonging to the namespacehttp://www.tracetracker.com/trd. All TRD XML documents MUST belong to this namespace.
Finally, the schemaLocation attribute declares that all attributes and elements that belong to the http://www.tracetracker.com/trd namespace should be validated against the XML Schema located at http://schema.tracetracker.com/ttTRD_5_0.xsd.

Elements

This section describes the different elements of the TRD XML.

TRDef

The TRDef is the root element of the TRD XML and encompasses all other elements.

Required attributes:

Required attributes	Description
id	The identifier of the TRD. Must be unique.
version	The version of the TRD. This attribute is intended for user reference only, it does not affect the behavior of the software. For example, it could be used to distinguish between successive versions of a TRD that keeps its id; similar to a car's model year. This attribute should not be confused with the version of the XML schema.
defaultType	The id of a TradeUnit type to be used as default. Whenever an EPCIS event mentions an EPC in an ObserveEvent with action=ADD, and contains no extensions specifying TRD type, the default type will be used.

Elements	Descriptions
Label	Human readable, localized labels for the TRD name.
GraphLabel	Human readable, localized labels for the TradeUnitTypes and BatchTypes when displayed in a graph. Only accepted in a BatchType or TradeUnitType. The label value can contain reference to PropertyRef Ids. Use ```${...}``` to reference a property value for given EPC. `<GraphLabel>` `<Text` `xml:lang="en">Salmon production: ${ID} - ${Temperature}C</Text></GraphLabel>` Use ```#{...}``` to reference master data for given EPC, values like `#{product-name} will be resolved by epcClass lookup for given EPC and itemRef for the BatchType or TradeUnitType.` `<GraphLabel>` `<Text xml:lang="en">Salmon production: ${ID} - #{product-name}</Text></GraphLabel>` TradeUnitType or BatchType property that are defined in the TRD with `isMasterdata=true` will be expanded by lookup of the property value in masterdata. The ```${product-name-ref}``` will be resolved to ``Frozen Salmon`` when the `product-name-ref` property is set to `urn:tracetracker:xx:prod:salmon:4`. `<GraphLabel>` `<Text xml:lang="en">Salmon production: ${ID} - ${product-name-ref}</Text></GraphLabel>` `<VocabularyElement` `id="urn:tracetracker:xx:prod:salmon:4">` `<attribute` `id="name">Frozen Salmon</attribute>` `</VocabularyElement>`
Description	Larger description of the TRD, also localized.
PropertyTypes	A collection of PropertyTypes.
PropertyGroupTypes	A collection of PropertyGroupTypes. Used for controlling the presentation of properties.
BatchTypes	A collection of BatchTypes.
TradeUnitTypes	A collection of TradeUnitTypes
StationTypes	A collection of StationTypes. (Legacy)

Example:

TRD Exammple

<?xml version="1.0" encoding="UTF-8"?>
<TRDef id="Example" version="1.0A" xmlns="http://www.tracetracker.com/trd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.tracetracker.com/trd
http://schema.tracetracker.com/ttTRD_5_0.xsd">
    <Label>
        <Text xml:lang="en">Example TRD</Text>
        <Text xml:lang="no">Eksempel TRD</Text>
    </Label>
    <Description>
        <Text xml:lang="en">This TRD is an example TRD.</Text>
        <Text xml:lang="no">Dette er en eksempel TRD.</Text>
    </Description>
    <PropertyTypes>
    ....
    </PropertyTypes>
    <PropertyGroupTypes>
    ....
    </PropertyGroupTypes>
    <BatchTypes>
    ....
    </BatchTypes>
    <TradeUnitTypes>
    ....
    </TradeUnitTypes>
</TRDef>

PropertyTypes

The PropertyTypes element define a set of PropertyType elements to be used by the traceability resources.

Optional attribute
defaultEpcisNamespace	Determines the namespace when properties are mapped to EPCIS event data where the PropertyType of the property does not have a value for attibute epcisNamespace. This attribute has a default value, so there will always be a default EPCIS namespace.

PropertyType

A PropertyType consists of a format and a name and human readable label which are required, and a description which is optional. Property types are later used to type property values attached to batches, trade units and business locations. This typing information is used by the Navigator and allows for type specific queries. The DATA-types used to limit property content, in TIX6 the properties are created from event extensions.

Required attributes	Description
id	The identifier of the PropertyType Must be unique for this TRD.
format	The property type format
Optional attributes	Description
unit	Specifies a physical unit of measurement.
remove	Specify the value "true" to request this property type to be removed from an existing TRD. A property type cannot be removed if it is referenced by a PropertyRef element.
epcisNamespace	If present, the value of this attribute will determine the namespace of the extention element when a property of this type is mapped to EPCIS event data.
isMasterData	If this attribute has the value true, then properties of this type will not be mapped to EPCIS event data, but will be populated through MasterData-queries.

Example:

<TRDef id="Example" version="1.0A" xmlns="http://www.tracetracker.com/trd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.tracetracker.com/trd
http://schema.tracetracker.com/ttTRD_5_0.xsd">
    <Label>
        <Text xml:lang="en">Example TRD</Text>
        <Text xml:lang="no">Eksempel TRD</Text>
    </Label>
    <PropertyTypes>
        <PropertyType format="REAL" id="temp" unit="celsius">
            <Label>
                <Text xml:lang="en">Temperature</Text>
                <Text xml:lang="no">Temperatur</Text>
            </Label>
        </PropertyType>
        <PropertyType format="DATETIME" id="Arrival_date">
            <Label>
                <Text xml:lang="en">Arrival Date</Text>
                <Text xml:lang="no">Ankomst dato</Text>
            </Label>
        </PropertyType>
    </PropertyTypes>
</TRDef>

This example defines two property types. One type named "temp" in a "REAL" format which is used for holding floating point numbers, with a "celsius" unit and another date property named "Arrival_date". Note that the usage of "celsius" does not require property values of this property type to be in "degrees celsius". This default unit will be used to normalize extensions matching this property type. If the extension does not conform to this unit, it will not be converted into a PropertyValue.

There are 10 property formats:

Format name	Description
TEXT	A text of arbitrary length
NUMBER	An integer value
REAL	A real number (IEEE-754). Scientific notation (1.0E+32) is also supported.
DATE	A date, on the format yyyy-MM-dd
DATETIME	A date and time, yyyy-MM-ddThh:mm:ss.sssZ Timezone is required, millisecond are optional.
URI	A Uniform Resource Identifier.
EPC-REF	An EPC referencing another entity.
ORG-REF	A reference to an organization. A GLN, ORD-ID or a local alias.
GAN-REF	A reference to a TIX node.
GEOLOCATION	A location on the globe in latitude, longitude. i.e 40°26'21"N 79°58'36"W See the appendix for more examples of accepted coordinate formats.

The EPC-REF, GAN-REF and ORG-REF types are not validated against existing data during import. It is perfectly legal to refer to non-existing trade units, batches, business locations and organizations. They are still helpful because they convey the fact that a property value is a reference.

PropertyGroupType

A PropertyGroupType defines a logical grouping of properties. It must have a human readable Label element and can optionally have a more verbose Description. This element only defines the group, when one uses PropertyRef elements on a TradeUnit or Batch one can assign each property to one of the defined groups. It is also possible to specify the ordering between the different property groups.

Required attributes:	Description
id	The identifier of the PropertyGroupType. Must be unique within the TRD.
Optional attributes:	Description
ordering	Specifies the ordering for a property group type in relation to other property group types.

Example of PropertyGroupTypes

<PropertyGroupTypes>
    <PropertyGroupType id="supplier-info" ordering="1">
        <Label>
            <Text xml:lang="en">Supplier Info</Text>
        </Label>
    </PropertyGroupType>
    <PropertyGroupType id="type-info" ordering="2">
        <Label>
            <Text xml:lang="en">Type of Trade unit</Text>
        </Label>
    </PropertyGroupType>
</PropertyGroupTypes>

PropertyRef

PropertyRefs are child elements of TradeUnitTypes, BatchTypes or StationTypes. They specify the possible presence of a Property on a TradeUnit, Batch or Station as well as grouping and ordering of properties.

Required attributes:	Description
id	The identifier of the PropertyRef. It must correspond to the id of one of the PropertyTypes defined in the TRD.
Optional attributes:	Description
remove	Specify a value of true to request that this property reference be removed from the TradeUnit, Batch or Station.
group	The group this property reference should belong to. The value of this attribute must correspond to an id of a PropertyGroupType defined in this TRD.
ordering	An integer specifying the ordering of this property reference in relation to other property references on this TradeUnit, Batch or Station. If grouping is used, the ordering is relative to the other property references within the group.
occurrence	There are four possible options for specifying the occurrence of a property reference; required, recommended, implied and static. Required means that the property reference have to be present, while both recommended and implied means optional. There is currently no functionality that differentiates these two. Static is not supported.

Example of use of PropertyRef

<TradeUnitType id="Packing" tradeunit-class="basic">
    <Label>
        <Text xml:lang="en">Packing</Text>
    </Label>
    <PropertyRef id="Supplier" occurrence="required" ordering="2" group="supplier-info"/>
    <PropertyRef id="OrderNo" occurrence="required" ordering="1" group="supplier-info"/>
    <PropertyRef id="Type" occurrence="required" ordering="1" group="type-info"/>
    <PropertyRef id="Material" occurrence="required" ordering="2" group="type-info"/>
</TradeUnitType>

Batches and TradeUnits

Batch and trade units are two kinds of traceable entities. They are the basic objects used to model the traceability chain.

Batch is an object of production. It has a type and a set of properties. It is used to model ingredients and raw material used in production and the results of the production process.

TradeUnit is, as the name suggests, a unit of trade. It may represent a large bulk of smaller trade items, but the TradeUnit is the smallest set of objects that can be uniquely identified. This means that a TradeUnit may exist at several physical locations at the same time. Ideally each physical object should be uniquely identified, but information to do this may not exist. The main difference between batches and trade units is that trade units can be traded between organizations. Anything traded between organizations is by definition a trade unit.

A consequence of this is that raw materials and ingredients received from other organizations to be used in production, will always be received as trade units.

A TradeUnitCluster is a usually contained set of TradeUnits or other TradeUnitClusters. It can be used to model pallets or boxes. It is typically used where a group of objects are inside a container making the content invisible and untraceable, while the external container is not. A Cluster may be heterogeneous, containing Trade units of multiple types, and may be used for modeling "virtual" grouping like a shipment.

BatchTypes

BatchTypes are used to define the properties of the batches defined in the data import files. All batch types must be inclosed in a <BatchTypes> element.

Required attributes:	Description
id	The identifier of the BatchType. Must be unique for this TRD.
Optional attributes:	Description
batch-class	Class of batch. Only the class "basic" is used, and is also the default.
production-batch	The production-batch attribute can be either "true" or "false. Declaring a BatchType as a production-batch signifies a special importance. Production batches will be shown in the global batch view, if permitted by the access control configuration.
visible	The visible attribute can be either "true" or "false. Declaring a BatchType as visible signifies a special importance. Visible batches will be shown in the global batch view, if permitted by the access control configuration.
remove	Specify the value "true" to request this batch type to be removed from an existing TRD. A batch type cannot be removed if it is referenced by existing traceability data.
itemRef	If present, this value should identify an EPCIS vocabularyelement (which may have master data attributes associated with it) that will apply to all Batches of this type. If a Batch has a value for its itemRef attribute, that will override any value present for this BatchType. An itemRef may contain parameters of the form $foo or ${foo} which will be replaced with matching properties of the TradeUnit/Batch in question. Given a pattern "urn:epc:id:n:dummy.$articlenumber.*" $articlenumber will be replaced with the content of the property value with a property type with id "articlenumber".
graphImage	If present this URI is assumed to reference an image that will be used when representing this batch type in a graph. The size of the image is 50 pixels wide by default (height is derived from this value keeping the image proportional) but it's possible to specify alternate sizes using key/value pairs after a # suffix. Example value: "http://www.google.com/images/srpr/logo11w.png#width=100,height=50" In case your source graphics is non-transparent it's possible to specify a mask color and tolerance which will be used to make parts of the image transparent. Example value: "http://www.tamaraclark.com/images/salmon.png#width=150,mask=ffffff,tolerance=20"

BatchTypes must contain a <Label> element and may contain a <Description> element. Also, any
number of <PropertyRef> elements may be included.

Example:

<TRDef id="Example" version="1.0A" xmlns="http://www.tracetracker.com/trd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.tracetracker.com/trd http://schema.tracetracker.com/ttTRD_5_0.xsd">
    <Label>
        <Text xml:lang="en">Example TRD</Text>
        <Text xml:lang="no">Eksempel TRD</Text>
    </Label>
    <PropertyTypes>
        <PropertyType format="REAL" id="Degrees" unit="celsius">
            <Label>
                <Text xml:lang="en">Amount</Text>
                <Text xml:lang="no">Antall</Text>
            </Label>
        </PropertyType>
        <PropertyType format="DATETIME" id="Arrival_date">
            <Label>
                <Text xml:lang="en">Arrival Date</Text>
                <Text xml:lang="no">Ankomst dato</Text>
            </Label>
        </PropertyType>
    </PropertyTypes>
    <BatchTypes>
        <BatchType id="rawmat" batch-class="basic" production-batch="true">
            <Label>
                <Text xml:lang="en">Raw material</Text>
            </Label>
            <GraphLabel>
                 <Text xml:lang="en">Raw material ${ID} - ${Degrees}C</Text>
            </GraphLabel>
            <Description>
                <Text xml:lang="en">Raw material for production</Text>
            </Description>
            <PropertyRef id="Degrees" occurrence="required"/>
            <PropertyRef id="Arrival_date" occurrence="recommended"/>
        </BatchType>
    </BatchTypes>
</TRDef>

This example declares a BatchType by the name of "rawmat" as a basic class and a production batch. It specifies that batches of this type should have a property of type "Degrees" and may have a property of type "Arrival_date". These property-ref names referr to the PropertyTypes declared earlier.

Trade Unit

TradeUnitTypes are used to define the properties of the trade units defined in the data import files. All trade unit types must be inclosed in a <TradeUnitTypes> element.

Required attributes:	Description
id	The identifier of the TradeUnitType. Must be unique for this TRD.
Optional attributes:	Description
tradeunit-class	Class of trade unit. Two classes exists "basic" and "cluster". A cluster is a container which can be used to describe a grouping of other trade units. If omitted, a "basic" type will be assumed.
remove	Specify the value "true" to request this trade unit type to be removed from an existing TRD. A trade unit type cannot be removed if it is referenced by existing traceability data.
itemRef	If present, this value should identify an EPCIS vocabulary element (which may have master data attributes associated with it) that will apply to all TradeUnits of this type. If a TradeUnit has a value for its itemRef attribute, that will override any value present for this TradeUnitType. An itemRef may contain parameters of the form $foo or ${foo} which will be replaced with matching properties of the TradeUnit/Batch in question. Given a pattern "urn:epc:id:n:dummy.$articlenumber.*" $articlenumber will be replaced with the content of the property value with a property type with id "articlenumber".
graphImage	If present this URI is assumed to reference an image that will be used when representing this batch type in a graph. The size of the image is 50 pixels wide by default (height is derived from this value keeping the image proportional) but it's possible to specify alternate sizes using key/value pairs after a # suffix. Example value: "http://www.google.com/images/srpr/logo11w.png#width=100,height=50"

Example:

Example

<TRDef id="Example" version="1.0A" xmlns="http://www.tracetracker.com/trd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.tracetracker.com/trd http://schema.tracetracker.com/ttTRD_5_0.xsd">
    <Label>
        <Text xml:lang="en">Example TRD</Text>
        <Text xml:lang="no">Eksempel TRD</Text>
    </Label>
    <PropertyTypes>
        <PropertyType format="REAL" id="Degrees" unit="celsius">
            <Label>
                <Text xml:lang="en">Amount</Text>
                <Text xml:lang="no">Antall</Text>
            </Label>
        </PropertyType>
        <PropertyType format="DATETIME" id="Arrival_date">
            <Label>
                <Text xml:lang="en">Arrival Date</Text>
                <Text xml:lang="no">Ankomst dato</Text>
            </Label>
        </PropertyType>
    </PropertyTypes>
    <TradeUnitTypes>    
        <TradeUnitType id="product" tradeunit-class="basic">
            <Label>
                <Text xml:lang="en">Product</Text>
            </Label>
            <GraphLabel>
                 <Text xml:lang="en">Product ${ID} - ${Degrees}C</Text>
            </GraphLabel>
            <Description>
                <Text xml:lang="en">Finished product for shipping</Text>
            </Description>
            <PropertyRef id="Degrees" occurrence="required"/>
            <PropertyRef id="Arrival_date" occurrence="recommended"/>
        </TradeUnitType>
    </TradeUnitTypes>
</TRDef>

This example declares a TradeUnitType by the name of "product" as a basic class. It specifies that trade units of this type must have a property of type "Degrees" and may have a property of type "Arrival_date". These property-ref names referr to the PropertyTypes declared earlier.

Using attachments

An attachment is a file or document associated with the property of a tracible entity. Each batch and tradeunit may have zero or more attachments.

Attachments must be referenced with a HTTPS URL in XML documents. In a TIX application, the user is redirected to the attachment in a new window when clicking on the link.

Defining attachments in the TRD

Each attachment is modeled as a PropertyType in the TRD, e.g:

<PropertyType format="URI" id="ProductCertificate">
    <Label>
        <Text xml:lang="en">Attachment</Text>
        <Text xml:lang="no">Vedlegg</Text>
    </Label>
</PropertyType>

Each attachment type needs its own PropertyType in the TRD.

Attachments are referred to in BatchType or TradeUnitType using PropertyRef, e.g:

<BatchType id="AttachmentTest" batch-class="basic">
    <Label>
        <Text xml:lang="en">Attachment</Text>
        <Text xml:lang="no">Vedlegg</Text>
    </Label>
    <Description>
        <Text xml:lang="en">Attachment description</Text>
        <Text xml:lang="no">Vedleggsbeskrivelse</Text>
    </Description>
    <PropertyRef id="ProductCertificate" occurrence="required"/>
</BatchType>

A file attachment is defined in the import file like this:

<ObjectEvent>
    <eventTime>2012-01-01T12:00:00Z</eventTime>
    <eventTimeZoneOfset>+00:00</eventTimeZoneOffset>
    <epcList>
        <ecp>example-epc</epc>
    </epcList>
    <action>OBSERVE</action>
    <tt:ProductCertificate>https://somewhere.tracetracker.com/example_certificate.pdf</tt:ProductCertificate>
</ObjectEvent>

Units

For property types of format REAL or NUMBER a unit of measurement may be specified. This places a limit on which units may be used for those properties when describing a batch or a trade unit. A batch with a property with the unit "kilogram" type may only hold values of weight-type units, for instance pounds. While a property with the "litre" unit may only hold values of this type or other volume.

It is possible to specify expressions of units (m/s, mg/kg, etc).