...
4.1.1.1 Summary of rules
The below following rules MUST be followed in the API design by developers if they are to achieve Open Air certification.
Rule 1: Developers MAY reuse the schema objects exactly as they appear in the JSON library.
Rule 2: Developers MAY select and reuse the subset of sub-schema objects from the “properties” section of the schema object, exactly as they appear in the JSON Library
Rule 3: The developers MAY apply restrictions to the properties of schema object, and/or the properties of sub-schema objects represented within the “properties” section of the schema object.
Rule 4: The “required” property of the schema object, as well as its value, MUST remain same in the proprietary API specification as they appear in the library.
Rule 5: Developers MAY add content in addition to, without changing, the existing value of “title” and “description” properties, to better elaborate the business scenario context in the API specification.
Rule 6: Developers SHOULD follow the guidelines in 5.5.4.4 to change the schema object and keep the desired direction of relationship in the proprietary API specification, instead of keeping the bi-directional relationship.
Rule 7: The API developers MAY extend the schema object. The extended schema object MUST be marked as experimental content following the guidelines in 5.5.2.5.
Rule 8: Developers MUST specify the unique IATA release number of the JSON library in the proprietary API
Rule 9: Developers SHOULD NOT use schema objects from different JSON Libraries in the same proprietary API specification.
Rule 10: Developers SHOULD only define the required references between schema objects. It is NOT RECOMMENDED to include recursive references in the data model of the proprietary API.
4.1.2 Basic Rules
If an API provider wants to achieve level 1 compliance, the JSON library SHOULD be used to fulfil “Req 2. Data definition MUST be derived from IATA Airline Industry Data Model (AIDM). Only applied restrictions are allowed”, as described in Figure 2.
...
Rule 1: Developers MAY reuse the schema objects exactly as they appear in the JSON library.
Example 1 - reuse schema Object
| Code Block |
|---|
...
| ||
"AirlineLoadInfo": {// the whole schema is reused as the same |
...
"title": "Airline Load Information", |
...
"description": "An Information distinguishing different categories of cargo used for load planning characterized by Airline specific codes in addition to codes defined in AHM510.", |
...
"type": "object", |
...
"x-iata-subject-areas": [ |
...
"Aircraft Load Calculations" |
...
], |
...
"required": [ |
...
"carrier" |
...
], |
...
"properties": { |
...
"carrier": { |
...
"title": "Each Airline Load Information must one and only one Carrier", |
...
"description": "An organization which carries the passenger, baggage, or goods, and/or commits to delivering the carriage as well as any related services such as issuance of ticket, creation of Order, etc.", |
...
"x-iata-$ref": "#/components/schemas/Carrier" |
...
}, |
...
"descText": { |
...
"title": "Airline Load Information.Description Text", |
...
"description": "Description of the airline specific load information code", |
...
"$ref": "#/components/schemas/Text" |
...
}, |
...
"loadInfoCode": { |
...
"title": "Airline Load Information.Load Information Code", |
...
"description": "Airline specific load information code.", |
...
"$ref": "#/components/schemas/Code" |
...
} |
...
} |
...
} |
...
Developers can copy the desired schema object from the JSON Library to reuse in the proprietary API specification. Another approach is to load the JSON Library, as common schema object components, into the desired API design tool, and reuse the common schema object in the proprietary API.
...
Rule 2: Developers MAY select and reuse the subset of sub-schema objects from the “properties” section of the schema object, exactly as they appear in the JSON Library
Example 2 - reuse subset of properties
{ // developers can reuse subset of sub-schema objects in the schema object; the subset is highlighted in BOLD; what the developer should NOT do is marked in blue … "BagActivity": { "title": "Bag Activity", "description": "A condition in which things are happening or being done to a bag, such as 'scan a bag'.", "required": [ //should NOT remove “required” property from the schema object, nor change the value of this property "bagSegment" ], "type": "object", [ //should NOT remove or change the value of “type” property "properties": { "activityCode": { "$ref": "#/components/schemas/BaggageActivityCode" }, "actualDateTime": { "$ref": "#/components/schemas/DateTime" }, "aircraftParkingPosition": { "title": "Each Bag Activity may one and only one Aircraft Parking Position", "description": "A Gate or hard stand where an aircraft may park.", "$ref": "#/components/schemas/AircraftParkingPosition" }, "bagSegment": { "$ref": "#/components/schemas/BagSegment" }, "bagStatus": { "title": "Each Bag Activity may be refering to one and only one Bag Status", "description": "A status of a bag at a particular time in a process.", "$ref": "#/components/schemas/BagStatus" }, … }, "BaggageActivityCode": { "$ref": "#/components/schemas/BaggageActivityCodeEnum" }, "BaggageActivityCodeEnum": { "title": "Baggage Activity Code", "type": "string", "description": "The codelist contents of IATA Baggage XML Function Activity Codes. Valid Values: Produce - Bag Identity Production; Recognize - Bag Recognition; Identify - Bag Identification; Verify - Bag Verification; Qualify - Bag Qualification; Screen - Bag Screening; Reconcile - Bag Inventory Reconciliation; Acquire - Bag Acquisition; Route - Bag Routing; Move - Bag Movement; Deliver - Bag Delivery; Reclaim - Bag Reclaim; PutAway - Bag Put Away; Receipt - Bag Receipting; Withdraw - Bag Withdraw; Sort - Bag Sorting; Load - Bag Loading; Remove - Bag Removal; Offload - Bag Offloading", "enum": [ //should NOT remove entries from the list of the enum value "Produce", "Recognize", "Identify", "Verify", "Qualify", "Screen", … ] } … |
...
Example 5 - extend schema object: #3 { //the schema has been changed in the way not following the guideline, which MUST be marked as experimental content "AirlineDesigCodeEnum": { "title": "Airline Designator Code", "type": "number", // type is change from string to number "description": "The codelist contents of IATA Resolution 762 airline codes, or of ICAO airline codes." “x-iata-experimental”:true }… } |
4.1.3 Release number
Rule 8: Developers MUST specify the unique IATA release number of the JSON library in the proprietary API
...
For more information on IATA release and API versioning best practice, refer to the section “Release Overview” in Open Air Standard and Best Practices document.
Example 6 - Release Number { “openapi": "3.0.0", “x-iata-release”:”21.3”, // data structure in this proprietary API is derived from 21.3 JSON Library .… } |
...
Example 7 – bi-directional relationship represented in the JSON Library
"Carrier": { "type": "object", ... "properties": { "orderItem": { ... "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" // primary directional relationship of the association } … }, "OrderItem": { "type": "object", ... "properties": { "marketingCarrier": { //marketingCarrier is the role name of the relationship "x-iata-$ref": "#/components/schemas/Carrier" //non-primary directional relationship of the association ... }, ... } |
4.1.4.4 Select directional relationship from the library
...
Example 9 – keep “non-primary” directional relationship
"Carrier": { "type": "object", ... "properties": {
… }, "OrderItem": { "type": "object", ... "properties": { "marketingCarrier": { //keep the non-primary directional relationship, and change “x-iata-$ref” to “$ref”, "$ref": "#/components/schemas/Carrier" ... }, ... } |
...
4.1.5 Multiple Derived Objects
...