|
See the Service interface protocols and data format section within the Donlon TOBT Setting Service Description.
UNDERWORK |
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 section of the guidance is split accordingly. |
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
"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" ] } |
|
Rules expressed for the cases as defined in Registry URD.
|
|
The corresponding information in the schema in split between
service document: provide an optional protocol specification document
within field securityMechanism, itself within field techncialDescription, list zero or more instances of SecurityMechanism.
A protocol dealing with security, that is implemented by all interfaces of this service
attribute name | description | type | guidance | rule | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | The type of security mechanism. |
| Provide zero or more code values that indicate the type of security mechanism. | Mandatory, minItems=0 | |||||||||||||||||
name | The name of the security mechanism. | string | Provide the name of the security mechanism, including version. Eg TLS 1.2 | Mandatory | |||||||||||||||||
description | The description of the security mechanism. | string | 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 all service interface protocols (including name and version) applcable for this interface, except for the security mechanism protocols which are already mentioned in securityMechanism.
| Mandatory |
Additional information may be provided as a document of type PROTOCOL_SPECIFICATION.
See Guidance on serviceDocument on how to fill in documents.
Within field exchangeSchema, itself within field serviceInformationDescription, list one or more occurrences of type ExchangeSchema.
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 |
TBD |
"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.