The XInput Schema - CWG Working Draft

[ravi-prakash-v]

The XInput Schema

CWG Working Draft - September 06, 2022

Document Details

This version

TODO

Latest published version

TODO

Latest editor's draft

TODO

Implementation report

TODO

Editors

Ravi Prakash (Beckn Foundation)

Authors

Ravi Prakash (Beckn Foundation)

Feedback

Issues: TODO
Discussions: TODO
PRs: TODO

Errata

No Errata exists as of now

Context

Beckn protocol defines a domain-agnostic specification that can be used to represent any customer- provider transaction by implementing a standard set of APIs and schema. Creating a transaction ideally involves the customer discovering products and services offered by various providers, selecting the desired products or services, obtaining the terms of service and payment, and then finally confirming the order. But sometimes, the provider might require additional metadata in order to confirm a transaction. This requirement may be due to legal requirements imposed by the regulatory authorities, or business requirements to allow better serviceability.

For example, a logistics service provider might require additional information from the logistics customer (like a restaurant) like the dimensions of the package, category of items (food, flammable, fragile etc), approximate weight of the package, the order Number etc,

to confirm the order. All of this information needs to be transmitted to the person availing the logistics service.

Similarly, a healthcare service might want the patient to provide information like, their medical history, a description of their symptoms, details of the insurance, etc, before confirming the order.

The nature of additional information required could vary significantly across sectors. These fields could be varied and many, and adding them as protocol attributes would make the protocol bulky and cluttered.

Problem

We require an object that captures additional information (over and above what has been published in the catalog) from the customer regarding the item being ordered without extending the core transaction protocol.

Solution

It is probably not such a good idea to transmit such required data fields as first class citizens of the transaction protocol, rather transmit them in some sort of a custom form object. This form could be a simple HTML form hosted on a url endpoint or transmitted as a whole as per standard form specifications like XForms 2.0.

The proposed design of this feature is as follows.

It starts with a schema called XInput of type Form. The definition of Form is also shown here among other relevant schemas.

 Item:
   type: object
   properties:
     xinput:
       $ref: XInput

 Order:
   type: object
   properties:
     xinput_required:
       $ref: XInput

 XInput:
   type: object
   properties:
     form:
       $ref: Form
     required:
       description: Indicates whether the form data is mandatorily required by the BPP to confirm the order. 
       type: boolean
       default: true

 Form:
   description: Describes a form that needs to be rendered to the BAP user before the confirmation of an order.
   type: object
   properties:
     url:
       description: The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. The BAP can choose to render the form as-is as an embeddable element, or process it further to blend it with the style of the application. In case the interface is non-visual, the BAP can process the form data and reproduce it as per the UI requirements.
       type: string
       format: uri
     mime_type:
       description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. If the mime_type is text/html, the application must render it inside a web view. If the mime_type is application/xml, then the application must consider it as an xForms 2.0 object and render it as per the XForms 2.0 specification.
       type: string
       enum:
       - text/html
       - application/xml
     submission_id:
       type: string
       format: uuid

 FormResponse:
   description: Describes the response to a form submission
   type: object
   properties:
     status:
       description: Contains the status of form submission.
       type: boolean
       default: true
     submission_id:
       description: This contains a UUID generated by the BPP on successful submission of the form. 
       type: string
       format: uuid
     errors:
       type: array
       items:
         $ref: Error

 Error:
   description: Describes an error object returned by the API in case of an exception scenario. The exception may be a technical one like a schema or a signature verification error; or business-related like an item not found, or an agent not available.
   type: object
   properties:
     code:
       type: string
       description: For full list of error codes, refer to docs/protocol-drafts/BECKN-RFC-005-ERROR-CODES-DRAFT-01.md of this repo
     path:
       type: string
       description: Path to json schema generating the error. Used only during json schema validation errors
     message:
       type: string
       description: Human readable message describing the error. Used mainly for logging. Not recommended to be shown to the user.
   required:
     - code
     - path

Recommendations for BPPs

The following recommendations are for BPPs who will create the form to be rendered on BAPs and receive the submissions from it.

