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

this is not a requirement

This guidance covers any additional information that is optional and would benefit service consumers.

It mimics the structure of a requirement for a good integration within the guidance material.

Context: The service description spec specifies Mandatory and Recommended information only. Making clear that information may be provided in addition to the prescribed minimum set of elements.

Requirement

 Requirement [+]

Title

Additional optional information

Identifier

SWIM-SERV-ADD

Requirement

A service description may include additional information for a good use of the service, and not covered by the other requirements.

Rationale

The spec requirements prescribe the minimum set of elements to be contained by a
service description. Additional information useful for a good use of the service should be made available.

Verification

Completeness: Not applicable.

Consistency: Not Applicable.

Correctness: Not Applicable.

Examples/Notes

Example additional optional information

  • design concepts related to the service
  • logical model
  • design considerations

Level of Implementation

Optional

Guidance

N/A

Guidance for JSON service description

tentative JSON Guidance

Schema

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

 Schema excerpt [+]
		"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
COMPLIANTOptional
CANDIDATEsame
DEFINITIONsame

Guidance

The JSON schema includes the concepts field allowing to cover additional information.

Consider using zero or more instances of the Concept type with information that would improve clarity to the reader.

Concept type

This type covers 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

attribute

description

guidance

rule

name The name of the concept.Define a short name that makes clear what the description is about. Mandatory
description Description of the concept.Provide the description.Mandatory



Predefined uses of the Concept type

The Concept type covers some predefined uses as well. Each predefined use is related to a requirement, and proposes a value for the "name" field (which would allow automatic processing).

The predefined uses are

requirement"name" field value
SWIM-SERV-024 Filter capabilities"Filter capabilities"
SERV-OVW-008 Geographical extent"Geographical extent"
SERV-OVW-017 Sources of information"Sources of information"

Example

on going

example to be improved (eg a more specific example)

		"serviceGeneralDescription": {
			...
			"concepts": [
				{
					"name": "... short name...",
					"description": "...optional information..."
				}
			]
			...
  • No labels