Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
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
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
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 ..." } ] ...