Declaring the form

• BPPs that require additional information pertaining to individual items being ordered to confirm an order, must send the xinput object in the Item schema with a form object containing a link to the form with item-specific fields. For example, a person buying an airline ticket containing two flights - an onward Journey by Etihad and a return journey by Lufthansa might have to provide his Etihad membership code for his onward journey. For his return journey, Lufthansa might require them to declare their luggage dimensions, and upload a Covid-19 vaccination certificate.
• If BPPs require additional information pertaining to the order as a whole, they must send the xinput object in the Order schema containing a link to the form with order-specific information. For example, a cash on delivery grocery order from a store might require the store owner to declare the amount to be collected, the number of items, package category, and the weight of the package before placing the order.
• If the form is cacheable, then it is recommended for BPPs to send the form link during on_search itself.
• If the form is dynamic, then it is recommended for BPPs to send the form link during on_select, or on_init wherever applicable.

Modeling the form

• BPPs can model the form in two ways namely, a) using HTML5 Forms, or b) xForms 2.0 objects
• For creating HTML Forms, please refer to this tutorial
• For creating xForms 2.0 Forms, please refer to this specification
• Networks can mandate only one, or both types of form specification. (For new networks, it is recommended to start with HTML forms)
• For HTML forms the submission url will be present in the action attribute of the form tag as highlighted in the example below

    <form action="http://example.com/submitForm" method="post"> … </form>

• For xForms 2.0 forms, the submission url will be present in the action attribute of the xform:submissions tag as highlighted in the example below

    <xforms:submission action="http://example.com/submitForm" method="post"** includenamespaceprefixes=""/>

• It is not recommended for BPPs to send script tags along with HTML forms as it will pose a security concern for BAPs
• It is not recommended for BPPs to send style tags along with HTML forms as BAPs may re-render the form as per their UI
• It is not recommended for BPPs to send button tags along with HTML forms as BAPs may render the CTA for form submission according to their UI
• For XForms 2.0 submissions, the BPP can send the <xforms:submission /> tag to specify submission URL, but it will not be rendered at the BAP.

Handling form requests

• The form must be hosted on a trusted url, preferably with the same domain name as the BPP’s subscriber_id to avoid security-related errors thrown by BAPs.
• When requested on HTTP, the BPPs must return Content-type: text/html or application/xml in the response body headers.
• It is recommended to send a unique nonce value in UUID format whenever it receives a form request from a BAP and persist it until a submission matches the nonce or the form expires

Handling form submissions

• The form submission method must always be a HTTP/POST when using HTTP as a transport layer. Example: <form action="url" method="post">
• The form submission API must also be on the same domain name as the BPP subscriber_id to avoid security-related errors thrown by BAPs
• Form submission request should be digitally signed by the BAP
• The following algorithm must be executed at the BPP when the form is submitted on HTTP/POST,
• Check if signature is valid
• Check if the nonce value exists and is not expired
• If the nonce value exists and is not expired
  • Validate the form inputs
  • Generate a FormResponse object and return it as an application/json response
• BPPs must persist this UUID at their ends so that they can match each submission with the corresponding confirm API call

Linking form submission to existing transactions

• After successful form submissions, the BPP should ideally receive a confirm API call containing references to the submissions.
• The form submission references can be found in Order.items[ ].xinput_required.form.submission_id, and Order.xinput_required.form.submission_id fields.

Discarding Form Submissions

• The BPP can choose to discard the form submissions if the confirm API call does not arrive within a specified time window after the form has been submitted

Recommendations for BAPs

The following recommendations are for BAPs who will render the form to its users and send the submissions to the BPPs.

Identifying form declarations

• BAPs can identify required item-specific form inputs by parsing the Item schema received in on_search callbacks.
• BAPs must also check for required order-specific form inputs by parsing the Order schema received in on_select, and on_init callbacks.
• The BAP may choose to cache the form by calling the {Item}.xinput.form.url endpoint from its API endpoint.
• It should expect either an HTML or an Xforms 2.0 object as a response. If the response body header has Content-type: text/html, then it should expect an HTML form object. If it is application/xml, it should expect an xForms 2.0 model object.

