IATA Open Air JSON Library Consumption Guide
- Vanni Sanvincenti
1 Background
IATA Open Air program enables creation of APIs and API data models within the Airline Industry by leveraging existing business and data models, validation rules, common taxonomy and other API design best practices. The industry adopted the process to create and maintain the Airline Industry Data Model (AIDM) which contains the features to allow creation of data models for message exchange. Within IATA Open Air program, that process and tooling is extended for creation of API specifications, both for IATA industry standard APIs as well as for any Airline Industry proprietary APIs.
For the consistency of data definition in the industry proprietary APIs, the IATA Open API working group has designed the procedure and specification to derive the JSON schema library from AIDM integrated Model under governance view, including all standard data entities and their definition. Developers can reuse the schemas from the JSON library, extend the standard data model by adding provider specific data definition, in the proprietary API specification and achieve IATA certification.
This document describes the scope of Industry API standardization, as well as the guidelines how the developer should follow the industry standards to consume the schemas from JSON Library in design of the proprietary API, and achieve the industry API certification.
2 Status of the document
This document is developed by the IATA Open Air working group and AIDM team, and has been reviewed by a targeted group of industry developers. The implementation feedback received from the reviewing parties at the time of publication has been incorporated in this document.
This document has been endorsed by IATA Architecture Technology Strategy Board (ATSB) under Passenger Standards Conference (PSC) governance.
The pilot Open Air JSON Library has been released in 22.2 package (second IATA release of 2022), and been made available for public access in IATA Release repository.
3 Industry API standardization
There are 2 types of APIs that are supported by the Open Air Industry standard.
Compliant API
Conformant API
3.1.1 Compliant – Proprietary API
IATA recommends API providers to follow the industry adopted Open Air API Standards and Best Practices in the proprietary API design and implementation. The proprietary API may be related to any business scenario in support of any stages or any steps described in Figure 1 the Airline Value Chain Reference Model.
Figure 1 AIDM Airline Value Chain Reference Model
Any industry API provider may apply for Open Air compliance certification for the proprietary API which follows the standards. Section 0 describes the Open Air certification framework. The certified API is recognized as a Compliant API and is listed in the Open Air Industry API Registry, providing visibility to the industry.
In future, the Open Air Industry API Registry will provide additional features, such as, self-service certification, API discoverability, etc.
3.1.2 Conformant – Industry Standard API
The objective of Conformant API is to define the industry standard API specification, to fulfill the common requirement from specific business scenario, which is faced by most of the applicable industry parties. Similar to what is described in section 0, the business scenario can be from any stages or steps across the Airline Value Chain capabilities shown in Figure 1.
Below are some example scenarios of an industry standard API, as well as the supported capability of that API.
Flight status API for Communication Management Capability
Common Use API (interact with Common Use devices, e.g self bag-drop, boarding pass printer, boarding gate, etc) for Departure Management Capability
BSP (Billing and Settlement Plan) Agency Risk monitoring APIs for Offer and Order Management Capability
The delivery of IATA Conformant APIs MUST follow industry governance process under the PSC. The business process and requirement MUST be adopted by corresponding business boards, for example, Plan Board, Shop-Order Board, Pay-Account Board, Travel Board, etc, and the API specification, as well as data model MUST be adopted by ATSB.
API providers, who want to deliver IATA conformant API specification, need to meet the below criteria. Most likely, IATA conformant API does not apply to the industry provider’s proprietary APIs.
Understand the industry standard data model - AIDM
Follow AIDM guidelines and methodology in the modeling activities
Use AIDM modeling tool
Follow industry governance process for adoption under PSC
3.2 Certification Framework
In order to promote adoption of industry API standards and best practices, IATA is running an Open API certification program.
As shown in Figure 2 Open Air certification framework, there are 3 compliance levels (Level 0-2) in the Open Air certification framework. In addition, Conformant API means the API is an industry standard API, which has been designed following AIDM methodology and been adopted under PSC governance. The requirements for each compliance levels, as well as the Conformant API, have been defined as shown in Figure 3. The requirements MUST be fulfilled to achieve the corresponding level of compliance certificate.
Figure 2 Open Air certification framework
Open Air JSON Library should be consumed by any developers, or any industry parties in their proprietary API model design. The API provider may thereafter apply for Open Air certification, as long as the API is intended to support a business scenario related to the airline industry.
In the proprietary API for certification purpose, developers must specify:
The release number of the Open Air JSON Library, from which the API data model is derived from, using the OAS extension “x-iata-release”, such as “x-iata-release”: ”22.3”
3.3 Proprietary API standardization
Figure 3 shows the process for API provider to standardize the proprietary APIs, collaborate with IATA Open Air team to verify the API specification and achieve the certificate.
Figure 3 API Standardization – Provider Proprietary API
3.3.1 General process
Please find below as the general process proprietary API standardization:
Design
API providers can use any API design tool, SCM tool and lifecycle management platform, at their own choice, to deliver the proprietary API. It is recommended for the providers to apply the Open Air standards and best practices at the stage of API design.
Certification application
API providers should follow the certification procedure described in IATA Open Air site to send the application form to IATA Open Air team. Along with the form, the provider must send the API specification in OAS 3.0 format to IATA team (openair@iata.org). OAS 3.0 is the API documentation specification adopted by Open Air standards at present.
Verification
IATA team will work with the API provider to validate the API specification, verify the level of compliance, and issue the certificate. The Open Air Design Governance tool may be used to collaborate during the verification period, for example, resolve errors/warnings in the API specification, record and resolve comments, etc. The certificate will only be issued to the API that is live in the production environment.
NOT all capabilities and tools described in Figure 3 are live yet. Some tools and services will be released in the later stage, such as data model self-verification, API style Compliance Rule Set, etc.
3.4 Open Air JSON Library
The Open Air JSON Library is delivered as per industry adopted requirement and procedure. The schema objects in the library represent all applicable data entities and elements with standard definition, which are produced from AIDM integrated model.
The schema objects in the library are compliant with OAS 3.0 schema objects specification. The structure of schema object in the library complies with the template and mapping defined in the Open Air Standards and Best Practices.
The JSON library can be imported in the API provider’s own API design tool and platform. The developer can reuse the data model and definition in the Open Air JSON library or extend the standard model by adding provider specific data definition in the proprietary API specification. Developers MUST follow the directives and guidelines in the section 4 - Directives and guidelines, to derive the data model from the JSON Library for the certification purpose.
The library has been tested in a couple of main API design tools. At a later stage, IATA team will provide the developer manual on how to use specific design tool(s) to reuse and extend the schemas in the library.
Open Air JSON Library is under the IATA PSC governance, following the PSC release cycles.
4 Directives and guidelines
This section defines the directives and guideline that MUST be followed by the developers in the standard API design. The developers, who want to achieve Open Air compliance certificate, MUST follow the directives and guidelines.
Developers may use the JSON Library for their own purposes in addition to those that have been described herein, for example, internal system implementation, database design, micro-service development, etc. That specific purpose may not have been considered in the JSON Library specification and may not be officially supported.
4.1.1 Normative
The key words MAY, MUST, MUST NOT, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The rules defined herein are normative.
The descriptive text, diagrams, examples, and notes in this specification are non-normative. Some of the examples, represented in JSON format, contain characters that are invalid JSON, such as inline comments (//) and the use of ellipsis (...) to denote information that adds some value to the example. Developers should remove this content if they desire to use the information as valid JSON.
4.1.1.1 Summary of rules
The 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.
Developers MUST follow the below rules to consume schema objects in the JSON Library.
4.1.2.1 Reuse the schema object
Rule 1: Developers MAY reuse the schema objects exactly as they appear in the JSON library.
Example 1 - reuse schema Object
"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.
4.1.2.2 Reuse subset of “properties” section of schema object
The developers may not need all the sub-schema objects represented within the “properties” section of the schema object (refer to schema object properties section in OAS 3.0 specification) in the API specification.
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", … ] } … |
Developers can copy the desired schema object from the JSON Library and select the subset of sub-schema objects from the “properties” section, to reuse it in the proprietary API specification. Another approach is to select the subset of common schema object components and reuse, using the propriate API design tool which offers such feature.
4.1.2.3 Apply restrictions to the schema object
The developers may want to apply more restrictions on the standard data model, to fulfil the business requirement, for example, limit the number of offers returned from one interaction.
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.
Table 1 is the summary of most of properties defined in the schema object in OAS 3.0 specification, and the examples of restrictions for those properties (refer to schema object properties section in OAS 3.0 specification). The property of OAS 3.0 schema object, that has not been listed in Table 1, for example title, type, items, allOf, etc, does NOT apply to Rule 3.
Property of OAS Schema Object | Restriction examples |
minimum/maximum, exclusiveMinimum/Maximum, min/maxLength, min/maxItems, min/maxProperties |
|
pattern, format |
|
uniqueItems |
|
multipleOf, required, enum, default, not |
|
additionalProperties |
|
Table 1 Restrictions on the schema object
4.1.2.4 Change the schema object
The developers SHOULD NOT change the value of any properties in the schema object, without marking the schema object as experimental content, except that the change on the value of the specific property has been explicitly defined as normative in the guidelines.
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 4.1.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.
4.1.2.5 Extend the schema object
Developers may want to extend the schema object to fulfill the business requirements. This section describes the guidelines to derive the data model by extending the schema objects from the JSON Library. The provider MUST follow the guidelines in 4.1.2.5 to meet “Req 3. "Experimental” content MUST be designated in a way in which identifies it as such” as described in Figure 2, in which case the API specification is still considered as Level 1 Compliance.
Rule 7: The API developers MAY extend the schema object. The extended schema object MUST be marked as experimental content following the guidelines in 4.1.2.5.
Experimental Content is any schema data structure, within an API specification, which has not been derived from the AIDM Logical Data Model.
OAS extension property “x-iata-experimental” MUST be defined as true, either on the level of schema object or on the level of sub-schema object represented within the “properties” section of the schema object, to mark the schema or sub-schema object as experimental content, as long as the schema object has been extended or denormalized in the way that does not follow the guidelines described in the sections 4.1.2.1, 4.1.2.2, 4.1.2.3 and 4.1.2.4.
Note: Experimental Content may also be used in the scenario that the API provider implements the Industry Standard Conformant API and would like to extend the data model in the Conformant API during the implementation. The implementation guidance for the Industry Conformant API is to be described in a separate document.
There are different scenarios where the schema object may need to be extended in the proprietary API.
The developers need an additional sub-schema object within the “properties” section of a schema object (A). There is already a schema object (B) in the library which can be used for that sub-schema object.
In this case the developer MAY add a property under “properties” section of the object (A) and add the $ref property to refer the schema object (B). The rest of schema object (A) remains unchanged from the library. The newly added sub-schema property in schema object (A) MUST be marked as experimental content.
Example 3 - extend schema object: #1 //need an additional property in Pax schema object (A), which show the vouchers that a passenger has; the changes to the standard schema object is in Bold "Pax": { "title": "Passenger", "type": "object", "properties": { … "birthdate": { "$ref": "#/components/schemas/Date" }, "booking": { "title": "Each Passenger may has one and only one Booking", "description": "A booking or reservation.", "$ref": "#/components/schemas/Booking" }, “vouchers”:{ //add one property in the Pax schema object, with $ref to the existing Voucher object "title": "Each Passenger may have one or more vouchers", "type": "array", “x-iata-experimental”:true, //mark the sub-schema as experimental content "items": { "$ref": "#/components/schemas/Voucher" } } … } "Voucher": { // the Voucher schema object (B) defined in the library "title": "Voucher", "description": "A document that entitles the holder to a discount or that may be exchanged for goods or services.", …. }, |
The developers need an additional sub-schema object within the “properties” section of one schema object (A), while there is no applicable schema object defined in the library.
In this case the developer MAY add another schema object (B) in the proprietary API specification, as well as a property under “properties” section of the object (A) with a $ref property to refer the schema object (B). Both the newly added sub-schema property in schema object (A) and the schema object (B) MUST be marked as experimental content.
Example 4 - extend schema object: #2 //need an additional property “passport” in Pax schema object (A), which is not defined in the library yet; the changes to the standard schema object is in Bold "Pax": { "title": "Passenger", "type": "object", "properties": { … "birthdate": { "$ref": "#/components/schemas/Date" }, "booking": { "title": "Each Passenger may has one and only one Booking", "description": "A booking or reservation.", "$ref": "#/components/schemas/Booking" }, “passport”:{ //add one property in the Pax schema object, with $ref to the Passport object "title": "Each Passenger may have one passport", "type": "object", “x-iata-experimental”:true, //mark the sub-schema as experimental content "$ref": "#/components/schemas/Passport" } … } "Passport": { // the Passport schema object (B) is added in the proprietary API specification "title": "Passport", “x-iata-experimental”:true, //mark the schema object as experimental content …. }, |
The developer MAY apply below changes to the schema object in the library. In this case, the impacted schema object and/or sub-schema object MUST be marked as experimental content.
a) De-normalize the structure of schema object in the library, for example, flattening the structure.
b) Create a brand new schema object, which is to be used in the proprietary API
c) Apply changes to the schema object in the library in the way that NOT following the guidelines in 4.1.2.3 and 4.1.2.4, for example, change the name or type of schema object, remove the restrictions on the schema object, change the relationship between elements in the model, etc.
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", "pattern": "^([A-Z]{3}|[A-Z]{2})|([0-9][A-Z])|([A-Z][0-9])$", //pattern is removed from original schema object "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
The release number indicates which JSON Library has been used by the developers to derive the API data model structure in the proprietary API specification. OAS extension “x-iata-release” MUST be used to specify the JSON Library release number, in the root level of the API specification.
Rule 9: Developers SHOULD NOT use schema objects from different JSON Libraries in the same proprietary API specification.
The purpose of Rule 9 is to keep consistency of data models in proprietary API design, minimize the design efforts from developers and simplify the certification verification of the API specification.
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 .… } |
4.1.4 Recursive references
4.1.4.1 Rules
Recursive or circular references in the API data structures may be problematic to API design tool or code generation tool.
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.
As described in 4.1.4.2, either direction of relationship between the schema objects is considered normative in the JSON Library. As per Rule 6, API developers SHOULD follow the guidelines in 5.5.4.4, and keep the desired direction of relationship in the proprietary API specification, instead of keeping the bi-directional relationships between schema objects represented in the JSON Library.
4.1.4.2 Bi-directional relationship in AIDM
As per industry expectation, the JSON library contains the schema objects in correspondence with each applicable ABIEs (entities) defined in the AIDM Governance Model. For one association between 2 entities in AIDM Governance Model, it is normative to traverse from either end of the association to another end. As shown in Figure 4, it is normative to traverse from Carrier to Order Item, or from Order Item to Carrier, in the data model.
Figure 4 bi-directional relationship between 2 entities in AIDM Governance Model
As both directions of relationships are represented in the JSON Library, it is necessary to break the recursive references in the JSON Library.
4.1.4.3 Representation of bi-directional relationship in JSON Library
The below solution has been adopted by the industry working group to represent bi-directional relationship between the schema objects in the JSON Library.
Solution:
The “primary” direction of an association is defined in the AIDM Governance Model. This is identified as the direction most likely to be used in messages or interfaces.
The primary direction would be the direction most commonly required by the developers in the proprietary API design. In this case, the primary directional relationship is represented by a “$ref” property in the source schema object, referring to the target schema object of the directional relationship.
The non-primary directional relationship is represented by an OAS extension property “x-iata-$ref” in the source schema object, referring to the target schema object of the directional relationship.
Example 7 shows how the bi-directional relationship between Carrier and Order Item objects is represented in the JSON Library, in accordance with the scenario described in Figure 4.
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
When developers derive the API data structure from the JSON Library, they SHOULD select the desired directional relationship from the schema objects. There may be 2 scenarios when selecting the desired directional relationship.
Keep primary directional relationship and remove the non-primary relationship
In the proprietary API specification, developers should keep the property, which represents the primary directional relationship, the same as it appears in the library, and remove the property, which represents the non-primary directional relationship. See Example 8.
Example 8 – keep primary directional relationship
"Carrier": { "type": "object", ... "properties": { "orderItem": { // keep the property, which represents the primary directional relationship ... "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } … }, "OrderItem": { "type": "object", ... "properties": { "marketingCarrier": { //remove the property, which represents the non-primary directional relationship "x-iata-$ref": "#/components/schemas/Carrier" ... }, ... } |
Keep non-primary directional relationship and remove the primary relationship
In the proprietary API specification, developers should modify the property, which represents the non-primary directional relationship, by changing “x-iata-$ref” to “$ref”, and remove the property, which represents the primary directional relationship. See Example 9.
Example 9 – keep “non-primary” directional relationship
"Carrier": { "type": "object", ... "properties": { "orderItem": { //remove the property, which represents the primary directional relationship ... "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } … }, "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
When developers consume the JSON Library, they may want to derive multiple schema objects in the proprietary API from a single standard schema object in the JSON Library, following the rules defined in the section 4. For example, multiple order object (A1, A2, A3…) may be derived from the standard “Order” object (A), including different subset of sub-schema objects, with extension or restrictions. The multiple derived objects can be consumed by different OAS objects, for example, request body object, response object, paths objects, etc, in the same API specification.
When there is only one object derived in the proprietary API specification, the derivation relationship can be identified easily as both the derived and standard schema objects have the same name.
When there are multiple objects derived, developers MUST use OAS extension “x-iata-derived” to specify from which standard schema object the current object is derived. In this case, one derived object SHOULD have the same name as the standard object which it is derived from, the other derived objects SHOULD have meaningful names which are relevant to the standard object, following the schema object naming convention (object name in Pascal Case).
5 Annex
5.1.1 Reference
5.1.2 List of OAS extension
OAS extension (x-) has been leveraged in the Open Air standards and best practices under different scenarios during API design. Below is the summary of Open Air OAS extensions. The names of the extension are all in lower case.
OAS Extension | Where it is used | Summary |
x-iata-experimental | Proprietary API spec | Specify the Experimental Content, as extension to the standard schema object, in the proprietary API specification See section 4.1.2.5 - Extend the schema object |
x-iata-$ref | JSON Library | To avoid bi-directional reference between 2 schema objects from the association, this extension is used to specify the non-primary directional relationship of that association. See section 4.1.4.3 - Representation of bi-directional relationship in JSON Library |
x-iata-derived | Proprietary API spec | In the scenario where multiple objects are derived from the same standard schema object in the proprietary API, this extension is used to specify the source schema object of the derivation. See section 4.1.5 - Multiple Derived Objects |
x-iata-release | Proprietary API spec | The JSON Library release number, which the data model is derived from. See section 3.2 - Certification Framework |
x-iata-checklist | Proprietary API spec | The version of Open Air checklist for certification purpose. See section 3.2 - Certification Framework |
Table 2 Open Air OAS extensions
5.1.3 Approach to Identify entities in AIDM
Identify the desired terms from Figure 1, which is defined in the Governance View of AIDM B1 – Business Contextual Models.
Find desired subject area terms from Figure 5 AIDM Subject Areas, which are defined in the Governance view of AIDM I1 – Information Contextual Models
Figure 5 AIDM Subject Areas
Click the subject area to review the class diagram defined in the AIDM Governance Model. The class diagram includes all ABIEs referred in the subject area, as well as corresponding relationships between the ABIEs.
Figure 6 Class Diagram for Price subject area is one example of the class diagram. Note that the same ABIE can be referenced in multiple subject areas in AIDM, so the corresponding JSON object are mapped to multiple subject areas in Open Air JSON library.
Figure 6 Class Diagram for Price subject area