From b3f9bd6971dae9c295561afbcb185e3d10edce9e Mon Sep 17 00:00:00 2001 From: Shane Date: Tue, 12 Feb 2019 20:33:50 -0800 Subject: [PATCH 1/4] fix: methodObject tag link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2ecba619..c375b60a 100644 --- a/README.md +++ b/README.md @@ -880,7 +880,7 @@ Components Object Example: #### Tag Object -Adds metadata to a single tag that is used by the [Method Object](#methodObject). +Adds metadata to a single tag that is used by the [Method Object](#method-object). It is not mandatory to have a Tag Object per tag defined in the Method Object instances. Field Name | Type | Description From 01900d44e2b582d5c4acc67409edcc00bf39ef8d Mon Sep 17 00:00:00 2001 From: Shane Date: Tue, 12 Feb 2019 20:38:45 -0800 Subject: [PATCH 2/4] fix: left over dasherizing --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c375b60a..27448862 100644 --- a/README.md +++ b/README.md @@ -307,11 +307,11 @@ Field Name | Type | Description summary | `string` | A short summary of what the method does. description | `string` | A verbose explanation of the method behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this method. -params | [[Content Descriptor](#contentDescriptorObject) \| [Reference Object](#reference-object)] | 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). +params | [[Content Descriptor](#content-descriptor-object) \| [Reference Object](#reference-object)] | 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). 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](#referenceObject)] | A list of custom application defined errors that MAY be returned. The Errors MUST have unique error codes. +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"` | Format the server expects the params. Defaults to `"by-positon"`. @@ -928,7 +928,7 @@ The Reference Object is defined by [JSON Schema](https://json-schema.org/latest/ Field Name | Type | Description ---|:---:|--- -$ref | `string` | **REQUIRED**. The reference string. +$ref | `string` | **REQUIRED**. The reference string. This object cannot be extended with additional properties and any properties added SHALL be ignored. From ffd8f23e01ab8446490c5e043bc003d010bf05d3 Mon Sep 17 00:00:00 2001 From: Shane Date: Tue, 12 Feb 2019 20:46:45 -0800 Subject: [PATCH 3/4] fix: remove left over a wrapper --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 27448862..2be112fe 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ The OpenRPC Specification does not require rewriting existing APIs. It does not How to contribute, build and release are outlined in [CONTRIBUTING.md](CONTRIBUTING.md), [BUILDING.md](BUILDING.md) and [RELEASING.md](RELEASING.md) respectively. Commits in this repository follow the [CONVENTIONAL_COMMITS.md](CONVENTIONAL_COMMITS.md) specification. ## Definitions -##### OpenRPC Document +##### OpenRPC Document A document (or set of documents) that defines or describes an API. An OpenRPC definition uses and conforms to the OpenRPC Specification. ## Specification From f3303cf7e6d49797335839d58b2c803043db9ae0 Mon Sep 17 00:00:00 2001 From: Shane Date: Tue, 12 Feb 2019 21:59:07 -0800 Subject: [PATCH 4/4] fix: use Github Flavored Markdown --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 2ecba619..5abbd272 100644 --- a/README.md +++ b/README.md @@ -110,8 +110,8 @@ It is RECOMMENDED that the root OpenRPC document be named: `openrpc.json`. The Data types MUST be in the set defined by the [JSON Schema Specification 7](https://json-schema.org/latest/json-schema-core.html) ### Rich Text Formatting -Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. -Where OpenRPC tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. +Throughout the specification `description` fields are noted as supporting Github markdown formatting. +Where OpenRPC tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [GitHub Flavored Markdown](https://github.github.com/gfm/). Tooling MAY choose to ignore some GitHub Flavored Markdown features to address security concerns. ### OpenRPC Schema Object This is the root document object of the [OpenRPC document](#openrpcDocument). @@ -135,7 +135,7 @@ The metadata MAY be used by the clients if needed, and MAY be presented in editi Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. The title of the application. -description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | A short description of the application. [GitHub Flavored Markdown](https://github.github.com/gfm/) MAY be used for rich text representation. termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. contact | [Contact Object](#contact-object) | The contact information for the exposed API. license | [License Object](#license-object) | The license information for the exposed API. @@ -213,7 +213,7 @@ Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. A name to be used as the cannonical name for the server. url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenRPC document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | An optional string describing the host designated by the URL. [CGitHub Flavored Markdown syntax](https://github.github.com/gfm/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -292,7 +292,7 @@ Field Name | Type | Description ---|:---:|--- enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schema-object) treatment of default values, because in those cases parameter values are optional. -description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | An optional description for the server variable. [GitHub Flavored Markdown syntax](https://github.github.com/gfm/) MAY be used for rich text representation. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -305,7 +305,7 @@ Field Name | Type | Description name | [`string`] | The cannonical name for the method. The name MUST be unique within the methods array. tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of methods by resources or any other qualifier. summary | `string` | A short summary of what the method does. -description | `string` | A verbose explanation of the method behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +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](#contentDescriptorObject) \| [Reference Object](#reference-object)] | 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). 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. @@ -368,7 +368,7 @@ Field Name | Type | Description ---|:---:|--- name | `string` | name of the content that is being described. summary | `string` | A short summary of what the method does. -description | `string` | A verbose explanation of the method behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +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. required | `boolean` | Determines if the content is a required field. schema | [Schema Object](#schema-object) | Schema that describes the content. examples | [[Example Object](#example-object)] | Examples of the parameter. The examples MUST match the specified schema. If referencing a `schema` which contains (an) example(s), the `examples` value SHALL _override_ the examples provided by the schema. To represent examples of media types that cannot naturally be represented in JSON, a string value can contain the example with escaping where necessary. @@ -606,7 +606,7 @@ Field Name | Type | Description ---|:---:|--- name | `string` | cannonical name of the example. summary | `string` | Short description for the example. -description | `string` | Long description for the example. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | Long description for the example. [GitHub Flavored Markdown syntax](https://github.github.com/gfm/) MAY be used for rich text representation. value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON, use a string value to contain the example, escaping where necessary. externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON documents. The `value` field and `externalValue` field are mutually exclusive. @@ -651,7 +651,7 @@ Field Name | Type | Description ---|:---:|--- 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. params | Map[`string`, Any \| [{expression}](#runtime-expression)] | A map representing parameters to pass to a method as specified with `method`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked method. -description | `string` | A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | A description of the link. [GitHub Flavored Markdown syntax](https://github.github.com/gfm/) MAY be used for rich text representation. server | [Server Object](#server-object) | A server object to be used by the target method. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -886,7 +886,7 @@ It is not mandatory to have a Tag Object per tag defined in the Method Object in Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the tag. -description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | A short description for the tag. [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 tag. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -906,7 +906,7 @@ Allows referencing an external resource for extended documentation. Field Name | Type | Description ---|:---:|--- -description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | A short description of the target documentation. [GitHub Flavored Markdown syntax](https://github.github.com/gfm/) MAY be used for rich text representation. url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specification-extensions).