Working towards the next version of the SWIM Supporting Material

Page tree

Working towards the next version of the SWIM Supporting Material

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »



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

tentative JSON Guidance

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

 Schema excerpt [+]
		"ServiceInformationDescription" : 
		{
			"description" : "A container for the description of the information exchanged by the information service.",
			"type": "object",
			"additionalProperties": false,
			"required": ["informationDefinition", "exchangeSchema"],
			"properties":
			{

				"exchangeSchema":
				{
					"description" : "Formal description of the data involved in an information exchange.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/ExchangeSchema" },
					"minItems": 1
				}
			}
		}


		"ExchangeSchema" : 
		{
			"description" : "Formal description of the data involved in an information exchange.",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "reference", "schemaLanguage"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the exchange schema. [SWIM-SERV-019]",
					"type" : "string",
					"minLength":1
				},
				"schemaLanguage":
				{
					"description" : "Description of the language used (e.g. XML, JSON). [SWIM-SERV-019]",
					"type" : "string",
					"minLength":1
				},
				"reference":
				{
					"description" : "A reference to the exchange schema containing the specifications of the data structures. [SWIM-SERV-019].",
					"type" : "string",
					"minLength":1
				}
			}
		}
 Rules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATEsame
DEFINITIONsame


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 namedescriptiontypeguidancerule
interfaceBindingDescriptionComplementary 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 namedescriptiontypeguidancerule
typeThe type of security mechanism.
 CodeSecurityMechanismType +

A code listing the types of service mechanisms.

AUDIT 


AUTHENTICATION 

 A security functionality enabling the verification of the validity of credentials and their correspondence with an identity.

AUTHORIZATION 


INTEGRITY 


IDENTITY_MANAGEMENTA security functionality enabling the management of identities (e.g. identity creation, identity validation, federated identity retrieval).

MONITORING 


POLICY_ENFORCEMENT
CONFIDENTIALITY 





Mandatory, minItems=0
nameThe name of the security mechanism.string
Mandatory
descriptionThe description of the security mechanism.string
Mandatory
interfaceBindingDescriptionComplementary 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

  • additionally supported requirements as specified in the selected SWIM TI Profile
  • list of service interface protocols (including name and version), except for security mechanism protocls which are mentioned in SecurityMechanism.


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 namedescriptiontypeguidancerule
---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)
informationDefinitionA formal representation of information concepts or data concepts. [SWIM-SERV-022]InformationDefinitionRational: Enables to understand the information provided by the service, with a specific focus to the semantics of the informationMandatory
exchangeSchemaFormal description of the data involved in an information exchange.ExchangeSchemaRational: Enables to understand data structure, and should include definition documents (XSD, JSON Schema,).Mandatory








ExchangeSchema - Mandatory

Enables to understand data format(s).

attribute namedescriptiontypeguidancerule
nameThe name of the exchange schema. [SWIM-SERV-019]stringProvide the name of the data format that is used to exchange data via the service interface.Mandatory
schemaLanguageDescription of the language used (e.g. XML, JSON). [SWIM-SERV-019]stringIndicate the language in which the data format is expressed (e.g. XSD, JSON, natural language,..)Mandatory
referenceA 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

tentative JSON Guidance

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

 Schema excerpt [+]
		"ServiceInformationDescription" : 
		{
			"description" : "A container for the description of the information exchanged by the information service.",
			"type": "object",
			"additionalProperties": false,
			"required": ["informationDefinition", "exchangeSchema"],
			"properties":
			{

				"exchangeSchema":
				{
					"description" : "Formal description of the data involved in an information exchange.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/ExchangeSchema" },
					"minItems": 1
				}
			}
		}


		"ExchangeSchema" : 
		{
			"description" : "Formal description of the data involved in an information exchange.",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "reference", "schemaLanguage"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the exchange schema. [SWIM-SERV-019]",
					"type" : "string",
					"minLength":1
				},
				"schemaLanguage":
				{
					"description" : "Description of the language used (e.g. XML, JSON). [SWIM-SERV-019]",
					"type" : "string",
					"minLength":1
				},
				"reference":
				{
					"description" : "A reference to the exchange schema containing the specifications of the data structures. [SWIM-SERV-019].",
					"type" : "string",
					"minLength":1
				}
			}
		}
 Rules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATEsame
DEFINITIONsame


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 namedescriptiontypeguidancerule
---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)
informationDefinitionA formal representation of information concepts or data concepts. [SWIM-SERV-022]InformationDefinitionRational: Enables to understand the information provided by the service, with a specific focus to the semantics of the informationMandatory
exchangeSchemaFormal description of the data involved in an information exchange.ExchangeSchemaRational: Enables to understand data structure, and should include definition documents (XSD, JSON Schema,).Mandatory








ExchangeSchema - Mandatory

Enables to understand data format(s).

attribute namedescriptiontypeguidancerule
nameThe name of the exchange schema. [SWIM-SERV-019]stringProvide the name of the data format that is used to exchange data via the service interface.Mandatory
schemaLanguageDescription of the language used (e.g. XML, JSON). [SWIM-SERV-019]stringIndicate the language in which the data format is expressed (e.g. XSD, JSON, natural language,..)Mandatory
referenceA 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.

  • No labels