Repository Structure

Note: All folders mentioned here are relative to the root folder protocol-specs

The full specification can be found at api/{module_name}/build/{module_name}.yaml

This is an autogenerated file created by compiling multiple sets of components namely,

1. Network Modified APIs : found at api/{module_name}/components/io/
   • [For core] This folder contains io yaml refreing to the base beckn specification io for version as per the submodule linked
   • [For domain] This folder contains io yaml refreing to the core specification of the repository
2. Linked Schema : found at api/{module_name}/components/schemas/index.yaml
   • This is a index file encomprising of all schema's of parent [beckn-core/repo-core module]
3. Enum: found at api/{module_name}/components/enum/
   • These are all the enums used in module specification while creating the module artifact
4. Examples: found at api/{module_name}/components/examples/
   • These are the examples created Illustrative use of the specification and embeeded in the yaml
   • Structure api/{module_name}/components/examples/{api_name}/example_{#}.yaml
5. Unresolved YAML: found at api/{module_name}/components/{module_name}-unresolved.yaml

Diagaram

/ (root directory)
|
|--beckn-core-protocol-specs (git submodule to specific beckn inheritated release)
|--api (contains all the api specific details)
|  |--financial-core (Core Module/Repo Common Module/Repo Parent)
|  |  |--build
|  |  |  |--financial-core.yaml (Built Single YAML with api specification of the module)
|  |  |--components (contains all components of the specification)
|  |  |  |--enum (contains all enums used in module)
|  |  |  |  |--index.yaml (index yaml) 
|  |  |  |  |  |  content
|  |  |  |  |  |    Enum1:
|  |  |  |  |  |      $ref: ./enum1.yaml
|  |  |  |  |  |    Enum2:
|  |  |  |  |  |      $ref: ./enum2.yaml
|  |  |  |  |  |    ....
|  |  |  |  |--enum1.yaml (enum1 yaml)
|  |  |  |  |  |  content
|  |  |  |  |  |    enum:
|  |  |  |  |  |      - Value1 #Value 1 Comment
|  |  |  |  |  |      - Value2 #Value 2 Comment
|  |  |  |  |--enum2.yaml (enum2 yaml)
|  |  |  |  |  |  content
|  |  |  |  |  |    enum:
|  |  |  |  |  |      - Value1 #Value 1 Comment
|  |  |  |  |  |      - Value2 #Value 2 Comment
|  |  |  |--io (conatains all io referenced from beckn + module updates)
|  |  |  |  |--index.yaml (index yaml) 
|  |  |  |  |  |  content
|  |  |  |  |  |    Search:
|  |  |  |  |  |      allOf:
|  |  |  |  |  |        - $ref: ../../../../beckn-core-protocol-specs/api/transaction/components/io/Search.yaml
|  |  |  |  |  |        - $ref: ./Search.yaml
|  |  |  |  |  |    OnSearch:
|  |  |  |  |  |      allOf:
|  |  |  |  |  |        - $ref: ../../../../beckn-core-protocol-specs/api/transaction/components/io/OnSearch.yaml
|  |  |  |  |  |        - $ref: ./OnSearch.yaml
|  |  |  |  |  |    ....
|  |  |  |  |--Search.yaml (Search io additions)
|  |  |  |  |  |  changes:
|  |  |  |  |  |    - Marked Required
|  |  |  |  |  |    - Add Enums
|  |  |  |  |  |    - OneOf use case
|  |  |  |  |   .....
|  |  |  |--examples (conatins examples of the APIs)
|  |  |  |  |--search (search request examples yaml)
|  |  |  |  |  |--example_0.yaml (example_0 yaml)
|  |  |  |  |  |  |  content
|  |  |  |  |  |  |    summary: Search Gift card by gift card name
|  |  |  |  |  |  |    description: Detail description of the example
|  |  |  |  |  |  |    value:
|  |  |  |  |  |  |        context:
|  |  |  |  |  |  |        ....
|  |  |  |--schema (contains beckn schema refrence index.yaml)
|  |  |  |  |--index.yaml (index yaml) 
|  |  |  |  |  |  content
|  |  |  |  |  |    Ack:
|  |  |  |  |  |      $ref: "../../../../beckn-core-protocol-specs/schema/Ack.yaml"
|  |  |  |  |  |    AddOn:
|  |  |  |  |  |      $ref: "../../../../beckn-core-protocol-specs/schema/AddOn.yaml"
|  |  |  |  |  |    ....
|  |  |  |--financial-core-unresolved.yaml (unresolved yaml to build final yaml)
|  |  |  |  |   changes:
|  |  |  |  |     - Include io from local io index.yaml
|  |  |  |  |     - Add module specific examples[if any]
|  |  |  |  |     - include schema in components section 
|  |  |  |  |     - include enums in components section 
|  |  |--docs
|  |  |  |--Readme.md (Module Introduction & description)
|  |  |  |--API_Workflow.md (API work flow illuration for business)
|  |  |  |--Attribute_to_Business.md (Attribute to business terminology mapping)
|  |  |  |--Tag_and_TagGroup.md (Supported Tags & Tag Groups with usage description)
|  |--gift-card (Module/Adaptor)
|  |  |--build
|  |  |  |--gift-card.yaml (Built Single YAML with api specification of the module)
|  |  |--components (contains all components of the specification)
|  |  |  |--enum (contains all enums used in module)
|  |  |  |--io (conatains all io referenced from beckn + module updates)
|  |  |  |  |--index.yaml (index yaml) 
|  |  |  |  |  |  content
|  |  |  |  |  |    Search:
|  |  |  |  |  |      allOf:
|  |  |  |  |  |        - $ref: "../../../financial-core/components/io/index.yaml#/Search"
|  |  |  |  |  |        - $ref: ./Search.yaml
|  |  |  |  |  |    OnSearch:
|  |  |  |  |  |      allOf:
|  |  |  |  |  |        - $ref: "../../../financial-core/components/io/index.yaml#/OnSearch"
|  |  |  |  |  |        - $ref: ./OnSearch.yaml
|  |  |  |  |  |    ....
|  |  |  |  |--Search.yaml (Search io additions)
|  |  |  |  |  |  changes:
|  |  |  |  |  |    - Marked Required
|  |  |  |  |  |    - Add Enums
|  |  |  |  |  |    - OneOf use case
|  |  |  |  |   .....
|  |  |  |--examples (conatins examples of the APIs)
|  |  |  |--schema (contains beckn schema refrence index.yaml)
|  |  |  |  |--index.yaml (index yaml) 
|  |  |  |  |  |  content
|  |  |  |  |  |    Ack:
|  |  |  |  |  |      $ref: "../../../financial-core/components/schema/index.yaml#/Ack"
|  |  |  |  |  |    AddOn:
|  |  |  |  |  |      $ref: "../../../financial-core/components/schema/index.yaml#/AddOn"
|  |  |  |  |  |    ....
|  |  |  |--gift-card-unresolved.yaml (unresolved yaml to build final yaml)
|  |  |  |  |   changes:
|  |  |  |  |     - Include io from local io index.yaml
|  |  |  |  |     - Add module specific examples[if any]
|  |  |  |  |     - include schema in components section
|  |  |  |  |     - include enums in components section 
|  |  |--docs
|  |  |  |--Readme.md (Module Introduction & description)
|  |  |  |--API_Workflow.md (API work flow illuration for business)
|  |  |  |--Attribute_to_Business.md (Attribute to business terminology mapping)
|  |  |  |--Tag_and_TagGroup.md (Supported Tags & Tag Groups with usage description)

The compilation flow is illustrated below

Setup steps

Pre-requisite

Install swagger CLI

• Install the swagger command line tool using npm (Note: you may need to use root privileges if installing it globally)

sudo npm install -g swagger-cli

Generate the resolved OpenAPI definition file on-demand

• Run the following command

./build_module {module_name}

• If the command runs successfully, you should see an output like this,

Created api/{module_name}/build/{module_name}.yaml from api/{module_name}/build/{module_name}.yaml