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


Requirement

Title

Filter capabilities

Identifier

SWIM-SERV-024

Requirement

A service description shall describe the filtering capabilities, including meaning and syntax of filter expressions, which can be applied to the information exchange.

Rationale

This requirement ensures that the precise meaning of the filter expressions is understood.

Verification

Completeness: If filter expressions are applied, verify that the capabilities, meaning and syntax are included.

Consistency: Not Applicable.

Correctness: Not Applicable.

Examples/Notes

Examples include indication of how to interpret and/or combine filters, including cases such as usage of wildcards, allowing and interpreting empty filters, combinations of filters in terms of logical expressions (e.g. implicit AND, implicit OR, explicit operator), etc.

Note: Nothing needs to be provided when the exchanged information has no filter expression.

Level of Implementation

Mandatory

Guidance

No guidance provided.

Guidance for JSON service description

tentative JSON Guidance

Schema

The guidance concerns JSON Schema v0.0.3 (see Schema releases).

 Schema excerpt [+]

The schema does NOT foresee an explicit field for describing filter capabilities. To cope with this shortcoming, the Concept type planned for optional information is used.

	
		"ServiceGeneralDescription" : 
		{
			"description" : "Description of the service in terms of what it provides, the purpose and under which conditions and quality levels the service is provided.",
			"type": "object",
			"additionalProperties": false,
			"required": ["operationalNeed", "functionality", "qualityOfService", "accessAndUseCondition", "validation"],
			"properties":
			{
				...
				"concepts":
				{
					"description" : "Optional information intended for a good understanding of the service. This may cover design concepts related to the service, logical model, design considerations, or any other information not pertaining to the other fields.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Concept" }
				},
				...
			}
		},


		"Concept" : 
		{
			"description" : "Optional information intended for a good understanding of the service. This may cover design concepts related to the service, logical model, design considerations, or any other information not pertaining to the other fields.",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description"],
			"properties":
			{
				"description":
				{
					"description" : "Description of the concept.",
					"type" : "string",
					"minLength":1
				},
				"name":
				{
					"description" : "The name of the concept.",
					"type" : "string",
					"minLength":1
				}
			}
		},
 Rules [+]

Rules expressed for the cases as defined in Registry URD.

caseschema rules
COMPLIANTconcept is optional in the schema
CANDIDATEsame
DEFINITIONsame

JSON Guidance

Case 1 - The service offers filter capabilities

info

The JSON schema does not provide specific attributes to capture this information. As a consequence the Concept structure within the schema will be used.   


When the service offers filter capabilities, these needs to be described clearly. 

1° Use the Concept structure to describe an overview of the filter capabilities 

  • attribute name = "Filter capabilities" 
  • attribute description = overview of filter capabilities

2° Describe the filter capabilities in detail, including meaning and syntax of filter expressions

  • Either, this can be added to the attribute description above
  • Or this is added to the service operation(s) that expresses these filter capabilities

Note: Make sure to include indication of how to interpret and/or combine filters, including cases such as usage of wildcards, allowing and interpreting empty filters, combinations of filters in terms of logical expressions (e.g. implicit AND, implicit OR, explicit operator), etc.

Case 2 - The service does not offer filter capabilities

When the service does not offer filter capabilities, nothing needs to be included in the service description.

JSON example

		"serviceGeneralDescription": {
			...
			"concepts": [
				{
					"name": "Filter capabilities",
					"description": "...overview and details here ..."
				}
			]
			...
  • No labels