OpenRPC documents getblock as a four-way oneOf on verbosity, but the dump does not say which integer selects which arm. Therefore, clients that expose a type or method per verbosity (e.g. corepc, btcd) have to hardcode that map.
This patch adds optional RPCResultDiscriminator metadata, emits it as x-bitcoin-discriminated-result, and stamps getblock. getblock request handling and returned block data are unchanged. Now, help getblock notes that verbosity 2 and 3 cannot be told apart by validating a response alone.
Also updates getopenrpcinfo schema text to document x-bitcoin-discriminated-result and x-bitcoin-default-hint.
The change to the schema's format is:
<details> <summary><code>x-bitcoin-discriminated-result</code> on <code>getblock</code></summary>
diff dump.json dump_new.json
5590c5590,5600
< ]
---
> ],
> "x-bitcoin-discriminated-result": {
> "parameter": "verbosity",
> "parameterIndex": 1,
> "values": [
> 0,
> 1,
> 2,
> 3
> ]
> }
</details>
<details> <summary><code>getblock</code> description notes verbosity 2 and 3 overlap</summary>
diff openrpc.json openrpc_new.json
4696c4696
< "description": "If verbosity is 0, returns a string that is serialized, hex-encoded data for block 'hash'.\nIf verbosity is 1, returns an Object with information about block <hash>.\nIf verbosity is 2, returns an Object with information about block <hash> and information about each transaction.\nIf verbosity is 3, returns an Object with information about block <hash> and information about each transaction, including prevout information for inputs (only for unpruned blocks in the current best chain).",
---
> "description": "If verbosity is 0, returns a string that is serialized, hex-encoded data for block 'hash'.\nIf verbosity is 1, returns an Object with information about block <hash>.\nIf verbosity is 2, returns an Object with information about block <hash> and information about each transaction.\nIf verbosity is 3, returns an Object with information about block <hash> and information about each transaction, including prevout information for inputs (only for unpruned blocks in the current best chain).\nThe verbosity = 2 and verbosity = 3 result schemas cannot be distinguished by validating a response alone because a block with no spent inputs returns byte-identical JSON at both levels (a coinbase input has no prevout to add), and the verbosity = 3 schema lists prevout as optional, so both object arms accept both responses.",
</details>
<details> <summary>schema text for <code>x-bitcoin-default-hint</code> and <code>x-bitcoin-discriminated-result</code></summary>
diff openrpc.json openrpc_new.json
8610c8610
< "description": "JSON Schema for the parameter."
---
> "description": "JSON Schema for the parameter. May include \"x-bitcoin-default-hint\" when the default cannot be expressed as a JSON value."
8649c8649
< "description": "JSON Schema for the result. Numeric schemas may include \"x-bitcoin-unit\" property: \"amount\" which denotes a Bitcoin amount in BTC."
---
> "description": "JSON Schema for the result. Numeric schemas may include \"x-bitcoin-unit\" property: \"amount\" which denotes a Bitcoin amount in BTC. Multi-result schemas may include \"x-bitcoin-discriminated-result\" naming the request parameter or parameters that select among the top-level oneOf branches."
13319c13319
< "description": "JSON Schema for the parameter."
---
> "description": "JSON Schema for the parameter. May include \"x-bitcoin-default-hint\" when the default cannot be expressed as a JSON value."
13358c13358
< "description": "JSON Schema for the result. Numeric schemas may include \"x-bitcoin-unit\" property: \"amount\" which denotes a Bitcoin amount in BTC."
---
> "description": "JSON Schema for the result. Numeric schemas may include \"x-bitcoin-unit\" property: \"amount\" which denotes a Bitcoin amount in BTC. Multi-result schemas may include \"x-bitcoin-discriminated-result\" naming the request parameter or parameters that select among the top-level oneOf branches."
</details>
Other results can also use the same discriminator pattern.
