diff --git a/spec.md b/spec.md index e12ada48..1421d26b 100644 --- a/spec.md +++ b/spec.md @@ -191,13 +191,13 @@ Field Name | Type | Description summary | `string` | A short summary of what the method does. description | `string` | A verbose explanation of the method behavior. [GitHub Flavored Markdown syntax](https://github.github.com/gfm/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this method. -params | [[Content Descriptor](#content-descriptor-object) \| [Reference Object](#reference-object) \| [OneOf Object](#oneof-object)] | **REQUIRED**. A list of parameters that are applicable for this method. The list MUST NOT include duplicated parameters and therefore require [name](#content-descriptor-name) to be unique. The list can use the [Reference Object](#reference-object) to link to parameters that are defined by the [Content Descriptor Object](#content-descriptor-object). It may also nest the content descriptor or reference object inside of a [OneOf Object](#oneof-object). All optional params (content descriptor objects with "required": false) MUST be positioned after all required params in the list. -result | [Content Descriptor](#content-descriptor-object) \| [Reference Object](#reference-object) \| [OneOf Object](#oneof-object) | **REQUIRED**. The description of the result returned by the method. It MUST be a Content Descriptor. +params | [[Content Descriptor](#content-descriptor-object) \| [Reference Object](#reference-object) | **REQUIRED**. A list of parameters that are applicable for this method. The list MUST NOT include duplicated parameters and therefore require [name](#content-descriptor-name) to be unique. The list can use the [Reference Object](#reference-object) to link to parameters that are defined by the [Content Descriptor Object](#content-descriptor-object). All optional params (content descriptor objects with "required": false) MUST be positioned after all required params in the list. +result | [Content Descriptor](#content-descriptor-object) \| [Reference Object](#reference-object) | **REQUIRED**. The description of the result returned by the method. It MUST be a Content Descriptor. deprecated | `boolean` | Declares this method to be deprecated. Consumers SHOULD refrain from usage of the declared method. Default value is `false`. servers | [[Server Object](#server-object)] | An alternative `servers` array to service this method. If an alternative `servers` array is specified at the Root level, it will be overridden by this value. errors | [[Error Object](#error-object) \| [Reference Object](#reference-object)] | A list of custom application defined errors that MAY be returned. The Errors MUST have unique error codes. links | [[Link Object](#link-object) \| [Reference Object](#reference-object)] | A list of possible links from this method call. -paramStructure | `"by-name"` \| `"by-position"` \| `"either"` | The expected format of the parameters. [As per the JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#parameter_structures), params may be either an array, an object, or either. Defaults to `"either"`. +paramStructure | `"by-name"` \| `"by-position"` \| `"either"` | The expected format of the parameters. [As per the JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#parameter_structures), the params of a [JSON-RPC request object](https://www.jsonrpc.org/specification#request_object) may be an array, object, or either (represented as `by-position`, `by-name`, and `either` respectively). When a method has a `paramStructure` value of `by-name`, callers of the method MUST send a [JSON-RPC request object](https://www.jsonrpc.org/specification#request_object) whose `params` field is an object. Further, the key names of the `params` object MUST be the same as the [`contentDescriptor.name`](#content-descriptor-name)s for the given method. Defaults to `"either"`. examples | [[Example Pairing Object](#example-pairing-object)] | Array of [Example Pairing Object](#example-pairing-object) where each example includes a valid params-to-result [Content Descriptor](#content-descriptor-object) pairing. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -208,11 +208,11 @@ Content Descriptors are objects that do just as they suggest - describe content. Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. name of the content that is being described. +name | `string` | **REQUIRED**. Name of the content that is being described. If the content described is a method parameter assignable [`by-name`](#method-param-structure), this field SHALL define the parameter's key (_ie_ name). summary | `string` | A short summary of the content that is being described. description | `string` | A verbose explanation of the content descriptor behavior. [GitHub Flavored Markdown syntax](https://github.github.com/gfm/) MAY be used for rich text representation. required | `boolean` | Determines if the content is a required field. Default value is `false`. -**REQUIRED** schema | [Schema Object](#schema-object) | Schema that describes the content. +schema | [Schema Object](#schema-object) | **REQUIRED**. Schema that describes the content. deprecated | `boolean` | Specifies that the content is deprecated and SHOULD be transitioned out of usage. Default value is `false`. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -266,7 +266,7 @@ For computing links, and providing instructions to execute them, a [runtime expr Field Name | Type | Description ---|:---:|--- -**REQUIRED** name | `string` | Cannonical name of the link. +name | `string` | **REQUIRED**. Cannonical name of the link. description | `string` | A description of the link. [GitHub Flavored Markdown syntax](https://github.github.com/gfm/) MAY be used for rich text representation. summary | `string` | Short description for the link. method | `string` | The name of an _existing_, resolvable OpenRPC method, as defined with a unique `method`. This field MUST resolve to a unique [Method Object](#method-object). As opposed to Open Api, Relative `method` values ARE NOT permitted. @@ -362,16 +362,6 @@ Field Name | Type | Description This object cannot be extended with additional properties and any properties added SHALL be ignored. -## oneOf Object - -A simple object allowing for conditional content descriptors. It MUST only be used in place of a content descriptor. It specifies that the content descriptor in question must match one of the listed content descriptors. This allows you to define content descriptors more granularly, without having to rely so heavily on json schemas. - -The oneOf Object is defined by [JSON Schema](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.7.3) and follows the same structure, behavior and rules. - -Field Name | Type | Description ----|:---:|--- -oneOf | [Content Descriptor](#content-descriptor-object) | **REQUIRED**. The reference string. - ## Specification Extensions While the OpenRPC Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.