Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
Requirement
Title | Service interface protocols and data format |
Identifier | SWIM-SERV-019 |
Requirement | A service description shall include the list of service interface protocols (including name and version) and data format to be used. |
Rationale | Makes explicit within the service description what the protocols are. |
Verification | Completeness: Verify that all relevant protocols and versions are listed; verify that the information is provided for each provider side and consumer side interface. Consistency: Verify that the protocols are consistent with the selected interface binding. Correctness: Not Applicable. |
Examples/Notes | Note: The list of supported protocols are the ones corresponding to the selected interface binding. The supported versions of the protocols need to be declared. E.g. version of the Transport Level Security (TLS). |
Level of Implementation | Mandatory |
Guidance
Examples
See the Service interface protocols and data format section within the Donlon TOBT Setting Service Description.
Guidance for JSON service description
UNDERWORK
structure of guidance
This requirement is about two kinds of information : "the list of service interface protocols (including name and version) and data format to be used".
Each part of the guidance is split accordingly.
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
schema for service interface protocols
"Interface" : { "description" : "The means by which the underlying capabilities of a service are accessed. [SWIM-SERV-016]", "type": "object", "additionalProperties": false, "required": ["name", "description", "interfaceProvisionSide", "tiPrimitiveMessageExchangePattern", "endPoint", "serviceInterfaceBinding", "networkInterfaceBinding", "interfaceBindingDescription", "operation", "behaviour"], "properties": { "interfaceBindingDescription": { "description" : "Complementary description of the protocols and other specifications used by the interface complementing the selected bindings, or any additional requirement specified in a SWIM TI Profile that is supported by the interface. [SWIM-SERV-018], [SWIM-SERV-019]", "type" : "string", "minLength":1 } } } "ServiceTechnicalDescription" : { "description" : "Description of the technical aspects of the service including data structures, interface and operations behaviour, security mechanisms and technical constraints", "type": "object", "additionalProperties": false, "properties": { "securityMechanism": { "description" : "A process (or a device incorporating such a process) that is utilized or implemented by the service in order to address a security threat.", "type" : "array", "items" : { "$ref":"#/definitions/SecurityMechanism" }, "minItems": 1 }, } }, "SecurityMechanism" : { "description" : "A process (or a device incorporating such a process) that is utilized or implemented by the service in order to address a security threat.", "type": "object", "additionalProperties": false, "required": ["name", "description"], "properties": { "type": { "description" : "The type of security mechanism.", "type" : "array", "items" : { "$ref":"#/definitions/CodeSecurityMechanismType" }, "minItems": 0 }, "name": { "description" : "The name of the security mechanism.", "type" : "string", "minLength":1 }, "description": { "description" : "The description of the security mechanism.", "type" : "string", "minLength":1 } } } "CodeSecurityMechanismType" : { "description" : "A code listing the types of service mechanisms.", "type": "string", "enum": [ "AUDIT", "AUTHENTICATION", "AUTHORIZATION", "CONFIDENTIALITY", "IDENTITY_MANAGEMENT", "INTEGRITY", "MONITORING", "POLICY_ENFORCEMENT" ] }
schema for data formats
Guidance
guidance for service interface protocols
excerpt from requirement
- Statement: Include the list of service interface protocols (including name and version)
- Rationale: Makes explicit within the service description what the protocols are.
- Note: The list of supported protocols are the ones corresponding to the selected interface binding. The supported versions of the protocols need to be declared. E.g. version of the Transport Level Security (TLS).
The corresponding information in the schema in split between
- security mechanism that list the security protocols globally for the service
- interfaceBindingDescription that list other protocls, per itnerface
an optional protocol specification document
interfaceBindingDescription - Mandatory
Within each Interface, use following attribute.
attribute name | description | type | guidance | rule |
---|---|---|---|---|
interfaceBindingDescription | Complementary description of the protocols and other specifications used by the interface complementing the selected bindings, or any additional requirement specified in a SWIM TI Profile that is supported by the interface. [SWIM-SERV-018], [SWIM-SERV-019] | string | List the service interface protocols (including name and version), except for security mechanism protocols which are mentioned in SecurityMechanism. This field is used as well by requirement SWIM-SERV-018 TI Profile and bindings to describe additionally supported requirements as specified in the selected SWIM TI Profile, if any. | Mandatory |
SecurityMechanism - Mandatory
Guidance: protocol dealing with security
attribute name | description | type | guidance | rule |
---|---|---|---|---|
type | The type of security mechanism. | Mandatory, minItems=0 | ||
name | The name of the security mechanism. | string | Mandatory | |
description | The description of the security mechanism. | string | Mandatory | |
interfaceBindingDescription | Complementary description of the protocols and other specifications used by the interface complementing the selected bindings, or any additional requirement specified in a SWIM TI Profile that is supported by the interface. [SWIM-SERV-018], [SWIM-SERV-019] | string | Rationale: Makes explicit within the service description what the protocols are. Guidance: Provide here a textual description of
Evolution: split the field, to separate information for each requirement (easier for readers and for guidance). Evolution: the list of protocols will become more structure (similar as for security mechanisms). | Mandatory, minLength=5 |
SecurityMechanism - Mandatory
Provide here the list of protocols dealing with security
Note: Note: Concrete access control and other security mechanisms are described in the technical section of the form (see SecurityMechanism)
Protocol specification document - Optional
Additional information may be provided as a document of type PROTOCOL_SPECIFICATION.
See Guidance on serviceDocument on how to fill in documents.
guidance for data formats
Within field exchangeSchema, itself within field serviceInformationDescription, list one or more occurrences of type ExchangeSchema.
attribute name | description | type | guidance | rule |
---|---|---|---|---|
--- | A container for the description of the information exchanged by the information service. | --- | Rationale: Provide a description of the information/data that is exchanged by the service. Guidance: SWIM-SERV-019 Protocols and data format requires a description of the elements of the exchanged information. This is provided here. It can be provided by reference and can make use of a published information exchange model. Therefore, use the option best suited to your service. | (M) |
informationDefinition | A formal representation of information concepts or data concepts. [SWIM-SERV-022] | InformationDefinition | Rational: Enables to understand the information provided by the service, with a specific focus to the semantics of the information | Mandatory |
exchangeSchema | Formal description of the data involved in an information exchange. | ExchangeSchema | Rational: Enables to understand data structure, and should include definition documents (XSD, JSON Schema,). | Mandatory |
ExchangeSchema - Mandatory
Enables to understand data format(s).
attribute name | description | type | guidance | rule |
---|---|---|---|---|
name | The name of the exchange schema. [SWIM-SERV-019] | string | Provide the name of the data format that is used to exchange data via the service interface. | Mandatory |
schemaLanguage | Description of the language used (e.g. XML, JSON). [SWIM-SERV-019] | string | Indicate the language in which the data format is expressed (e.g. XSD, JSON, natural language,..) | Mandatory |
reference | A reference to the exchange schema containing the specifications of the data structures. | string | Indicate with a reference the location of where the data format is defined (e.g. See service documents) | Optional |
Example
example on service interface protocols
TBD
example on data formats
"serviceInformationDescription": { "exchangeSchema": [ { "name": "TOBT Setting Schema", "schemaLanguage": "XML", "reference": "This schema defines the data structures used to exchange data with the service. See service documents" } ] }
A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.
Requirement
Title | Service interface protocols and data format |
Identifier | SWIM-SERV-019 |
Requirement | A service description shall include the list of service interface protocols (including name and version) and data format to be used. |
Rationale | Makes explicit within the service description what the protocols are. |
Verification | Completeness: Verify that all relevant protocols and versions are listed; verify that the information is provided for each provider side and consumer side interface. Consistency: Verify that the protocols are consistent with the selected interface binding. Correctness: Not Applicable. |
Examples/Notes | Note: The list of supported protocols are the ones corresponding to the selected interface binding. The supported versions of the protocols need to be declared. E.g. version of the Transport Level Security (TLS). |
Level of Implementation | Mandatory |
Guidance
Examples
See the Service interface protocols and data format section within the Donlon TOBT Setting Service Description.
Guidance for JSON service description
UNDERWORK
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
schema for service interface protocols
"Interface" : { "description" : "The means by which the underlying capabilities of a service are accessed. [SWIM-SERV-016]", "type": "object", "additionalProperties": false, "required": ["name", "description", "interfaceProvisionSide", "tiPrimitiveMessageExchangePattern", "endPoint", "serviceInterfaceBinding", "networkInterfaceBinding", "interfaceBindingDescription", "operation", "behaviour"], "properties": { "interfaceBindingDescription": { "description" : "Complementary description of the protocols and other specifications used by the interface complementing the selected bindings, or any additional requirement specified in a SWIM TI Profile that is supported by the interface. [SWIM-SERV-018], [SWIM-SERV-019]", "type" : "string", "minLength":1 } } } "ServiceTechnicalDescription" : { "description" : "Description of the technical aspects of the service including data structures, interface and operations behaviour, security mechanisms and technical constraints", "type": "object", "additionalProperties": false, "properties": { "securityMechanism": { "description" : "A process (or a device incorporating such a process) that is utilized or implemented by the service in order to address a security threat.", "type" : "array", "items" : { "$ref":"#/definitions/SecurityMechanism" }, "minItems": 1 }, } }, "SecurityMechanism" : { "description" : "A process (or a device incorporating such a process) that is utilized or implemented by the service in order to address a security threat.", "type": "object", "additionalProperties": false, "required": ["name", "description"], "properties": { "type": { "description" : "The type of security mechanism.", "type" : "array", "items" : { "$ref":"#/definitions/CodeSecurityMechanismType" }, "minItems": 0 }, "name": { "description" : "The name of the security mechanism.", "type" : "string", "minLength":1 }, "description": { "description" : "The description of the security mechanism.", "type" : "string", "minLength":1 } } } "CodeSecurityMechanismType" : { "description" : "A code listing the types of service mechanisms.", "type": "string", "enum": [ "AUDIT", "AUTHENTICATION", "AUTHORIZATION", "CONFIDENTIALITY", "IDENTITY_MANAGEMENT", "INTEGRITY", "MONITORING", "POLICY_ENFORCEMENT" ] }
schema for data formats
Guidance
guidance for service interface protocols
SecurityMechanism - Mandatory
Note:
"technicalConstraint":
{
"description" : "A characteristic of the environment or larger system within which the service operates. [SWIM-SERV-015]",
"type" : "array",
"items" : { "$ref":"#/definitions/TechnicalConstraint" },
"minItems": 1
}
Protocol specification document - Optional
Additional information may be provided as a document of type PROTOCOL_SPECIFICATION.
See Guidance on serviceDocument on how to fill in documents.
guidance for data formats
Within field exchangeSchema, itself within field serviceInformationDescription, list one or more occurrences of type ExchangeSchema.
attribute name | description | type | guidance | rule |
---|---|---|---|---|
--- | A container for the description of the information exchanged by the information service. | --- | Rationale: Provide a description of the information/data that is exchanged by the service. Guidance: SWIM-SERV-019 Protocols and data format requires a description of the elements of the exchanged information. This is provided here. It can be provided by reference and can make use of a published information exchange model. Therefore, use the option best suited to your service. | (M) |
informationDefinition | A formal representation of information concepts or data concepts. [SWIM-SERV-022] | InformationDefinition | Rational: Enables to understand the information provided by the service, with a specific focus to the semantics of the information | Mandatory |
exchangeSchema | Formal description of the data involved in an information exchange. | ExchangeSchema | Rational: Enables to understand data structure, and should include definition documents (XSD, JSON Schema,). | Mandatory |
ExchangeSchema - Mandatory
Enables to understand data format(s).
attribute name | description | type | guidance | rule |
---|---|---|---|---|
name | The name of the exchange schema. [SWIM-SERV-019] | string | Provide the name of the data format that is used to exchange data via the service interface. | Mandatory |
schemaLanguage | Description of the language used (e.g. XML, JSON). [SWIM-SERV-019] | string | Indicate the language in which the data format is expressed (e.g. XSD, JSON, natural language,..) | Mandatory |
reference | A reference to the exchange schema containing the specifications of the data structures. | string | Indicate with a reference the location of where the data format is defined (e.g. See service documents) | Optional |
Example
example on service interface protocols
TBD
example on data formats
"serviceInformationDescription": { "exchangeSchema": [ { "name": "TOBT Setting Schema", "schemaLanguage": "XML", "reference": "This schema defines the data structures used to exchange data with the service. See service documents" } ] }
A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.