Clarification/fixes on example files

[AkilaJayasinghe]

Hi Everyone,

I have notice some problems with the example files provided, want to discuss on clarify with you all here.

BNPL Example
https://github.com/OAI/Arazzo-Specification/blob/main/examples/1.0.0/bnpl-arazzo.yaml

**->**The schema only allows path, query, header, and cookie. However on the BNPL example I can see "headers" is used, is this a mistake or intentionally added?

parameters:
- name: redirectAuthToken
in: query
value: $steps.authenticateCustomerAndAuthorizeLoan.outputs.redirectAuthToken
successCriteria:
- condition: $statusCode == 302
outputs:
redirectUrl: $response.headers.Location

-> Missing comma on line number 173

requestBody:
contentType: application/json
payload: |
{
"firstName": "{$inputs.customer.firstName}",
"lastName": "{$inputs.customer.lastName}",
"dateOfBirth": "{$inputs.customer.dateOfBirth}",
"postalCode": "{$inputs.customer.postalCode}"
"termsAndConditionsAccepted": true
}

FAPI-PAR Example
https://github.com/OAI/Arazzo-Specification/blob/main/examples/1.0.0/FAPI-PAR.arazzo.yaml

-> Incorrect operationId is defined in line number 102. According to the OpenAPI Specification the operationId should be case sensitive, in this case the OpenAPI documents operationId is "Par", but what is mentioned in the Arazzo spec is "PAR"

Arazzo

steps:
- stepId: PARStep
description: Pushed Authorization Request
operationId: $sourceDescriptions.auth-api.PAR

OpenAPI

operationId: Par
tags:
- OAuth2
parameters:

[frankkilcommins]

Hi @AkilaJayasinghe,

Nice spots. Thank you for reporting.

[AkilaJayasinghe]

Hi @frankkilcommins, thank you!

I found few more possible issues with step output references, appreciate it if you can have a look at them as well on BNPL example.

1. In the updateOrderStatus step, the loanTransactionId value in the parameter object is referencing an undefined step output value.

• stepId: updateOrderStatus
  description: Send update from eCommerce platform to indicate order fulfilled and loan is therefore active
  operationId: updateBnplLoanTransactionStatus
  parameters:
  - name: loanTransactionId
  in: path
  value: $steps.initiateBnplTransaction.outputs.loanTransactionId
  requestBody:
  contentType: application/json
  payload: { "loanStatus": "Completed" }
  successCriteria:
  - condition: $statusCode == 204
  outputs:
  finalizedPaymentPlan: $steps.retrieveFinalizedPaymentPlan.finalizedPaymentPlan

• stepId: initiateBnplTransaction
  description: Initiate the BNPL transaction by sending the customer identifier, eligible products, and indicative loan amount to initiate the loan process
  operationId: createBnplTransaction
  requestBody:
  contentType: application/json
  payload: |
  {
  "enrolledCustomer": "{$inputs.customer.uri}",
  "newCustomer": "{$steps.createCustomer.outputs.customer}",
  "products": "{$steps.checkLoanCanBeProvided.outputs.eligibleProducts}"
  }
  successCriteria:
  - condition: $statusCode == 202
  onSuccess:
  - name: CustomerAuthorizationRequired
  type: goto
  stepId: authenticateCustomerAndAuthorizeLoan
  criteria:
  - condition: $response.body#/redirectAuthToken != null
  - name: CustomerAuthorizationNotRequired
  type: goto
  stepId: retrieveFinalizedPaymentPlan
  criteria:
  - condition: $response.body#/redirectAuthToken == null
  outputs:
  redirectAuthToken: $response.body#/redirectAuthToken
  loanTransactionResourceUrl: $response.body#/links/self

2. In the authenticateCustomerAndAuthorizeLoan step, the redirectAuthToken parameter is incorrectly referencing its own output value. Instead, it should get redirectAuthToken from the initiateBnplTransaction step's redirectAuthToken output. (suggestion)

• stepId: authenticateCustomerAndAuthorizeLoan
  description: |
  Authenticate the customer and seek authorization for the loan.

  Notes:
  
  - Authenticate in this case does not necessarily mean with a valid set of credentials. It could be to prove the identity of the end user, possibly doing an UMA style interaction (which is too complex to tie into this example).
  - A redirect is returned for to be sent to the customer. The customer should follow this, but the success of the authorisation is out-of-band.
  - This flow mimics OAuth style authorization but is not an exact match as it does not rely on an authorisation code/access token exchange (as this seems somewhat artificial in this context).

operationId: getAuthorization
parameters:
  - name: redirectAuthToken
    in: query
    value: $steps.authenticateCustomerAndAuthorizeLoan.outputs.redirectAuthToken
successCriteria:
  - condition: $statusCode == 302
outputs:
  redirectUrl: $response.headers.Location