# Appendix D: Notes on Related Technologies

This partially normative appendix highlights technologies leveraged within SIF or related to SIF, either in their entirety or as a subset. It points out specifics casual readers of referenced documents on these technologies must not ignore when implementing SIF Zone Integration Servers and Agents.

## D.1 SIF and HTTP(S)

SIF uses a small subset of HTTP 1.1 (SIF HTTP), as defined in Infrastructure Transport Layer , to promote interoperability. This section also defines a secure transport for SIF HTTP, SIF HTTPS, the required and default transport layer for use in SIF.

## D.2 SIF and URLs

Zone Integration Servers and Push-mode Agents, when using SIF HTTPS or SIF HTTP, are addressable by an `http` or `https` Uniform Resource Locator (URL). As far as HTTP is concerned, these are simply formatted strings; no assumptions should be made about their format (e.g. that all ZIS URLs consist of a host, port and Zone ID, or that all agent URLs consist of a host, port and Agent ID) beyond the `http` and `https` schemes and the consituent parts from the generic URI (Uniform Resource Identifier) syntax [RFC 2396].

`http://` host[`:`port][abs_path[`?`query]]
`http://`host[`:`port][abs_path[`?`query]]

Just because one Zone Integration Server seems to follow a certain convention with regard to its URLs, e.g.:

`http://www.YourZIS.com/YourZone`

does not imply another Zone Integration Server will not have a completely different format for a URL, for instance:

`http://www.ZISesAreUs.com:8080/applications/ZIS;version=2.3.1?zone=ZoneA&cust=2A9823B2`

or that a vendor's product might not change its URL conventions.

The same applies to URLs that address Push-mode Agents; conventions for URLs, within the general formatting that applies to URLs, can and do vary widely.

Zone Integration Servers and Agents MUST treat SIF HTTPS and SIF HTTP URLs as whole strings, whose only format rules stem from associated standards. This promotes interoperability as Zone administrators deploy Zone Integration Servers and Agents with different Zone configurations and products from different vendors.

## D.3 SIF and XML

With its use in both Infrastructure and the SIF Data Model, SIF is greatly dependent on the structure and syntax of XML 1.0 [XML]. SIF excludes the use of the `doctypedecl` syntax from the optional `prolog` with which every XML document may begin. This implies that Zone Integration Servers and Agents MUST NOT reference an external DTD or internal DTD subset using the `doctypedecl` production (e.g. `<!DOCTYPE SIF_Message ... !>`).