Rendering the form

• BAPs should render their forms typically any time before confirming the order
• For item-specific inputs, BAPs should typically render the form when the user selects the item for ordering
• For order-specific inputs, BAPs should typically render the form
• BAPs should remove any script, style, and button tags when rendering the form inside their own UI

Submitting the form

• BAPs should submit the form data on the submission url specified in the form object via a HTTP/POST request.
• For HTML forms the submission url will be present in the action attribute of the form tag as highlighted in the example below

<form **action="http://example.com/submitForm" method=”post”**> … </form>

• For xForms 2.0 forms, the submission url will be present in the action attribute of the xform:submissions tag as highlighted in the example below

<xforms:submission **action="http://example.com/submitForm"** **method="post"** id="submit" includenamespaceprefixes=""/>

• When submitting the form, the BAPs must digitally sign the request body in the request header
• All form submissions must be digitally signed by the BAP

Handling form submission responses

• Form responses are received in the FormResponse object
• The FormResponse object contains status, submission_id and an error array
• After receiving the form response, the BAP should execute the following algorithm

    If FormResponse.status is true
    	save the submission_id
    Else
    	throw an exception based on the data inside the error object

Post-Form Submission

After successful submission of the form, the BAP must ideally, send the submission_id received in the previous submission and send it in the corresponding item’s xinput.form.submission_id field, in the confirm API.

Recommendations for Network Facilitators

• Network Faciliators should publish a list of supported fields with their datatypes that can be used to create forms. This is to reduce form misuse through over-collection of data, and privacy protection.
• These fields can be the same as supported Tags list published by networks
• The IDs of the inputs are the codes

Examples

The following examples show how XInput can be used by BPPs to collect additional information from the user before confirming the order.

Example 1 : A logistics provider wants additional information on the nature of the package just before placing the order

In this example, the Logistics BPP can create a XInput object containing a link the the following form

   <form action="https://api.example-bpp.com/sendPackageDetails" method="post">
     <label for="itemCount">Number of items</label>
     <input type="number" id="itemCount" name="itemCount" value="0" />
     <label for="plength">Package length in cm</label>
     <input type="number" id="plength" name="plength" value="0" />
     <label for="pwidth">Package width in cm</label>
     <input type="number" id="pwidth" name="pwidth" value="0" />
     <label for="pheight">Package height in cm</label>
     <input type="number" id="pheight" name="pheight" value="0" />
     <label for="itemCategory">Select your degree</label>
     <select name="itemCategory" id="itemCategory">
       <option value="fnb">Food and Beverages</option>
       <option value="bns">Books and Stationery</option>
       <option value="etg">Electronic Goods</option>
       <option value="hhg">Household goods</option>
     ><br/><br/>
     <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
   </form>

Let us assume this form is hosted at - https://api.example-bpp.com/getForm?id=t8923y4ryu328473y4

The BPP can choose to send this form at an Item level or at an order level. To keep things simple, let us send this form at an order level.

Let us assume, the Logistics BAP has already declared the intent (via search), received the catalogs (via on_search), selected a specific item ( via select), and has received a quote(via on_select).

Form identification

When the BAP calls init, the Logistics BPP sends the following order object

{
   "context" : {
       "action" : "on_init",
       ...// other context details
   },
   "message" : {
       "order" : {
           "items" : [
               {
                   "id" : "4aa3feca-96b5-47dd-a233-f7fd2525922c",
                   "descriptor" : {
                       "name" : "Hyperlocal delivery"
                   },
                   "price" : {
                       "value" : "50",
                       "currency" : "INR"
                   }
               }
           ],
           "xinput" : {
               "form" : {
                   "url" : "https://api.example-bpp.com/getForm?id=t8923y4ryu328473y4",
                   "mime_type" : "text/html"
               }
           },
           "billing" : {
               ...// billing details
           },
           "fulfillment" : {
               ...// fulfillment details
           },
           ...// other order level details
       }
   }
}

Form Fetching from BPP

