# 3 Data Model

## 3.1 Introduction

This section presents the XML structure for SIF Data Model common elements and objects in a tabular format for readers less versed in parsing formal XML schema definitions, along with conventions that typically apply in the data model for easy reference.

### 3.1.1 Format

The Char(acteristics) column for all of the tables in this section use the following codes:

Code | Characteristic
M | Mandatory element or attribute
O | Optional element or attribute
C | Conditional element or attribute
MR | Mandatory and repeatable element
OR | Optional and repeatable element
CR | Conditional and repeatable element

Mandatory elements MUST be present in Add events, and in non-empty and non-error responses to requests for entire SIF objects (e.g., no `SIF_Query/SIF_QueryObject/SIF_Element` elements supplied in the request). Mandatory attributes MUST always be present if their corresponding element is present.

SIF Adapters and message brokers MUST supply data according to the types specified in the Type columns and their corresponding equivalents in the most recent schema files associated with this specification. If there is a discrepancy between object and element definitions in this specification and the corresponding schema files, the definition in the schema files takes precedence; every effort will be made to note discrepancies in the errata for this document as they are identified.

### 3.1.2 Conventions

#### 3.1.2.1 Object Attributes/Primary Keys

While XML attributes are primarily used in SIF to provide additional processing information regarding the associated element content, attributes at the root level of an object have special significance. These attributes serve as the primary key or identifier for the object; in all cases this is no more than a `RefId` GUID of `RefIdType`

#### 3.1.2.2 Object References

As stated elsewhere, SIF primarily uses GUIDs as object identifiers, primary keys, or `RefId`s. References to primary keys (foreign key references) follow certain conventions in SIF in most objects:

- An element or attribute of type `IdRefType` can be defined that consists of the referenced object name concatenated with `RefId`, e.g., `DataPersonalRefId` (a reference to the object identifier/primary key/`RefId` of a `DataPersonal` object);
- An element requiring a more descriptive name for the reference or one that refers to more than one object type is defined as `IdRefType`, has an element name of a group's choosing (or generically `SIF_RefId`) and enumerates all possible object types that can be referenced in the `SIF_RefObject` attribute; or
- A pair of attributes can be defined, one of type `IdRefType` containing the referenced object's `RefId`, the other enumerating all possible object types that can be referenced; generically these are named `SIF_RefId` and `SIF_RefObject`, respectively; naming conventions that programmatically allow identification of the pair beyond the generic names will be documented when the need arises.

#### 3.1.2.3 Lists/Repeatable Elements

To those accustomed with normalized relational databases, the SIF Data Model will appear to not be especially normalized, especially with regard to repeating groups of data not being separated into their own "tables," or in SIF's case, "objects" with primary/foreign keys to maintain the relationship. Bear in mind that SIF is not a format for storing data; it is a format for transmitting data asynchronously between disparate and distributed systems needing to share data for interoperability; the format this data takes in different systems can vary greatly, and the data related to any given "entity" may come from a variety of sources and systems. The goals of normalization—eliminating redundancy, organizing data efficiently, reducing inconsistencies, etc.—take on a different meaning in a message queuing system. Of primary importance is transmitting the data needed for interoperability in a minimum number of messages. The need to "join" together a great number of separate objects is kept to a minimum in SIF, as individual systems do not have access to all the data required and due to the asynchronous nature of SIF, any one of these systems may take a fair amount of time before returning data necessary for joins (`SIF_ExtendedQuery` has been developed to communicate a join to a single system that may have direct access to the all the data necessary to efficiently accomplish this task). It's one thing to make a separate request for a student's picture or enrollment information, another entirely to request every available phone number, address and e-mail address separately from the SIF Environment. As such, it is often the case in SIF that repeating data is stored directly in an object, rather than being separated out into a separate object.

Repeating data is very analogous to objects, though, within any given object. In SIF's Publish/Subscribe model, repeating elements in objects can be added to, changed in or deleted from an object, much like objects can be added to, changed in or deleted from a SIF Environment. Within an existing object, all of these actions take place within a `Change` event, and repeating elements—if any exist initially—are first made available within an object in an `Add` event or can be obtained directly via requests. Repeatable elements are contained within a parent List element in most SIF objects whether or not they support events, e.g.:

##### 3.1.2.3.1 List

While a unique, primary key may still be identifiable in its child elements, a List is used primarily when:

- the list is a cohesive whole conceptually, where supporting or referring to a subset of the list is of little value;
- when the list consists only of keys, and no associated data;
- the list is informational/temporary state information and not typically persisted; or
- when no key exists to uniquely identify items in the list.

Lists are always transmitted as a cohesive unit consisting of the parent list container element and all child elements. If no child elements exist in the list, the list consists of the container element alone. Omission of an optional List in an `Add` event also implies no list items. In a `Change` event, omission of the List indicates no changes have been made; otherwise the parent container element and all child elements, if any, are included. Systems storing List data should replace all corresponding data in their systems when persisting the list; likewise when a change is made to one or more list items or when all items in the list are deleted, systems should send the whole list in a `Change` event.

JSON
{ "CountriesOfCitizenship": { "CountryOfCitizenship": [ "US", "DE" ] } }
XML
<CountriesOfCitizenship> <CountryOfCitizenship>US</CountryOfCitizenship> <CountryOfCitizenship>DE</CountryOfCitizenship> </CountriesOfCitizenship>
Example 3.1.2.3.1-1: Indicating an updated list of country citizenships

A system that supports `CountriesOfCitizenship` updates its local data to reflect United States and German citizenship.

### 3.1.3 Validation

#### 3.1.3.1 Supported Optional Elements Without Values

Some agents follow the convention of supplying an optional element as empty (e.g. `<BirthDate></BirthDate>` or `<BirthDate/>` to indicate that the application supports the element, but that it currently has no value available within a given object. To allow for this convention within SIF—as in this example an empty string does not satisfy the `xs:date` type definition of `BirthDate`—all optional elements in SIF are defined as `nillable` [SCHEMA]. To satisfy type constraints on an element while still supplying an empty or "nil" value, agents MUST tag the element with a `true` value for the `nil` attribute from namespace `http://www.w3.org/2001/XMLSchema-instance` [SCHEMA] (e.g. `<BirthDate xsi:nil="true"/>` where the prefix `xsi` has been mapped to the namespace `http://www.w3.org/2001/XMLSchema-instance`), unless an empty value is valid with regard to the element's type definition, in which case supplying the `nil` attribute value of `true` is optional.

#### 3.1.3.2 Externally-Defined XML

Note that XML not defined within SIF does not necessarily support ad hoc omission of XML elements at will to conform with the conventions of the SIF Publish/Subscribe Model (where unchanged elements are typically omitted in Change events, and where non-key elements are often omitted in Delete events) or of the SIF Request/Response Model (where a subset of elements can be retrieved from objects with requests). If externally-defined XML occurs within a SIF data object, SIF conventions do not extend to that XML unless that XML is defined to accommodate SIF conventions; the XML, when transmitted, must only conform to any external definitions dictating its structure, if any. Applications should be prepared for the possibility of receiving whole externally-defined XML structures in Change events (regardless of how little or much of the external XML has changed) and possibly also Delete events, likewise in responses even when a subset of the XML structure's child elements may have explicitly been requested.

#### 3.1.3.3 Payload Validation

There are two sets of XSDs available for Validation of Payload.

##### 3.1.3.3.1 Create

The first set, "DataModel" is 'strict' and all of the elements that are required for validation are 'Mandatory' in this suite of XSDs. This suite is traditionally used for Creation of new entities, which generally require validation before being saved into a Data Store.

##### 3.1.3.3.2 Update

The second set, "SIF_Message" is 'lax' and every element within the schema is 'optional' except the 'RefId' the identifying GUID/UUID. (However, required elements are not nillable.) This suite of XSDs are traditionally used for Update and Delete of current entities. If an element is not included in the payload of an Update operation, its value is assumed to be unchanged. In additon, if the payload contains the RefId/UUID only, the consumer must assume that object to be DELETED or that it has been deleted since the original request was made.