Working towards the next version of the SWIM Supporting Material

Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents

Requirement

Panel
borderColorlightgrey
bgColorwhitesmoke
borderStyledashed

Title

Define abbreviations and acronyms

Identifier

SWIM-SERV-003

Requirement

A service description shall define all used abbreviations and acronyms and be in accordance with the AIRM abbreviation list [RD 4].

Rationale

It is best practice to document all abbreviations and acronyms used in a document.

Verification

Completeness: Verify that all used acronyms and abbreviations are defined in the service description.

Consistency: For abbreviations/acronyms existing in AIRM, verify that the definitions are the same.

Correctness: Not Applicable.

Examples/Notes

Note: It is allowed to use abbreviations/acronyms not defined in AIRM abbreviation list [RD 4]. However, when using one of those, their definitions must be the same.

Level of Implementation

Mandatory


Guidance

Examples

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

Guidance for JSON service description 

Excerpt
Info
titletentative JSON Guidance

Guidance for JSON service descriptions integrated within the SWIM Service Description Handbook.

Schema

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

Expand
titleSchema excerpt [+]
Code Block
languagejs
		"DescriptionInformation" : 
		{
			"description" : "Information identifying the service description.",
			"type": "object",
			"additionalProperties": false,
			"required": ["serviceDescriptionIdentification", "abbreviations"],
			"properties":
			{
				...
				"abbreviations":
				{
					"description" : "Abbreviations or acronyms used by the service description.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Abbreviation" },
					"SemanticCorrespondence" : "No Semantic Correspondence established"
				},
			}
		},


		"Abbreviation" : 
		{
			"description" : "An abbreviation or acronym used by the service description. [SWIM-SERV-003]",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the abbreviation. [SWIM-SERV-003]",
					"type" : "string",
					"minLength":1
				},
				"description":
				{
					"description" : "The description of the abbreviation.",
					"type" : "string",
					"minLength":1
				}
			}
		},


Expand
titleRules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTMandatory
CANDIDATEsame
DEFINITIONsame

Guidance

Within field abbreviations, (itself witinh field descriptionInformation, within field informationService), fill zero or more instances of Abbreviations.

Note:

  • the abbreviation attribute is mandatory
  • The list of abbreviations can be empty in the following cases
    • There are no abbreviation used in the document
    • All used abbreviations being are systematically made explicit, such as in "IFR (Instrument Flight Rules)".

Abbreviation

Be in accordance with the AIRM abbreviation list. It is allowed to use abbreviations/acronyms not defined in AIRM abbreviation list. However, when using one of those, their definitions must be the same. 

attributetypedescriptionguidancerule
namestringThe name of the abbreviation

The abbreviated form eg "IFR".

Verification: Check if the abbreviation exists in AIRM, verify the term is the same.

Mandatory
descriptionstringThe description of the abbreviation.

The term in full lenth eg "Instrument Flight Rules".

Verification: Check if the term exists in AIRM and is abbreviated, verify the abbreviation is the same.


Mandatory

Example

Code Block
languagejs
 "informationService": {
        "descriptionInformation": {
            ...
            "abbreviations": [
                {
                    "name": "TOBT",
                    "description": "Target Off-Block Time"
                }
            ]
        },


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