When the Logistics BAP receives this object via on_init, it must pull the form data from the order.xinput.form.url field and render the form on the UI. It is recommended that the Logistics BAP keeps watching for the xinput field at the item and order level.

Form Rendering on the BAP

Once pulled the BAP can render the form as-is on its UI, but it is not recommended, as doing so would result in a sub-optimal user experience. This is how the form will look if the BAP renders the form as-is using an HTML parser.

However, the BAP application can apply any styling framework (like css) on the form and render it as per the style guide of the application.

This form must be rendered just before firing the confirm API. This is typically just before checkout, when the BAP invokes the payment flow.

The BAP must render the submit button for this form. This submit button functionality can be merged with the final checkout button or placed exclusively for this form as part of a two-step process.

For example, in the case of a two step process, the flow might look like this

• Step 1:

  • 1.1 Render form with the first button
  • 1.2 Capture form data and submit it to BPP
  • 1.3 Save submission_id if submission is successful

• Step 2:

  • 2.1 Render the final confirmation screen with final checkout button
  • 2.2 Fire confirm along with the submission_id reference in the order object

In the case of a one step process, the BAP can collect all the data on a single form and then fire two consecutive API calls, one to submit the form, and the other to confirm the order.

In any case, the form submission id must be transmitted along with the confirm API call.

The BPP will receive the confirm call with the submission_id as reference. It will verify the submission against the submission_id and link that data along with the confirm API.

Now the BPP has all the information required to confirm the order. It can either go ahead with the confirmation or reject the request if applicable.

Example 2: A health & wellness service provider wants additional information about the patient's symptoms before confirming a teleconsultation appointment. The provider and customer are on apps that are DHP-enabled (beckn protocol for health and wellness).

[TODO]

Example 3: A recruitment agency wants additional information about the candidate before confirming a job application. The provider and customer are on apps that are DSEP-enabled (beckn protocol for education and skilling).

   <form action="https://api.example-bpp.com/candidateDetails" name="job_application" method="post">
     <label for="locationPreference">Select you preferred location of work</label>
     <select name="backend_technologies" id="example-bpp.com/locationPreference">
       <option value="std:011">Delhi</option>
       <option value="std:080">Bangalore</option>
       <option value="remote">Remote</option>
     >
     <label for="experience">Years of experience</label>
     <input type="number" id="years_of_experience" name="experience" value="0" />
     <label for="backend_technologies">Select the technologies that you have experience in</label>
     <select name="backend_technologies" id="example-bpp.com/backend_technologies" multiple>
       <option value="php">PHP</option>
       <option value="ruby_on_rails">Ruby on Rails</option>
       <option value="node_js">Node JS</option>
       <option value="python">Python</option>
     >
     <label for="other_technologies">Select any other technologies that you are profient in</label>
     <input type="text" id="example-bpp.com/other_technologies" name="other_technologies" value="0" />
     <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
   </form>

Example 4: A flight booking system wants the passenger to declare his Covid vaccination status before confirming the booking.

   <form action="https://api.example-bpp.com/covidDeclaration" name="covid_declaration_form" method="post">
     <input type="radio" id="vaccinated" name="vaccination_status" value="true">
     <label for="vaccinated">Yes</label>
     <input type="radio" id="not_vaccinated" name="vaccination_status" value="false">
     <label for="not_vaccinated">No</label>
     <label for="from_addr">Enter the address you are travelling from </label>
     <input type="text" id="from_addr" name="from_address" />
     <label for="from_addr">Enter the address where you are travelling to</label>
     <input type="text" id="from_addr" name="to_address" />
     <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
   </form>

Example 5: A mentor can seek additional information about a mentee before accepting the mentee's request for enrollment into the session(1-1 session as well as 1-many sessions). The provider and customer are on apps that are DSEP-enabled (Beckn protocol for education and skilling).

In this case, the on_init BPP passes the form URL to BAP, which is rendered and filled by the mentee on BAP. The BAP then sends the acknowledgment ID received after the submission of the form in the confirm API call to BPP.

