159. Based on analysis of the “Technical Service Data Sheet for Notification Broker v.002”, [NC3A RD-3139] and “RD-3139 Publish/Subscribe Service Interface Profile Proposal v.1.0” [DEU SDS] the following document structure is proposed for the consolidated Profile:
| Section | Description |
|---|---|
| Keywords | Should contain relevant names of the [C3 Taxonomy] services plus other relevant keywords like the names of profiled standards. |
| Metadata | Metadata of the document, that should be based on the NATO Discovery Metadata Specification [NDMS] and MUST include: Security classification, Service name (title), Version, Unique identifier, Date, Creator, Subject, Description, Relation with other SIPs. The unique identifier MUST encode a version number and C3 Board needs to decide on a namespace. It needs to be decided whether URN or URL should be used to format the identifier. |
| Abstract | General description of the service being profiled. |
| Record of changes and amendments | The list of changes should include version number, date, originator and main changes. The originator should identify an organisation/Nation (not a person). |
| Table of Contents | Self-explanatory |
| Table of Figures | Self-explanatory |
| 1. Introduction | Should provide an overview about the key administrative information and the goals/non-goals of the service |
| 1.1 Purpose of the document | Same for all SIPs. Does not contain a service specific description. “Provide a set of specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability.” |
| 1.2 Audience | The envisioned audience consists of: Project Managers procuring Bi-SC or NNEC related systems; The architects and developers of service consumers and providers; Coalition partners whose services may need to interact with NNEC Services; Systems integrators delivering systems into the NATO environment |
| 1.3 Notational Conventions | Describes the notational conventions for this document: italics Syntax derived from underpinning standards should use the Courier font. |
| 1.4 Taxonomy allocation | Provides information on the position and description of the service within the [C3 Taxonomy] |
| 1.5 Terminology/Definitions | Introducing service specific terminology used in the document with short descriptions for every term. |
| 1.6 Namespaces | Table with the prefix and the namespaces used in the document. |
| 1.7 Goals | Service specific goals of the profile. They will tell which aspects of the service will be covered by the profile, e.g. identify specific protocols, data structures, security mechanisms etc. |
| 1.8 Non-goals | An explanation for not addressing the listed non-goals potentially relevant in a given context. This section may contain references to external documents dealing with the identified issues (e.g. security mechanisms are described in different SIP/document). |
| 1.9 References | Normative and non-normative references to external specifications. |
| 1.10 Service relationship | Relationships to other services in the [C3 Taxonomy]. |
| 1.11 Constraints | Preconditions to run the service; when to use and when not to use the service. service is not intended to work with encrypted messages” |
| 2. Background (non-normative) | Descriptive part of the document |
| 2.1 Description of the operational requirements | Description of the operational background of the service to give an overview where and in which environment the service will be deployed. |
| 2.2 Description of the Service | Purpose of the service, its functionality and intended use. Which potential issues can be solved with this service? |
| 2.3 Typical Service Interactions | Most typical interactions the service can take part in. Should provide better understanding and potential application of a service and its context. This part is non-normative and will not be exhaustive (i.e. is not intended to illustrate all possible interactions). Interactions can be illustrated using UML interaction, sequence, use case, and/or state diagrams. |
| 3. Service Interface Specification (normative) | Prescriptive part of the document (not repeating the specification) |
| 3.1 Interface Overview | Introduction with a short description (containing operations, etc.) of the interface. Short overview table with all operations identifying which ones are defined by the SIP as mandatory, recommended or optional. Any extensions to underlying services (e.g. new operations) must be clearly marked. Specific example: Response “service unavailable” if operations are not implemented/available. |
| 3.2 Technical Requirements | Description of the specific technical requirements. Generic non-functional requirements |
| 3.3 Operations | Detailed description of mandatory, recommended and optional operations: input, output, faults, sequence diagram if necessary. Clearly mark extensions to the underlying referenced standards. Any non-standard behaviour must be explicitly requested and described, including specific operations or parameters to initiate it. Specific examples : Explicitly request non-standard filter mode; explicitly request particular transport mode. - Internal faults could be handled as an unknown error. Additional information (internal error code) can be ignored by the user. |
| 3.4 Errors (Optional section) | Description of the specific errors and how the recipient is informed about them. |
| 4. References | Contains document references. |
| Appendices (optional) | Service specific artefacts (non-normative and normative), e.g. WSDLs / Schemas for specific extensions |