SSRF defines the XML document and business processes but not the method of exchange.
Introduction
The following definitions are used when discussing SSRF document handling:
- The word “document” follows the XML definition, ie the set of elements from <SSRF> to
</SSRF> included.
- The word “package” designates an electronic package of information including the SSRF
“document” and any attached files.
The challenge for the SSRF standard is to be able to adapt to a variety of scenarios and approaches to
sharing information across a wide variety of systems ranging from disconnected laptops to high
speed, interconnected central repositories. SSRF supports interoperability between connected and
disconnected systems. The important aspect is for information to be shared in a controlled and
structured manner.
Due to the variety of environments and constraints within each organization and operational area,
this standard cannot and does not mandate the way in which SSRF documents are transmitted; in particular
it does not mandate specific transport and security protocols.
However, SSRF provides a number of core principles and processes
which MUST be followed by every organization when implementing SSRF compliant capabilities to
ensure interoperability.
SSRF Document Distribution
This standard supports many different scenarios, both as an internal communication mechanism to
support sharing of information between internal systems within an organization as well as
interoperability with external agencies/organizations and other nations.
The Figure above provides a summary of the different communication mechanisms that MAY be used to
share information. Despite these approaches all containing their own rules, they are all similar in
that a data file (in this case XML) can be moved from location A to location B.
SSRF System Connectivity Scenarios
The connectivity between national and international spectrum management systems vary greatly.
The Figures in this paragraph illustrate two simple scenarios:
-
Intra-system interoperability (between two systems the same e.g.: ARCADE to ARCADE)
-
Inter-system interoperability (between two differing systems that may not have direct connectivity)
It should be noted that the standard does not currently provide guidance for direct international
connectivity between differing national systems.
Interoperability with external services (or systems with no direct connectivity):
This scenario typically involves asynchronous communications between a spectrum management
system and one or more external organizations. A physical separation will often exist between the
two systems (For example, this may be required to address security barriers or limitations in
connectivity or bandwidth).
Establishing Communication (Initial Handshake)
Before any communication and interaction can take place an initial handshaking process must
occur. This process is detailed in Figure 6.2.4.
-
Identify Target User / System
The first step in setting up communication for SSRF exchange is to identify the communities that are
to participate in the exchange.
-
Identify Initial Point of Contact
Points of contact need to be established to start the manual handshaking process. This is typically
conducted through verbal or email dialogue.
-
Establish Communication Strategy
The communities shall agree on the transport strategy. This could range from web services through
to files on physical media.
-
Establish Communication
Once the strategy has been agreed, it is implemented and communication established.
-
Transmit / Receive Package(s)
Once the communication between the communities has been established, spectrum management
interoperability can be conducted through the use of SSRF.
Data Transfer Integrity and Security
The standard is based on the assumption that the communication channel between parties ensures
the data transfer integrity and security. Classification information for the data items is stored within
each document, as described within the data standard (see Volume II, section 1.4).
SSRF Package Types
The generic distribution process of a SSRF package is illustrated below.
The SSRF data standard specifies two different types of packages:
- Asynchronous (one way with no answer expected, e.g. providing a Table Of Allocation to another
party)
- Synchronous (Request / Response, e.g. request for assignment expecting a notification)
SSRF Document Structure
A SSRF document is essentially a list container; it contains lists of
SSRF datasets. Within a SSRF document there is no established minimum
configuration: document configuration requirements are business process-
specific. Additionally, each SSRF data element has a set
of required attributes and elements which together establish a minimum
configuration requirement for each respective element type.
SSRF is the root element for any SSRF-XML message. It contains
attributes defining the namespace used. Any SSRF-XML message may contain any
number of datasets. For example:
<SSRF>
<Dataset_1/>
< ... />
<Dataset_N/>
</SSRF>
SSRF Document Property Order (DEPRECATED)
SSRF v3.1.x does not enforce a property order within a SSRF document.
It is the responsibility of the implementation to track internal element
references.
Because some datasets require other reference data to be present in the data repository (e.g.
locations, equipment specifications) in order to be validated, datasets within transactions MUST be
ordered to enable the receiving system to immediately resolve dependencies. This order is provided
and enforced by the XML Schema (see Volume II, section 2). The order in which each type of
dataset appears, as defined by the SSRF Schema, enables the receiving system to resolve
dependencies by processing the document sequentially.
For example, a document including location, equipment and frequency assignment datasets will be
ordered so that location and equipment specifications will be provided before the frequency
assignment data. That way the receiving system can process the location and equipment
information into its data repository, and further on will validate the assignment dataset against the
newly imported location and equipment datasets.
Distribution of Referenced Data
Distribution of referenced data is decided at the initial handshake or specified using the external
attribute of the Administrative element. Two options are available:
-
Transmit only essential information
Where spectrum management systems are assumed to be synchronized, transactions normally
omit reference datasets. For example, an assignment transaction MAY include only a LocationRef,
omitting detailed location information (if the requester knows that the location has been previously
defined).
-
Transmit all information
Where spectrum management systems are assumed not to be synchronized, transactions normally
include all reference datasets. For example, an assignment transaction SHOULD include the
detailed location information referenced within the assignment.
Core versus National Elements
SSRF documents are based on SMADEF-XML and contain core elements which must be
managed and recorded in every SSRF compliant software tool. SSRF documents may also contain national
elements that support a specific nation’s requirements.
Within the description of the element, information is provided if an element belongs to a specific
nation. For example: “This is a National element (used by: USA).” SSRF implementations MUST
support USA national elements as required by the element description, and MUST be prepared to
merge USA national elements back into SMADEF-XML or OSMDD formatted datasets received
from systems which support those standards when those datasets are owned by DoD.
Input Requirements and Validation Rules
For national elements, the rules appearing in the section "Input Requirements" (such as "this
element is REQUIRED") apply only to the nation(s) implementing this element. All non-USA national
elements are considered as optional in the SSRF Schema, and the implementation of national
validation rules is left to the nation implementing these elements. Validation rules of a general
nature are implemented as part of the standard and are shown in the "Validation rules" section (see
Volume II Paragraph 1.1).
For core elements, additional national rules for a Nation XXX may be indicated in sub-paragraphs
"Additional checks for XXX". Rules that refer to "USA" MUST be implemented by SSRF compliant
software. Rules for other nations MAY be supported as desired within SSRF implementations.
Validation of non-USA rules is OPTIONAL.
Implementation Notes
-
A modification may not be a simple "purge and replace" operation.
When a dataset is sent from tool A implementing some national elements to tool B which did not
implement them these elements will not be recorded by tool B.
If tool B sends a modification of this dataset to tool A, this tool A must be able to merge
the incoming modified dataset with the existing dataset without losing the national elements
currently stored in tool A.
-
The receiver must add their own proprietary markings.
When a dataset is sent from tool A not implementing some elements specific to nation B
expecting them, it is Nation B responsibility to populate and manage these elements.
The other nations are NOT expected to populate these national elements.
The owning (receiving) nation is responsible to ensure that the modification of records
(received from non-owning nations) maintain the national elements.
Dataset Management
The method for updating and tracking element is “solution specific” and managed and controlled by each spectrum
management system. It is the responsibility of each system to conduct its own data management.
Dataset Locking and Ownership
The ownership of datasets can be supported by SSRF using the first two parts of the dataset
identifier (see Country and orgCode). However, the following MAY be
used as guidance for ownership operational policies:
- The owner of a dataset is responsible for the dataset throughout its life cycle.
- Solution specific software systems SHOULD allow only the owner to modify their own datasets;
- If someone other than the owner needs to modify the dataset, the dataset SHOULD be sent to the
owner for update action.
The locking of individual datasets is a solution specific procedure. Experience in spectrum
management software as well as in other cooperative domains has demonstrated that data integrity
can best be ensured when only one user has the ability to modify a specific dataset at any time. A
modification of a dataset must be approved or withdrawn from the system before another
modification can be created.
Referential Integrity between Datasets
A modification may modify any item within a dataset. However, it cannot be used to modify the
dataset identifier (attribute serial), as it constitutes the unique identifier attached to each dataset
from its creation until it is deleted.
Warning:
The modification and deletion of datasets should be considered very carefully. Modifying or deleting
datasets SHOULD be validated where they are inter-related with existing datasets. Amendments to
inter-related datasets SHOULD only be permitted within a controlled process. Further details about
modifying and deleting specific datasets are contained within the description of each data element.
Dataset Deletion
If a dataset expires or requires deleting the “Deletion” SSRF message is used. The processes for
managing the deletion of data are illustrated in Figure 6.5.2. The messages form a request for
expiry/deletion. The internal management of datasets is “solution specific”.
The messages form a request for expiry / deletion. It is the responsibility of each systems solution
to manage its own datasets.
Requesting Data
The Administrative message is used to request dataset(s) from other spectrum management
systems. This element can be used to request specific datasets by specifying the dataset identifier
required. Alternatively it can be used to query another repository for information. It is the
responsibility of each spectrum management system to manage and control the release of
information.
If a received document contains invalid or missing data then the Administrative message SHOULD
be used to request that the document is re-sent with the necessary amendments.
Data Distribution from a Central Server
This section contains indications which MAY be taken into consideration when implementing a
client/server system.
SSRF Roles
Users of a centralized system may have one or more roles usually depending upon assigned
responsibilities.
A Role (or Job Account) is assigned to an office or position so the account does not
change as staff within an office or organization change. The Role identifies the account which has
edit authority / control of the proposed action. One or more roles can be assigned to a spectrum
manager who has more than one distinctly different areas of responsibility (e.g., a tactical and a
sustaining-base function) and who may use the same computer to perform both jobs.
The Role is similar to an e-mail address because it is used like an address for workflow routing dataset of
proposals.
A new Role, if created on a client computer, is uploaded to the server where it is
validated before being made available to other clients on the network. Once a Role has been
established, the operator can use it to route a dataset within the system.
Status tracking codes are
assigned to datasets as they move through the approval cycle. As a proposal is passed from one
user to another, the receiving user’s Role is added to the proposal. When a Role is added to a
proposal / action it has an associated status entry and may have related status comments when
applicable.
Once a Role has been sent a copy of a dataset (for action or information), that Role will
continue to get all updates to that dataset (as long as that Role remains active) or until the dataset
is finally approved. Before creating a new Role, the existing list of accounts should be checked to
prevent duplicates.
Area of Interest
The Area of Interest (AOI) defines the datasets that are to be transferred from a superior level to a
subordinate level (or vice-versa). They consist of the data in use by the subordinate level (and its
own subordinate levels), and also the "background" data which may not belong to this Force
Element or Command but which are used in the same or adjacent area and must therefore be
considered.
The definition of the AOI results (from a data request response or query response) may be used in
two ways depending on the implementation of the hierarchical dialog:
- The AOI may be used by the subordinate level to "pull" all relevant datasets from its superior
level (most efficient in a client-server architecture over a network)
- The AOI may be used by the superior level to "push" all relevant datasets to each of its
subordinates (solution to be used when the different levels are not permanently connected).
Handling SSRF Document Attachments
From a user perspective, the mechanisms used for attaching files to a SSRF document to form a
package should remain largely transparent, similar to e-mail attachments.
The storage and management of the receipt of attachments is “solution specific” to be managed by
the implementation, this could include:
- storage as Binary Large Objects (BLOB’s) within a data repository or
- files stored within a set of folders.
The transport protocol will dictate how the package should be distributed.
Package File Format
The Package File is intended for use in disconnected environments or between dissimilar systems.
It supports the transfer of multiple datasets of various types along with their associated attachments
in a single file. The package file is a ZIP archive that contains a single XML file containing all the
datasets, and binary files as needed, containing the attachments associated with the datasets in the
XML file.
It is RECOMMENDED that sending implementations limit the package file contents to no more than
65534 (64k - 2) attachments and limit the total compressed file size to no larger than 2 GB. When
using E-Mail exchanges, it is RECOMMENDED to limit the total compressed file size to no larger
than 2 MB to avoid E-Mail server limitations. In any case, it is RECOMMENDED to check the local
(operational) limitations before starting the exchanges.
The sending implementation MAY create multiple package files, each within the recommended
constraints in order to transfer all the desired datasets. Adhering to these constraints will increase
the probability that the package file can be processed by the receiving implementation.
File Names
The datasets in a package MUST be stored in an XML file named "datasets.xml" at the root level of
the archive. The order of the datasets within the XML file is significant.
The attachments are described in ExtReference datasets, and will also be stored
at the root level of the archive.
The file name of each attachment SHOULD be derived from the ExtReference.serial data with
colons":" replaced by dashes"-", and its normal extension as given by the originating software
package. As the serial numbers are unique, using the naming convention will create unique file
names in the package with no risk of collision.
Example
Following is an example of an XML document with datasets that have associated attachments to
illustrate the relationship between ExtReference and file names.
ExternalReference contains bibliographic or any other references applicable
to the dataset except those placed in Derivative Classification Authority
(Data element ClsDerived).
Example:
<ExternalReference cls="U">
<Serial cls="U">USA:AF:EX:123</Serial>
<Type cls="U">Document</Type>
<Title cls="U">plan 5027</Title>
<Organisation cls="U">PACOM</Organisation>
<Date cls="U">2000-04-27</Date>
<ResourceLocator cls="U">USA-AF-EX-123.PDF</ResourceLocator>
</ExternalReference>
Notes:
- When an ExternalReference is exported from the data repository the attachment
file MAY automatically be exported with the dataset.
- When attaching a file, user SHOULD follow current national / NATO information security policies.
Shown below is a view of the contents of the package file created using the datasets in the example
XML document.
SSRF Document Validation
There are two categories of SSRF document validation:
-
Document Format
Validates that the SSRF document is well formed XML and passes all
standard XML schema validation checks using the SSRF XML Schema Definition (XSD) document.
- Document Semantics
Validates that the SSRF data elements contain all required fields and configurable
parameters and that all field values contain valid enumerated types, where specified
within the SSRF XML Schema Definition (XSD) document.
Invalid Document Format
A SSRF document is considered invalid, and an error message SHOULD be returned, if:
- The document is not “well-formed” (i.e. does not have a correct XML structure);
- The document does not validate against the standard via the SSRF Schema.
If an invalid document is received the sender SHOULD be informed that the document could not be
processed and requesting that the data is re-issued. This is accomplished using the Administrative
message with reason="INVMSG".
Invalid Document Semantics
SSRF transactions MAY omit reference datasets and send only the dependent dataset that is of
interest.
For example, an Assignment document MAY include only a LocationRef,
omitting detailed location information.
If referenced data is not included in the SSRF document the receiving system SHOULD
check if this data exists locally and SHOULD generate an error if
the data does not exist locally.
If the data does not exist locally then the receiving system MAY automatically create a transaction
using the Administrative dataset to request the required reference data from the sender.
When a sending system does not have all the reference data associated with a dataset it SHOULD
indicate or allow the user to discover that it lacks some reference data before sending the dataset to
the receiving system. In general systems that send SSRF data SHOULD be able to provide the
data required to resolve dependencies in outgoing transactions. Note that there may be security or
other policy or procedural considerations involved in transferring reference data associated with
dependent datasets.
Data Object
SSRF is the root element for any SSRF-XML message. It contains
attributes defining the namespace used. Any SSRF-XML message may contain any
number of datasets.
See the OpenSSRF Javadoc for more details.
A de minimis example:
<SSRF xmlns:ssrf="urn:us:gov:dod:standard:ssrf:3.1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Datasets_here/>
</SSRF>
Example SSRF Message Exchange & Data Object
The sequence diagram shown below demonstrates a sample set of interactions between two
spectrum management systems sharing assignment information.
A complete SSRF Assignment example describing the CKCO-TV Canadian
(civilian) broadcast television service.
<?xml version="1.0" encoding="UTF-8"?>
<SSRF xmlns:ssrf="urn:us:gov:dod:standard:ssrf:3.1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Transmitter cls="U">
<Serial cls="U">CAN:IC:TX:0d6ad4883d8840</Serial>
<EntryDateTime cls="U">1986-01-23T05:00:00Z</EntryDateTime>
<Generic cls="U">Yes</Generic>
<OutputDeviceType cls="U">Klystron</OutputDeviceType>
<TxMode>
<ModeID cls="U">TV</ModeID>
<Description cls="U">Broadcast Television</Description>
<Power>
<PowerMin cls="U">59.27370363039024</PowerMin>
<PowerType cls="U">Carrier</PowerType>
<Calculated cls="U">No</Calculated>
</Power>
</TxMode>
</Transmitter>
<Antenna cls="U">
<Serial cls="U">CAN:IC:AN:e0e5e6a303b042</Serial>
<EntryDateTime cls="U">1986-01-23T05:00:00Z</EntryDateTime>
<Generic cls="U">No</Generic>
<AntType cls="U">Other</AntType>
<Nomenclature>
<Type cls="U">Civilian/Commercial</Type>
<Name cls="U">MFR not declared</Name>
</Nomenclature>
<AntMode>
<ModeID cls="U">2005-PRECISE</ModeID>
<ModeUse cls="U">Transmit Only</ModeUse>
<MotionType cls="U">Directional</MotionType>
<SectBlanking cls="U">No</SectBlanking>
<PolarisationType cls="U">Horizontal linear</PolarisationType>
<BeamType cls="U">Shaped Beam</BeamType>
<AntPattern>
<Type cls="U">HH</Type>
<Calculated cls="U">No</Calculated>
<AntPatternPoint>
<Dir cls="U">359.0</Dir>
<Gain cls="U">-5.1032</Gain>
</AntPatternPoint>
<AntPatternPoint>
<Dir cls="U">357.0</Dir>
<Gain cls="U">-4.721</Gain>
</AntPatternPoint>
<AntPatternPoint>
<Dir cls="U">350.0</Dir>
<Gain cls="U">-1.6205</Gain>
</AntPatternPoint>
<AntPatternPoint>
<Dir cls="U">346.0</Dir>
<Gain cls="U">-0.5634</Gain>
</AntPatternPoint>
<AntPatternPoint ... />
<AntPatternPoint>
<Dir cls="U">16.0</Dir>
<Gain cls="U">-0.0847</Gain>
</AntPatternPoint>
<AntPatternPoint>
<Dir cls="U">15.0</Dir>
<Gain cls="U">-0.0619</Gain>
</AntPatternPoint>
<AntPatternPoint>
<Dir cls="U">11.0</Dir>
<Gain cls="U">-0.6033</Gain>
</AntPatternPoint>
<AntPatternPoint>
<Dir cls="U">9.0</Dir>
<Gain cls="U">-1.2376</Gain>
</AntPatternPoint>
<AntPatternPoint>
<Dir cls="U">7.0</Dir>
<Gain cls="U">-2.5382</Gain>
</AntPatternPoint>
<AntPatternPoint>
<Dir cls="U">2.0</Dir>
<Gain cls="U">-4.555</Gain>
</AntPatternPoint>
</AntPattern>
</AntMode>
</Antenna>
<Assignment cls="U">
<Serial cls="U">CAN:IC:AS:2ccba89c0dab41</Serial>
<EntryDateTime cls="U">1986-01-23T05:00:00Z</EntryDateTime>
<LastChangeDateTime cls="U">2012-03-21T04:00:00Z</LastChangeDateTime>
<CaseNum>
<Country cls="U">Canada</Country>
<Type cls="U">callsign</Type>
<Identifier cls="U">CKCO-TV-3</Identifier>
</CaseNum>
<UsageType cls="U">Approved Permanent</UsageType>
<EffectiveDateTime cls="U">1986-01-23T05:00:00Z</EffectiveDateTime>
<AssignmentAuthority cls="U">User-assigned</AssignmentAuthority>
<DataSource cls="U">Industry Canada</DataSource>
<FCCFileNum cls="U">3897</FCCFileNum>
<OriginalAssignmentDate cls="U">1986-01-23T05:00:00Z</OriginalAssignmentDate>
<SupplementaryDetails cls="U">CTV</SupplementaryDetails>
<TypeOfService cls="U">Broadcast</TypeOfService>
<Configuration>
<ConfigID cls="U">OP:CKCO-TV-3</ConfigID>
<Description cls="U">Class C</Description>
<Usage>
<EqpFnct cls="U">Broadcast Radio/Television</EqpFnct>
<StnClass cls="U">BT</StnClass>
<RadioService cls="U">Broadcasting Service</RadioService>
</Usage>
<ConfigFreq idx="1">
<FreqMin cls="U">0.638</FreqMin>
<InBand cls="U">Yes</InBand>
<Priority cls="U">Primary</Priority>
</ConfigFreq>
<TxRef>
<Serial cls="U" xsi:type="TSerial">CAN:IC:TX:0d6ad4883d8840</Serial>
<TxModeRef>
<ModeID cls="U">TV</ModeID>
</TxModeRef>
<TxAntModeRef>
<Serial cls="U" xsi:type="TSerial">CAN:IC:AN:e0e5e6a303b042</Serial>
<ModeID cls="U">2005-PRECISE</ModeID>
</TxAntModeRef>
</TxRef>
</Configuration>
<Station>
<StationID cls="U">OP: Operational</StationID>
<CallSign cls="U">CKCO-TV-3</CallSign>
<AntStructureHeight cls="U">497</AntStructureHeight>
<POCInformation>
<Type cls="U">User</Type>
</POCInformation>
<StationLoc/>
</Station>
<Link>
<LinkID cls="U">CKCO-TV-3</LinkID>
<IntermediateFunction cls="U">BROADCAST</IntermediateFunction>
<MajorFunction cls="U">BROADCAST</MajorFunction>
<StationConfig>
<Type cls="U">Transmit Only</Type>
<ConfigID cls="U">OP: Operational</ConfigID>
<StationID cls="U">CKCO-TV-3</StationID>
<EIRPMin cls="U">59.27370363039024</EIRPMin>
<AntFeedpointHeight cls="U">497</AntFeedpointHeight>
</StationConfig>
</Link>
</Assignment>
</SSRF>
See the OpenSSRF Javadoc for more details.