An example of a form can be as below:-

    <form action="https://api.example-bpp.com/sendMenteeInformation" method="post">
        <label for="resume">Bio of Mentee</label>
        <input type="file" id="resume" name="resume" multiple="true" />
        <label for="experience">Experience in No Of Years </label>
        <input type="text" id="experience" name="experience" value="0" />
        <label for="recommendationLetter">Recommendation Letter from any organisation</label>
        <input type="file" id="recommendationLetter" name="recommendationLetter" multiple="false" />
        <label for="degree">Select your degree</label>
        <select name="degree" id="degree">
            <option value="BTECH">Btech in Computer Science</option>
            <option value="PHD">PHD in Computer Science</option>
            <option value="MS">Masters in Computer Science</option>
        </select>
        <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
   </form>

Acknowledgements

The authors would like to thank the following people for their support and contributions to this document.

• Venkataramanan Mahadevan (Humbhionline)
• Pramod Varma (Beckn Foundation)
• Sujith Nair (Beckn Foundation)
• Akash Shah (Shikshalokam)
• Sankarshan Mukhopadyay (Dhiway Networks)

[aks30]

Example: A mentor can seek additional information about a mentee before accepting the mentee's request for enrollment into the session(1-1 session as well as 1-many sessions). The provider and customer are on apps that are DSEP-enabled (Beckn protocol for education and skilling).

Workflow: In this case, the on_init BPP passes the form URL to BAP, which is rendered and filled by the mentee on BAP. The BAP then sends the acknowledgment ID received after the submission of the form in the confirm API call to BPP.

An example of a form can be as below:-

    <form action="https://api.example-bpp.com/sendMenteeInformation" method="post">
        <label for="resume">Bio of Mentee</label>
            <input type="file" id="resume" name="resume" multiple="true" />
     
        <label for="experience">Experience in No Of Years </label>
            <input type="text" id="experience" name="experience" value="0" />
        
        <label for="recommendationLetter">Recommendation Letter from any organisation</label>
            <input type="file" id="recommendationLetter" name="recommendationLetter" multiple="false" />

        <label for="degree">Select your degree</label>
            <select name="degree" id="degree">
                <option value="BTECH">Btech in Computer Science</option>
                <option value="PHD">PHD in Computer Science</option>
                <option value="MS">Masters in Computer Science</option>
            </select>
            <br/><br/>
        <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
   </form>

Cc - @vijiurs @kiranharidas187

[sankarshanmukhopadhyay]

Example: A mentor can seek additional information about a mentee before accepting the mentee's request for enrollment into the session(1-1 session as well as 1-many sessions). The provider and customer are on apps that are DSEP-enabled (Beckn protocol for education and skilling).

Would this correspond to meeting eligibility requirements related to the mentoring event? For instance, evidence of previous knowledge or skills which are prerequisite for the mentoring etc. Would the form also allow a combination of required and optional additional information?

[ravi-prakash-v]

@sankarshanmukhopadhyay @aks30 it would be helpful to elaborate on the nature of information requested by the BPP using a concrete example. For example,

A mentor registered on a Mentorship BPP may require the candidate's bio, their experience, a recommendation letter, and degree to decide whether or not to accept the application for a mentorship under him.

It helps to keep the example verbose and as realistic as possible so that implementors can relate.

[ravi-prakash-v]

@sankarshanmukhopadhyay form can contain both required and optional fields.

[cybervivek]

Hi @core-wg-admin

Point 1:

HTML Forms may contain lot of "UI" definition schema given the "wide specification" of HTML, whereas we need a "data field schema".
Supporting/Expecting an HTML form would be too "open" and "wide" specification. And as you mentioned, from UI rendering perspective, it won't be of much use, as most of the BAPs will require to parse and render it in different way based on Web/Mobile/IoT devices. And HTML form parsing would be quite difficult if we just want to extract the "fields schema" from within it.

XForm could still be applicable, but again that is too wide specification. Can there be a simpler schema for "form fields"?
E.g. (Can be elaborated if needed):

