Working towards the next version of the SWIM Supporting Material
Page History
Table of Contents |
---|
Requirement
Expand | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||
Panel | ||||||||||||||
| ||||||||||||||
|
Guidance
Examples
See the Service interface protocols and data format section within the Donlon TOBT Setting Service Description.
Guidance for JSON service description
Excerpt | ||||||
---|---|---|---|---|---|---|
|
Info | ||
---|---|---|
| ||
This requirement is about two kinds of information. The guidance is structured accordingly
|
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
part 1 - service interface protocols
Expand | |||||
---|---|---|---|---|---|
| |||||
|
part 2 - data formats
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Expand | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Rules expressed for the cases as defined in Registry URD.
|
Guidance
part 1 - guidance for service interface protocols
Info | ||
---|---|---|
| ||
|
The corresponding information in the schema in split between
- security mechanism : list the (security protocols) that are global for the service, if any
- interfaceBindingDescription : list per interface the protocols not already mentioned in security mechanism
securityMechanism - Optional
within field securityMechanism, itself within field techncialDescription, list zero or more instances of SecurityMechanism , for security mechanism protocols that are implemented in all interfaces of the service.
SecurityMechanism - Optional - zero or more
A protocol dealing with security.
attribute name | description | type | guidance | rule | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name | The name of the security mechanism. | string | Provide the name and version of the security mechanism. Eg X.509v3 Client Certificate | Mandatory | |||||||||||||||||||||
description | The description of the security mechanism. | string | Describe the mechanism Eg Authentication performed based on X.509 client certificates over a secured connection based on TLS. | Mandatory | |||||||||||||||||||||
type | The type of security mechanism. |
| Select zero or more code values that indicate the type of security mechanism. | Optional |
interfaceBindingDescription - Mandatory
Additional attribute to Interface type as described in SWIM-SERV-016 Service interfaces.
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 all service interface protocols (including name and version) applicable for this interface, and that are not mentioned in securityMechanism.
| Mandatory |
part 2 - guidance for data formats
Within field exchangeSchema, itself within field serviceInformationDescription, list one or more occurrences of type ExchangeSchema.
ExchangeSchema - Mandatory
Enables to understand data format(s).
attribute name | description | type | guidance | rule |
---|---|---|---|---|
name | The name of the exchange schema. | 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). | 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
part 1 - service interface protocols
Code Block | ||
---|---|---|
| ||
"securityMechanism": [
{
"name": "TLS 1.2",
"description": "The service relies on TLS 1.2 to provide integrity and confidentiality.",
"type": [
"AUTHENTICATION",
"CONFIDENTIALITY",
"INTEGRITY"
]
},
{
"name": "Cypher Suites",
"description": "The following cipher suites are allowed in accordance with ECRYPT-CSA recommendations https://www.ecrypt.eu.org/csa/documents/D5.4-FinalAlgKeySizeProt.pdf: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 , TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
"type": [
"AUTHENTICATION",
"CONFIDENTIALITY",
"INTEGRITY"
]
},
{
"name": "X.509v3 Server Certificate",
"description": "The service utilizes X.509v3 public certificate to authenticate the provider.",
"type": [
"AUTHENTICATION"
]
},
{
"name": "X.509v3 Client Certificate",
"description": "The service utilizes X.509v3 public certificate to authenticate the consumer.",
"type": [
"AUTHENTICATION"
]
}
]
"serviceInterface": [
{
"interfaceBindingDescription": "XML requests and replies embedded into SOAP messages, themselves embedded into HTTP requests and responses. Operation names are associated to SOAP requests. The interface does not use compression or message transmission optimization mechanism (MTOM).",
} |
part 2 - data formats
Code Block | ||
---|---|---|
| ||
"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.