PLT-8746 - Generated schema does not conform to OpenApi spec

[bjornkihlberg]

PLT-8746

Background

tx-pipe found problems with the schema and reported it here.

Subtasks

• [x] Get validator
  • nix-shell -p openapi-generator-cli
  • openapi-generator-cli validate -i openapi.json
• [x] Get openapi.json
  • cabal run marlowe-runtime-web -- --enable-open-api --http-port 8000
  • Navigate to http://localhost:8000/openapi.json
• [x] List issues
  • Errors:
  • attribute components.schemas.MarloweState.items is not of type object
  • attribute components.schemas.Plutus.StakingCredential.items is missing
  • attribute components.schemas.Plutus.StakingCredential.items is not of type object
  • attribute components.schemas.MarloweState.items is missing
  • Warnings:
  • Unused model: WithdrawTxBodyEnvelope
  • Unused model: CreateTxBodyEnvelope
• [x] Fix issues
  • [x] attribute components.schemas.MarloweState.items is not of type object
  • [x] attribute components.schemas.Plutus.StakingCredential.items is missing
  • [x] attribute components.schemas.Plutus.StakingCredential.items is not of type object
  • [x] attribute components.schemas.MarloweState.items is missing
  • [x] ~Unused model: WithdrawTxBodyEnvelope~ Wont do this, requires more thought and isn't urgent.
  • [x] ~Unused model: CreateTxBodyEnvelope~ Wont do this, requires more thought and isn't urgent.
• [x] ~Test ToSchema instances to prevent further issues~
  • Relevant procedures can be found in Data.OpenApi.Schema.Validation.
  • No need, it's handled already with validateEveryToJSONWithPatternChecker!
  • [x] ~StakingCredential (marlowe-runtime-web/src/Language/Marlowe/Runtime/Web/Orphans.hs)~
  • [x] ~State (marlowe-runtime-web/src/Language/Marlowe/Runtime/Web/Orphans.hs)~

Notes

• The problem with the schema is that you can't seem to model Haskell tuples as [13, "hey"] with the following schema according to the OpenAPI specification:

  { "type": "array"
  , "minItems": 2
  , "maxItems": 2
  , "items": [ { "type": "integer" }
           , { "type": "string" }
           ]
  }

  ... because items must be an object, and not an array.

• One solution is to serialize tuples as object, eg:

  { "type": "object"
  , "properties": { "n": { "type": "integer" }
                , "s": { "type": "string" }
                }
  }

  This would introduce a breaking change because now [13, "hey"] becomes { "n": 13, "s": "hey" } @hrajchert notes regarding this:

  is more than the ts-sdk, tuples are serialized like that from the core specification it is too much of a breaking change

• One solution is:

  { "type": "array"
  , "minItems": 2
  , "maxItems": 2
  , "items": { "oneOf": [ { "type": "integer" }
                      , { "type": "string" }
                      ]
           }
  }

  ... which doesn't introduce breaking changes but it

  • makes the derived documentation less clear. This can be mitigated by including a description.
  • makes any autogenerated interface that tx-pipe is building less type safe (because you could construct ["hey", 13] or [3, 14] etc etc).

Definition of done

• Generated schema in marlowe runtime web satisfies the OpenApi specification

PR

PLT-8746: Generated schema conforms to OpenApi spec #761

[bjornkihlberg]

Apparently the schema satisfies the OpenApi 3.1 specification but currently targets the OpenApi 3.0 specification. This ticket is closed and another takes its place.