Form:
   description: Describes a form that needs to be rendered to the BAP user before the confirmation of an order.
   type: object
   fields:
          type: array
          field:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
              field-type:
                description: data type of this form field
                type: string
                enum: 
                - int
                - string
                - date-time
                - etc
              field-validation:
                description: field level validation rules, regex, min-max length etc (TBD - Needs to elloborate)
                type: string

Point 2:

Apart from having a "URL" for fetching a form, would it be beneficial to directly provide the complete form (XForm schema) details within the on_init response body? So instead of having "url", it'll have a string/json field which will have the complete form itself.

Consider a case, where BPP needs XInput for multiple "items" of the "order" object. In such case, having "URL" based forms, would require multiple network round-trips not only for "fetch" but also to "submit" the forms. And this may degrade the user experience due to the "time" delays, apart from the network/bandwidth overheads.

To see the XInput requirement at item level, you can correlate it with the world of customized/personlized products (e.g. https://www.vistaprint.in/), where each product item will have some custom information added by the shopper.

If we support form fields schema within the on_init response itself, then we would also need the "XInput" property for confirm request's order schema too.

Please let me know, if I am understanding this XInput draft correctly or not?

[ravi-prakash-v]

@cybervivek, regarding Pt 1

As per the section Recommendations / Modeling the form,

It is not recommended for BPPs to send script tags along with HTML forms as it will pose a security concern for BAPs

It is not recommended for BPPs to send style tags along with HTML forms as BAPs may re-render the form as per their UI

It is not recommended for BPPs to send button tags along with HTML forms as BAPs may render the CTA for form submission according to their UI

The above points clearly mention how Forms must be modeled by BPPs and BAPs aren't mandated to render this form as-is. If present, BAPs should strip away all scripts and styling attributes. We can expand this section further, but I would not recommend creating a new form standard. It will be difficult to maintain and evolve. We can explore simpler form standards if there are any.

Regarding Pt 2, static forms can be cached prior to init. If BPPs send form urls during on_search, it can be cached allowing faster rendering on the UI. But if forms are dynamic, then urls are the way to go. I don't see a major issue with urls, it keeps the protocol light weight. Sending form strings for a large catalog will make the packet quite heavy. The BAP will not even use most of the forms, only the ones related to the Order.

[singhs020]

@core-wg-admin Is there a possibility to implement a strict schema for the form which can be returned by the uri. The structure mentioned by @cybervivek can work. for example:

{
  "form": {
    "action": "https://api.example.com",
    "method": "POST",
    "fields": [
      {
       "name": "test1"
        "type": "text",
        "required": true
      },
      {
        "type": "list",
        "required": true,
        "name": "test1"
        "options": [
          {
            "label": "foo",
            "value": "bar"
          }
        ]
      }
    ]
  }
}

The BAP will be able to render the form using their components. It will give enough flexibility to mobile apps to choose native components and use their design guide to render the components.

Regarding the submissions of the form, as the form is submitted separately and is not tied with the actual object, are we going to send some meta information like transactionId etc. which can be used by the seller apps to to link the order with the form and show it in a proper way to the seller?

The submission will look something like:

{
  "test1": "value",
  "test2": "value", 
  "meta": {
    "transactionId": "transactionId",
    "any other": "relevant property"
  }
}

[cybervivek]

@core-wg-admin

For point 1 (Regarding Form Schema)

I would agree that maintaining a new Form Schema, would be a difficult one, and we should look for some simple pre-existing form definitions. I'll see if I can find any pre-developed schema around this.

For point 2 (Regarding Form Url):

Agree to you, I was looking to avoid some additional round trips to BPP server, but to keep the spec light, URLs are fine.

Example Use Case, I was referring:
Personalised merchandising website, sells custom printed/embroidered T-shirts, Cap, Business Card etc.

1. Shopper is on "Custom Tshirt" product page, (based on on_search form), XInput needed > "Name to be Imprinted" field. Based on the size of imprint, updated product price is shown to the shopper.
2. Shopper goes to "Cap" product page, XInput needed > "Logo to be Imprinted" field. Based on number of colors in the logo, the updated product price is shown to the shopper.
3. Shopper is now on "Business Card" page, XInput needed > "Name, Title, Contact" fields.
4. Shopper is on checkout page, to see the total price, and provide payment and address details.

In this case, Item level XInput fields has impact on product pricing, For e.g. Number of colors chosen for custom printing on Tshirt.

Question:

So can we say that the "form submission" would take place before "select" request, And "form submission id" would be sent with "select" request to get the price quote right on the Product Detail page, right?

[ravi-prakash-v]

@cybervivek I see where you are coming from. BPPs may need a way to indicate when the additional data would be needed.

One way could be to add a flag to the XInput object that indicates at what stage the data is needed. Like { "required_before" : "select" }. What do you think?

[cybervivek]

@core-wg-admin Yes, that flag solves the problem.
So we can have a Enum defined for the supported phases, those would be mostly similar to the request types we have.

[ravi-prakash-v]

@sankarshanmukhopadhyay added your inputs regarding standardizing forms by network facilitators to prevent misuse of forms.

[ravi-prakash-v]

@aks30 added your example to the draft

[RashmiG-Protean]

Example: A scholarship provider wants additional information from student while applying to scholarship

In this example, we will assume ABC Limited is providing scholarship for engineering students and student is applying to this scholarship.

Below is XInput object containing a link the following form:

<form action="https://api.example-bpp.com/sendApplicationDetails" method="post">
     <label for="sscMrk">SSC Marks</label>
     <input type="number" id="sscMrk" name="sscMrk" /><br />
     <label for="sscMrkFile">Upload SSC Marksheet</label>
     <input type="file" id="sscMrkFile" name="sscMrkFile" /><br />
     <label for="hscMrk">HSC Marks</label>
     <input type="number" id="hscMrk" name="hscMrk" /><br />
     <label for="hscMrkFile">Upload HSC Marksheet</label>
     <input type="file" id="hscMrkFile" name="hscMrkFile" /><br />
     <label for="admFile">Upload Admission Letter</label>
     <input type="file" id="admFile" name="admFile" /><br />
     <label>Is your parents working with ABC Limited?</label>
     <input type="radio" id="isFamMemWrkng_yes" name="isFamMemWrkng" value="Y">
     <label for="isFamMemWrkng_yes">Yes</label>
     <input type="radio" id="isFamMemWrkng_no" name="isFamMemWrkng" value="N">
     <label for="isFamMemWrkng_no">No</label><br />
     <!-- If Yes, below inputs (Person Name, Department Name, Branch, ID Card, Relationship with Person) are required -->
     <label for="pname">Name of Person</label>
     <input type="text" id="pname" name="pname" /><br />
     <label for="pdept">Departmane Name</label>
     <input type="text" id="pdept" name="pdept" /><br />
     <label for="pbranch">Select Branch</label>
     <select name="pbranch" id="pbranch">
         <option value="mum">Mumbai</option>
         <option value="pne">Pune</option>
         <option value="bng">Banglore</option>
         <option value="del">Delhi</option>
     </select><br />
     <label for="pidcard">Upload ID card of Person</label>
     <input type="file" id="pidcard" name="pidcard" /><br />
     <label>Relationship with Person</label>
     <input type="radio" id="prel_m" name="prel" value="M">
     <label for="prel_m">Mother</label>
     <input type="radio" id="prel_f" name="prel" value="F">
     <label for="prel_f">Father</label><br />

     <br /><br />

     <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
 </form>

Let us assume this form is hosted at - https://api.example-bpp.com/getForm?id=t8923y4ryu328473y4
BPP will send this form at order level.

Let us assume, the DSEP BAP has already declared the intent (via search), received the catalogs (via on_search), selected a specific scholarship (via select), and has received a scholarship details (via on_select).

Form identification
When the DSEP BAP calls init, the DSEP BPP sends the following order object

{
   "context" : {
       "action" : "on_init",
       ...// other context details
   },
   "message" : {
       "order" : {
           "items" : [
               {
                   "id" : "4aa3feca-96b5-47dd-a233-f7fd2525922c",
                   "descriptor" : {
                       "name" : "ABC Ltd Scholarship for Engineering Students"
                   },
                   "price" : {
                       "value" : "0",   // application fee
                       "currency" : "INR"
                   }
               }
           ],
           "xinput" : {
               "form" : {
                   "url" : "https://api.example-bpp.com/getForm?id=t8923y4ryu328473y4",
                   "mime_type" : "text/html"
               }
           },
           "fulfillment" : {
               ...// fulfillment details
           },
           ...// other order level details
       }
   }
}

Form Fetching from BPP
When the DSEP BAP receives this object via on_init, it will pull form data from the order.xinput.form.url field and render the form on the UI.

Form Rendering on the BAP
Once form is pulled, the BAP will render the form as-is on its UI with some UI modifications. Below image depicts how the form will look if the BAP renders the form as-is using an HTML parser.

The BAP has to render the submit button for this form. Once this form is submitted, submission_id will be received at BAP end in response. BAP has to send this submission_id along with the confirm API call to BPP.
The BPP will receive the confirm call with the submission_id as reference. It will verify the submission against the submission_id and link that data along with the confirm API.
Now the BPP has all the information required to confirm the order. It can either go ahead with the confirmation or reject the request if applicable.

[sankarshanmukhopadhyay]

This mock-up of the form being rendered requests an extensive set of data including files on disk - is there a way for the BAP to indicate the data usage, retention and processing policies which the end consumer can make themselves familiar with should they find a need to?

[ravi-prakash-v]

Data usage, collection and retention policies might be declared at the network policy level.

[ravi-prakash-v]

@RashmiG-Protean thanks for this. Will add it to the draft.

[sankarshanmukhopadhyay]

Data usage, collection and retention policies might be declared at the network policy level.

A clarifying question using two possible scenarios (or user interaction journeys)

• A trust/fund wants to offer scholarship for education to deserving candidates and seeks necessary/MUST documents to process application. In this case while the information is necessary to process the workflow, the data does not need to be retained once funds are allocated

• A vocational training institute offers courses to eligible candidates and seeks necessary/MUST documents to process application. In this case the information received is part of the learning record portfolio and is likely to be retained by the institute

Would these be two different networks?

[bharatkashyap]

Thanks @core-wg-admin!

What benefit does supporting the XForms standard provide given that the engineering effort required to render forms on the client app is doubled by having to support two standards? HTML is clearly the dominant standard of the world in rendering forms, whereas XForms seems to be dead by comparison.

[ravi-prakash-v]

XForms is an option. At a protocol-level, any form standard works as long as the participants of the network agree to it. However, protocol cannot mandate one form over the other, rather recommend that we use HTML forms as much as possible.

[DhruvBarot]

@core-wg-admin Not sure, if this is the right concern or not but we are providing a way to show a BPPs form inside the BAPs system
if the BAPs can support multiple languages then In which language the forms will be shown up?
How do the BPPs know which languages will be supported by BAPs?

[ravi-prakash-v]

The BPP forms are not to be considered as embeddable objects but more an HTML Parser-friendly object. Any language translations can happen at the backend while parsing the form. BAP can reorganize the form in whichever way it chooses to.

Regarding your question on which languages are supported by BAPs, I suggest you move it to a separate discussion thread.

[DhruvBarot]

The BPP is interested in the fields to show on BAPs UI, Why not chose what they wanted to show on UI?
If BAP performs some language translations then might be some misunderstanding for synonyms of the same words.
I.e In the English you but in Gujarati, we have three different words તમે, આપ and તું.

I feel like BPP can provide an HTML form in the BAPs-supported language, As BAPs need to do just HTML parsing and styling.

[venkatramanm]

I think we could merge this 2 step process to a single-step process.

1. BAP can parse the form and render it in their chosen fashion,
2. Collect data and prepare a flat XResponse object with attribute name as the input's name attribute. and value as the collected value.
3. File data may be transmitted as data URL (baser64 encoded data)

[ravi-prakash-v]

Makes sense. So we create a schema called XInputResponse. This can be a simple array of key-value pairs that correspond to the form fields send in the XInput object. Right?