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

Service description identification

Identifier

SWIM-SERV-005

Requirement

A service description shall include:

  • a title by which the service description is known;
  • an edition; and
  • a reference date for use in citing the service description.

Rationale

This requirement supports the identification and citation of a service description.

Verification

Completeness: Verify that the 3 elements are included.

Consistency: Not Applicable.

Correctness: Not Applicable. 

Examples/Notes

Example service description identification:

  • “Flight Management service description, edition 20.0, 14 Mar 2016”.

Note: The edition of the service description is not to be confused with the version of the service. A service description can evolve to a new edition while still describing the same service version.

Level of Implementation

Mandatory


Guidance

Examples

See the Description Identification section within the Donlon TOBT Setting Service Description.

Guidance for JSON service description 

tentative JSON Guidance

Schema

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

 Schema excerpt [+]
		"DescriptionInformation" : 
		{
			"description" : "Information identifying the service description.",
			"type": "object",
			"additionalProperties": false,
			"required": ["serviceDescriptionIdentification", "abbreviations"],
			"properties":
			{
				"serviceDescriptionIdentification":
				{
					"description" : "Information identifying the service description.",
					"$ref" : "#/definitions/ServiceDescription",
				}
				
			}
		}

		"ServiceDescription" : 
		{
			"description" : "Information needed in order to use, or consider using, a service.",
			"type": "object",
			"additionalProperties": false,
			"required": ["serviceDescriptionTitle", "serviceDescriptionEdition", "serviceDescriptionReferenceDate"],
			"properties":
			{
				"serviceDescriptionTitle":
				{
					"description" : "The name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010]",
					"type" : "string",
					"minLength":1
				},
				"serviceDescriptionEdition":
				{
					"description" : "Manifestations of a publication embodying essentially the same content. [SWIM-SERV-005]",
					"type" : "string",
					"minLength":1
				},
				"serviceDescriptionReferenceDate":
				{
					"description" : "The date at which the document has been published. [SWIM-SERV-005]",
					"type" : "string",
					"minLength":1
				}
			}
		}
 Rules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTMandatory
CANDIDATEsame
DEFINITIONsame

Guidance

Within field serviceDescriptionIdentification, itself witinh field descriptionInformation, fill the ServiceDescription attributes.

ServiceDescription - Mandatory

Information that supports the identification and citation of a service description

attributetypedescriptionguidancerule
serviceDescriptionTitlestringThe title by which the service description is known

Provide the title of the document

Mandatory
serviceDescriptionEditionstringThe edition of the document 

Provide the edition of the document 

edition vs version

The edition of the service description is not to be confused with the version of the service. A service description can evolve to a new edition while still describing the same service version.

Mandatory
serviceDescription ReferenceDatestringA reference date for use in citing the service description

Provide a reference date for citing the service description

Format is "yyyy-mm-dd"

Mandatory


Example

        "descriptionInformation": {
	
            "serviceDescriptionIdentification": {
                "serviceDescriptionTitle": "Donlon TOBT Setting Service Description",
                "serviceDescriptionEdition": "0.93i",
                "serviceDescriptionReferenceDate": "2020-06-02"
            }
            
        }


A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.

  • No labels