This should not be construed to imply that the rest of the XML `prolog` may not preface a SIF message, even though it never occurs in examples within this specification, being superfluous within SIF. As SIF mandates the use of XML 1.0, the character encoding of `UTF-8` (contained in the HTTP `Content-Type` header), and all SIF messages are `standalone` due to the exclusion of `doctypedecl` above, the values that can be communicated in the XML `prolog` are fixed within SIF. This implies that if a Zone Integration Server or Agent includes an XML `prolog` before a SIF message, it MUST take one of the following or equivalent forms (equivalent including case-insensitive character encoding names, XML's choice with regard to single or double quotes and optional spacing):

`<?xml version="1.0"?>`
`<?xml version="1.0" encoding="UTF-8"?>`
`<?xml version="1.0" standalone="yes"?>`
`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`

## D.4 SIF and Unicode

The character set supported in XML 1.0 is Unicode/ISO 10646, a character set designed to be universal in nature with regard to its support for previously used character sets in the computer industry, ability to represent most human languages, numbers, commonly used symbols, etc. Thus the character set supported in SIF is Unicode/ISO 10646. If a Zone Integration Server or SIF-enabled application does not support Unicode/ISO 10646 internally, it MUST map Unicode/ISO 10646 to its local character set upon receipt of a SIF message and MUST map its local character set to Unicode/ISO 10646 when sending or responding to a SIF message. To promote interoperability and prevent loss of data in these conversions, it is RECOMMENDED that all Zone Integration Servers and SIF-enabled applications support Unicode/ISO 10646.

SIF HTTP further requires that the Unicode/ISO 10646 character set be encoded using the UTF-8 character encoding; Zone Integration Servers and Agents MUST encode SIF XML messages using UTF-8. To further promote interoperability, when the SIF Infrastructure or Data Model specifies that an octet/byte-based transformation of a text/string value be stored in a given element or attribute (e.g. Base64 encoding, hash value, encrypted form), Zone Integration Servers and Agents MUST convert the local character set of the value to Unicode/ISO 10646 if necessary, encode the resulting value using UTF-8, then apply the specified transformation.

## D.5 SIF and XPath

SIF uses a small subset of XPath 1.0 [XPATH] in its own path syntax for referencing elements/attributes. This is defined in SIF_Element Syntax. This document may often use the same notation in referring to nested elements and/or attributes (e.g. `Name/FirstName`, `Name/@Type`), though it may include an object as the root element whereas the SIF_Element syntax does not (e.g. `StudentPersonal/Name/FirstName`, `StudentPersonal/@RefId`).

## D.6 SIF and XML Schema

SIFA hosts and provides XML Schemas [SCHEMA] for validating SIF messages, should Zone Integration Servers or Agents choose to perform message validation. These schemas leverage basic data types and structures as defined in that document. When these types and structures are referenced in this document they are prefixed with `xs:`.

Note that due to the ability of Zone Integration Servers and Agents to omit elements from data objects in the SIF Request/Response and SIF Event models, all elements defined as mandatory for SIF data objects in Infrastructure or Data Model and referenced common elements are defined as optional in the schema for validating any SIF_Message. SIFA hosts and provides alternate schemas that allow for validation of these data objects where mandatory elements cannot be omitted (e.g. in a `Add` event or in a `SIF_Response` where the `SIF_Request` did not specify a specific subset of elements to be returned from matching objects).

Notes on specific XML Schema types follow:

### D.6.1 xs:boolean

Agents and Zone Integration servers SHOULD send values of `true` or `false`, but must understand equivalent `1` and `0` values.

### D.6.2 xs:time

Agents and Zone Integration Servers MUST specify a time zone offset from UTC or indicate that the time is UTC unless the time zone is apparent locally from other elements/attributes per supplied documentation.

### D.6.3 xs:date

Agents and Zone Integration Servers MAY specify a time zone offset or indicate UTC for dates, but in most cases do not need to do so unless zone activity spans great international distances.

### D.6.4 xs:dateTime

Agents and Zone Integration Servers MUST specify a time zone offset from UTC or indicate that the time is UTC unless the time zone is apparent locally from other elements/attributes per supplied documentation.

Though use of a combined `xs:dateTime` may seem a natural fit for specifying a point in time, some SIFA working groups and task forces prefer to separate `xs:dateTime` into element/attribute pairs of `xs:date` and `xs:time` per their object design/usage goals and/or for simplified quering. Applications wishing to query the date or time portion of `xs:dateTime` values may use comparison and boolean operators to do so.

## D.7 SIF and XML Namespaces

Namespaces allow XML elements and attributes to be organized into units that allow for the separation of a set of names from others, effectively allowing the integration of XML defined from various sources to be included in the same XML document without risk of name/definition collisions. SIF has since its initial release used the default namespace attribute `xmlns` [XMLNS] in the `SIF_Message` element. To a namespace-aware parser, the effective names of the elements in:

<SIF_Message Version="1.5r1" xmlns="http://www.sifinfo.org/infrastructure/1.x"> <SIF_Event>...</SIF_Event> </SIF_Message>
Example D.7-1: SIF_Message Namespace

are conceptually:

- `http://www.sifinfo.org/infrastructure/1.x:SIF_Message`
- `http://www.sifinfo.org/infrastructure/1.x:SIF_Event`

with the local names:

- `SIF_Message`
- `SIF_Event`

To a namespace-aware parser, the effective names of these same elements in the SIF `2.x` namespace:

<SIF_Message Version="2.2" xmlns="http://www.sifinfo.org/infrastructure/2.x"> <SIF_Event>...</SIF_Event> </SIF_Message>
Example D.7-2: SIF_Message Namespace

are conceptually:

- `http://www.sifinfo.org/infrastructure/2.x:SIF_Message`
- `http://www.sifinfo.org/infrastructure/2.x:SIF_Event`

with the local names:

- `SIF_Message`
- `SIF_Event`

A namespace-unaware parser simply interprets elements by their local names, and SIF 1.x and SIF 2.x elements are considered equivalent. If the local name is prefixed, a namespace-unaware parser considers the prefix and colon part of the name. To a namespace-unaware parser, `xml:lang` is named just that. To a namespace-aware parser, this is effectively `http://www.w3.org/XML/1998/namespace:lang` (the `xml` prefix is reserved in XML 1.0 and is always bound to this namespace in [XMLNS]) with a local name of `lang`.

Given the timing of the first release of SIF and the release of Namespaces in XML [XMLNS] it was never mandated in SIF that Zone Integration Servers and Agents be namespace-aware. Given the number of Zone Integration Servers and Agents that may at this point be namespace-unaware, it is not yet mandated that these components be namespace-aware, but this requirement may arise in a future major release of this specification. To allow for namespace-unaware parsers to reliably process SIF-defined XML by local names only, SIF messages MUST define the namespace for the corresponding SIF version as the default namespace of `SIF_Message` as documented in `SIF_Message`.

Furthermore, given the gradual proliferation of XML defined in other namespaces appearing in SIF XML, the following prefix-to-namespace mappings MUST be used should elements from these namespaces occur in SIF messages, to allow namespace-unaware parsers to reliably interpret names in these namespaces by local name:

Prefix | Namespace | Declaration
--- | --- | ---
`xml` | `http://www.w3.org/XML/1998/namespace` | This is bound and fixed by default without declaration.
`xsi` | `http://www.w3.org/2001/XMLSchema-instance` | `xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"`
`xs` | `http://www.w3.org/2001/XMLSchema` | `xmlns:xs="http://www.w3.org/2001/XMLSchema"`

It is RECOMMENDED that other namespaces occuring in SIF messages (e.g. XML from outside SIF included in assessments, exchange of student records, etc.) have fixed prefix mappings, but it is not required. Affected elements MAY locally change the default namespace as desired, given that the default namespace for the `SIF_Message` as a whole remains the namespace for the corresponding SIF version.

When a fixed prefix is not defined for a given namespace, a namespace-unaware agent will be unable to reliably process these elements by name when prefixes vary, and must become namespace-aware to do so. XML not defined by SIF that in turn contains SIF-defined XML MAY reference SIF XML by its own prefix mapping rather than specifying the namespace of the corresponding SIF version as the default namespace using `xmlns`.

It is RECOMMENDED that as Zone Integration Servers and Agents are updated in their release schedules, they use namespace-aware parsers or parser options if they are not doing so already.

## D.8 SIF and UUIDs/GUIDs

SIF leverages Universally Unique Identifiers (UUIDs), or Globally Unique Identifiers (GUIDs), as message and object identifiers, or primary keys, and occasionally for element identifiers internal to objects, per [RFC 4122]. Note that SIF defines its own textual representation for GUIDs, uppercase and un-hyphenated (e.g. `F81D4FAE7DEC11D0A76500A0C91E6BF6` vs. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`). It should also be noted with SIF being a distributed system, to avoid the possibility of GUID collisions, especially in the SIF data model, systems generating GUIDs SHOULD use version 1 GUIDs which are unique in space as well as time when an IEEE 802 MAC address is available. Systems MAY use version 4 GUIDs which use a (pseudo-)random number-based algorithm if an IEEE 802 MAC address is unavailable or if the inclusion of that address in a GUID poses a compromising security risk.

## D.9 SIF and Web Services

SIF is a web service, "a software system designed to support interoperable machine-to-machine interaction over a network [WSARCH]." It is not a Web Service, as it lacks "an interface described in a machine-processable format (specifically WSDL) [WSARCH]." To meet this requirement and produce the Web Services Definition Language (WSDL) definition for SIF is a trivial exercise, creating a WSDL HTTP POST binding for the `SIF_Message`-in/`SIF_Message`-out exchange that describes the SIF HTTP(S) transport layer between Agents and ZIS, and between ZIS and Push-mode Agents. But the binding would be just that, a simple `SIF_Message`-in/`SIF_Message`-out exchange that doesn't capture the richness of the SIF infrastructure or necessarily provide the interoperability resulting from the precise definition of SIF HTTP(S). To do so and to meet the final requirement of a Web Service per [WSARCH], the use of SOAP messages, would require redefinition of much of SIF using SOAP messages. SIFA's Web Services Task Force has determined that this exercise has little value currently, given SIF's precisely defined transport layer and installed base. The task force has left it as a future task how to best leverage Web Services in the future of SIF's infrastructure, if at all. In the meantime, the task force has, however, decided to provide a Web Services interface that provides external systems access to the rich amount of data available in SIF Zones via its own specification [SIF Reporting WS]. Future opportunities to provide additional services may be identified.