diff --git a/code/API_definitions/one-time-password-sms.yaml b/code/API_definitions/one-time-password-sms.yaml
index becb337..c363dac 100644
--- a/code/API_definitions/one-time-password-sms.yaml
+++ b/code/API_definitions/one-time-password-sms.yaml
@@ -5,10 +5,10 @@ info:
     Service Enabling Network Function API to send short-lived OTPs (one time passwords) to a phone number via SMS and validate it afterwards, in order to verify the phone number as a proof of possession.
 
     # Relevant  Definitions and concepts
-    - **NaaS**: *Network-as-a-Service* model where Telco Network resources are exposed to third parties through APIs. In this particular API, One Time Password is exposed following this model. 
+    - **NaaS**: *Network-as-a-Service* model where Telco Network resources are exposed to third parties through APIs. In this particular API, One Time Password is exposed following this model.
     - **OTP**: *One Time password* is a one-time authorization code (OTAC) that is valid for only one login session or transaction.
 
-    # API Functionality 
+    # API Functionality
     It enables a Service Provider (SP) to send an OTP code by SMS and validate it to verify the phone number (MSISDN) as a proof of possession.
 
     # Resources and Operations overview
@@ -92,7 +92,7 @@ paths:
           $ref: '#/components/responses/Generic504'
       security:
         - two_legged:
-          - one-time-password-sms:send-validate
+            - one-time-password-sms:send-validate
   /validate-code:
     post:
       tags:
@@ -146,20 +146,22 @@ paths:
           $ref: '#/components/responses/Generic504'
       security:
         - two_legged:
-          - one-time-password-sms:send-validate
+            - one-time-password-sms:send-validate
 components:
   schemas:
     SendCodeBody:
+      description: Structure to request sending a code to a phone number
       type: object
       properties:
         phoneNumber:
           $ref: '#/components/schemas/PhoneNumber'
         message:
-          $ref: '#/components/schemas/Message'         
+          $ref: '#/components/schemas/Message' 
       required:
         - phoneNumber
         - message
     SendCodeResponse:
+      description: Structure to provide authentication identifier
       type: object
       properties:
         authenticationId:
@@ -167,6 +169,7 @@ components:
       required:
         - authenticationId
     ValidateCodeBody:
+      description: Strcuture to request code verification
       type: object
       properties:
         authenticationId:
@@ -198,6 +201,7 @@ components:
       maxLength: 10
       example: AJY3
     ErrorInfo:
+      description: Structure to describe error
       type: object
       required:
         - status
@@ -216,11 +220,12 @@ components:
   securitySchemes:
     two_legged:
       type: oauth2
+      description: oauth2 security schema
       flows:
         clientCredentials:
           tokenUrl: https://auth.example.com/token
           scopes:
-            one-time-password-sms:send-validate: Permission to send OTP by SMS and to validate it  
+            one-time-password-sms:send-validate: Permission to send OTP by SMS and to validate it
   responses:
     Generic400:
       description: Problem with the client request