interaction/precedence between examples and schema.examples

[BelfordZ]

When a method has schema.examples, but no examplePairings, there may be some inferences to be made as to what some pairings could be.

When a method has schema.examples and examplePairings, it becomes unclear how the different tooling projects should approach chosing examples to use.

This issue is to discuss solutions and approaches to the above.

[BelfordZ]

for PR #323 - Should we specify how the schema.examples are mapped into examplePairingObjects? For example, if a client makes a request using examplePairings params, and is expecting the result to be the pairing result, but the mock server is ordering the pairings differently, then the client will receive a result for the example pairing that is not what it was expecting.

[BelfordZ]

As an alternative, What if exampleObjects.value was either a referenceObject | any, allowing the user to opt to using schema.examples as part of their examplePairings. This way, we can remove the externalValue field all together (you can just use a ref instead), incorperate schema.examples into exampleObjects. It still doesn't address the issue of ordering when there are no example pairings are provided. For this, we can include a definition of how to create a set of examplePairings from varying numbers of schema.examples for each param/result schema.

[BelfordZ]

If we add this to the spec, should the exampleObject.value be made optional?

If we all we are saying here is 'feel free to derive examples using the schema.examples urself', it's not exactly very helpful unless we are also speccing out how.

IMO the way of coming up with default examplePairings when there are schema.examples belongs in the tooling space, in the realm of 'document upgraders' - tools for assembling, performing additional checking, and in this case, applying some defaults in a subjective way (which is okay for the tooling). The feature added to schema-tools-js is a good place for best practice to evolve around the way to default things 'smartly'.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.