From 0bef16601f087950b0a341fb4790c55bd8b318ef Mon Sep 17 00:00:00 2001 From: "Rob Dolin (MSFT)" Date: Fri, 16 Jun 2017 09:47:07 -0700 Subject: [PATCH 001/104] Create MAINTAINERS.md Create a MAINTAINERS file to align with OAI charter section 4.e. >The maintainers of the TDC shall be those listed in the MAINTAINERS file in the project repository, available in the top level of the code repository. AFAIK, this list represents the current people with access to push the green `Merge` button on the OpenAPI Spec repository --- MAINTAINERS.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 MAINTAINERS.md diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000000..4a2f1256fc --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,7 @@ +* Darrel Miller [@darrelmiller](https://github.com/darrelmiller) +* Jason Harmon [@jharmn](https://github.com/jharmn) +* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) +* Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) +* Rob Dolin [@RobDolinMS](https://github.com/robdolinms) +* Ron Ratovsky [@webron](https://github.com/webron) +* Tony Tam [@fehguy](https://github.com/fehguy) From 9c2ffda7052e3df19e48325351e63e380b49d005 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 16 Jun 2017 15:04:04 -0400 Subject: [PATCH 002/104] Updating to include TDC maintainers only as per charter --- MAINTAINERS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 4a2f1256fc..5a5ab82e15 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -2,6 +2,5 @@ * Jason Harmon [@jharmn](https://github.com/jharmn) * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) -* Rob Dolin [@RobDolinMS](https://github.com/robdolinms) * Ron Ratovsky [@webron](https://github.com/webron) * Tony Tam [@fehguy](https://github.com/fehguy) From 28c37be1352a8ab71939524ec8a41ae9dc6c8e3a Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Wed, 28 Jun 2017 11:01:12 +0200 Subject: [PATCH 003/104] Update 3.0.md added smartAPI info block elements --- versions/3.0.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index 95d382c1f4..3414fb3469 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -220,6 +220,22 @@ Field Name | Type | Description license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **REQUIRED**. The version of the API definition (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). +##### smartAPI Fields +Field Name | Type | Description +---|:---:|--- +description | `string` | **SHOULD** A human readable description of the service. +descriptors | `string` | **MAY** Keyword or concepts that describe the API. +termsOfService | `URL` | **REQUIRED** A URL that describes the terms of use for the API. +version | 'string' | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. +Website | `URI` | **MAY** A web page that describes the API. +Documentation | `URL` | **SHOULD** Additional documentation for the API. +Developer Forum | `URL` | **MAY** Forum or Mailing list. +Access Restrictions | `URL` | **MAY** Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. +Social Media | `URI` | **MAY** Links to social media presence such as Twitter, Facebook, LinkedIn, GitHub, etc. +Implementation Language | `string` | **MAY** Language the API was written in. +Maturity | `enum` | **MAY** Maturity of the API. Values to use: development, production. +Publications | `URI` | **MAY** Publications that describe the API. +Funding | `string` | **MAY** Indicate sources of funding. This object can be extended with [Specification Extensions](#specificationExtensions). From 0b7173ed96aff538463ffa307532a02a5ee0ffe6 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Wed, 28 Jun 2017 11:14:33 +0200 Subject: [PATCH 004/104] Update 3.0.md smartAPI info block yaml --- versions/3.0.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 3414fb3469..2a27e7e724 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -226,7 +226,7 @@ Field Name | Type | Description description | `string` | **SHOULD** A human readable description of the service. descriptors | `string` | **MAY** Keyword or concepts that describe the API. termsOfService | `URL` | **REQUIRED** A URL that describes the terms of use for the API. -version | 'string' | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. +version | 'string' | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. Website | `URI` | **MAY** A web page that describes the API. Documentation | `URL` | **SHOULD** Additional documentation for the API. Developer Forum | `URL` | **MAY** Forum or Mailing list. @@ -241,7 +241,7 @@ This object can be extended with [Specification Extensions](#specificationExtens ##### Info Object Example: -```json +```OpenAPI json { "title": "Sample Pet Store App", "description": "This is a sample server for a pet store.", @@ -259,7 +259,7 @@ This object can be extended with [Specification Extensions](#specificationExtens } ``` -```yaml +```OpenAPI yaml title: Sample Pet Store App description: This is a sample server for a pet store. termsOfService: http://example.com/terms/ @@ -273,6 +273,35 @@ license: version: 1.0.1 ``` +```smartAPI yaml +{ + title: mygene.info + description: MyGene.info is a high performance API for gene descriptions. + x-keywords: + - genes + - http://semanticscience.org/resource/SIO_010035 + version: 2.0.0 + termsOfService: http://mygene.info/terms/ + x-homepage: http://mygene.info + documentation: http://docs.mygene.info/en/v3/ + x-developerForum: + - https://bitbucket.org/sulab/mygene.hub + x-accessRestrictions: + - none + x-accounts: + - name: twitter + accountid: mygeneinfo + x-implementationLanguage: python + x-maturity: production + x-publications: + - https://doi.org/10.1093/nar/gks1114 + x-funding: + - name: National Institutes of Health + x-id: https://www.wikidata.org/wiki/Q390551 + funding-id: HG008473 +} +``` + #### Contact Object Contact information for the exposed API. From d7ad91fbe226f7e35c0dd90db3945225d7cfcccc Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Wed, 28 Jun 2017 11:23:57 +0200 Subject: [PATCH 005/104] Update 3.0.md smartAPI info block yaml --- versions/3.0.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index 2a27e7e724..641238ea87 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -236,6 +236,10 @@ Field Name | Type | Description Maturity | `enum` | **MAY** Maturity of the API. Values to use: development, production. Publications | `URI` | **MAY** Publications that describe the API. Funding | `string` | **MAY** Indicate sources of funding. +Responsible Organization | `string` | **REQUIRED** Provide the name of the organization responsible for the service. +Responsible Organization | `string` | **REQUIRED** Provide the name of the organization responsible for the service. +Responsible Developer | `URI` | **REQUIRED** Provide the name, ID and email for the responsible developer. +Contributor | `string` | **MAY** Indicate any other contributor to the conception, development, or support of the API. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -299,6 +303,19 @@ version: 1.0.1 - name: National Institutes of Health x-id: https://www.wikidata.org/wiki/Q390551 funding-id: HG008473 + contact: + - name: The Scripps Research Institute + x-id: https://www.wikidata.org/wiki/Q793867 + x-role: responsible organization + url: http://www.scripps.edu/ + - name: Chunlei Wu + x-id: https://orcid.org/0000-0002-2629-6124 + x-role: responsible developer + email: cwu@scripps.edu + - name: Andrew Su + x-id: https://orcid.org/0000-0002-9859-4104 + x-role: contributor + email: asu@scripps.edu } ``` From 3c57d21a56c8e1bac8859fccd99503ac997deb30 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Wed, 28 Jun 2017 11:27:30 +0200 Subject: [PATCH 006/104] Update 3.0.md typo --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 641238ea87..744ecc04b1 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -226,7 +226,7 @@ Field Name | Type | Description description | `string` | **SHOULD** A human readable description of the service. descriptors | `string` | **MAY** Keyword or concepts that describe the API. termsOfService | `URL` | **REQUIRED** A URL that describes the terms of use for the API. -version | 'string' | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. +version | `string` | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. Website | `URI` | **MAY** A web page that describes the API. Documentation | `URL` | **SHOULD** Additional documentation for the API. Developer Forum | `URL` | **MAY** Forum or Mailing list. From 662b17b21d3d6c5ae7643d060edab5b2e82ad340 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Thu, 13 Jul 2017 22:20:44 +0200 Subject: [PATCH 007/104] Update 3.0.md re-worked info block's smartAPI elements --- versions/3.0.md | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 744ecc04b1..b30946ed32 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -223,23 +223,19 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -description | `string` | **SHOULD** A human readable description of the service. -descriptors | `string` | **MAY** Keyword or concepts that describe the API. -termsOfService | `URL` | **REQUIRED** A URL that describes the terms of use for the API. +termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. -Website | `URI` | **MAY** A web page that describes the API. -Documentation | `URL` | **SHOULD** Additional documentation for the API. -Developer Forum | `URL` | **MAY** Forum or Mailing list. -Access Restrictions | `URL` | **MAY** Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. -Social Media | `URI` | **MAY** Links to social media presence such as Twitter, Facebook, LinkedIn, GitHub, etc. -Implementation Language | `string` | **MAY** Language the API was written in. -Maturity | `enum` | **MAY** Maturity of the API. Values to use: development, production. -Publications | `URI` | **MAY** Publications that describe the API. -Funding | `string` | **MAY** Indicate sources of funding. -Responsible Organization | `string` | **REQUIRED** Provide the name of the organization responsible for the service. -Responsible Organization | `string` | **REQUIRED** Provide the name of the organization responsible for the service. -Responsible Developer | `URI` | **REQUIRED** Provide the name, ID and email for the responsible developer. -Contributor | `string` | **MAY** Indicate any other contributor to the conception, development, or support of the API. +description | `string` | **SHOULD** See above. +documentation | `URL` | **SHOULD** Additional documentation for the API. +x-keywords | `string` | Keyword or concepts that describe the API. +x-homepage | `URI` | A web page that describes the API. +x-developerForum | `URL` | Forum or Mailing list. +x-accessRestrictions | `URL` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. +x-accounts | `URI` | Links to social media presence such as Twitter, Facebook, LinkedIn, GitHub, etc. +x-implementationLanguage | `string` | Language the API was written in. +x-maturity | `enum` | Maturity of the API. Values to use: development, production. +x-publications | `URI` | Publications that describe the API. +x-funding | `string` | Indicate sources of funding. This object can be extended with [Specification Extensions](#specificationExtensions). From 7c7c258f1e8f8e45fa93963bc7337535bb7bb4df Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Thu, 13 Jul 2017 22:22:30 +0200 Subject: [PATCH 008/104] Update 3.0.md --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index b30946ed32..d5b09112ab 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -223,9 +223,9 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -termsOfService | `URL` | **REQUIRED** See above. +termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. -description | `string` | **SHOULD** See above. +description | `string` | **SHOULD** See See above. documentation | `URL` | **SHOULD** Additional documentation for the API. x-keywords | `string` | Keyword or concepts that describe the API. x-homepage | `URI` | A web page that describes the API. From 2d8f799cce27eafbb45c97fe62f0d79000330b47 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Thu, 13 Jul 2017 22:31:16 +0200 Subject: [PATCH 009/104] Update 3.0.md re-ordered --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index d5b09112ab..53eb621d21 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -223,9 +223,9 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- +description | `string` | **SHOULD** See See above. termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. -description | `string` | **SHOULD** See See above. documentation | `URL` | **SHOULD** Additional documentation for the API. x-keywords | `string` | Keyword or concepts that describe the API. x-homepage | `URI` | A web page that describes the API. From 0ae594fef14b6a4ff27a0a5f1ef9173a316da68d Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Thu, 13 Jul 2017 23:01:14 +0200 Subject: [PATCH 010/104] Update 3.0.md contact block --- versions/3.0.md | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 53eb621d21..56a03477da 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -299,19 +299,6 @@ version: 1.0.1 - name: National Institutes of Health x-id: https://www.wikidata.org/wiki/Q390551 funding-id: HG008473 - contact: - - name: The Scripps Research Institute - x-id: https://www.wikidata.org/wiki/Q793867 - x-role: responsible organization - url: http://www.scripps.edu/ - - name: Chunlei Wu - x-id: https://orcid.org/0000-0002-2629-6124 - x-role: responsible developer - email: cwu@scripps.edu - - name: Andrew Su - x-id: https://orcid.org/0000-0002-9859-4104 - x-role: contributor - email: asu@scripps.edu } ``` @@ -327,6 +314,14 @@ Field Name | Type | Description url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. +##### smartAPI Fields + +Field Name | Type | Description +---|:---:|--- +responsibleOrganization | `string` | **REQUIRED** Provide the name of the organization responsible for the service. +responsibleDeveloper | `URI` | **REQUIRED** Provide the name, ID and email for the responsible developer. +Contributor | `string` | Indicate any other contributor to the conception, development, or support of the API. + This object can be extended with [Specification Extensions](#specificationExtensions). ##### Contact Object Example: @@ -345,6 +340,23 @@ url: http://www.example.com/support email: support@example.com ``` +```smartAPI yaml +{ contact: + - name: The Scripps Research Institute + x-id: https://www.wikidata.org/wiki/Q793867 + x-role: responsible organization + url: http://www.scripps.edu/ + - name: Chunlei Wu + x-id: https://orcid.org/0000-0002-2629-6124 + x-role: responsible developer + email: cwu@scripps.edu + - name: Andrew Su + x-id: https://orcid.org/0000-0002-9859-4104 + x-role: contributor + email: asu@scripps.edu +} +``` + #### License Object License information for the exposed API. From 9154c8bb5093d203ab15d3a0a6e9ee20013ae6fa Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Thu, 13 Jul 2017 23:06:02 +0200 Subject: [PATCH 011/104] Update 3.0.md info block smartAPI yaml --- versions/3.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 56a03477da..da6e2191e7 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -277,13 +277,13 @@ version: 1.0.1 { title: mygene.info description: MyGene.info is a high performance API for gene descriptions. + termsOfService: http://mygene.info/terms/ + version: 2.0.0 + documentation: http://docs.mygene.info/en/v3/ x-keywords: - genes - http://semanticscience.org/resource/SIO_010035 - version: 2.0.0 - termsOfService: http://mygene.info/terms/ - x-homepage: http://mygene.info - documentation: http://docs.mygene.info/en/v3/ + x-homepage: http://mygene.info x-developerForum: - https://bitbucket.org/sulab/mygene.hub x-accessRestrictions: From cc001ec504048fce81a60fa7d1c546a9db3d16b5 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 09:48:40 +0200 Subject: [PATCH 012/104] Update 3.0.md --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index da6e2191e7..86bc6bf3a1 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -223,7 +223,7 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -description | `string` | **SHOULD** See See above. +description | `string` | **SHOULD** See above. termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. documentation | `URL` | **SHOULD** Additional documentation for the API. From 7baf04ca360ebbf50306b7c5bb6d0e54e8cb295e Mon Sep 17 00:00:00 2001 From: Brendan Abbott Date: Fri, 14 Jul 2017 17:57:10 +1000 Subject: [PATCH 013/104] Update IMPLEMENTATIONS.md Add lincoln and serverless-openapi-documentation projects to the IMPLEMENTATIONS.md --- IMPLEMENTATIONS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/IMPLEMENTATIONS.md b/IMPLEMENTATIONS.md index 773e2595a9..9bcf75b8ab 100644 --- a/IMPLEMENTATIONS.md +++ b/IMPLEMENTATIONS.md @@ -34,6 +34,7 @@ These tools are not necessarily endorsed by the OAI. | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| | openapi-viewer | [GitHub/koumoul/openapi-viewer](https://github.com/koumoul-dev/openapi-viewer) | Vue.js | Browse and test a REST API described with the OpenAPI 3.0 Specification. | +| lincoln | [GitHub/temando/open-api-renderer](https://github.com/temando/open-api-renderer)| React.js| A React renderer for Open API v3 | #### Server Implementations @@ -45,3 +46,4 @@ These tools are not necessarily endorsed by the OAI. |----------------|--------------|----------|---------------------| | baucis-openapi3 | [Github/metadevpro/baucis-openapi3](https://github.com/metadevpro/baucis-openapi3) | Node.js | [Baucis.js](https://github.com/wprl/baucis) plugin for generating OpenAPI 3.0 compliant API contracts. | | Google Gnostic | [GitHub/googleapis/gnostic](https://github.com/googleapis/gnostic) | Go | Compile OpenAPI descriptions into equivalent Protocol Buffer representations. | +| serverless-openapi-documentation | [GitHub/temando/serverless-openapi-documentation](https://github.com/temando/serverless-openapi-documentation) | Typescript | Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration | From 2cb70b7de12f885ac3cf868a19f49dcace6138c2 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 10:06:07 +0200 Subject: [PATCH 014/104] Update 3.0.md --- versions/3.0.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 86bc6bf3a1..8f3219a499 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -226,8 +226,6 @@ Field Name | Type | Description description | `string` | **SHOULD** See above. termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. -documentation | `URL` | **SHOULD** Additional documentation for the API. -x-keywords | `string` | Keyword or concepts that describe the API. x-homepage | `URI` | A web page that describes the API. x-developerForum | `URL` | Forum or Mailing list. x-accessRestrictions | `URL` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. From 44727a30f979dbac7007a220fc499e2893a1cbbc Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 11:09:35 +0200 Subject: [PATCH 015/104] Update 3.0.md external documentation block --- versions/3.0.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 8f3219a499..aa3ec6d5c6 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -232,8 +232,6 @@ Field Name | Type | Description x-accounts | `URI` | Links to social media presence such as Twitter, Facebook, LinkedIn, GitHub, etc. x-implementationLanguage | `string` | Language the API was written in. x-maturity | `enum` | Maturity of the API. Values to use: development, production. -x-publications | `URI` | Publications that describe the API. -x-funding | `string` | Indicate sources of funding. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1029,6 +1027,14 @@ Field Name | Type | Description description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. +##### smartAPI Fields + +Field Name | Type | Description +---|:---:|--- +documentation | `URL` | **SHOULD** Additional documentation for the API. +x-funding | `string` | Indicate sources of funding. +x-publications | `URI` | Publications that describe the API. + This object can be extended with [Specification Extensions](#specificationExtensions). ##### External Documentation Object Example From 29e4558cb3a403f2b9b67f0eedb6c6871ef390d6 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 11:11:44 +0200 Subject: [PATCH 016/104] Update 3.0.md external docs elements --- versions/3.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index aa3ec6d5c6..1261db7de5 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1031,9 +1031,9 @@ Field Name | Type | Description Field Name | Type | Description ---|:---:|--- -documentation | `URL` | **SHOULD** Additional documentation for the API. -x-funding | `string` | Indicate sources of funding. -x-publications | `URI` | Publications that describe the API. +url | `URL` | **SHOULD** See above. +x-funding | `string` | Indicate sources of funding. +x-publications | `URI` | Publications that describe the API. This object can be extended with [Specification Extensions](#specificationExtensions). From b4f184d12d52d7cfea8642de5bb62cddc9df7761 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 11:17:05 +0200 Subject: [PATCH 017/104] Update 3.0.md external docs smartAPI example --- versions/3.0.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 1261db7de5..136eeed966 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -275,10 +275,6 @@ version: 1.0.1 description: MyGene.info is a high performance API for gene descriptions. termsOfService: http://mygene.info/terms/ version: 2.0.0 - documentation: http://docs.mygene.info/en/v3/ - x-keywords: - - genes - - http://semanticscience.org/resource/SIO_010035 x-homepage: http://mygene.info x-developerForum: - https://bitbucket.org/sulab/mygene.hub @@ -289,12 +285,6 @@ version: 1.0.1 accountid: mygeneinfo x-implementationLanguage: python x-maturity: production - x-publications: - - https://doi.org/10.1093/nar/gks1114 - x-funding: - - name: National Institutes of Health - x-id: https://www.wikidata.org/wiki/Q390551 - funding-id: HG008473 } ``` @@ -1050,6 +1040,16 @@ This object can be extended with [Specification Extensions](#specificationExtens description: Find more info here url: https://example.com ``` +##### External Documentation Object Example +```yaml +url: http://docs.mygene.info/en/v3/ +x-publications: + - https://doi.org/10.1093/nar/gks1114 +x-funding: + - name: National Institutes of Health + x-id: https://www.wikidata.org/wiki/Q390551 + funding-id: HG008473 +``` #### Parameter Object From 225b679fae4a620b01a8613fb1e5f585457a3869 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 11:28:26 +0200 Subject: [PATCH 018/104] Update 3.0.md Server Object smartAPI Example --- versions/3.0.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index 136eeed966..4cca50ffda 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -382,6 +382,12 @@ Field Name | Type | Description description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. +##### smartAPi Fields + +Field Name | Type | Description +---|:---:|--- +location | `uri` | Location, city and country of the server hosting the API. + This object can be extended with [Specification Extensions](#specificationExtensions). ##### Server Object Example @@ -399,6 +405,19 @@ A single server would be described as: url: https://development.gigantic-server.com/v1 description: Development server ``` +##### Server Object smartAPI Example + +```yaml +server: + - url: http://mygene.info/v3/api + description: Production server + - url: https://mygene.info/v3/api + description: Fictional HTTPS Production server + - url: http://mirror1.mygene.info/api + description: Fictional mirror + - url: http://mygene.info/v3/api + x-location: USA +``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): From c29e2ac0dceb2a1b05b077b68a199753bd737d90 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 11:29:16 +0200 Subject: [PATCH 019/104] Update 3.0.md --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 4cca50ffda..c171bce0b8 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -412,9 +412,9 @@ server: - url: http://mygene.info/v3/api description: Production server - url: https://mygene.info/v3/api - description: Fictional HTTPS Production server + description: Fictional HTTPS Production server - url: http://mirror1.mygene.info/api - description: Fictional mirror + description: Fictional mirror - url: http://mygene.info/v3/api x-location: USA ``` From 85e36c6f12d87deb7ed3dec7f8f68319fa15e5ec Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 12:18:56 +0200 Subject: [PATCH 020/104] Update 3.0.md response mime type --- versions/3.0.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index c171bce0b8..270891bf6f 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -268,6 +268,7 @@ license: url: http://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 ``` +##### Info Object smartAPI Example: ```smartAPI yaml { @@ -1779,6 +1780,11 @@ Field Name | Type | Description content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it. links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). +##### smartAPI Fields +Field Name | Type | Description +---|:---:|--- +responseMimeType | `string` | **REQUIRED**. A list of media types the APIs can produce. The media type definitions should be in compliance with RFC6838. + This object can be extended with [Specification Extensions](#specificationExtensions). ##### Response Object Examples @@ -3295,6 +3301,13 @@ Field Name | Type | Applies To | Description flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. +##### Fixed Fields +Field Name | Type | Applies To | Description +---|:---:|---|--- +type | `string` | Any | **SHOULD** See above. +name | `string` | `apiKey` | **SHOULD**. See above. +in | `string` | `apiKey` | **SHOULD**. See above. + This object can be extended with [Specification Extensions](#specificationExtensions). ##### Security Scheme Object Example From c9f1a44c6e1193fc4a49a45debe1c57621804ffb Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 12:25:14 +0200 Subject: [PATCH 021/104] Update 3.0.md tags/keywords/descriptors --- versions/3.0.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index 270891bf6f..345581506a 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2265,6 +2265,11 @@ Field Name | Type | Description description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. +##### smartAPI Fields +Field Name | Type | Description +---|:---:|--- +x-keywords | `string` | Keyword or concepts that describe the API. + This object can be extended with [Specification Extensions](#specificationExtensions). ##### Tag Object Example From 35f226550eee2d26ecb69f3fa89e7b0672fb7f50 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 13:12:40 +0200 Subject: [PATCH 022/104] Update 3.0.md operationObject smartAPI elements --- versions/3.0.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index 345581506a..673d23629a 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -914,6 +914,14 @@ Field Name | Type | Description security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. +##### smartAPI Fields + +Field Name | Type | Description +---|:---:|--- +x-operationTitle | `string` | **REQUIRED** A unique identifier for the operation. +description | `string` | **REQUIRED** See above. +x-consumes | `string` | **SHOULD** A list of MIME types the operation can consume. + This object can be extended with [Specification Extensions](#specificationExtensions). ##### Operation Object Example @@ -1025,6 +1033,11 @@ security: - read:pets ``` +##### Operation Object smartAPI Example +```yaml +operation title: query gene +consumes: application/json +``` #### External Documentation Object From ba3de68512248d08f300db0617fc3a0b584a97e9 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 13:48:07 +0200 Subject: [PATCH 023/104] Update 3.0.md Operation Object Example --- versions/3.0.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 673d23629a..4476ae109d 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -921,6 +921,10 @@ Field Name | Type | Description x-operationTitle | `string` | **REQUIRED** A unique identifier for the operation. description | `string` | **REQUIRED** See above. x-consumes | `string` | **SHOULD** A list of MIME types the operation can consume. +x-transferProtocol | `string` | **SHOULD** The transfer protocol of the API. Values must be from the list: "http", "https", "ws", "wss". This optional value will override the top-level schemes if present. +x-pathTemplate | `string` | The path for the operation. +x-accessRestrictions | `string` | Access restrictions to invoke the operation. +x-collection | `string` | Names of collections of which the resource is a part e.g. a suite, library etc. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1035,8 +1039,12 @@ security: ##### Operation Object smartAPI Example ```yaml -operation title: query gene -consumes: application/json +x-operationTitle: query gene +x-consumes: application/json +x-transferProtocol: http +x-pathTemplate: /query +x-accessRestrictions: free +x-collection: Gene Annotation ``` #### External Documentation Object From 3e5e35965d7b42e778cf053c14d2e7a538d59f07 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 14:03:19 +0200 Subject: [PATCH 024/104] Update 3.0.md parameter object --- versions/3.0.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 4476ae109d..e3ecabcf12 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -305,9 +305,9 @@ Field Name | Type | Description Field Name | Type | Description ---|:---:|--- -responsibleOrganization | `string` | **REQUIRED** Provide the name of the organization responsible for the service. -responsibleDeveloper | `URI` | **REQUIRED** Provide the name, ID and email for the responsible developer. -Contributor | `string` | Indicate any other contributor to the conception, development, or support of the API. +x-role: responsibleOrganization | `string` | **REQUIRED** Provide the name of the organization responsible for the service. +x-role: responsibleDeveloper | `URI` | **REQUIRED** Provide the name, ID and email for the responsible developer. +x-role: contributor | `string` | Indicate any other contributor to the conception, development, or support of the API. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -387,7 +387,7 @@ Field Name | Type | Description Field Name | Type | Description ---|:---:|--- -location | `uri` | Location, city and country of the server hosting the API. +x-location | `uri` | Location, city and country of the server hosting the API. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1116,6 +1116,15 @@ Field Name | Type | Description deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. +##### smartAPI Fields +Field Name | Type | Description +---|:---:|--- +description | `string` | **SHOULD** See above. +x-location | `string` | **REQUIRED** Determines the location of the parameters +x-parameterType | `string` | **SHOULD** Type of the parameter in terms of its role in the operation. +x-parameterValueType | `string` | **SHOULD** Semantic identifiers of particular parameters, retreived from identifiers.org. + + The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. @@ -1291,6 +1300,13 @@ schema: style: form ``` +##### Parameter Object smartAPI Examples +```yaml +x-location: "query" +x-parameterType: "input parameter" +x-parameterValueType": "http://identifiers.org/ensembl" +``` + A complex parameter using `content` to define serialization: ```json @@ -1804,7 +1820,7 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -responseMimeType | `string` | **REQUIRED**. A list of media types the APIs can produce. The media type definitions should be in compliance with RFC6838. +x-responseMimeType | `string` | **REQUIRED**. A list of media types the APIs can produce. The media type definitions should be in compliance with RFC6838. This object can be extended with [Specification Extensions](#specificationExtensions). From b8282e46f1358c5f03c4b5f6431636c5d283fd5a Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 21:51:20 +0200 Subject: [PATCH 025/104] Update 3.0.md parameter object --- versions/3.0.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index e3ecabcf12..cc95c5d560 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1123,7 +1123,8 @@ Field Name | Type | Description x-location | `string` | **REQUIRED** Determines the location of the parameters x-parameterType | `string` | **SHOULD** Type of the parameter in terms of its role in the operation. x-parameterValueType | `string` | **SHOULD** Semantic identifiers of particular parameters, retreived from identifiers.org. - +x-defaultValue | `string` | Default value for each input/output. +x-exampleValue | `string` | Example value for each input/output. The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. @@ -1305,6 +1306,8 @@ style: form x-location: "query" x-parameterType: "input parameter" x-parameterValueType": "http://identifiers.org/ensembl" +x-defaultValue: "cdk2" +x-exampleValue: "cdk2" ``` A complex parameter using `content` to define serialization: From c41117422809b98f6833e973ccb03ee4f9d6934e Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 22:00:27 +0200 Subject: [PATCH 026/104] Update 3.0.md response object --- versions/3.0.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index cc95c5d560..35b2c1500b 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1823,7 +1823,10 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -x-responseMimeType | `string` | **REQUIRED**. A list of media types the APIs can produce. The media type definitions should be in compliance with RFC6838. +x-responseMimeType | `string` | **REQUIRED** A list of media types the APIs can produce. The media type definitions should be in compliance with RFC6838. +x-responseExampleValue | `string` | An example of the response value. +x-responseProfile | `URI` | Conformance to a specified format. +x-responseDataType | `array of objects` | Semantic annotation of the response using the smartAPI profiler. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1949,6 +1952,15 @@ Response with no return value: ```yaml description: object created ``` +##### Response Object smartAPI Examples +```yaml +responses: + - content: + - application/json: +x-responseExampleValue +x-responseProfile: "http://www.w3.org/ns/anno.jsonld" +x-responseDataType: [{"elementPath":"ec","datatype":"http://identifiers.org/ec-code/"},{"elementPath":"ensembl.gene","datatype":"http://identifiers.org/ensembl/"}] +``` #### Callback Object From 58cd8334b17f3f43b675938a9af5c032b79dad5a Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 14 Jul 2017 22:08:58 +0200 Subject: [PATCH 027/104] Update 3.0.md typo --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 35b2c1500b..ba1d791730 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1824,7 +1824,7 @@ Field Name | Type | Description Field Name | Type | Description ---|:---:|--- x-responseMimeType | `string` | **REQUIRED** A list of media types the APIs can produce. The media type definitions should be in compliance with RFC6838. -x-responseExampleValue | `string` | An example of the response value. +x-responseExampleValue | `integer` | An example of the response value. x-responseProfile | `URI` | Conformance to a specified format. x-responseDataType | `array of objects` | Semantic annotation of the response using the smartAPI profiler. @@ -1957,7 +1957,7 @@ description: object created responses: - content: - application/json: -x-responseExampleValue +x-responseExampleValue: "200" x-responseProfile: "http://www.w3.org/ns/anno.jsonld" x-responseDataType: [{"elementPath":"ec","datatype":"http://identifiers.org/ec-code/"},{"elementPath":"ensembl.gene","datatype":"http://identifiers.org/ensembl/"}] ``` From 44ea4108f343cb9f07be32db4c335eed7a86893f Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Sat, 15 Jul 2017 00:12:08 +0200 Subject: [PATCH 028/104] Update 3.0.md moved things around and renamed them revised and merged most smartAPI examples into existing example blocks --- versions/3.0.md | 219 +++++++++++++++++------------------------------- 1 file changed, 78 insertions(+), 141 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index ba1d791730..49ca117260 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1,6 +1,7 @@ # OpenAPI Specification #### Version 3.0.0-rc2 +#### adapted for smartAPI The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. @@ -220,20 +221,17 @@ Field Name | Type | Description license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **REQUIRED**. The version of the API definition (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). +This object can be extended with [Specification Extensions](#specificationExtensions). + ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- description | `string` | **SHOULD** See above. termsOfService | `URL` | **REQUIRED** See above. -version | `string` | **REQUIRED** The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set. -x-homepage | `URI` | A web page that describes the API. -x-developerForum | `URL` | Forum or Mailing list. -x-accessRestrictions | `URL` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. -x-accounts | `URI` | Links to social media presence such as Twitter, Facebook, LinkedIn, GitHub, etc. -x-implementationLanguage | `string` | Language the API was written in. +version | `string` | **REQUIRED** The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. x-maturity | `enum` | Maturity of the API. Values to use: development, production. - -This object can be extended with [Specification Extensions](#specificationExtensions). +x-accessRestrictions | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. +x-implementationLanguage | `string` | Language the API was written in. ##### Info Object Example: @@ -267,26 +265,9 @@ license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 -``` -##### Info Object smartAPI Example: - -```smartAPI yaml -{ - title: mygene.info - description: MyGene.info is a high performance API for gene descriptions. - termsOfService: http://mygene.info/terms/ - version: 2.0.0 - x-homepage: http://mygene.info - x-developerForum: - - https://bitbucket.org/sulab/mygene.hub - x-accessRestrictions: - - none - x-accounts: - - name: twitter - accountid: mygeneinfo - x-implementationLanguage: python - x-maturity: production -} +x-accessRestrictions: none +x-maturity: production +x-implementationLanguage: python ``` #### Contact Object @@ -301,15 +282,15 @@ Field Name | Type | Description url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. +This object can be extended with [Specification Extensions](#specificationExtensions). + ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -x-role: responsibleOrganization | `string` | **REQUIRED** Provide the name of the organization responsible for the service. -x-role: responsibleDeveloper | `URI` | **REQUIRED** Provide the name, ID and email for the responsible developer. -x-role: contributor | `string` | Indicate any other contributor to the conception, development, or support of the API. +x-role: | `enum` | **REQUIRED** Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. +x-id: | `string` | **SHOULD** Provide a unique identifier for the contact. -This object can be extended with [Specification Extensions](#specificationExtensions). ##### Contact Object Example: @@ -322,26 +303,17 @@ This object can be extended with [Specification Extensions](#specificationExtens ``` ```yaml -name: API Support -url: http://www.example.com/support -email: support@example.com -``` - -```smartAPI yaml -{ contact: - - name: The Scripps Research Institute - x-id: https://www.wikidata.org/wiki/Q793867 - x-role: responsible organization - url: http://www.scripps.edu/ - - name: Chunlei Wu - x-id: https://orcid.org/0000-0002-2629-6124 - x-role: responsible developer - email: cwu@scripps.edu - - name: Andrew Su - x-id: https://orcid.org/0000-0002-9859-4104 - x-role: contributor - email: asu@scripps.edu -} +- name: API Support + url: http://www.example.com/support + email: support@example.com +- name: The Pet Store + x-id: https://www.wikidata.org/wiki/Q220142 + x-role: responsible organization + url: http://www.example.com +- name: The developer + x-id: https://example.org/#me + x-role: responsible developer + email: dev@example.org ``` #### License Object @@ -387,7 +359,7 @@ Field Name | Type | Description Field Name | Type | Description ---|:---:|--- -x-location | `uri` | Location, city and country of the server hosting the API. +x-location | `string` | Location, city and country of the server hosting the API. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -398,26 +370,15 @@ A single server would be described as: ```json { "url": "https://development.gigantic-server.com/v1", - "description": "Development server" + "description": "Development server", + "x-location": "California, USA" } ``` ```yaml url: https://development.gigantic-server.com/v1 description: Development server -``` -##### Server Object smartAPI Example - -```yaml -server: - - url: http://mygene.info/v3/api - description: Production server - - url: https://mygene.info/v3/api - description: Fictional HTTPS Production server - - url: http://mirror1.mygene.info/api - description: Fictional mirror - - url: http://mygene.info/v3/api - x-location: USA +x-location: California, USA ``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): @@ -914,19 +875,14 @@ Field Name | Type | Description security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. +This object can be extended with [Specification Extensions](#specificationExtensions). + ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -x-operationTitle | `string` | **REQUIRED** A unique identifier for the operation. -description | `string` | **REQUIRED** See above. -x-consumes | `string` | **SHOULD** A list of MIME types the operation can consume. -x-transferProtocol | `string` | **SHOULD** The transfer protocol of the API. Values must be from the list: "http", "https", "ws", "wss". This optional value will override the top-level schemes if present. -x-pathTemplate | `string` | The path for the operation. -x-accessRestrictions | `string` | Access restrictions to invoke the operation. -x-collection | `string` | Names of collections of which the resource is a part e.g. a suite, library etc. - -This object can be extended with [Specification Extensions](#specificationExtensions). +summary | `string` | **REQUIRED** See above. +x-accessRestriction | `enum` | Access restrictions to invoke the operation. values: none, limited, fee. ##### Operation Object Example @@ -1000,6 +956,7 @@ tags: - pet summary: Updates a pet in the store with form data operationId: updatePetWithForm +x-accessRestriction: free parameters: - name: petId in: path @@ -1037,16 +994,6 @@ security: - read:pets ``` -##### Operation Object smartAPI Example -```yaml -x-operationTitle: query gene -x-consumes: application/json -x-transferProtocol: http -x-pathTemplate: /query -x-accessRestrictions: free -x-collection: Gene Annotation -``` - #### External Documentation Object Allows referencing an external resource for extended documentation. @@ -1058,15 +1005,16 @@ Field Name | Type | Description description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can 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 can be extended with [Specification Extensions](#specificationExtensions). + ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -url | `URL` | **SHOULD** See above. -x-funding | `string` | Indicate sources of funding. -x-publications | `URI` | Publications that describe the API. +x-type | `enum` | **REQUIRED** values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` -This object can be extended with [Specification Extensions](#specificationExtensions). + + ##### External Documentation Object Example @@ -1078,18 +1026,13 @@ This object can be extended with [Specification Extensions](#specificationExtens ``` ```yaml -description: Find more info here -url: https://example.com -``` -##### External Documentation Object Example -```yaml -url: http://docs.mygene.info/en/v3/ -x-publications: - - https://doi.org/10.1093/nar/gks1114 -x-funding: - - name: National Institutes of Health - x-id: https://www.wikidata.org/wiki/Q390551 - funding-id: HG008473 +- description: Find more info here + url: https://example.com + type: website +- type: api documentation + url: http://example.org/api/docs +- type: publication + url: https://doi.org/10.1093/nar/gks1114 ``` #### Parameter Object @@ -1116,16 +1059,6 @@ Field Name | Type | Description deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. -##### smartAPI Fields -Field Name | Type | Description ----|:---:|--- -description | `string` | **SHOULD** See above. -x-location | `string` | **REQUIRED** Determines the location of the parameters -x-parameterType | `string` | **SHOULD** Type of the parameter in terms of its role in the operation. -x-parameterValueType | `string` | **SHOULD** Semantic identifiers of particular parameters, retreived from identifiers.org. -x-defaultValue | `string` | Default value for each input/output. -x-exampleValue | `string` | Example value for each input/output. - The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. @@ -1189,6 +1122,14 @@ deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object can be extended with [Specification Extensions](#specificationExtensions). +##### smartAPI Fields +Field Name | Type | Description +---|:---:|--- +x-parameterType | `uri` | **SHOULD** A concept URI to describe the type of parameter. +x-valueType | [`uri`] | **SHOULD** A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from +x-defaultValue | `string` | Default value. +x-exampleValue | `string` | Example value. + ##### Parameter Object Examples A header parameter with an array of 64 bit integer numbers: @@ -1243,6 +1184,10 @@ description: username to fetch required: true schema: type: string +x-parameterType: http://example.org/username +x-valueType: http://example.org/facebookid +x-defaultValue: +x-exampleValue: bob ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: @@ -1301,15 +1246,6 @@ schema: style: form ``` -##### Parameter Object smartAPI Examples -```yaml -x-location: "query" -x-parameterType: "input parameter" -x-parameterValueType": "http://identifiers.org/ensembl" -x-defaultValue: "cdk2" -x-exampleValue: "cdk2" -``` - A complex parameter using `content` to define serialization: ```json @@ -1820,15 +1756,14 @@ Field Name | Type | Description content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it. links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). +This object can be extended with [Specification Extensions](#specificationExtensions). + ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -x-responseMimeType | `string` | **REQUIRED** A list of media types the APIs can produce. The media type definitions should be in compliance with RFC6838. -x-responseExampleValue | `integer` | An example of the response value. -x-responseProfile | `URI` | Conformance to a specified format. -x-responseDataType | `array of objects` | Semantic annotation of the response using the smartAPI profiler. - -This object can be extended with [Specification Extensions](#specificationExtensions). +content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. +x-responseSchema| `URI` | Conformance to a particular schema/format. +x-responseValueType | `array of responseValueType object` | To specify the types of objects in the response. The responseValueType object consists of a required `valueType` that should provide URI values to the type of object, and an optional `path` to specify to location in the response for that valueType. ##### Response Object Examples @@ -1956,10 +1891,13 @@ description: object created ```yaml responses: - content: - - application/json: -x-responseExampleValue: "200" -x-responseProfile: "http://www.w3.org/ns/anno.jsonld" -x-responseDataType: [{"elementPath":"ec","datatype":"http://identifiers.org/ec-code/"},{"elementPath":"ensembl.gene","datatype":"http://identifiers.org/ensembl/"}] + - application/ld+json: + x-responseProfile: http://www.w3.org/ns/anno.jsonld + x-responseValueType: + - path: a.id + valueType: http://example.org/a.id + - path: a.b.c.id + valueType: http://example.org/c.id ``` #### Callback Object @@ -2320,7 +2258,7 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -x-keywords | `string` | Keyword or concepts that describe the API. +name | `string` | **REQUIRED**. The name of the tag. Recommend that you use URI to specify the concept. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -2334,8 +2272,14 @@ This object can be extended with [Specification Extensions](#specificationExtens ``` ```yaml -name: pet -description: Pets operations +- name: pet + description: Pets operations + +``` +##### Tag Object smartAPI Examples +```yaml +- name: http://purl.bioontology.org/ontology/MESH/D057805 + description: Pets ``` #### Examples Object @@ -3358,13 +3302,6 @@ Field Name | Type | Applies To | Description flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. -##### Fixed Fields -Field Name | Type | Applies To | Description ----|:---:|---|--- -type | `string` | Any | **SHOULD** See above. -name | `string` | `apiKey` | **SHOULD**. See above. -in | `string` | `apiKey` | **SHOULD**. See above. - This object can be extended with [Specification Extensions](#specificationExtensions). ##### Security Scheme Object Example From ef803e9b9f9bcc5ccde2bc6a05421a270eccee98 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Sat, 15 Jul 2017 00:13:22 +0200 Subject: [PATCH 029/104] Update 3.0.md renamed accessRestrictions to accessRestriction --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 49ca117260..3e48fa53fc 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -230,7 +230,7 @@ Field Name | Type | Description termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. x-maturity | `enum` | Maturity of the API. Values to use: development, production. -x-accessRestrictions | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. +x-accessRestriction | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. x-implementationLanguage | `string` | Language the API was written in. ##### Info Object Example: @@ -265,7 +265,7 @@ license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 -x-accessRestrictions: none +x-accessRestriction: none x-maturity: production x-implementationLanguage: python ``` From 687c3111eb5a889705480211890208e78d3e80d0 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Sat, 15 Jul 2017 00:14:45 +0200 Subject: [PATCH 030/104] Update 3.0.md moved elements in contact block --- versions/3.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 3e48fa53fc..eb09a26341 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -307,13 +307,13 @@ Field Name | Type | Description url: http://www.example.com/support email: support@example.com - name: The Pet Store - x-id: https://www.wikidata.org/wiki/Q220142 - x-role: responsible organization url: http://www.example.com + x-role: responsible organization + x-id: https://www.wikidata.org/wiki/Q220142 - name: The developer - x-id: https://example.org/#me - x-role: responsible developer email: dev@example.org + x-role: responsible developer + x-id: https://example.org/#me ``` #### License Object From bf573dde8af87c4bb63dbc943766505428b77ff4 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Sat, 15 Jul 2017 00:15:41 +0200 Subject: [PATCH 031/104] Update 3.0.md moved smartAPI version inline with openAPI version --- versions/3.0.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index eb09a26341..ea90a10af0 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1,7 +1,6 @@ # OpenAPI Specification -#### Version 3.0.0-rc2 -#### adapted for smartAPI +#### Version 3.0.0-rc2 [adapted for smartAPI] The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. From 4d355ebdc95865bef2c715abdc690b93e42bd4ba Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Sat, 15 Jul 2017 00:22:03 +0200 Subject: [PATCH 032/104] Update 3.0.md added social media example --- versions/3.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index ea90a10af0..1dedb2116e 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1032,6 +1032,8 @@ Field Name | Type | Description url: http://example.org/api/docs - type: publication url: https://doi.org/10.1093/nar/gks1114 +- type: social media + url: http://twitter.com/mypetstore ``` #### Parameter Object From 92b5ad1450eb9bcbda6b16ba66eee567a8b17c1c Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sat, 15 Jul 2017 14:12:52 +0200 Subject: [PATCH 033/104] Update 3.0.md x-type for external docs --- versions/3.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 1dedb2116e..8c2c14494d 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1028,11 +1028,11 @@ Field Name | Type | Description - description: Find more info here url: https://example.com type: website -- type: api documentation +- x-type: api documentation url: http://example.org/api/docs -- type: publication +- x-type: publication url: https://doi.org/10.1093/nar/gks1114 -- type: social media +- x-type: social media url: http://twitter.com/mypetstore ``` From cf6b272e9b7c3ae7c47e9cc673f0022a3f4bcf7c Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sat, 15 Jul 2017 14:20:52 +0200 Subject: [PATCH 034/104] Update 3.0.md response object smartAPI example formatting --- versions/3.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 8c2c14494d..8ec5916e20 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1895,10 +1895,10 @@ responses: - application/ld+json: x-responseProfile: http://www.w3.org/ns/anno.jsonld x-responseValueType: - - path: a.id - valueType: http://example.org/a.id - - path: a.b.c.id - valueType: http://example.org/c.id + - path: a.id + valueType: http://example.org/a.id + - path: a.b.c.id + valueType: http://example.org/c.id ``` #### Callback Object From 7b7630498d4c3283b0680b9f81d6b98feea8e8e1 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sat, 15 Jul 2017 14:22:04 +0200 Subject: [PATCH 035/104] Update 3.0.md formatting fixed --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 8ec5916e20..e0d5af11b6 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1896,9 +1896,9 @@ responses: x-responseProfile: http://www.w3.org/ns/anno.jsonld x-responseValueType: - path: a.id - valueType: http://example.org/a.id + valueType: http://example.org/a.id - path: a.b.c.id - valueType: http://example.org/c.id + valueType: http://example.org/c.id ``` #### Callback Object From d1a625e7978980b7da57a21b939412d37a5c2173 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sat, 15 Jul 2017 14:29:29 +0200 Subject: [PATCH 036/104] Update 3.0.md typo fixed --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index e0d5af11b6..548ce9d2b6 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -229,7 +229,7 @@ Field Name | Type | Description termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. x-maturity | `enum` | Maturity of the API. Values to use: development, production. -x-accessRestriction | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. +x-accessRestriction | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, free. x-implementationLanguage | `string` | Language the API was written in. ##### Info Object Example: From 610c1e6c55fe2d4eddebc3bf4b5b440e4930dda0 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sat, 15 Jul 2017 14:43:23 +0200 Subject: [PATCH 037/104] Create smartAPI_spec_v3 smartAPI spec v3 example of mygene.info --- versions/smartAPI_spec_v3 | 931 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 931 insertions(+) create mode 100644 versions/smartAPI_spec_v3 diff --git a/versions/smartAPI_spec_v3 b/versions/smartAPI_spec_v3 new file mode 100644 index 0000000000..120833a15d --- /dev/null +++ b/versions/smartAPI_spec_v3 @@ -0,0 +1,931 @@ +swagger: '2.0' +info: + version: 3.0.0.2 + title: MyGene.info API + description: >- + Documentation of the MyGene.info Gene Query web services. Learn more about + [MyGene.info](http://mygene.info/) + termsOfService: http://example.com/terms/ + contact: + name: Chunlei Wu + x-role: responsibleDeveloper + email: help@mygene.info + x-id: 'http://orcid.org/0000-0002-2629-6124' + x-accessRestriction: none + x-maturity: production + x-implementationLanguage: python +server: + url: https://development.gigantic-server.com/v1 + description: Development server + x-location: California, USA +host: mygene.info +basePath: /v3 +schemes: + - http + - https +produces: + - application/json +tags: + - name: query + description: Query for gene information + - name: gene + description: Gene annotation information + - name: metadata + description: Metadata about the data available from MyGene.info. + - name: http://purl.bioontology.org/ontology/MESH/D005796 + description: Genes +paths: + /query: + get: + tags: + - query + summary: Makes gene query and returns matching gene list. + x-accessRestriction: free + parameters: + - name: q + in: query + description: >- + Query string. Examples "CDK2", "NM_052827", "204639_at". The + detailed query syntax can be found at + http://docs.mygene.info/en/latest/doc/query_service.html + required: true + schema: + type: string + x-parameterType: InputParameter + x-valueType: + - 'http://identifiers.org/hgnc.symbol' + - 'http://identifiers.org/refseq' + - 'http://identifiers.org/unigene' + - 'http://identifiers.org/uniprot' + - 'http://identifiers.org/pdb' + - 'http://identifiers.org/prosite' + - 'http://identifiers.org/pfam' + - 'http://identifiers.org/interpro' + - 'http://identifiers.org/hgnc' + - 'http://identifiers.org/mgi' + - 'http://identifiers.org/rgd' + - 'http://identifiers.org/flybase' + - 'http://identifiers.org/wormbase' + - 'http://identifiers.org/zfin' + - 'http://identifiers.org/tair.gene' + - 'http://identifiers.org/xenbase' + - 'http://identifiers.org/mirbase' + x-defaultValue: "CDK2" + x-exampleValue: "CDK2" + - name: fields + in: query + description: >- + A comma-separated field to limit the fields returned from the + matching gene hits. The supported field names can be found from any + gene object (e.g. http://mygene.info/v2/gene/1017). Note that it + supports dot notation as well, e.g., you can pass "refseq.rna". If + "fields=all", all available fields will be returned. Default + "symbol,name,taxid,entrezgene,ensemblgene". + required: false + type: string + - name: species + in: query + description: >- + can be used to limit the gene hits from given species. You can use + "common names" for nine common species (human, mouse, rat, fruitfly, + nematode, zebrafish, thale-cress, frog and pig). All other species, + you can provide their taxonomy ids. Multiple species can be passed + using comma as a separator. Passing “all” will query against all + available species. Default human,mouse,rat. + required: false + type: string + - name: size + in: query + description: >- + the maximum number of matching gene hits to return (with a cap of + 1000 at the moment). Default 10. + required: false + type: integer + - name: from + in: query + description: >- + the number of matching gene hits to skip, starting from 0. Combining + with "size" parameter, this can be useful for paging. Default 0. + required: false + type: integer + - name: sort + in: query + description: >- + comma-separated fields to sort on. Prefix with "-" for descending + order, otherwise in ascending order. Sort by matching scores in + decending order. + required: false + type: string + - name: facets + in: query + description: >- + a single field or comma-separated fields to return facets, for + example, “facets=taxid”, “facets=taxid,type_of_gene”. + required: false + type: string + - name: species_facet_filter + in: query + description: >- + relevant when faceting on species (i.e., “facets=taxid” are passed). + It’s used to pass species filter without changing the scope of + faceting, so that the returned facet counts won’t change. Either + species name or taxonomy id can be used, just like “species” + parameter above. + required: false + type: string + - name: entrezonly + in: query + description: >- + when passed as “true” or “1”, the query returns only the hits with + valid Entrez gene ids. Default: false + required: false + type: boolean + - name: ensemblonly + in: query + description: >- + when passed as “true” or “1”, the query returns only the hits with + valid Ensembl gene ids. Default: false. + required: false + type: boolean + - name: callback + in: query + description: you can pass a "callback" parameter to make a JSONP call. + required: false + type: string + - name: dotfield + in: query + description: >- + control the format of the returned fields when passed "fields" + parameter contains dot notation, e.g. "fields=refseq.rna". If "true" + or "1", the returned data object contains a single "refseq.rna" + field, otherwise ("false" or "0"), a single "refseq" field with a + sub-field of "rna". Default: true + type: boolean + - name: filter + in: query + description: alias for "fields" parameter. + type: string + - name: limit + in: query + description: alias for "size" parameter. + type: integer + - name: skip + in: query + description: alias for "from" parameter. + type: integer + - name: email + in: query + description: >- + If you are regular users of our services, we encourage you to + provide us an email, so that we can better track the usage or follow + up with you. + type: string + description: >- + Make gene query and return matching gene list. Support JSONP and CORS as + well. + operationId: queryGene + responses: + '200': + schema: + type: object + properties: + hits: + type: array + items: + type: object + properties: + name: + type: string + entrezgene: + type: integer + taxid: + type: integer + symbol: + type: string + _id: + type: integer + max_score: + type: integer + took: + type: integer + total: + type: integer + description: Successful response + responses: + - content: + - application/ld+json: + x-responseProfile: http://www.w3.org/ns/anno.jsonld + x-responseValueType: + - path: a.id + valueType: http://example.org/a.id + - path: a.b.c.id + valueType: http://example.org/c.id + /metadata: + get: + tags: + - metadata + parameters: + - name: callback + in: query + description: you can pass a "callback" parameter to make a JSONP call. + required: false + type: string + description: | + Get metadata about the data available from MyGene.info + operationId: getMetadata + responses: + '200': + schema: + properties: + app_revision: + type: string + genome_assembly: + properties: + fruitfly: + type: string + zebrafish: + type: string + nematode: + type: string + human: + type: string + rat: + type: string + pig: + type: string + mouse: + type: string + frog: + type: string + type: object + source: + type: string + taxonomy: + properties: + fruitfly: + type: integer + thale-cress": + type: integer + zebrafish: + type: integer + nematode: + type: integer + human: + type: integer + rat: + type: integer + pig: + type: integer + mouse: + type: integer + frog: + type: integer + type: object + timestamp: + type: string + src_version: + properties: + netaffy: + type: string + entrez: + type: integer + pharmgkb: + type: integer + ucsc: + type: integer + cpdb: + type: integer + refseq: + type: integer + ensembl: + type: integer + uniprot: + type: integer + type: object + stats: + properties: + total_ensembl_genes_mapped_to_entrez: + type: integer + total_entrez_genes: + type: integer + total_ensembl_only_genes: + type: integer + total_ensembl_genes: + type: integer + total_genes: + type: integer + total_species: + type: integer + type: object + available_fields: + type: string + type: object + description: Successful response + '/gene/{geneid}': + get: + tags: + - gene + parameters: + - name: geneid + in: path + description: >- + Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired + Entrez Gene id works too if it is replaced by a new one, e.g., + 245794 + required: true + type: string + x-parameterType: InputParameter + x-valueType: + - 'http://identifiers.org/ncbigene' + - 'http://identifiers.org/ensembl' + x-defaultValue: + x-exampleValue: "1017" + - name: fields + in: query + description: >- + a comma-separated fields to limit the fields returned from the + matching gene hits. The supported field names can be found from any + gene object (e.g. http://mygene.info/v2/gene/1017). Note that it + supports dot notation as well, e.g., you can pass "refseq.rna". If + "fields=all", all available fields will be returned. Default + "symbol,name,taxid,entrezgene,ensemblgene". + required: false + type: string + - name: callback + in: query + description: you can pass a "callback" parameter to make a JSONP call. + required: false + type: string + - name: filter + in: query + description: alias for "fields" parameter. + required: false + type: string + - name: dotfield + in: query + description: >- + control the format of the returned fields when passed "fields" + parameter contains dot notation, e.g. "fields=refseq.rna". If "true" + or "1", the returned data object contains a single "refseq.rna" + field, otherwise ("false" or "0"), a single "refseq" field with a + sub-field of "rna". Default true. + required: false + type: string + - name: email + in: query + description: >- + If you are regular users of our services, we encourage you to + provide us an email, so that we can better track the usage or follow + up with you. + required: false + type: string + description: | + Retrieve gene annotation based on Entrez or Ensembl gene id, support + JSONP and CORS as well. + operationId: getAnnotation + responses: + '200': + schema: + properties: + reporter: + properties: + HTA-2_0: + type: string + HG-U133_Plus_2: + items: + type: string + type: array + HuEx-1_0: + type: integer + HuGene-1_1: + type: integer + HuGene-2_1: + type: integer + HG-U95Av2: + items: + type: string + type: array + type: object + prosite: + type: string + summary: + type: string + exons: + type: object + symbol: + type: string + genomic_pos: + properties: + chr: + type: integer + strand: + type: integer + end: + type: integer + start: + type: integer + type: object + homologene: + properties: + id: + type: integer + genes: + items: + type: integer + type: array + type: object + taxid: + type: integer + pathway: + properties: + kegg: + items: + properties: + id: + type: string + name: + type: string + type: object + type: array + wikipathways: + items: + properties: + id: + type: string + name: + type: string + type: object + type: array + pid: + items: + properties: + id: + type: string + name: + type: string + type: object + type: array + netpath: + items: + properties: + id: + type: string + name: + type: string + type: object + type: array + reactome: + items: + properties: + id: + type: string + name: + type: string + type: object + type: array + biocarta: + items: + properties: + id: + type: string + name: + type: string + type: object + type: array + type: object + Vega: + type: string + entrezgene: + type: string + pfam: + type: string + ec: + type: string + refseq: + properties: + genomic: + items: + type: string + type: array + rna: + items: + type: string + type: array + protein: + items: + type: string + type: array + type: object + wikipedia: + properties: + url_stub: + type: string + type: object + ensembl: + properties: + transcript: + items: + type: string + type: array + gene: + type: string + type: object + accession: + properties: + genomic: + items: + type: string + type: array + rna: + items: + type: string + type: array + protein: + items: + type: string + type: array + type: object + MIM: + type: integer + HPRD: + type: integer + unigene: + items: + type: string + type: array + pharmgkb: + type: string + genomic_pos_hg19: + properties: + chr: + type: integer + strand: + type: integer + end: + type: integer + start: + type: integer + type: object + HGNC: + type: integer + type_of_gene: + type: string + pir: + type: string + _id: + type: string + pdb: + items: + type: string + type: array + name: + type: string + map_location: + type: string + go: + properties: + BP: + items: + properties: + evidence: + type: string + id: + type: string + term: + type: string + type: object + type: array + CC: + items: + properties: + evidence: + type: string + id: + type: string + term: + type: string + type: object + type: array + MF: + items: + properties: + evidence: + type: string + id: + type: string + term: + type: string + type: object + type: array + type: object + reagent: + properties: + GNF_hs_LentiORF-HA-MYC: + properties: + id: + type: string + relationship: + type: string + type: object + GNF_hs-Origene: + items: + properties: + id: + type: string + relationonship: + type: string + type: object + type: array + GNF_Qia_hs-genome_v1_siRNA: + items: + properties: + id: + type: string + relationonship: + type: string + type: object + type: array + GNF_hs_LentiORF-Jred: + properties: + id: + type: string + relationonship: + type: string + type: object + GNF_hs-druggable_siRNA: + items: + properties: + id: + type: string + relationonship: + type: string + type: object + type: array + GNF_hs-ORFeome1_1_reads: + properties: + id: + type: string + relationonship: + type: string + type: object + Invitrogen_IVTHSSIPKv2: + items: + properties: + id: + type: string + relationonship: + type: string + type: object + type: array + GNF_hs-druggable_lenti-shRNA: + items: + properties: + id: + type: string + relationonship: + type: string + type: object + type: array + GNF_mm+hs-MGC: + properties: + id: + type: string + relationonship: + type: string + type: object + GNF_hs-pkinase_IDT-siRNA: + items: + properties: + id: + type: string + relationonship: + type: string + type: object + type: array + GNF_hs-druggable_plasmid-shRNA: + items: + properties: + id: + type: string + relationonship: + type: string + type: object + type: array + NOVART_hs-genome_siRNA: + items: + properties: + id: + type: string + relationonship: + type: string + type: object + type: array + NIBRI_hs-Secretome_pDEST: + properties: + id: + type: string + relationship: + type: string + type: object + type: object + interpro: + items: + properties: + id: + type: string + description: + type: string + short_desc: + type: string + type: object + type: array + ipi: + items: + type: string + type: array + alias: + items: + type: string + type: array + generif: + items: + properties: + pubmed: + type: string + text: + type: string + type: object + type: array + uniprot: + properties: + Swiss-Prot: + type: string + TrEMBL: + items: + type: string + type: array + type: object + type: object + description: Successful response + responseDataType: + - elementPath: ec + datatype: 'http://identifiers.org/ec-code/' + - elementPath: ensembl.gene + datatype: 'http://identifiers.org/ensembl/' + - elementPath: ensembl.translation.protein + datatype: 'http://identifiers.org/ensembl/' + - elementPath: ensembl.translation.rna + datatype: 'http://identifiers.org/ensembl/' + - elementPath: entrezgene + datatype: 'http://identifiers.org/ncbigene/' + - elementPath: generif.pubmed + datatype: 'http://identifiers.org/pubmed/' + - elementPath: go.bp.evidence + datatype: 'http://identifiers.org/eco/' + - elementPath: go.bp.id + datatype: 'http://identifiers.org/go/' + - elementPath: go.bp.pubmed + datatype: 'http://identifiers.org/pubmed/' + - elementPath: go.bp.term + datatype: 'http://identifiers.org/go/' + - elementPath: go.cc.evidence + datatype: 'http://identifiers.org/eco/' + - elementPath: go.cc.id + datatype: 'http://identifiers.org/go/' + - elementPath: go.cc.pubmed + datatype: 'http://identifiers.org/pubmed/' + - elementPath: go.cc.term + datatype: 'http://identifiers.org/go/' + - elementPath: go.mf.evidence + datatype: 'http://identifiers.org/eco/' + - elementPath: go.mf.id + datatype: 'http://identifiers.org/go/' + - elementPath: go.mf.pubmed + datatype: 'http://identifiers.org/pubmed/' + - elementPath: go.mf.qualifier + datatype: 'http://identifiers.org/go/' + - elementPath: go.mf.term + datatype: 'http://identifiers.org/go/' + - elementPath: hgnc + datatype: 'http://identifiers.org/hgnc/' + - elementPath: homologene.id + datatype: 'http://identifiers.org/homologene/' + - elementPath: interpro.desc + datatype: 'http://identifiers.org/interpro/' + - elementPath: interpro.id + datatype: 'http://identifiers.org/interpro/' + - elementPath: interpro.short_desc + datatype: 'http://identifiers.org/interpro/' + - elementPath: mim + datatype: 'http://identifiers.org/omim/' + - elementPath: pathway.biocarta.id + datatype: 'http://identifiers.org/biocarta.pathway/' + - elementPath: pathway.biocarta.name + datatype: 'http://identifiers.org/biocarta.pathway/' + - elementPath: pathway.kegg.id + datatype: 'http://identifiers.org/kegg.pathway/' + - elementPath: pathway.kegg.name + datatype: 'http://identifiers.org/kegg.pathway/' + - elementPath: pathway.pid.id + datatype: 'http://identifiers.org/pid.pathway/' + - elementPath: pathway.pid.name + datatype: 'http://identifiers.org/pid.pathway/' + - elementPath: pathway.reactome.id + datatype: 'http://identifiers.org/reactome/' + - elementPath: pathway.reactome.name + datatype: 'http://identifiers.org/reactome/' + - elementPath: pathway.wikipathways.id + datatype: 'http://identifiers.org/wikipathways/' + - elementPath: pathway.wikipathways.name + datatype: 'http://identifiers.org/wikipathways/' + - elementPath: pfam + datatype: 'http://identifiers.org/pfam/' + - elementPath: pharmgkb + datatype: 'http://identifiers.org/pharmgkb.pathways/' + - elementPath: prosite + datatype: 'http://identifiers.org/prosite/' + - elementPath: refseq.translation.protein + datatype: 'http://identifiers.org/refseq/' + - elementPath: refseq.translation.rna + datatype: 'http://identifiers.org/refseq/' + - elementPath: taxid + datatype: 'http://identifiers.org/taxonomy/' + - elementPath: uniprot.swiss-prot + datatype: 'http://identifiers.org/uniprot/' + - elementPath: wikipedia.url_stub + datatype: 'http://identifiers.org/wikipedia.en/' + /gene: + post: + tags: + - gene + parameters: + - name: ids + in: query + description: >- + multiple geneids seperated by comma, e.g., "ids=1017,1018" or + "ids=695,ENSG00000123374". Note that currently we only take the + input ids up to 1000 maximum, the rest will be omitted. + required: true + type: string + - name: fields + in: query + description: >- + a comma-separated fields to limit the fields returned from the + matching gene hits. The supported field names can be found from any + gene object (e.g. http://mygene.info/v2/gene/1017). Note that it + supports dot notation as well, e.g., you can pass "refseq.rna". If + "fields=all", all available fields will be returned. Default + "symbol,name,taxid,entrezgene,ensemblgene". + required: false + type: string + - name: species + in: query + description: >- + Optional, can be used to limit the gene hits from given species. You + can use "common names" for nine common species (human, mouse, rat, + fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other + species, you can provide their taxonomy ids. Multiple species can be + passed using comma as a separator. Default all. + required: false + type: string + - name: dotfield + in: query + description: >- + control the format of the returned fields when passed "fields" + parameter contains dot notation, e.g. "fields=refseq.rna". If "true" + or "1", the returned data object contains a single "refseq.rna" + field, otherwise ("false" or "0"), a single "refseq" field with a + sub-field of "rna". Default true. + required: false + type: string + - name: email + in: query + description: >- + If you are regular users of our services, we encourage you to + provide us an email, so that we can better track the usage or follow + up with you. + required: false + type: string + description: | + Make gene queries in batch for a list of Entrez or Ensembl gene ids. + operationId: getGenes + responses: + '200': + schema: + items: + properties: + name: + type: string + entrezgene: + type: integer + symbol: + type: string + taxid: + type: integer + query: + type: string + _id: + type: string + type: object + type: array + description: Successful response From d9268eeb9ecea14c3b0865f8294ad617de203d16 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sat, 15 Jul 2017 14:50:07 +0200 Subject: [PATCH 038/104] Update 3.0.md "free" --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 548ce9d2b6..77b77f873e 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -881,7 +881,7 @@ This object can be extended with [Specification Extensions](#specificationExtens Field Name | Type | Description ---|:---:|--- summary | `string` | **REQUIRED** See above. -x-accessRestriction | `enum` | Access restrictions to invoke the operation. values: none, limited, fee. +x-accessRestriction | `enum` | Access restrictions to invoke the operation. values: none, limited, free. ##### Operation Object Example From 415d61bd00da8a72231abb9a81d04a0f4ddf2fb2 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sat, 15 Jul 2017 21:59:20 +0200 Subject: [PATCH 039/104] Update smartAPI_spec_v3 updated example --- versions/smartAPI_spec_v3 | 2247 ++++++++++++++++++++++--------------- 1 file changed, 1316 insertions(+), 931 deletions(-) diff --git a/versions/smartAPI_spec_v3 b/versions/smartAPI_spec_v3 index 120833a15d..3a4b2d9466 100644 --- a/versions/smartAPI_spec_v3 +++ b/versions/smartAPI_spec_v3 @@ -1,931 +1,1316 @@ -swagger: '2.0' -info: - version: 3.0.0.2 - title: MyGene.info API - description: >- - Documentation of the MyGene.info Gene Query web services. Learn more about - [MyGene.info](http://mygene.info/) - termsOfService: http://example.com/terms/ - contact: - name: Chunlei Wu - x-role: responsibleDeveloper - email: help@mygene.info - x-id: 'http://orcid.org/0000-0002-2629-6124' - x-accessRestriction: none - x-maturity: production - x-implementationLanguage: python -server: - url: https://development.gigantic-server.com/v1 - description: Development server - x-location: California, USA -host: mygene.info -basePath: /v3 -schemes: - - http - - https -produces: - - application/json -tags: - - name: query - description: Query for gene information - - name: gene - description: Gene annotation information - - name: metadata - description: Metadata about the data available from MyGene.info. - - name: http://purl.bioontology.org/ontology/MESH/D005796 - description: Genes -paths: - /query: - get: - tags: - - query - summary: Makes gene query and returns matching gene list. - x-accessRestriction: free - parameters: - - name: q - in: query - description: >- - Query string. Examples "CDK2", "NM_052827", "204639_at". The - detailed query syntax can be found at - http://docs.mygene.info/en/latest/doc/query_service.html - required: true - schema: - type: string - x-parameterType: InputParameter - x-valueType: - - 'http://identifiers.org/hgnc.symbol' - - 'http://identifiers.org/refseq' - - 'http://identifiers.org/unigene' - - 'http://identifiers.org/uniprot' - - 'http://identifiers.org/pdb' - - 'http://identifiers.org/prosite' - - 'http://identifiers.org/pfam' - - 'http://identifiers.org/interpro' - - 'http://identifiers.org/hgnc' - - 'http://identifiers.org/mgi' - - 'http://identifiers.org/rgd' - - 'http://identifiers.org/flybase' - - 'http://identifiers.org/wormbase' - - 'http://identifiers.org/zfin' - - 'http://identifiers.org/tair.gene' - - 'http://identifiers.org/xenbase' - - 'http://identifiers.org/mirbase' - x-defaultValue: "CDK2" - x-exampleValue: "CDK2" - - name: fields - in: query - description: >- - A comma-separated field to limit the fields returned from the - matching gene hits. The supported field names can be found from any - gene object (e.g. http://mygene.info/v2/gene/1017). Note that it - supports dot notation as well, e.g., you can pass "refseq.rna". If - "fields=all", all available fields will be returned. Default - "symbol,name,taxid,entrezgene,ensemblgene". - required: false - type: string - - name: species - in: query - description: >- - can be used to limit the gene hits from given species. You can use - "common names" for nine common species (human, mouse, rat, fruitfly, - nematode, zebrafish, thale-cress, frog and pig). All other species, - you can provide their taxonomy ids. Multiple species can be passed - using comma as a separator. Passing “all” will query against all - available species. Default human,mouse,rat. - required: false - type: string - - name: size - in: query - description: >- - the maximum number of matching gene hits to return (with a cap of - 1000 at the moment). Default 10. - required: false - type: integer - - name: from - in: query - description: >- - the number of matching gene hits to skip, starting from 0. Combining - with "size" parameter, this can be useful for paging. Default 0. - required: false - type: integer - - name: sort - in: query - description: >- - comma-separated fields to sort on. Prefix with "-" for descending - order, otherwise in ascending order. Sort by matching scores in - decending order. - required: false - type: string - - name: facets - in: query - description: >- - a single field or comma-separated fields to return facets, for - example, “facets=taxid”, “facets=taxid,type_of_gene”. - required: false - type: string - - name: species_facet_filter - in: query - description: >- - relevant when faceting on species (i.e., “facets=taxid” are passed). - It’s used to pass species filter without changing the scope of - faceting, so that the returned facet counts won’t change. Either - species name or taxonomy id can be used, just like “species” - parameter above. - required: false - type: string - - name: entrezonly - in: query - description: >- - when passed as “true” or “1”, the query returns only the hits with - valid Entrez gene ids. Default: false - required: false - type: boolean - - name: ensemblonly - in: query - description: >- - when passed as “true” or “1”, the query returns only the hits with - valid Ensembl gene ids. Default: false. - required: false - type: boolean - - name: callback - in: query - description: you can pass a "callback" parameter to make a JSONP call. - required: false - type: string - - name: dotfield - in: query - description: >- - control the format of the returned fields when passed "fields" - parameter contains dot notation, e.g. "fields=refseq.rna". If "true" - or "1", the returned data object contains a single "refseq.rna" - field, otherwise ("false" or "0"), a single "refseq" field with a - sub-field of "rna". Default: true - type: boolean - - name: filter - in: query - description: alias for "fields" parameter. - type: string - - name: limit - in: query - description: alias for "size" parameter. - type: integer - - name: skip - in: query - description: alias for "from" parameter. - type: integer - - name: email - in: query - description: >- - If you are regular users of our services, we encourage you to - provide us an email, so that we can better track the usage or follow - up with you. - type: string - description: >- - Make gene query and return matching gene list. Support JSONP and CORS as - well. - operationId: queryGene - responses: - '200': - schema: - type: object - properties: - hits: - type: array - items: - type: object - properties: - name: - type: string - entrezgene: - type: integer - taxid: - type: integer - symbol: - type: string - _id: - type: integer - max_score: - type: integer - took: - type: integer - total: - type: integer - description: Successful response - responses: - - content: - - application/ld+json: - x-responseProfile: http://www.w3.org/ns/anno.jsonld - x-responseValueType: - - path: a.id - valueType: http://example.org/a.id - - path: a.b.c.id - valueType: http://example.org/c.id - /metadata: - get: - tags: - - metadata - parameters: - - name: callback - in: query - description: you can pass a "callback" parameter to make a JSONP call. - required: false - type: string - description: | - Get metadata about the data available from MyGene.info - operationId: getMetadata - responses: - '200': - schema: - properties: - app_revision: - type: string - genome_assembly: - properties: - fruitfly: - type: string - zebrafish: - type: string - nematode: - type: string - human: - type: string - rat: - type: string - pig: - type: string - mouse: - type: string - frog: - type: string - type: object - source: - type: string - taxonomy: - properties: - fruitfly: - type: integer - thale-cress": - type: integer - zebrafish: - type: integer - nematode: - type: integer - human: - type: integer - rat: - type: integer - pig: - type: integer - mouse: - type: integer - frog: - type: integer - type: object - timestamp: - type: string - src_version: - properties: - netaffy: - type: string - entrez: - type: integer - pharmgkb: - type: integer - ucsc: - type: integer - cpdb: - type: integer - refseq: - type: integer - ensembl: - type: integer - uniprot: - type: integer - type: object - stats: - properties: - total_ensembl_genes_mapped_to_entrez: - type: integer - total_entrez_genes: - type: integer - total_ensembl_only_genes: - type: integer - total_ensembl_genes: - type: integer - total_genes: - type: integer - total_species: - type: integer - type: object - available_fields: - type: string - type: object - description: Successful response - '/gene/{geneid}': - get: - tags: - - gene - parameters: - - name: geneid - in: path - description: >- - Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired - Entrez Gene id works too if it is replaced by a new one, e.g., - 245794 - required: true - type: string - x-parameterType: InputParameter - x-valueType: - - 'http://identifiers.org/ncbigene' - - 'http://identifiers.org/ensembl' - x-defaultValue: - x-exampleValue: "1017" - - name: fields - in: query - description: >- - a comma-separated fields to limit the fields returned from the - matching gene hits. The supported field names can be found from any - gene object (e.g. http://mygene.info/v2/gene/1017). Note that it - supports dot notation as well, e.g., you can pass "refseq.rna". If - "fields=all", all available fields will be returned. Default - "symbol,name,taxid,entrezgene,ensemblgene". - required: false - type: string - - name: callback - in: query - description: you can pass a "callback" parameter to make a JSONP call. - required: false - type: string - - name: filter - in: query - description: alias for "fields" parameter. - required: false - type: string - - name: dotfield - in: query - description: >- - control the format of the returned fields when passed "fields" - parameter contains dot notation, e.g. "fields=refseq.rna". If "true" - or "1", the returned data object contains a single "refseq.rna" - field, otherwise ("false" or "0"), a single "refseq" field with a - sub-field of "rna". Default true. - required: false - type: string - - name: email - in: query - description: >- - If you are regular users of our services, we encourage you to - provide us an email, so that we can better track the usage or follow - up with you. - required: false - type: string - description: | - Retrieve gene annotation based on Entrez or Ensembl gene id, support - JSONP and CORS as well. - operationId: getAnnotation - responses: - '200': - schema: - properties: - reporter: - properties: - HTA-2_0: - type: string - HG-U133_Plus_2: - items: - type: string - type: array - HuEx-1_0: - type: integer - HuGene-1_1: - type: integer - HuGene-2_1: - type: integer - HG-U95Av2: - items: - type: string - type: array - type: object - prosite: - type: string - summary: - type: string - exons: - type: object - symbol: - type: string - genomic_pos: - properties: - chr: - type: integer - strand: - type: integer - end: - type: integer - start: - type: integer - type: object - homologene: - properties: - id: - type: integer - genes: - items: - type: integer - type: array - type: object - taxid: - type: integer - pathway: - properties: - kegg: - items: - properties: - id: - type: string - name: - type: string - type: object - type: array - wikipathways: - items: - properties: - id: - type: string - name: - type: string - type: object - type: array - pid: - items: - properties: - id: - type: string - name: - type: string - type: object - type: array - netpath: - items: - properties: - id: - type: string - name: - type: string - type: object - type: array - reactome: - items: - properties: - id: - type: string - name: - type: string - type: object - type: array - biocarta: - items: - properties: - id: - type: string - name: - type: string - type: object - type: array - type: object - Vega: - type: string - entrezgene: - type: string - pfam: - type: string - ec: - type: string - refseq: - properties: - genomic: - items: - type: string - type: array - rna: - items: - type: string - type: array - protein: - items: - type: string - type: array - type: object - wikipedia: - properties: - url_stub: - type: string - type: object - ensembl: - properties: - transcript: - items: - type: string - type: array - gene: - type: string - type: object - accession: - properties: - genomic: - items: - type: string - type: array - rna: - items: - type: string - type: array - protein: - items: - type: string - type: array - type: object - MIM: - type: integer - HPRD: - type: integer - unigene: - items: - type: string - type: array - pharmgkb: - type: string - genomic_pos_hg19: - properties: - chr: - type: integer - strand: - type: integer - end: - type: integer - start: - type: integer - type: object - HGNC: - type: integer - type_of_gene: - type: string - pir: - type: string - _id: - type: string - pdb: - items: - type: string - type: array - name: - type: string - map_location: - type: string - go: - properties: - BP: - items: - properties: - evidence: - type: string - id: - type: string - term: - type: string - type: object - type: array - CC: - items: - properties: - evidence: - type: string - id: - type: string - term: - type: string - type: object - type: array - MF: - items: - properties: - evidence: - type: string - id: - type: string - term: - type: string - type: object - type: array - type: object - reagent: - properties: - GNF_hs_LentiORF-HA-MYC: - properties: - id: - type: string - relationship: - type: string - type: object - GNF_hs-Origene: - items: - properties: - id: - type: string - relationonship: - type: string - type: object - type: array - GNF_Qia_hs-genome_v1_siRNA: - items: - properties: - id: - type: string - relationonship: - type: string - type: object - type: array - GNF_hs_LentiORF-Jred: - properties: - id: - type: string - relationonship: - type: string - type: object - GNF_hs-druggable_siRNA: - items: - properties: - id: - type: string - relationonship: - type: string - type: object - type: array - GNF_hs-ORFeome1_1_reads: - properties: - id: - type: string - relationonship: - type: string - type: object - Invitrogen_IVTHSSIPKv2: - items: - properties: - id: - type: string - relationonship: - type: string - type: object - type: array - GNF_hs-druggable_lenti-shRNA: - items: - properties: - id: - type: string - relationonship: - type: string - type: object - type: array - GNF_mm+hs-MGC: - properties: - id: - type: string - relationonship: - type: string - type: object - GNF_hs-pkinase_IDT-siRNA: - items: - properties: - id: - type: string - relationonship: - type: string - type: object - type: array - GNF_hs-druggable_plasmid-shRNA: - items: - properties: - id: - type: string - relationonship: - type: string - type: object - type: array - NOVART_hs-genome_siRNA: - items: - properties: - id: - type: string - relationonship: - type: string - type: object - type: array - NIBRI_hs-Secretome_pDEST: - properties: - id: - type: string - relationship: - type: string - type: object - type: object - interpro: - items: - properties: - id: - type: string - description: - type: string - short_desc: - type: string - type: object - type: array - ipi: - items: - type: string - type: array - alias: - items: - type: string - type: array - generif: - items: - properties: - pubmed: - type: string - text: - type: string - type: object - type: array - uniprot: - properties: - Swiss-Prot: - type: string - TrEMBL: - items: - type: string - type: array - type: object - type: object - description: Successful response - responseDataType: - - elementPath: ec - datatype: 'http://identifiers.org/ec-code/' - - elementPath: ensembl.gene - datatype: 'http://identifiers.org/ensembl/' - - elementPath: ensembl.translation.protein - datatype: 'http://identifiers.org/ensembl/' - - elementPath: ensembl.translation.rna - datatype: 'http://identifiers.org/ensembl/' - - elementPath: entrezgene - datatype: 'http://identifiers.org/ncbigene/' - - elementPath: generif.pubmed - datatype: 'http://identifiers.org/pubmed/' - - elementPath: go.bp.evidence - datatype: 'http://identifiers.org/eco/' - - elementPath: go.bp.id - datatype: 'http://identifiers.org/go/' - - elementPath: go.bp.pubmed - datatype: 'http://identifiers.org/pubmed/' - - elementPath: go.bp.term - datatype: 'http://identifiers.org/go/' - - elementPath: go.cc.evidence - datatype: 'http://identifiers.org/eco/' - - elementPath: go.cc.id - datatype: 'http://identifiers.org/go/' - - elementPath: go.cc.pubmed - datatype: 'http://identifiers.org/pubmed/' - - elementPath: go.cc.term - datatype: 'http://identifiers.org/go/' - - elementPath: go.mf.evidence - datatype: 'http://identifiers.org/eco/' - - elementPath: go.mf.id - datatype: 'http://identifiers.org/go/' - - elementPath: go.mf.pubmed - datatype: 'http://identifiers.org/pubmed/' - - elementPath: go.mf.qualifier - datatype: 'http://identifiers.org/go/' - - elementPath: go.mf.term - datatype: 'http://identifiers.org/go/' - - elementPath: hgnc - datatype: 'http://identifiers.org/hgnc/' - - elementPath: homologene.id - datatype: 'http://identifiers.org/homologene/' - - elementPath: interpro.desc - datatype: 'http://identifiers.org/interpro/' - - elementPath: interpro.id - datatype: 'http://identifiers.org/interpro/' - - elementPath: interpro.short_desc - datatype: 'http://identifiers.org/interpro/' - - elementPath: mim - datatype: 'http://identifiers.org/omim/' - - elementPath: pathway.biocarta.id - datatype: 'http://identifiers.org/biocarta.pathway/' - - elementPath: pathway.biocarta.name - datatype: 'http://identifiers.org/biocarta.pathway/' - - elementPath: pathway.kegg.id - datatype: 'http://identifiers.org/kegg.pathway/' - - elementPath: pathway.kegg.name - datatype: 'http://identifiers.org/kegg.pathway/' - - elementPath: pathway.pid.id - datatype: 'http://identifiers.org/pid.pathway/' - - elementPath: pathway.pid.name - datatype: 'http://identifiers.org/pid.pathway/' - - elementPath: pathway.reactome.id - datatype: 'http://identifiers.org/reactome/' - - elementPath: pathway.reactome.name - datatype: 'http://identifiers.org/reactome/' - - elementPath: pathway.wikipathways.id - datatype: 'http://identifiers.org/wikipathways/' - - elementPath: pathway.wikipathways.name - datatype: 'http://identifiers.org/wikipathways/' - - elementPath: pfam - datatype: 'http://identifiers.org/pfam/' - - elementPath: pharmgkb - datatype: 'http://identifiers.org/pharmgkb.pathways/' - - elementPath: prosite - datatype: 'http://identifiers.org/prosite/' - - elementPath: refseq.translation.protein - datatype: 'http://identifiers.org/refseq/' - - elementPath: refseq.translation.rna - datatype: 'http://identifiers.org/refseq/' - - elementPath: taxid - datatype: 'http://identifiers.org/taxonomy/' - - elementPath: uniprot.swiss-prot - datatype: 'http://identifiers.org/uniprot/' - - elementPath: wikipedia.url_stub - datatype: 'http://identifiers.org/wikipedia.en/' - /gene: - post: - tags: - - gene - parameters: - - name: ids - in: query - description: >- - multiple geneids seperated by comma, e.g., "ids=1017,1018" or - "ids=695,ENSG00000123374". Note that currently we only take the - input ids up to 1000 maximum, the rest will be omitted. - required: true - type: string - - name: fields - in: query - description: >- - a comma-separated fields to limit the fields returned from the - matching gene hits. The supported field names can be found from any - gene object (e.g. http://mygene.info/v2/gene/1017). Note that it - supports dot notation as well, e.g., you can pass "refseq.rna". If - "fields=all", all available fields will be returned. Default - "symbol,name,taxid,entrezgene,ensemblgene". - required: false - type: string - - name: species - in: query - description: >- - Optional, can be used to limit the gene hits from given species. You - can use "common names" for nine common species (human, mouse, rat, - fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other - species, you can provide their taxonomy ids. Multiple species can be - passed using comma as a separator. Default all. - required: false - type: string - - name: dotfield - in: query - description: >- - control the format of the returned fields when passed "fields" - parameter contains dot notation, e.g. "fields=refseq.rna". If "true" - or "1", the returned data object contains a single "refseq.rna" - field, otherwise ("false" or "0"), a single "refseq" field with a - sub-field of "rna". Default true. - required: false - type: string - - name: email - in: query - description: >- - If you are regular users of our services, we encourage you to - provide us an email, so that we can better track the usage or follow - up with you. - required: false - type: string - description: | - Make gene queries in batch for a list of Entrez or Ensembl gene ids. - operationId: getGenes - responses: - '200': - schema: - items: - properties: - name: - type: string - entrezgene: - type: integer - symbol: - type: string - taxid: - type: integer - query: - type: string - _id: - type: string - type: object - type: array - description: Successful response +{ + "swagger": "2.0", + "info": { + "version": "3.0.0.2", + "title": "MyGene.info API", + "description": "Documentation of the MyGene.info Gene Query web services. Learn more about [MyGene.info](http://mygene.info/)", + "termsOfService": "http://example.com/terms/", + "contact": { + "name": "Chunlei Wu", + "x-role": "responsibleDeveloper", + "email": "help@mygene.info", + "x-id": "http://orcid.org/0000-0002-2629-6124" + }, + "x-accessRestriction": "none", + "x-maturity": "production", + "x-implementationLanguage": "python" + }, + "externalDocs": [ + { + "description": "Find more info here", + "url": "https://example.com", + "x-type": "website" + }, + { + "x-type": "api documentation", + "url": "http://docs.mygene.info/en/latest/" + }, + { + "x-type": "publication", + "url": "https://doi.org/10.1093/nar/gks1114" + }, + { + "x-type": "social media", + "url": "http://twitter.com/mygeneinfo" + } + ], + "server": { + "url": "https://development.gigantic-server.com/v1", + "description": "Development server", + "x-location": "California, USA" + }, + "host": "mygene.info", + "basePath": "/v3", + "schemes": [ + "http", + "https" + ], + "produces": [ + "application/json" + ], + "tags": [ + { + "name": "query", + "description": "Query for gene information" + }, + { + "name": "gene", + "description": "Gene annotation information" + }, + { + "name": "metadata", + "description": "Metadata about the data available from MyGene.info." + }, + { + "name": "http://purl.bioontology.org/ontology/MESH/D005796", + "description": "Genes" + } + ], + "paths": { + "/query": { + "get": { + "tags": [ + "query" + ], + "summary": "Makes gene query and returns matching gene list.", + "x-accessRestriction": "free", + "parameters": [ + { + "name": "q", + "in": "query", + "description": "Query string. Examples \"CDK2\", \"NM_052827\", \"204639_at\". The detailed query syntax can be found at http://docs.mygene.info/en/latest/doc/query_service.html", + "required": true, + "schema": { + "type": "string" + }, + "x-parameterType": "InputParameter", + "x-valueType": [ + "http://identifiers.org/hgnc.symbol", + "http://identifiers.org/refseq", + "http://identifiers.org/unigene", + "http://identifiers.org/uniprot", + "http://identifiers.org/pdb", + "http://identifiers.org/prosite", + "http://identifiers.org/pfam", + "http://identifiers.org/interpro", + "http://identifiers.org/hgnc", + "http://identifiers.org/mgi", + "http://identifiers.org/rgd", + "http://identifiers.org/flybase", + "http://identifiers.org/wormbase", + "http://identifiers.org/zfin", + "http://identifiers.org/tair.gene", + "http://identifiers.org/xenbase", + "http://identifiers.org/mirbase" + ], + "x-defaultValue": "CDK2", + "x-exampleValue": "CDK2" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated field to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", + "required": false, + "type": "string" + }, + { + "name": "species", + "in": "query", + "description": "can be used to limit the gene hits from given species. You can use \"common names\" for nine common species (human, mouse, rat, fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other species, you can provide their taxonomy ids. Multiple species can be passed using comma as a separator. Passing “all” will query against all available species. Default human,mouse,rat.", + "required": false, + "type": "string" + }, + { + "name": "size", + "in": "query", + "description": "the maximum number of matching gene hits to return (with a cap of 1000 at the moment). Default 10.", + "required": false, + "type": "integer" + }, + { + "name": "from", + "in": "query", + "description": "the number of matching gene hits to skip, starting from 0. Combining with \"size\" parameter, this can be useful for paging. Default 0.", + "required": false, + "type": "integer" + }, + { + "name": "sort", + "in": "query", + "description": "comma-separated fields to sort on. Prefix with \"-\" for descending order, otherwise in ascending order. Sort by matching scores in decending order.", + "required": false, + "type": "string" + }, + { + "name": "facets", + "in": "query", + "description": "a single field or comma-separated fields to return facets, for example, “facets=taxid”, “facets=taxid,type_of_gene”.", + "required": false, + "type": "string" + }, + { + "name": "species_facet_filter", + "in": "query", + "description": "relevant when faceting on species (i.e., “facets=taxid” are passed). It’s used to pass species filter without changing the scope of faceting, so that the returned facet counts won’t change. Either species name or taxonomy id can be used, just like “species” parameter above.", + "required": false, + "type": "string" + }, + { + "name": "entrezonly", + "in": "query", + "description": "when passed as “true” or “1”, the query returns only the hits with valid Entrez gene ids. Default: false", + "required": false, + "type": "boolean" + }, + { + "name": "ensemblonly", + "in": "query", + "description": "when passed as “true” or “1”, the query returns only the hits with valid Ensembl gene ids. Default: false.", + "required": false, + "type": "boolean" + }, + { + "name": "callback", + "in": "query", + "description": "you can pass a \"callback\" parameter to make a JSONP call.", + "required": false, + "type": "string" + }, + { + "name": "dotfield", + "in": "query", + "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default: true", + "type": "boolean" + }, + { + "name": "filter", + "in": "query", + "description": "alias for \"fields\" parameter.", + "type": "string" + }, + { + "name": "limit", + "in": "query", + "description": "alias for \"size\" parameter.", + "type": "integer" + }, + { + "name": "skip", + "in": "query", + "description": "alias for \"from\" parameter.", + "type": "integer" + }, + { + "name": "email", + "in": "query", + "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", + "type": "string" + } + ], + "description": "Make gene query and return matching gene list. Support JSONP and CORS as well.", + "operationId": "queryGene", + "responses": { + "200": { + "schema": { + "type": "object", + "properties": { + "hits": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "entrezgene": { + "type": "integer" + }, + "taxid": { + "type": "integer" + }, + "symbol": { + "type": "string" + }, + "_id": { + "type": "integer" + } + } + } + }, + "max_score": { + "type": "integer" + }, + "took": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "description": "Successful response" + } + } + } + }, + "/metadata": { + "get": { + "tags": [ + "metadata" + ], + "parameters": [ + { + "name": "callback", + "in": "query", + "description": "you can pass a \"callback\" parameter to make a JSONP call.", + "required": false, + "type": "string" + } + ], + "description": "Get metadata about the data available from MyGene.info\n", + "operationId": "getMetadata", + "responses": { + "200": { + "schema": { + "properties": { + "app_revision": { + "type": "string" + }, + "genome_assembly": { + "properties": { + "fruitfly": { + "type": "string" + }, + "zebrafish": { + "type": "string" + }, + "nematode": { + "type": "string" + }, + "human": { + "type": "string" + }, + "rat": { + "type": "string" + }, + "pig": { + "type": "string" + }, + "mouse": { + "type": "string" + }, + "frog": { + "type": "string" + } + }, + "type": "object" + }, + "source": { + "type": "string" + }, + "taxonomy": { + "properties": { + "fruitfly": { + "type": "integer" + }, + "thale-cress\"": { + "type": "integer" + }, + "zebrafish": { + "type": "integer" + }, + "nematode": { + "type": "integer" + }, + "human": { + "type": "integer" + }, + "rat": { + "type": "integer" + }, + "pig": { + "type": "integer" + }, + "mouse": { + "type": "integer" + }, + "frog": { + "type": "integer" + } + }, + "type": "object" + }, + "timestamp": { + "type": "string" + }, + "src_version": { + "properties": { + "netaffy": { + "type": "string" + }, + "entrez": { + "type": "integer" + }, + "pharmgkb": { + "type": "integer" + }, + "ucsc": { + "type": "integer" + }, + "cpdb": { + "type": "integer" + }, + "refseq": { + "type": "integer" + }, + "ensembl": { + "type": "integer" + }, + "uniprot": { + "type": "integer" + } + }, + "type": "object" + }, + "stats": { + "properties": { + "total_ensembl_genes_mapped_to_entrez": { + "type": "integer" + }, + "total_entrez_genes": { + "type": "integer" + }, + "total_ensembl_only_genes": { + "type": "integer" + }, + "total_ensembl_genes": { + "type": "integer" + }, + "total_genes": { + "type": "integer" + }, + "total_species": { + "type": "integer" + } + }, + "type": "object" + }, + "available_fields": { + "type": "string" + } + }, + "type": "object" + }, + "description": "Successful response" + } + } + } + }, + "/gene/{geneid}": { + "get": { + "tags": [ + "gene" + ], + "parameters": [ + { + "name": "geneid", + "in": "path", + "description": "Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired Entrez Gene id works too if it is replaced by a new one, e.g., 245794", + "required": true, + "type": "string", + "x-parameterType": "InputParameter", + "x-valueType": [ + "http://identifiers.org/ncbigene", + "http://identifiers.org/ensembl" + ], + "x-defaultValue": null, + "x-exampleValue": "1017" + }, + { + "name": "fields", + "in": "query", + "description": "a comma-separated fields to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", + "required": false, + "type": "string" + }, + { + "name": "callback", + "in": "query", + "description": "you can pass a \"callback\" parameter to make a JSONP call.", + "required": false, + "type": "string" + }, + { + "name": "filter", + "in": "query", + "description": "alias for \"fields\" parameter.", + "required": false, + "type": "string" + }, + { + "name": "dotfield", + "in": "query", + "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default true.", + "required": false, + "type": "string" + }, + { + "name": "email", + "in": "query", + "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", + "required": false, + "type": "string" + } + ], + "description": "Retrieve gene annotation based on Entrez or Ensembl gene id, support\nJSONP and CORS as well.\n", + "operationId": "getAnnotation", + "responses": { + "200": { + "schema": { + "properties": { + "reporter": { + "properties": { + "HTA-2_0": { + "type": "string" + }, + "HG-U133_Plus_2": { + "items": { + "type": "string" + }, + "type": "array" + }, + "HuEx-1_0": { + "type": "integer" + }, + "HuGene-1_1": { + "type": "integer" + }, + "HuGene-2_1": { + "type": "integer" + }, + "HG-U95Av2": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "prosite": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "exons": { + "type": "object" + }, + "symbol": { + "type": "string" + }, + "genomic_pos": { + "properties": { + "chr": { + "type": "integer" + }, + "strand": { + "type": "integer" + }, + "end": { + "type": "integer" + }, + "start": { + "type": "integer" + } + }, + "type": "object" + }, + "homologene": { + "properties": { + "id": { + "type": "integer" + }, + "genes": { + "items": { + "type": "integer" + }, + "type": "array" + } + }, + "type": "object" + }, + "taxid": { + "type": "integer" + }, + "pathway": { + "properties": { + "kegg": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "wikipathways": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "pid": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "netpath": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "reactome": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "biocarta": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "Vega": { + "type": "string" + }, + "entrezgene": { + "type": "string" + }, + "pfam": { + "type": "string" + }, + "ec": { + "type": "string" + }, + "refseq": { + "properties": { + "genomic": { + "items": { + "type": "string" + }, + "type": "array" + }, + "rna": { + "items": { + "type": "string" + }, + "type": "array" + }, + "protein": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "wikipedia": { + "properties": { + "url_stub": { + "type": "string" + } + }, + "type": "object" + }, + "ensembl": { + "properties": { + "transcript": { + "items": { + "type": "string" + }, + "type": "array" + }, + "gene": { + "type": "string" + } + }, + "type": "object" + }, + "accession": { + "properties": { + "genomic": { + "items": { + "type": "string" + }, + "type": "array" + }, + "rna": { + "items": { + "type": "string" + }, + "type": "array" + }, + "protein": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "MIM": { + "type": "integer" + }, + "HPRD": { + "type": "integer" + }, + "unigene": { + "items": { + "type": "string" + }, + "type": "array" + }, + "pharmgkb": { + "type": "string" + }, + "genomic_pos_hg19": { + "properties": { + "chr": { + "type": "integer" + }, + "strand": { + "type": "integer" + }, + "end": { + "type": "integer" + }, + "start": { + "type": "integer" + } + }, + "type": "object" + }, + "HGNC": { + "type": "integer" + }, + "type_of_gene": { + "type": "string" + }, + "pir": { + "type": "string" + }, + "_id": { + "type": "string" + }, + "pdb": { + "items": { + "type": "string" + }, + "type": "array" + }, + "name": { + "type": "string" + }, + "map_location": { + "type": "string" + }, + "go": { + "properties": { + "BP": { + "items": { + "properties": { + "evidence": { + "type": "string" + }, + "id": { + "type": "string" + }, + "term": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "CC": { + "items": { + "properties": { + "evidence": { + "type": "string" + }, + "id": { + "type": "string" + }, + "term": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "MF": { + "items": { + "properties": { + "evidence": { + "type": "string" + }, + "id": { + "type": "string" + }, + "term": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "reagent": { + "properties": { + "GNF_hs_LentiORF-HA-MYC": { + "properties": { + "id": { + "type": "string" + }, + "relationship": { + "type": "string" + } + }, + "type": "object" + }, + "GNF_hs-Origene": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_Qia_hs-genome_v1_siRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_hs_LentiORF-Jred": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "GNF_hs-druggable_siRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_hs-ORFeome1_1_reads": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "Invitrogen_IVTHSSIPKv2": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_hs-druggable_lenti-shRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_mm+hs-MGC": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "GNF_hs-pkinase_IDT-siRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_hs-druggable_plasmid-shRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "NOVART_hs-genome_siRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "NIBRI_hs-Secretome_pDEST": { + "properties": { + "id": { + "type": "string" + }, + "relationship": { + "type": "string" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "interpro": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "description": { + "type": "string" + }, + "short_desc": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "ipi": { + "items": { + "type": "string" + }, + "type": "array" + }, + "alias": { + "items": { + "type": "string" + }, + "type": "array" + }, + "generif": { + "items": { + "properties": { + "pubmed": { + "type": "string" + }, + "text": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "uniprot": { + "properties": { + "Swiss-Prot": { + "type": "string" + }, + "TrEMBL": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "description": "Successful response", + "responseDataType": [ + { + "elementPath": "ec", + "datatype": "http://identifiers.org/ec-code/" + }, + { + "elementPath": "ensembl.gene", + "datatype": "http://identifiers.org/ensembl/" + }, + { + "elementPath": "ensembl.translation.protein", + "datatype": "http://identifiers.org/ensembl/" + }, + { + "elementPath": "ensembl.translation.rna", + "datatype": "http://identifiers.org/ensembl/" + }, + { + "elementPath": "entrezgene", + "datatype": "http://identifiers.org/ncbigene/" + }, + { + "elementPath": "generif.pubmed", + "datatype": "http://identifiers.org/pubmed/" + }, + { + "elementPath": "go.bp.evidence", + "datatype": "http://identifiers.org/eco/" + }, + { + "elementPath": "go.bp.id", + "datatype": "http://identifiers.org/go/" + }, + { + "elementPath": "go.bp.pubmed", + "datatype": "http://identifiers.org/pubmed/" + }, + { + "elementPath": "go.bp.term", + "datatype": "http://identifiers.org/go/" + }, + { + "elementPath": "go.cc.evidence", + "datatype": "http://identifiers.org/eco/" + }, + { + "elementPath": "go.cc.id", + "datatype": "http://identifiers.org/go/" + }, + { + "elementPath": "go.cc.pubmed", + "datatype": "http://identifiers.org/pubmed/" + }, + { + "elementPath": "go.cc.term", + "datatype": "http://identifiers.org/go/" + }, + { + "elementPath": "go.mf.evidence", + "datatype": "http://identifiers.org/eco/" + }, + { + "elementPath": "go.mf.id", + "datatype": "http://identifiers.org/go/" + }, + { + "elementPath": "go.mf.pubmed", + "datatype": "http://identifiers.org/pubmed/" + }, + { + "elementPath": "go.mf.qualifier", + "datatype": "http://identifiers.org/go/" + }, + { + "elementPath": "go.mf.term", + "datatype": "http://identifiers.org/go/" + }, + { + "elementPath": "hgnc", + "datatype": "http://identifiers.org/hgnc/" + }, + { + "elementPath": "homologene.id", + "datatype": "http://identifiers.org/homologene/" + }, + { + "elementPath": "interpro.desc", + "datatype": "http://identifiers.org/interpro/" + }, + { + "elementPath": "interpro.id", + "datatype": "http://identifiers.org/interpro/" + }, + { + "elementPath": "interpro.short_desc", + "datatype": "http://identifiers.org/interpro/" + }, + { + "elementPath": "mim", + "datatype": "http://identifiers.org/omim/" + }, + { + "elementPath": "pathway.biocarta.id", + "datatype": "http://identifiers.org/biocarta.pathway/" + }, + { + "elementPath": "pathway.biocarta.name", + "datatype": "http://identifiers.org/biocarta.pathway/" + }, + { + "elementPath": "pathway.kegg.id", + "datatype": "http://identifiers.org/kegg.pathway/" + }, + { + "elementPath": "pathway.kegg.name", + "datatype": "http://identifiers.org/kegg.pathway/" + }, + { + "elementPath": "pathway.pid.id", + "datatype": "http://identifiers.org/pid.pathway/" + }, + { + "elementPath": "pathway.pid.name", + "datatype": "http://identifiers.org/pid.pathway/" + }, + { + "elementPath": "pathway.reactome.id", + "datatype": "http://identifiers.org/reactome/" + }, + { + "elementPath": "pathway.reactome.name", + "datatype": "http://identifiers.org/reactome/" + }, + { + "elementPath": "pathway.wikipathways.id", + "datatype": "http://identifiers.org/wikipathways/" + }, + { + "elementPath": "pathway.wikipathways.name", + "datatype": "http://identifiers.org/wikipathways/" + }, + { + "elementPath": "pfam", + "datatype": "http://identifiers.org/pfam/" + }, + { + "elementPath": "pharmgkb", + "datatype": "http://identifiers.org/pharmgkb.pathways/" + }, + { + "elementPath": "prosite", + "datatype": "http://identifiers.org/prosite/" + }, + { + "elementPath": "refseq.translation.protein", + "datatype": "http://identifiers.org/refseq/" + }, + { + "elementPath": "refseq.translation.rna", + "datatype": "http://identifiers.org/refseq/" + }, + { + "elementPath": "taxid", + "datatype": "http://identifiers.org/taxonomy/" + }, + { + "elementPath": "uniprot.swiss-prot", + "datatype": "http://identifiers.org/uniprot/" + }, + { + "elementPath": "wikipedia.url_stub", + "datatype": "http://identifiers.org/wikipedia.en/" + } + ] + } + } + } + }, + "/gene": { + "post": { + "tags": [ + "gene" + ], + "parameters": [ + { + "name": "ids", + "in": "query", + "description": "multiple geneids seperated by comma, e.g., \"ids=1017,1018\" or \"ids=695,ENSG00000123374\". Note that currently we only take the input ids up to 1000 maximum, the rest will be omitted.", + "required": true, + "type": "string" + }, + { + "name": "fields", + "in": "query", + "description": "a comma-separated fields to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", + "required": false, + "type": "string" + }, + { + "name": "species", + "in": "query", + "description": "Optional, can be used to limit the gene hits from given species. You can use \"common names\" for nine common species (human, mouse, rat, fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other species, you can provide their taxonomy ids. Multiple species can be passed using comma as a separator. Default all.", + "required": false, + "type": "string" + }, + { + "name": "dotfield", + "in": "query", + "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default true.", + "required": false, + "type": "string" + }, + { + "name": "email", + "in": "query", + "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", + "required": false, + "type": "string" + } + ], + "description": "Make gene queries in batch for a list of Entrez or Ensembl gene ids.\n", + "operationId": "getGenes", + "responses": { + "200": { + "schema": { + "items": { + "properties": { + "name": { + "type": "string" + }, + "entrezgene": { + "type": "integer" + }, + "symbol": { + "type": "string" + }, + "taxid": { + "type": "integer" + }, + "query": { + "type": "string" + }, + "_id": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "description": "Successful response" + } + } + } + } + } +} From 7ca1d432665b866cfea98d5b3de8128c4704ded3 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sun, 16 Jul 2017 16:01:48 +0200 Subject: [PATCH 040/104] Update 3.0.md external resource object added --- versions/3.0.md | 40 ++++++++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 77b77f873e..ae7f4a0d17 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -43,6 +43,7 @@ Additional utilities, such as testing tools, can also use the files. - [Path Item Object](#pathItemObject) - [Operation Object](#operationObject) - [External Documentation Object](#externalDocumentationObject) + - [External Resource Object](#externalDocumentationObject) - [Parameter Object](#parameterObject) - [Request Body Object](#requestBodyObject) - [Media Type Object](#mediaTypeObject) @@ -201,6 +202,7 @@ Field Name | Type | Description security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. +externalResources | [External Resource Object](#externalResourceObject) | Additional external resources. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1006,14 +1008,6 @@ Field Name | Type | Description This object can be extended with [Specification Extensions](#specificationExtensions). -##### smartAPI Fields - -Field Name | Type | Description ----|:---:|--- -x-type | `enum` | **REQUIRED** values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` - - - ##### External Documentation Object Example @@ -1028,12 +1022,30 @@ Field Name | Type | Description - description: Find more info here url: https://example.com type: website -- x-type: api documentation - url: http://example.org/api/docs -- x-type: publication - url: https://doi.org/10.1093/nar/gks1114 -- x-type: social media - url: http://twitter.com/mypetstore +``` + +#### External Resource Object + +Allows referencing external resources for extended documentation. + +##### smartAPI Fields + +Field Name | Type | Description +---|:---:|--- +x-url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. +x-type | `enum` | **REQUIRED** values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` +x-description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. + +##### External Resource Object Example + +```yaml +- x-url: http://example.org/api/docs + x-type: api documentation +- x-url: https://doi.org/10.1093/nar/gks1114 + x-type: publication + x-description: "BioGPS and MyGene.info: organizing online, gene-centric information" +- x-url: http://twitter.com/mygeneinfo + x-type: social media ``` #### Parameter Object From c8fb8f4af002e75feb043f19745bcdf9e1088976 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sun, 16 Jul 2017 16:03:09 +0200 Subject: [PATCH 041/104] Update 3.0.md links fixed --- versions/3.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index ae7f4a0d17..bc5eea9899 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -43,7 +43,7 @@ Additional utilities, such as testing tools, can also use the files. - [Path Item Object](#pathItemObject) - [Operation Object](#operationObject) - [External Documentation Object](#externalDocumentationObject) - - [External Resource Object](#externalDocumentationObject) + - [External Resource Object](#externalResourceObject) - [Parameter Object](#parameterObject) - [Request Body Object](#requestBodyObject) - [Media Type Object](#mediaTypeObject) @@ -1024,7 +1024,7 @@ This object can be extended with [Specification Extensions](#specificationExtens type: website ``` -#### External Resource Object +#### External Resource Object [smartAPI extension] Allows referencing external resources for extended documentation. @@ -1036,7 +1036,7 @@ Field Name | Type | Description x-type | `enum` | **REQUIRED** values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` x-description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -##### External Resource Object Example +##### External Resource Object smartAPI Example ```yaml - x-url: http://example.org/api/docs From d717630df6c23af392f579de9cab82cce8d34bd1 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Sun, 16 Jul 2017 16:40:24 +0200 Subject: [PATCH 042/104] Update smartAPI_spec_v3 example updated --- versions/smartAPI_spec_v3 | 197 +++++++++++++++++++------------------- 1 file changed, 99 insertions(+), 98 deletions(-) diff --git a/versions/smartAPI_spec_v3 b/versions/smartAPI_spec_v3 index 3a4b2d9466..459b5873e0 100644 --- a/versions/smartAPI_spec_v3 +++ b/versions/smartAPI_spec_v3 @@ -1,5 +1,6 @@ { "swagger": "2.0", + "openapi": "string", "info": { "version": "3.0.0.2", "title": "MyGene.info API", @@ -15,23 +16,23 @@ "x-maturity": "production", "x-implementationLanguage": "python" }, - "externalDocs": [ - { - "description": "Find more info here", - "url": "https://example.com", - "x-type": "website" - }, + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + }, + "x-externalResource": [ { - "x-type": "api documentation", - "url": "http://docs.mygene.info/en/latest/" + "x-url": "http://example.org/api/docs", + "x-type": "api documentation" }, { + "x-url": "https://doi.org/10.1093/nar/gks1114", "x-type": "publication", - "url": "https://doi.org/10.1093/nar/gks1114" + "x-description": "BioGPS and MyGene.info: organizing online, gene-centric information" }, { - "x-type": "social media", - "url": "http://twitter.com/mygeneinfo" + "x-url": "http://twitter.com/mygeneinfo", + "x-type": "social media" } ], "server": { @@ -1057,178 +1058,178 @@ "type": "object" }, "description": "Successful response", - "responseDataType": [ + "responseValueType": [ { - "elementPath": "ec", - "datatype": "http://identifiers.org/ec-code/" + "path": "ec", + "valueType": "http://identifiers.org/ec-code/" }, { - "elementPath": "ensembl.gene", - "datatype": "http://identifiers.org/ensembl/" + "path": "ensembl.gene", + "valueType": "http://identifiers.org/ensembl/" }, { - "elementPath": "ensembl.translation.protein", - "datatype": "http://identifiers.org/ensembl/" + "path": "ensembl.translation.protein", + "valueType": "http://identifiers.org/ensembl/" }, { - "elementPath": "ensembl.translation.rna", - "datatype": "http://identifiers.org/ensembl/" + "path": "ensembl.translation.rna", + "valueType": "http://identifiers.org/ensembl/" }, { - "elementPath": "entrezgene", - "datatype": "http://identifiers.org/ncbigene/" + "path": "entrezgene", + "valueType": "http://identifiers.org/ncbigene/" }, { - "elementPath": "generif.pubmed", - "datatype": "http://identifiers.org/pubmed/" + "path": "generif.pubmed", + "valueType": "http://identifiers.org/pubmed/" }, { - "elementPath": "go.bp.evidence", - "datatype": "http://identifiers.org/eco/" + "path": "go.bp.evidence", + "valueType": "http://identifiers.org/eco/" }, { - "elementPath": "go.bp.id", - "datatype": "http://identifiers.org/go/" + "path": "go.bp.id", + "valueType": "http://identifiers.org/go/" }, { - "elementPath": "go.bp.pubmed", - "datatype": "http://identifiers.org/pubmed/" + "path": "go.bp.pubmed", + "valueType": "http://identifiers.org/pubmed/" }, { - "elementPath": "go.bp.term", - "datatype": "http://identifiers.org/go/" + "path": "go.bp.term", + "valueType": "http://identifiers.org/go/" }, { - "elementPath": "go.cc.evidence", - "datatype": "http://identifiers.org/eco/" + "path": "go.cc.evidence", + "valueType": "http://identifiers.org/eco/" }, { - "elementPath": "go.cc.id", - "datatype": "http://identifiers.org/go/" + "path": "go.cc.id", + "valueType": "http://identifiers.org/go/" }, { - "elementPath": "go.cc.pubmed", - "datatype": "http://identifiers.org/pubmed/" + "path": "go.cc.pubmed", + "valueType": "http://identifiers.org/pubmed/" }, { - "elementPath": "go.cc.term", - "datatype": "http://identifiers.org/go/" + "path": "go.cc.term", + "valueType": "http://identifiers.org/go/" }, { - "elementPath": "go.mf.evidence", - "datatype": "http://identifiers.org/eco/" + "path": "go.mf.evidence", + "valueType": "http://identifiers.org/eco/" }, { - "elementPath": "go.mf.id", - "datatype": "http://identifiers.org/go/" + "path": "go.mf.id", + "valueType": "http://identifiers.org/go/" }, { - "elementPath": "go.mf.pubmed", - "datatype": "http://identifiers.org/pubmed/" + "path": "go.mf.pubmed", + "valueType": "http://identifiers.org/pubmed/" }, { - "elementPath": "go.mf.qualifier", - "datatype": "http://identifiers.org/go/" + "path": "go.mf.qualifier", + "valueType": "http://identifiers.org/go/" }, { - "elementPath": "go.mf.term", - "datatype": "http://identifiers.org/go/" + "path": "go.mf.term", + "valueType": "http://identifiers.org/go/" }, { - "elementPath": "hgnc", - "datatype": "http://identifiers.org/hgnc/" + "path": "hgnc", + "valueType": "http://identifiers.org/hgnc/" }, { - "elementPath": "homologene.id", - "datatype": "http://identifiers.org/homologene/" + "path": "homologene.id", + "valueType": "http://identifiers.org/homologene/" }, { - "elementPath": "interpro.desc", - "datatype": "http://identifiers.org/interpro/" + "path": "interpro.desc", + "valueType": "http://identifiers.org/interpro/" }, { - "elementPath": "interpro.id", - "datatype": "http://identifiers.org/interpro/" + "path": "interpro.id", + "valueType": "http://identifiers.org/interpro/" }, { - "elementPath": "interpro.short_desc", - "datatype": "http://identifiers.org/interpro/" + "path": "interpro.short_desc", + "valueType": "http://identifiers.org/interpro/" }, { - "elementPath": "mim", - "datatype": "http://identifiers.org/omim/" + "path": "mim", + "valueType": "http://identifiers.org/omim/" }, { - "elementPath": "pathway.biocarta.id", - "datatype": "http://identifiers.org/biocarta.pathway/" + "path": "pathway.biocarta.id", + "valueType": "http://identifiers.org/biocarta.pathway/" }, { - "elementPath": "pathway.biocarta.name", - "datatype": "http://identifiers.org/biocarta.pathway/" + "path": "pathway.biocarta.name", + "valueType": "http://identifiers.org/biocarta.pathway/" }, { - "elementPath": "pathway.kegg.id", - "datatype": "http://identifiers.org/kegg.pathway/" + "path": "pathway.kegg.id", + "valueType": "http://identifiers.org/kegg.pathway/" }, { - "elementPath": "pathway.kegg.name", - "datatype": "http://identifiers.org/kegg.pathway/" + "path": "pathway.kegg.name", + "valueType": "http://identifiers.org/kegg.pathway/" }, { - "elementPath": "pathway.pid.id", - "datatype": "http://identifiers.org/pid.pathway/" + "path": "pathway.pid.id", + "valueType": "http://identifiers.org/pid.pathway/" }, { - "elementPath": "pathway.pid.name", - "datatype": "http://identifiers.org/pid.pathway/" + "path": "pathway.pid.name", + "valueType": "http://identifiers.org/pid.pathway/" }, { - "elementPath": "pathway.reactome.id", - "datatype": "http://identifiers.org/reactome/" + "path": "pathway.reactome.id", + "valueType": "http://identifiers.org/reactome/" }, { - "elementPath": "pathway.reactome.name", - "datatype": "http://identifiers.org/reactome/" + "path": "pathway.reactome.name", + "valueType": "http://identifiers.org/reactome/" }, { - "elementPath": "pathway.wikipathways.id", - "datatype": "http://identifiers.org/wikipathways/" + "path": "pathway.wikipathways.id", + "valueType": "http://identifiers.org/wikipathways/" }, { - "elementPath": "pathway.wikipathways.name", - "datatype": "http://identifiers.org/wikipathways/" + "path": "pathway.wikipathways.name", + "valueType": "http://identifiers.org/wikipathways/" }, { - "elementPath": "pfam", - "datatype": "http://identifiers.org/pfam/" + "path": "pfam", + "valueType": "http://identifiers.org/pfam/" }, { - "elementPath": "pharmgkb", - "datatype": "http://identifiers.org/pharmgkb.pathways/" + "path": "pharmgkb", + "valueType": "http://identifiers.org/pharmgkb.pathways/" }, { - "elementPath": "prosite", - "datatype": "http://identifiers.org/prosite/" + "path": "prosite", + "valueType": "http://identifiers.org/prosite/" }, { - "elementPath": "refseq.translation.protein", - "datatype": "http://identifiers.org/refseq/" + "path": "refseq.translation.protein", + "valueType": "http://identifiers.org/refseq/" }, { - "elementPath": "refseq.translation.rna", - "datatype": "http://identifiers.org/refseq/" + "path": "refseq.translation.rna", + "valueType": "http://identifiers.org/refseq/" }, { - "elementPath": "taxid", - "datatype": "http://identifiers.org/taxonomy/" + "path": "taxid", + "valueType": "http://identifiers.org/taxonomy/" }, { - "elementPath": "uniprot.swiss-prot", - "datatype": "http://identifiers.org/uniprot/" + "path": "uniprot.swiss-prot", + "valueType": "http://identifiers.org/uniprot/" }, { - "elementPath": "wikipedia.url_stub", - "datatype": "http://identifiers.org/wikipedia.en/" + "path": "wikipedia.url_stub", + "valueType": "http://identifiers.org/wikipedia.en/" } ] } From a4ed682e7c4e2fff5b3b46b19c1c78ed56b1679a Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Mon, 17 Jul 2017 11:42:52 +0200 Subject: [PATCH 043/104] Update smartAPI_spec_v3 updated servers --- versions/smartAPI_spec_v3 | 2536 ++++++++++++++++++------------------- 1 file changed, 1267 insertions(+), 1269 deletions(-) diff --git a/versions/smartAPI_spec_v3 b/versions/smartAPI_spec_v3 index 459b5873e0..eb770b8394 100644 --- a/versions/smartAPI_spec_v3 +++ b/versions/smartAPI_spec_v3 @@ -1,1317 +1,1315 @@ { - "swagger": "2.0", - "openapi": "string", - "info": { - "version": "3.0.0.2", - "title": "MyGene.info API", - "description": "Documentation of the MyGene.info Gene Query web services. Learn more about [MyGene.info](http://mygene.info/)", - "termsOfService": "http://example.com/terms/", - "contact": { - "name": "Chunlei Wu", - "x-role": "responsibleDeveloper", - "email": "help@mygene.info", - "x-id": "http://orcid.org/0000-0002-2629-6124" + "swagger": "2.0", + "openapi": "string", + "info": { + "version": "3.0.0.2", + "title": "MyGene.info API", + "description": "Documentation of the MyGene.info Gene Query web services. Learn more about [MyGene.info](http://mygene.info/)", + "termsOfService": "http://example.com/terms/", + "contact": { + "name": "Chunlei Wu", + "x-role": "responsibleDeveloper", + "email": "help@mygene.info", + "x-id": "http://orcid.org/0000-0002-2629-6124" + }, + "x-accessRestriction": "none", + "x-maturity": "production", + "x-implementationLanguage": "python" }, - "x-accessRestriction": "none", - "x-maturity": "production", - "x-implementationLanguage": "python" - }, - "externalDocs": { - "description": "Find more info here", - "url": "https://example.com" - }, - "x-externalResource": [ - { - "x-url": "http://example.org/api/docs", - "x-type": "api documentation" + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" }, - { - "x-url": "https://doi.org/10.1093/nar/gks1114", - "x-type": "publication", - "x-description": "BioGPS and MyGene.info: organizing online, gene-centric information" - }, - { - "x-url": "http://twitter.com/mygeneinfo", - "x-type": "social media" - } - ], - "server": { - "url": "https://development.gigantic-server.com/v1", - "description": "Development server", - "x-location": "California, USA" - }, - "host": "mygene.info", - "basePath": "/v3", - "schemes": [ - "http", - "https" - ], - "produces": [ - "application/json" - ], - "tags": [ - { - "name": "query", - "description": "Query for gene information" - }, - { - "name": "gene", - "description": "Gene annotation information" - }, - { - "name": "metadata", - "description": "Metadata about the data available from MyGene.info." - }, - { - "name": "http://purl.bioontology.org/ontology/MESH/D005796", - "description": "Genes" - } - ], - "paths": { - "/query": { - "get": { - "tags": [ - "query" - ], - "summary": "Makes gene query and returns matching gene list.", - "x-accessRestriction": "free", - "parameters": [ - { - "name": "q", - "in": "query", - "description": "Query string. Examples \"CDK2\", \"NM_052827\", \"204639_at\". The detailed query syntax can be found at http://docs.mygene.info/en/latest/doc/query_service.html", - "required": true, - "schema": { - "type": "string" - }, - "x-parameterType": "InputParameter", - "x-valueType": [ - "http://identifiers.org/hgnc.symbol", - "http://identifiers.org/refseq", - "http://identifiers.org/unigene", - "http://identifiers.org/uniprot", - "http://identifiers.org/pdb", - "http://identifiers.org/prosite", - "http://identifiers.org/pfam", - "http://identifiers.org/interpro", - "http://identifiers.org/hgnc", - "http://identifiers.org/mgi", - "http://identifiers.org/rgd", - "http://identifiers.org/flybase", - "http://identifiers.org/wormbase", - "http://identifiers.org/zfin", - "http://identifiers.org/tair.gene", - "http://identifiers.org/xenbase", - "http://identifiers.org/mirbase" - ], - "x-defaultValue": "CDK2", - "x-exampleValue": "CDK2" - }, - { - "name": "fields", - "in": "query", - "description": "A comma-separated field to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", - "required": false, - "type": "string" - }, - { - "name": "species", - "in": "query", - "description": "can be used to limit the gene hits from given species. You can use \"common names\" for nine common species (human, mouse, rat, fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other species, you can provide their taxonomy ids. Multiple species can be passed using comma as a separator. Passing “all” will query against all available species. Default human,mouse,rat.", - "required": false, - "type": "string" - }, - { - "name": "size", - "in": "query", - "description": "the maximum number of matching gene hits to return (with a cap of 1000 at the moment). Default 10.", - "required": false, - "type": "integer" - }, - { - "name": "from", - "in": "query", - "description": "the number of matching gene hits to skip, starting from 0. Combining with \"size\" parameter, this can be useful for paging. Default 0.", - "required": false, - "type": "integer" - }, - { - "name": "sort", - "in": "query", - "description": "comma-separated fields to sort on. Prefix with \"-\" for descending order, otherwise in ascending order. Sort by matching scores in decending order.", - "required": false, - "type": "string" - }, - { - "name": "facets", - "in": "query", - "description": "a single field or comma-separated fields to return facets, for example, “facets=taxid”, “facets=taxid,type_of_gene”.", - "required": false, - "type": "string" - }, - { - "name": "species_facet_filter", - "in": "query", - "description": "relevant when faceting on species (i.e., “facets=taxid” are passed). It’s used to pass species filter without changing the scope of faceting, so that the returned facet counts won’t change. Either species name or taxonomy id can be used, just like “species” parameter above.", - "required": false, - "type": "string" - }, - { - "name": "entrezonly", - "in": "query", - "description": "when passed as “true” or “1”, the query returns only the hits with valid Entrez gene ids. Default: false", - "required": false, - "type": "boolean" - }, - { - "name": "ensemblonly", - "in": "query", - "description": "when passed as “true” or “1”, the query returns only the hits with valid Ensembl gene ids. Default: false.", - "required": false, - "type": "boolean" - }, - { - "name": "callback", - "in": "query", - "description": "you can pass a \"callback\" parameter to make a JSONP call.", - "required": false, - "type": "string" - }, - { - "name": "dotfield", - "in": "query", - "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default: true", - "type": "boolean" - }, - { - "name": "filter", - "in": "query", - "description": "alias for \"fields\" parameter.", - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "alias for \"size\" parameter.", - "type": "integer" - }, - { - "name": "skip", - "in": "query", - "description": "alias for \"from\" parameter.", - "type": "integer" - }, - { - "name": "email", - "in": "query", - "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", - "type": "string" - } - ], - "description": "Make gene query and return matching gene list. Support JSONP and CORS as well.", - "operationId": "queryGene", - "responses": { - "200": { - "schema": { - "type": "object", - "properties": { - "hits": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "entrezgene": { - "type": "integer" - }, - "taxid": { - "type": "integer" - }, - "symbol": { - "type": "string" - }, - "_id": { - "type": "integer" - } - } - } - }, - "max_score": { - "type": "integer" - }, - "took": { - "type": "integer" - }, - "total": { - "type": "integer" - } - } - }, - "description": "Successful response" - } + "x-externalResource": [ + { + "x-url": "http://example.org/api/docs", + "x-type": "api documentation" + }, + { + "x-url": "https://doi.org/10.1093/nar/gks1114", + "x-type": "publication", + "x-description": "BioGPS and MyGene.info: organizing online, gene-centric information" + }, + { + "x-url": "http://twitter.com/mygeneinfo", + "x-type": "social media" } - } - }, - "/metadata": { - "get": { - "tags": [ - "metadata" - ], - "parameters": [ - { - "name": "callback", - "in": "query", - "description": "you can pass a \"callback\" parameter to make a JSONP call.", - "required": false, - "type": "string" - } - ], - "description": "Get metadata about the data available from MyGene.info\n", - "operationId": "getMetadata", - "responses": { - "200": { - "schema": { - "properties": { - "app_revision": { - "type": "string" - }, - "genome_assembly": { - "properties": { - "fruitfly": { - "type": "string" - }, - "zebrafish": { - "type": "string" - }, - "nematode": { - "type": "string" - }, - "human": { - "type": "string" - }, - "rat": { - "type": "string" - }, - "pig": { - "type": "string" - }, - "mouse": { - "type": "string" - }, - "frog": { - "type": "string" - } - }, - "type": "object" - }, - "source": { - "type": "string" - }, - "taxonomy": { - "properties": { - "fruitfly": { - "type": "integer" - }, - "thale-cress\"": { - "type": "integer" - }, - "zebrafish": { - "type": "integer" - }, - "nematode": { - "type": "integer" - }, - "human": { - "type": "integer" - }, - "rat": { - "type": "integer" - }, - "pig": { - "type": "integer" - }, - "mouse": { - "type": "integer" - }, - "frog": { - "type": "integer" - } - }, - "type": "object" - }, - "timestamp": { - "type": "string" - }, - "src_version": { - "properties": { - "netaffy": { - "type": "string" - }, - "entrez": { - "type": "integer" - }, - "pharmgkb": { - "type": "integer" - }, - "ucsc": { - "type": "integer" - }, - "cpdb": { - "type": "integer" - }, - "refseq": { - "type": "integer" - }, - "ensembl": { - "type": "integer" - }, - "uniprot": { - "type": "integer" - } - }, - "type": "object" - }, - "stats": { - "properties": { - "total_ensembl_genes_mapped_to_entrez": { - "type": "integer" - }, - "total_entrez_genes": { - "type": "integer" - }, - "total_ensembl_only_genes": { - "type": "integer" - }, - "total_ensembl_genes": { - "type": "integer" - }, - "total_genes": { - "type": "integer" - }, - "total_species": { - "type": "integer" - } - }, - "type": "object" - }, - "available_fields": { - "type": "string" + ], + "servers": [ + { + "url": "https://development.gigantic-server.com/v", + "description": "Development server", + "x-location": "California, USA", + "variables": { + "basePath": { + "default": "/v3" } - }, - "type": "object" - }, - "description": "Successful response" - } + } } - } - }, - "/gene/{geneid}": { - "get": { - "tags": [ - "gene" - ], - "parameters": [ - { - "name": "geneid", - "in": "path", - "description": "Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired Entrez Gene id works too if it is replaced by a new one, e.g., 245794", - "required": true, - "type": "string", - "x-parameterType": "InputParameter", - "x-valueType": [ - "http://identifiers.org/ncbigene", - "http://identifiers.org/ensembl" - ], - "x-defaultValue": null, - "x-exampleValue": "1017" - }, - { - "name": "fields", - "in": "query", - "description": "a comma-separated fields to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", - "required": false, - "type": "string" - }, - { - "name": "callback", - "in": "query", - "description": "you can pass a \"callback\" parameter to make a JSONP call.", - "required": false, - "type": "string" - }, - { - "name": "filter", - "in": "query", - "description": "alias for \"fields\" parameter.", - "required": false, - "type": "string" - }, - { - "name": "dotfield", - "in": "query", - "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default true.", - "required": false, - "type": "string" - }, - { - "name": "email", - "in": "query", - "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", - "required": false, - "type": "string" - } - ], - "description": "Retrieve gene annotation based on Entrez or Ensembl gene id, support\nJSONP and CORS as well.\n", - "operationId": "getAnnotation", - "responses": { - "200": { - "schema": { - "properties": { - "reporter": { - "properties": { - "HTA-2_0": { - "type": "string" - }, - "HG-U133_Plus_2": { - "items": { + ], + "tags": [ + { + "name": "query", + "description": "Query for gene information" + }, + { + "name": "gene", + "description": "Gene annotation information" + }, + { + "name": "metadata", + "description": "Metadata about the data available from MyGene.info." + }, + { + "name": "http://purl.bioontology.org/ontology/MESH/D005796", + "description": "Genes" + } + ], + "paths": { + "/query": { + "get": { + "tags": [ + "query" + ], + "summary": "Makes gene query and returns matching gene list.", + "x-accessRestriction": "free", + "parameters": [ + { + "name": "q", + "in": "query", + "description": "Query string. Examples \"CDK2\", \"NM_052827\", \"204639_at\". The detailed query syntax can be found at http://docs.mygene.info/en/latest/doc/query_service.html", + "required": true, + "schema": { + "type": "string" + }, + "x-parameterType": "InputParameter", + "x-valueType": [ + "http://identifiers.org/hgnc.symbol", + "http://identifiers.org/refseq", + "http://identifiers.org/unigene", + "http://identifiers.org/uniprot", + "http://identifiers.org/pdb", + "http://identifiers.org/prosite", + "http://identifiers.org/pfam", + "http://identifiers.org/interpro", + "http://identifiers.org/hgnc", + "http://identifiers.org/mgi", + "http://identifiers.org/rgd", + "http://identifiers.org/flybase", + "http://identifiers.org/wormbase", + "http://identifiers.org/zfin", + "http://identifiers.org/tair.gene", + "http://identifiers.org/xenbase", + "http://identifiers.org/mirbase" + ], + "x-defaultValue": "CDK2", + "x-exampleValue": "CDK2" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated field to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", + "required": false, "type": "string" - }, - "type": "array" }, - "HuEx-1_0": { - "type": "integer" - }, - "HuGene-1_1": { - "type": "integer" - }, - "HuGene-2_1": { - "type": "integer" - }, - "HG-U95Av2": { - "items": { + { + "name": "species", + "in": "query", + "description": "can be used to limit the gene hits from given species. You can use \"common names\" for nine common species (human, mouse, rat, fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other species, you can provide their taxonomy ids. Multiple species can be passed using comma as a separator. Passing “all” will query against all available species. Default human,mouse,rat.", + "required": false, "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "prosite": { - "type": "string" - }, - "summary": { - "type": "string" - }, - "exons": { - "type": "object" - }, - "symbol": { - "type": "string" - }, - "genomic_pos": { - "properties": { - "chr": { - "type": "integer" - }, - "strand": { - "type": "integer" }, - "end": { - "type": "integer" - }, - "start": { - "type": "integer" - } - }, - "type": "object" - }, - "homologene": { - "properties": { - "id": { - "type": "integer" - }, - "genes": { - "items": { + { + "name": "size", + "in": "query", + "description": "the maximum number of matching gene hits to return (with a cap of 1000 at the moment). Default 10.", + "required": false, "type": "integer" - }, - "type": "array" - } - }, - "type": "object" - }, - "taxid": { - "type": "integer" - }, - "pathway": { - "properties": { - "kegg": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "wikipathways": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "pid": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" }, - "netpath": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "reactome": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" + { + "name": "from", + "in": "query", + "description": "the number of matching gene hits to skip, starting from 0. Combining with \"size\" parameter, this can be useful for paging. Default 0.", + "required": false, + "type": "integer" }, - "biocarta": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - } - }, - "type": "object" - }, - "Vega": { - "type": "string" - }, - "entrezgene": { - "type": "string" - }, - "pfam": { - "type": "string" - }, - "ec": { - "type": "string" - }, - "refseq": { - "properties": { - "genomic": { - "items": { + { + "name": "sort", + "in": "query", + "description": "comma-separated fields to sort on. Prefix with \"-\" for descending order, otherwise in ascending order. Sort by matching scores in decending order.", + "required": false, "type": "string" - }, - "type": "array" }, - "rna": { - "items": { + { + "name": "facets", + "in": "query", + "description": "a single field or comma-separated fields to return facets, for example, “facets=taxid”, “facets=taxid,type_of_gene”.", + "required": false, "type": "string" - }, - "type": "array" }, - "protein": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "wikipedia": { - "properties": { - "url_stub": { - "type": "string" - } - }, - "type": "object" - }, - "ensembl": { - "properties": { - "transcript": { - "items": { + { + "name": "species_facet_filter", + "in": "query", + "description": "relevant when faceting on species (i.e., “facets=taxid” are passed). It’s used to pass species filter without changing the scope of faceting, so that the returned facet counts won’t change. Either species name or taxonomy id can be used, just like “species” parameter above.", + "required": false, "type": "string" - }, - "type": "array" }, - "gene": { - "type": "string" - } - }, - "type": "object" - }, - "accession": { - "properties": { - "genomic": { - "items": { + { + "name": "entrezonly", + "in": "query", + "description": "when passed as “true” or “1”, the query returns only the hits with valid Entrez gene ids. Default: false", + "required": false, + "type": "boolean" + }, + { + "name": "ensemblonly", + "in": "query", + "description": "when passed as “true” or “1”, the query returns only the hits with valid Ensembl gene ids. Default: false.", + "required": false, + "type": "boolean" + }, + { + "name": "callback", + "in": "query", + "description": "you can pass a \"callback\" parameter to make a JSONP call.", + "required": false, "type": "string" - }, - "type": "array" }, - "rna": { - "items": { - "type": "string" - }, - "type": "array" + { + "name": "dotfield", + "in": "query", + "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default: true", + "type": "boolean" }, - "protein": { - "items": { + { + "name": "filter", + "in": "query", + "description": "alias for \"fields\" parameter.", "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "MIM": { - "type": "integer" - }, - "HPRD": { - "type": "integer" - }, - "unigene": { - "items": { - "type": "string" - }, - "type": "array" - }, - "pharmgkb": { - "type": "string" - }, - "genomic_pos_hg19": { - "properties": { - "chr": { - "type": "integer" }, - "strand": { - "type": "integer" + { + "name": "limit", + "in": "query", + "description": "alias for \"size\" parameter.", + "type": "integer" }, - "end": { - "type": "integer" + { + "name": "skip", + "in": "query", + "description": "alias for \"from\" parameter.", + "type": "integer" }, - "start": { - "type": "integer" + { + "name": "email", + "in": "query", + "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", + "type": "string" } - }, - "type": "object" - }, - "HGNC": { - "type": "integer" - }, - "type_of_gene": { - "type": "string" - }, - "pir": { - "type": "string" - }, - "_id": { - "type": "string" - }, - "pdb": { - "items": { - "type": "string" - }, - "type": "array" - }, - "name": { - "type": "string" - }, - "map_location": { - "type": "string" - }, - "go": { - "properties": { - "BP": { - "items": { - "properties": { - "evidence": { - "type": "string" - }, - "id": { - "type": "string" - }, - "term": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "CC": { - "items": { - "properties": { - "evidence": { - "type": "string" - }, - "id": { - "type": "string" - }, - "term": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "MF": { - "items": { - "properties": { - "evidence": { - "type": "string" - }, - "id": { - "type": "string" - }, - "term": { - "type": "string" - } + ], + "description": "Make gene query and return matching gene list. Support JSONP and CORS as well.", + "operationId": "queryGene", + "responses": { + "200": { + "schema": { + "type": "object", + "properties": { + "hits": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "entrezgene": { + "type": "integer" + }, + "taxid": { + "type": "integer" + }, + "symbol": { + "type": "string" + }, + "_id": { + "type": "integer" + } + } + } + }, + "max_score": { + "type": "integer" + }, + "took": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } }, - "type": "object" - }, - "type": "array" + "description": "Successful response" } - }, - "type": "object" - }, - "reagent": { - "properties": { - "GNF_hs_LentiORF-HA-MYC": { - "properties": { - "id": { - "type": "string" - }, - "relationship": { - "type": "string" - } - }, - "type": "object" - }, - "GNF_hs-Origene": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_Qia_hs-genome_v1_siRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_hs_LentiORF-Jred": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "GNF_hs-druggable_siRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_hs-ORFeome1_1_reads": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "Invitrogen_IVTHSSIPKv2": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_hs-druggable_lenti-shRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_mm+hs-MGC": { - "properties": { - "id": { - "type": "string" + } + } + }, + "/metadata": { + "get": { + "tags": [ + "metadata" + ], + "parameters": [ + { + "name": "callback", + "in": "query", + "description": "you can pass a \"callback\" parameter to make a JSONP call.", + "required": false, + "type": "string" + } + ], + "description": "Get metadata about the data available from MyGene.info\n", + "operationId": "getMetadata", + "responses": { + "200": { + "schema": { + "properties": { + "app_revision": { + "type": "string" + }, + "genome_assembly": { + "properties": { + "fruitfly": { + "type": "string" + }, + "zebrafish": { + "type": "string" + }, + "nematode": { + "type": "string" + }, + "human": { + "type": "string" + }, + "rat": { + "type": "string" + }, + "pig": { + "type": "string" + }, + "mouse": { + "type": "string" + }, + "frog": { + "type": "string" + } + }, + "type": "object" + }, + "source": { + "type": "string" + }, + "taxonomy": { + "properties": { + "fruitfly": { + "type": "integer" + }, + "thale-cress\"": { + "type": "integer" + }, + "zebrafish": { + "type": "integer" + }, + "nematode": { + "type": "integer" + }, + "human": { + "type": "integer" + }, + "rat": { + "type": "integer" + }, + "pig": { + "type": "integer" + }, + "mouse": { + "type": "integer" + }, + "frog": { + "type": "integer" + } + }, + "type": "object" + }, + "timestamp": { + "type": "string" + }, + "src_version": { + "properties": { + "netaffy": { + "type": "string" + }, + "entrez": { + "type": "integer" + }, + "pharmgkb": { + "type": "integer" + }, + "ucsc": { + "type": "integer" + }, + "cpdb": { + "type": "integer" + }, + "refseq": { + "type": "integer" + }, + "ensembl": { + "type": "integer" + }, + "uniprot": { + "type": "integer" + } + }, + "type": "object" + }, + "stats": { + "properties": { + "total_ensembl_genes_mapped_to_entrez": { + "type": "integer" + }, + "total_entrez_genes": { + "type": "integer" + }, + "total_ensembl_only_genes": { + "type": "integer" + }, + "total_ensembl_genes": { + "type": "integer" + }, + "total_genes": { + "type": "integer" + }, + "total_species": { + "type": "integer" + } + }, + "type": "object" + }, + "available_fields": { + "type": "string" + } + }, + "type": "object" }, - "relationonship": { - "type": "string" - } - }, - "type": "object" + "description": "Successful response" + } + } + } + }, + "/gene/{geneid}": { + "get": { + "tags": [ + "gene" + ], + "parameters": [ + { + "name": "geneid", + "in": "path", + "description": "Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired Entrez Gene id works too if it is replaced by a new one, e.g., 245794", + "required": true, + "type": "string", + "x-parameterType": "InputParameter", + "x-valueType": [ + "http://identifiers.org/ncbigene", + "http://identifiers.org/ensembl" + ], + "x-defaultValue": null, + "x-exampleValue": "1017" + }, + { + "name": "fields", + "in": "query", + "description": "a comma-separated fields to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", + "required": false, + "type": "string" }, - "GNF_hs-pkinase_IDT-siRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" + { + "name": "callback", + "in": "query", + "description": "you can pass a \"callback\" parameter to make a JSONP call.", + "required": false, + "type": "string" }, - "GNF_hs-druggable_plasmid-shRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" + { + "name": "filter", + "in": "query", + "description": "alias for \"fields\" parameter.", + "required": false, + "type": "string" }, - "NOVART_hs-genome_siRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" + { + "name": "dotfield", + "in": "query", + "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default true.", + "required": false, + "type": "string" }, - "NIBRI_hs-Secretome_pDEST": { - "properties": { - "id": { - "type": "string" + { + "name": "email", + "in": "query", + "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", + "required": false, + "type": "string" + } + ], + "description": "Retrieve gene annotation based on Entrez or Ensembl gene id, support\nJSONP and CORS as well.\n", + "operationId": "getAnnotation", + "responses": { + "200": { + "schema": { + "properties": { + "reporter": { + "properties": { + "HTA-2_0": { + "type": "string" + }, + "HG-U133_Plus_2": { + "items": { + "type": "string" + }, + "type": "array" + }, + "HuEx-1_0": { + "type": "integer" + }, + "HuGene-1_1": { + "type": "integer" + }, + "HuGene-2_1": { + "type": "integer" + }, + "HG-U95Av2": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "prosite": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "exons": { + "type": "object" + }, + "symbol": { + "type": "string" + }, + "genomic_pos": { + "properties": { + "chr": { + "type": "integer" + }, + "strand": { + "type": "integer" + }, + "end": { + "type": "integer" + }, + "start": { + "type": "integer" + } + }, + "type": "object" + }, + "homologene": { + "properties": { + "id": { + "type": "integer" + }, + "genes": { + "items": { + "type": "integer" + }, + "type": "array" + } + }, + "type": "object" + }, + "taxid": { + "type": "integer" + }, + "pathway": { + "properties": { + "kegg": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "wikipathways": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "pid": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "netpath": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "reactome": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "biocarta": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "Vega": { + "type": "string" + }, + "entrezgene": { + "type": "string" + }, + "pfam": { + "type": "string" + }, + "ec": { + "type": "string" + }, + "refseq": { + "properties": { + "genomic": { + "items": { + "type": "string" + }, + "type": "array" + }, + "rna": { + "items": { + "type": "string" + }, + "type": "array" + }, + "protein": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "wikipedia": { + "properties": { + "url_stub": { + "type": "string" + } + }, + "type": "object" + }, + "ensembl": { + "properties": { + "transcript": { + "items": { + "type": "string" + }, + "type": "array" + }, + "gene": { + "type": "string" + } + }, + "type": "object" + }, + "accession": { + "properties": { + "genomic": { + "items": { + "type": "string" + }, + "type": "array" + }, + "rna": { + "items": { + "type": "string" + }, + "type": "array" + }, + "protein": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "MIM": { + "type": "integer" + }, + "HPRD": { + "type": "integer" + }, + "unigene": { + "items": { + "type": "string" + }, + "type": "array" + }, + "pharmgkb": { + "type": "string" + }, + "genomic_pos_hg19": { + "properties": { + "chr": { + "type": "integer" + }, + "strand": { + "type": "integer" + }, + "end": { + "type": "integer" + }, + "start": { + "type": "integer" + } + }, + "type": "object" + }, + "HGNC": { + "type": "integer" + }, + "type_of_gene": { + "type": "string" + }, + "pir": { + "type": "string" + }, + "_id": { + "type": "string" + }, + "pdb": { + "items": { + "type": "string" + }, + "type": "array" + }, + "name": { + "type": "string" + }, + "map_location": { + "type": "string" + }, + "go": { + "properties": { + "BP": { + "items": { + "properties": { + "evidence": { + "type": "string" + }, + "id": { + "type": "string" + }, + "term": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "CC": { + "items": { + "properties": { + "evidence": { + "type": "string" + }, + "id": { + "type": "string" + }, + "term": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "MF": { + "items": { + "properties": { + "evidence": { + "type": "string" + }, + "id": { + "type": "string" + }, + "term": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "reagent": { + "properties": { + "GNF_hs_LentiORF-HA-MYC": { + "properties": { + "id": { + "type": "string" + }, + "relationship": { + "type": "string" + } + }, + "type": "object" + }, + "GNF_hs-Origene": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_Qia_hs-genome_v1_siRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_hs_LentiORF-Jred": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "GNF_hs-druggable_siRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_hs-ORFeome1_1_reads": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "Invitrogen_IVTHSSIPKv2": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_hs-druggable_lenti-shRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_mm+hs-MGC": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "GNF_hs-pkinase_IDT-siRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "GNF_hs-druggable_plasmid-shRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "NOVART_hs-genome_siRNA": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "relationonship": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "NIBRI_hs-Secretome_pDEST": { + "properties": { + "id": { + "type": "string" + }, + "relationship": { + "type": "string" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "interpro": { + "items": { + "properties": { + "id": { + "type": "string" + }, + "description": { + "type": "string" + }, + "short_desc": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "ipi": { + "items": { + "type": "string" + }, + "type": "array" + }, + "alias": { + "items": { + "type": "string" + }, + "type": "array" + }, + "generif": { + "items": { + "properties": { + "pubmed": { + "type": "string" + }, + "text": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "uniprot": { + "properties": { + "Swiss-Prot": { + "type": "string" + }, + "TrEMBL": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "type": "object" }, - "relationship": { - "type": "string" - } - }, - "type": "object" + "description": "Successful response", + "responseValueType": [ + { + "path": "ec", + "valueType": "http://identifiers.org/ec-code/" + }, + { + "path": "ensembl.gene", + "valueType": "http://identifiers.org/ensembl/" + }, + { + "path": "ensembl.translation.protein", + "valueType": "http://identifiers.org/ensembl/" + }, + { + "path": "ensembl.translation.rna", + "valueType": "http://identifiers.org/ensembl/" + }, + { + "path": "entrezgene", + "valueType": "http://identifiers.org/ncbigene/" + }, + { + "path": "generif.pubmed", + "valueType": "http://identifiers.org/pubmed/" + }, + { + "path": "go.bp.evidence", + "valueType": "http://identifiers.org/eco/" + }, + { + "path": "go.bp.id", + "valueType": "http://identifiers.org/go/" + }, + { + "path": "go.bp.pubmed", + "valueType": "http://identifiers.org/pubmed/" + }, + { + "path": "go.bp.term", + "valueType": "http://identifiers.org/go/" + }, + { + "path": "go.cc.evidence", + "valueType": "http://identifiers.org/eco/" + }, + { + "path": "go.cc.id", + "valueType": "http://identifiers.org/go/" + }, + { + "path": "go.cc.pubmed", + "valueType": "http://identifiers.org/pubmed/" + }, + { + "path": "go.cc.term", + "valueType": "http://identifiers.org/go/" + }, + { + "path": "go.mf.evidence", + "valueType": "http://identifiers.org/eco/" + }, + { + "path": "go.mf.id", + "valueType": "http://identifiers.org/go/" + }, + { + "path": "go.mf.pubmed", + "valueType": "http://identifiers.org/pubmed/" + }, + { + "path": "go.mf.qualifier", + "valueType": "http://identifiers.org/go/" + }, + { + "path": "go.mf.term", + "valueType": "http://identifiers.org/go/" + }, + { + "path": "hgnc", + "valueType": "http://identifiers.org/hgnc/" + }, + { + "path": "homologene.id", + "valueType": "http://identifiers.org/homologene/" + }, + { + "path": "interpro.desc", + "valueType": "http://identifiers.org/interpro/" + }, + { + "path": "interpro.id", + "valueType": "http://identifiers.org/interpro/" + }, + { + "path": "interpro.short_desc", + "valueType": "http://identifiers.org/interpro/" + }, + { + "path": "mim", + "valueType": "http://identifiers.org/omim/" + }, + { + "path": "pathway.biocarta.id", + "valueType": "http://identifiers.org/biocarta.pathway/" + }, + { + "path": "pathway.biocarta.name", + "valueType": "http://identifiers.org/biocarta.pathway/" + }, + { + "path": "pathway.kegg.id", + "valueType": "http://identifiers.org/kegg.pathway/" + }, + { + "path": "pathway.kegg.name", + "valueType": "http://identifiers.org/kegg.pathway/" + }, + { + "path": "pathway.pid.id", + "valueType": "http://identifiers.org/pid.pathway/" + }, + { + "path": "pathway.pid.name", + "valueType": "http://identifiers.org/pid.pathway/" + }, + { + "path": "pathway.reactome.id", + "valueType": "http://identifiers.org/reactome/" + }, + { + "path": "pathway.reactome.name", + "valueType": "http://identifiers.org/reactome/" + }, + { + "path": "pathway.wikipathways.id", + "valueType": "http://identifiers.org/wikipathways/" + }, + { + "path": "pathway.wikipathways.name", + "valueType": "http://identifiers.org/wikipathways/" + }, + { + "path": "pfam", + "valueType": "http://identifiers.org/pfam/" + }, + { + "path": "pharmgkb", + "valueType": "http://identifiers.org/pharmgkb.pathways/" + }, + { + "path": "prosite", + "valueType": "http://identifiers.org/prosite/" + }, + { + "path": "refseq.translation.protein", + "valueType": "http://identifiers.org/refseq/" + }, + { + "path": "refseq.translation.rna", + "valueType": "http://identifiers.org/refseq/" + }, + { + "path": "taxid", + "valueType": "http://identifiers.org/taxonomy/" + }, + { + "path": "uniprot.swiss-prot", + "valueType": "http://identifiers.org/uniprot/" + }, + { + "path": "wikipedia.url_stub", + "valueType": "http://identifiers.org/wikipedia.en/" + } + ] } - }, - "type": "object" - }, - "interpro": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "description": { - "type": "string" - }, - "short_desc": { + } + } + }, + "/gene": { + "post": { + "tags": [ + "gene" + ], + "parameters": [ + { + "name": "ids", + "in": "query", + "description": "multiple geneids seperated by comma, e.g., \"ids=1017,1018\" or \"ids=695,ENSG00000123374\". Note that currently we only take the input ids up to 1000 maximum, the rest will be omitted.", + "required": true, "type": "string" - } }, - "type": "object" - }, - "type": "array" - }, - "ipi": { - "items": { - "type": "string" - }, - "type": "array" - }, - "alias": { - "items": { - "type": "string" - }, - "type": "array" - }, - "generif": { - "items": { - "properties": { - "pubmed": { + { + "name": "fields", + "in": "query", + "description": "a comma-separated fields to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", + "required": false, "type": "string" - }, - "text": { + }, + { + "name": "species", + "in": "query", + "description": "Optional, can be used to limit the gene hits from given species. You can use \"common names\" for nine common species (human, mouse, rat, fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other species, you can provide their taxonomy ids. Multiple species can be passed using comma as a separator. Default all.", + "required": false, "type": "string" - } }, - "type": "object" - }, - "type": "array" - }, - "uniprot": { - "properties": { - "Swiss-Prot": { - "type": "string" + { + "name": "dotfield", + "in": "query", + "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default true.", + "required": false, + "type": "string" }, - "TrEMBL": { - "items": { + { + "name": "email", + "in": "query", + "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", + "required": false, "type": "string" - }, - "type": "array" } - }, - "type": "object" + ], + "description": "Make gene queries in batch for a list of Entrez or Ensembl gene ids.\n", + "operationId": "getGenes", + "responses": { + "200": { + "schema": { + "items": { + "properties": { + "name": { + "type": "string" + }, + "entrezgene": { + "type": "integer" + }, + "symbol": { + "type": "string" + }, + "taxid": { + "type": "integer" + }, + "query": { + "type": "string" + }, + "_id": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "description": "Successful response" + } } - }, - "type": "object" - }, - "description": "Successful response", - "responseValueType": [ - { - "path": "ec", - "valueType": "http://identifiers.org/ec-code/" - }, - { - "path": "ensembl.gene", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "ensembl.translation.protein", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "ensembl.translation.rna", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "entrezgene", - "valueType": "http://identifiers.org/ncbigene/" - }, - { - "path": "generif.pubmed", - "valueType": "http://identifiers.org/pubmed/" - }, - { - "path": "go.bp.evidence", - "valueType": "http://identifiers.org/eco/" - }, - { - "path": "go.bp.id", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.bp.pubmed", - "valueType": "http://identifiers.org/pubmed/" - }, - { - "path": "go.bp.term", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.cc.evidence", - "valueType": "http://identifiers.org/eco/" - }, - { - "path": "go.cc.id", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.cc.pubmed", - "valueType": "http://identifiers.org/pubmed/" - }, - { - "path": "go.cc.term", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.mf.evidence", - "valueType": "http://identifiers.org/eco/" - }, - { - "path": "go.mf.id", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.mf.pubmed", - "valueType": "http://identifiers.org/pubmed/" - }, - { - "path": "go.mf.qualifier", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.mf.term", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "hgnc", - "valueType": "http://identifiers.org/hgnc/" - }, - { - "path": "homologene.id", - "valueType": "http://identifiers.org/homologene/" - }, - { - "path": "interpro.desc", - "valueType": "http://identifiers.org/interpro/" - }, - { - "path": "interpro.id", - "valueType": "http://identifiers.org/interpro/" - }, - { - "path": "interpro.short_desc", - "valueType": "http://identifiers.org/interpro/" - }, - { - "path": "mim", - "valueType": "http://identifiers.org/omim/" - }, - { - "path": "pathway.biocarta.id", - "valueType": "http://identifiers.org/biocarta.pathway/" - }, - { - "path": "pathway.biocarta.name", - "valueType": "http://identifiers.org/biocarta.pathway/" - }, - { - "path": "pathway.kegg.id", - "valueType": "http://identifiers.org/kegg.pathway/" - }, - { - "path": "pathway.kegg.name", - "valueType": "http://identifiers.org/kegg.pathway/" - }, - { - "path": "pathway.pid.id", - "valueType": "http://identifiers.org/pid.pathway/" - }, - { - "path": "pathway.pid.name", - "valueType": "http://identifiers.org/pid.pathway/" - }, - { - "path": "pathway.reactome.id", - "valueType": "http://identifiers.org/reactome/" - }, - { - "path": "pathway.reactome.name", - "valueType": "http://identifiers.org/reactome/" - }, - { - "path": "pathway.wikipathways.id", - "valueType": "http://identifiers.org/wikipathways/" - }, - { - "path": "pathway.wikipathways.name", - "valueType": "http://identifiers.org/wikipathways/" - }, - { - "path": "pfam", - "valueType": "http://identifiers.org/pfam/" - }, - { - "path": "pharmgkb", - "valueType": "http://identifiers.org/pharmgkb.pathways/" - }, - { - "path": "prosite", - "valueType": "http://identifiers.org/prosite/" - }, - { - "path": "refseq.translation.protein", - "valueType": "http://identifiers.org/refseq/" - }, - { - "path": "refseq.translation.rna", - "valueType": "http://identifiers.org/refseq/" - }, - { - "path": "taxid", - "valueType": "http://identifiers.org/taxonomy/" - }, - { - "path": "uniprot.swiss-prot", - "valueType": "http://identifiers.org/uniprot/" - }, - { - "path": "wikipedia.url_stub", - "valueType": "http://identifiers.org/wikipedia.en/" - } - ] - } - } - } - }, - "/gene": { - "post": { - "tags": [ - "gene" - ], - "parameters": [ - { - "name": "ids", - "in": "query", - "description": "multiple geneids seperated by comma, e.g., \"ids=1017,1018\" or \"ids=695,ENSG00000123374\". Note that currently we only take the input ids up to 1000 maximum, the rest will be omitted.", - "required": true, - "type": "string" - }, - { - "name": "fields", - "in": "query", - "description": "a comma-separated fields to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", - "required": false, - "type": "string" - }, - { - "name": "species", - "in": "query", - "description": "Optional, can be used to limit the gene hits from given species. You can use \"common names\" for nine common species (human, mouse, rat, fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other species, you can provide their taxonomy ids. Multiple species can be passed using comma as a separator. Default all.", - "required": false, - "type": "string" - }, - { - "name": "dotfield", - "in": "query", - "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default true.", - "required": false, - "type": "string" - }, - { - "name": "email", - "in": "query", - "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", - "required": false, - "type": "string" - } - ], - "description": "Make gene queries in batch for a list of Entrez or Ensembl gene ids.\n", - "operationId": "getGenes", - "responses": { - "200": { - "schema": { - "items": { - "properties": { - "name": { - "type": "string" - }, - "entrezgene": { - "type": "integer" - }, - "symbol": { - "type": "string" - }, - "taxid": { - "type": "integer" - }, - "query": { - "type": "string" - }, - "_id": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "description": "Successful response" - } + } } - } } - } } From 55df85b3590b020439c1b7697f138e873f7d2518 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Mon, 17 Jul 2017 14:28:52 +0200 Subject: [PATCH 044/104] Update and rename smartAPI_spec_v3 to mygene.info.v3.compliant --- ...artAPI_spec_v3 => mygene.info.v3.compliant} | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) rename versions/{smartAPI_spec_v3 => mygene.info.v3.compliant} (98%) diff --git a/versions/smartAPI_spec_v3 b/versions/mygene.info.v3.compliant similarity index 98% rename from versions/smartAPI_spec_v3 rename to versions/mygene.info.v3.compliant index eb770b8394..d863f0585e 100644 --- a/versions/smartAPI_spec_v3 +++ b/versions/mygene.info.v3.compliant @@ -2,14 +2,14 @@ "swagger": "2.0", "openapi": "string", "info": { - "version": "3.0.0.2", + "version": "3.0.2", "title": "MyGene.info API", - "description": "Documentation of the MyGene.info Gene Query web services. Learn more about [MyGene.info](http://mygene.info/)", - "termsOfService": "http://example.com/terms/", + "description": "MyGene.info provides simple-to-use REST web services to query/retrieve gene annotation data. It’s designed with simplicity and performance emphasized. A typical use case is to use it to power a web application which requires querying genes and obtaining common gene annotations. Learn more about [MyGene.info](http://mygene.info/)", + "termsOfService": "http://mygene.info/terms/", "contact": { "name": "Chunlei Wu", - "x-role": "responsibleDeveloper", "email": "help@mygene.info", + "x-role": "responsible developer", "x-id": "http://orcid.org/0000-0002-2629-6124" }, "x-accessRestriction": "none", @@ -17,12 +17,12 @@ "x-implementationLanguage": "python" }, "externalDocs": { - "description": "Find more info here", - "url": "https://example.com" + "description": "Website", + "url": "https://mygene.info" }, "x-externalResource": [ { - "x-url": "http://example.org/api/docs", + "x-url": "http://docs.mygene.info/en/latest/s", "x-type": "api documentation" }, { @@ -37,8 +37,8 @@ ], "servers": [ { - "url": "https://development.gigantic-server.com/v", - "description": "Development server", + "url": "http:/mygene.info", + "description": "Production server", "x-location": "California, USA", "variables": { "basePath": { From 5b0eaf0097acb7f06a863a5d6bb4c9f6cbee2345 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Mon, 17 Jul 2017 20:33:05 +0200 Subject: [PATCH 045/104] Update mygene.info.v3.compliant added components & response --- versions/mygene.info.v3.compliant | 1534 +++++------------------------ 1 file changed, 240 insertions(+), 1294 deletions(-) diff --git a/versions/mygene.info.v3.compliant b/versions/mygene.info.v3.compliant index d863f0585e..f2cde9ba8b 100644 --- a/versions/mygene.info.v3.compliant +++ b/versions/mygene.info.v3.compliant @@ -1,1315 +1,261 @@ { - "swagger": "2.0", - "openapi": "string", - "info": { - "version": "3.0.2", - "title": "MyGene.info API", - "description": "MyGene.info provides simple-to-use REST web services to query/retrieve gene annotation data. It’s designed with simplicity and performance emphasized. A typical use case is to use it to power a web application which requires querying genes and obtaining common gene annotations. Learn more about [MyGene.info](http://mygene.info/)", - "termsOfService": "http://mygene.info/terms/", - "contact": { - "name": "Chunlei Wu", - "email": "help@mygene.info", - "x-role": "responsible developer", - "x-id": "http://orcid.org/0000-0002-2629-6124" - }, - "x-accessRestriction": "none", - "x-maturity": "production", - "x-implementationLanguage": "python" + "openapi": "string", + "info": { + "version": "3.0.0.2", + "title": "MyGene.info API", + "description": "Documentation of the MyGene.info Gene Query web services. Learn more about [MyGene.info](http://mygene.info/)", + "termsOfService": "http://example.com/terms/", + "contact": { + "name": "Chunlei Wu", + "x-role": "responsibleDeveloper", + "email": "help@mygene.info", + "x-id": "http://orcid.org/0000-0002-2629-6124" }, - "externalDocs": { - "description": "Website", - "url": "https://mygene.info" + "x-accessRestriction": "none", + "x-maturity": "production", + "x-implementationLanguage": "python" + }, + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + }, + "x-externalResource": [ + { + "x-url": "http://example.org/api/docs", + "x-type": "api documentation" }, - "x-externalResource": [ - { - "x-url": "http://docs.mygene.info/en/latest/s", - "x-type": "api documentation" - }, - { - "x-url": "https://doi.org/10.1093/nar/gks1114", - "x-type": "publication", - "x-description": "BioGPS and MyGene.info: organizing online, gene-centric information" - }, - { - "x-url": "http://twitter.com/mygeneinfo", - "x-type": "social media" + { + "x-url": "https://doi.org/10.1093/nar/gks1114", + "x-type": "publication", + "x-description": "BioGPS and MyGene.info: organizing online, gene-centric information" + }, + { + "x-url": "http://twitter.com/mygeneinfo", + "x-type": "social media" + } + ], + "servers": [{ + "url": "http://mygene.info", + "description": "Development server", + "x-location": "California, USA" + }], + "tags": [ + { + "name": "http://purl.bioontology.org/ontology/MESH/D005796", + "description": "Genes" + } + ], + "components": { + "schemas": { + "Category": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } } - ], - "servers": [ - { - "url": "http:/mygene.info", - "description": "Production server", - "x-location": "California, USA", - "variables": { - "basePath": { - "default": "/v3" - } - } + }, + "Tag": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } } - ], - "tags": [ - { - "name": "query", - "description": "Query for gene information" - }, - { - "name": "gene", - "description": "Gene annotation information" - }, - { - "name": "metadata", - "description": "Metadata about the data available from MyGene.info." - }, - { - "name": "http://purl.bioontology.org/ontology/MESH/D005796", - "description": "Genes" + } + }, + "parameters": { + "skipParam": { + "name": "skip", + "in": "query", + "description": "number of items to skip", + "required": true, + "schema": { + "type": "integer", + "format": "int32" } - ], - "paths": { - "/query": { - "get": { - "tags": [ - "query" - ], - "summary": "Makes gene query and returns matching gene list.", - "x-accessRestriction": "free", - "parameters": [ - { - "name": "q", - "in": "query", - "description": "Query string. Examples \"CDK2\", \"NM_052827\", \"204639_at\". The detailed query syntax can be found at http://docs.mygene.info/en/latest/doc/query_service.html", - "required": true, - "schema": { - "type": "string" - }, - "x-parameterType": "InputParameter", - "x-valueType": [ - "http://identifiers.org/hgnc.symbol", - "http://identifiers.org/refseq", - "http://identifiers.org/unigene", - "http://identifiers.org/uniprot", - "http://identifiers.org/pdb", - "http://identifiers.org/prosite", - "http://identifiers.org/pfam", - "http://identifiers.org/interpro", - "http://identifiers.org/hgnc", - "http://identifiers.org/mgi", - "http://identifiers.org/rgd", - "http://identifiers.org/flybase", - "http://identifiers.org/wormbase", - "http://identifiers.org/zfin", - "http://identifiers.org/tair.gene", - "http://identifiers.org/xenbase", - "http://identifiers.org/mirbase" - ], - "x-defaultValue": "CDK2", - "x-exampleValue": "CDK2" - }, - { - "name": "fields", - "in": "query", - "description": "A comma-separated field to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", - "required": false, - "type": "string" - }, - { - "name": "species", - "in": "query", - "description": "can be used to limit the gene hits from given species. You can use \"common names\" for nine common species (human, mouse, rat, fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other species, you can provide their taxonomy ids. Multiple species can be passed using comma as a separator. Passing “all” will query against all available species. Default human,mouse,rat.", - "required": false, - "type": "string" - }, - { - "name": "size", - "in": "query", - "description": "the maximum number of matching gene hits to return (with a cap of 1000 at the moment). Default 10.", - "required": false, - "type": "integer" - }, - { - "name": "from", - "in": "query", - "description": "the number of matching gene hits to skip, starting from 0. Combining with \"size\" parameter, this can be useful for paging. Default 0.", - "required": false, - "type": "integer" - }, - { - "name": "sort", - "in": "query", - "description": "comma-separated fields to sort on. Prefix with \"-\" for descending order, otherwise in ascending order. Sort by matching scores in decending order.", - "required": false, - "type": "string" - }, - { - "name": "facets", - "in": "query", - "description": "a single field or comma-separated fields to return facets, for example, “facets=taxid”, “facets=taxid,type_of_gene”.", - "required": false, - "type": "string" - }, - { - "name": "species_facet_filter", - "in": "query", - "description": "relevant when faceting on species (i.e., “facets=taxid” are passed). It’s used to pass species filter without changing the scope of faceting, so that the returned facet counts won’t change. Either species name or taxonomy id can be used, just like “species” parameter above.", - "required": false, - "type": "string" - }, - { - "name": "entrezonly", - "in": "query", - "description": "when passed as “true” or “1”, the query returns only the hits with valid Entrez gene ids. Default: false", - "required": false, - "type": "boolean" - }, - { - "name": "ensemblonly", - "in": "query", - "description": "when passed as “true” or “1”, the query returns only the hits with valid Ensembl gene ids. Default: false.", - "required": false, - "type": "boolean" - }, - { - "name": "callback", - "in": "query", - "description": "you can pass a \"callback\" parameter to make a JSONP call.", - "required": false, - "type": "string" - }, - { - "name": "dotfield", - "in": "query", - "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default: true", - "type": "boolean" - }, - { - "name": "filter", - "in": "query", - "description": "alias for \"fields\" parameter.", - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "alias for \"size\" parameter.", - "type": "integer" - }, - { - "name": "skip", - "in": "query", - "description": "alias for \"from\" parameter.", - "type": "integer" - }, - { - "name": "email", - "in": "query", - "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", - "type": "string" - } - ], - "description": "Make gene query and return matching gene list. Support JSONP and CORS as well.", - "operationId": "queryGene", - "responses": { - "200": { - "schema": { - "type": "object", - "properties": { - "hits": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "entrezgene": { - "type": "integer" - }, - "taxid": { - "type": "integer" - }, - "symbol": { - "type": "string" - }, - "_id": { - "type": "integer" - } - } - } - }, - "max_score": { - "type": "integer" - }, - "took": { - "type": "integer" - }, - "total": { - "type": "integer" - } - } - }, - "description": "Successful response" - } - } + }, + "limitParam": { + "name": "limit", + "in": "query", + "description": "max records to return", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + }, + "responses": { + "NotFound": { + "description": "Entity not found." + }, + "IllegalInput": { + "description": "Illegal input for operation." + } + }, + "securitySchemes": { + "api_key": { + "type": "apiKey", + "name": "api_key", + "in": "header" + }, + "petstore_auth": { + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "http://example.org/api/oauth/dialog", + "scopes": { + "write:pets": "modify genes in your account", + "read:pets": "read your genes" } - }, - "/metadata": { - "get": { - "tags": [ - "metadata" - ], - "parameters": [ - { - "name": "callback", - "in": "query", - "description": "you can pass a \"callback\" parameter to make a JSONP call.", - "required": false, - "type": "string" - } - ], - "description": "Get metadata about the data available from MyGene.info\n", - "operationId": "getMetadata", - "responses": { - "200": { - "schema": { - "properties": { - "app_revision": { - "type": "string" - }, - "genome_assembly": { - "properties": { - "fruitfly": { - "type": "string" - }, - "zebrafish": { - "type": "string" - }, - "nematode": { - "type": "string" - }, - "human": { - "type": "string" - }, - "rat": { - "type": "string" - }, - "pig": { - "type": "string" - }, - "mouse": { - "type": "string" - }, - "frog": { - "type": "string" - } - }, - "type": "object" - }, - "source": { - "type": "string" - }, - "taxonomy": { - "properties": { - "fruitfly": { - "type": "integer" - }, - "thale-cress\"": { - "type": "integer" - }, - "zebrafish": { - "type": "integer" - }, - "nematode": { - "type": "integer" - }, - "human": { - "type": "integer" - }, - "rat": { - "type": "integer" - }, - "pig": { - "type": "integer" - }, - "mouse": { - "type": "integer" - }, - "frog": { - "type": "integer" - } - }, - "type": "object" - }, - "timestamp": { - "type": "string" - }, - "src_version": { - "properties": { - "netaffy": { - "type": "string" - }, - "entrez": { - "type": "integer" - }, - "pharmgkb": { - "type": "integer" - }, - "ucsc": { - "type": "integer" - }, - "cpdb": { - "type": "integer" - }, - "refseq": { - "type": "integer" - }, - "ensembl": { - "type": "integer" - }, - "uniprot": { - "type": "integer" - } - }, - "type": "object" - }, - "stats": { - "properties": { - "total_ensembl_genes_mapped_to_entrez": { - "type": "integer" - }, - "total_entrez_genes": { - "type": "integer" - }, - "total_ensembl_only_genes": { - "type": "integer" - }, - "total_ensembl_genes": { - "type": "integer" - }, - "total_genes": { - "type": "integer" - }, - "total_species": { - "type": "integer" - } - }, - "type": "object" - }, - "available_fields": { - "type": "string" - } - }, - "type": "object" - }, - "description": "Successful response" - } + } + } + } + } + }, + "paths": { + "/query": { + "get": { + "description": "Makes gene query and returns matching gene list.", + "x-accessRestriction": "free", + "parameters": [ + { + "name": "q", + "in": "query", + "description": "Query string. Examples \"CDK2\", \"NM_052827\", \"204639_at\". The detailed query syntax can be found at http://docs.mygene.info/en/latest/doc/query_service.html", + "required": true, + "schema": { + "type": "string" + }, + "x-parameterType": "InputParameter", + "x-valueType": [ + "http://identifiers.org/hgnc.symbol", + "http://identifiers.org/refseq", + "http://identifiers.org/unigene", + "http://identifiers.org/uniprot", + "http://identifiers.org/pdb" + ] + } + ], + "operationId": "queryGene", + "responses": { + "200": { + "description": "Successful response.", + "content": { + "application/json": { + "x-responseProfile": "http://www.w3.org/ns/anno.jsonld", + "x-responseValueType": [ + { + "path": "a.id", + "valueType": "http://example.org/a.id" + }, + { + "path": "a.b.c.id", + "valueType": "http://example.org/c.id" } + ] } - }, - "/gene/{geneid}": { - "get": { - "tags": [ - "gene" - ], - "parameters": [ - { - "name": "geneid", - "in": "path", - "description": "Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired Entrez Gene id works too if it is replaced by a new one, e.g., 245794", - "required": true, - "type": "string", - "x-parameterType": "InputParameter", - "x-valueType": [ - "http://identifiers.org/ncbigene", - "http://identifiers.org/ensembl" - ], - "x-defaultValue": null, - "x-exampleValue": "1017" - }, - { - "name": "fields", - "in": "query", - "description": "a comma-separated fields to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", - "required": false, - "type": "string" - }, - { - "name": "callback", - "in": "query", - "description": "you can pass a \"callback\" parameter to make a JSONP call.", - "required": false, - "type": "string" - }, - { - "name": "filter", - "in": "query", - "description": "alias for \"fields\" parameter.", - "required": false, - "type": "string" + } + } + } + } + }, + "/gene/{geneid}": { + "get": { + "tags": [ + "gene" + ], + "parameters": [ + { + "name": "geneid", + "in": "path", + "description": "Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired Entrez Gene id works too if it is replaced by a new one, e.g., 245794", + "required": true, + "type": "string", + "x-parameterType": "InputParameter", + "x-valueType": [ + "http://identifiers.org/ncbigene", + "http://identifiers.org/ensembl" + ], + "x-defaultValue": null, + "x-exampleValue": "1017" + } + ], + "operationId": "getAnnotation", + "responses": { + "200": { + "schema": { + "properties": { + "reporter": { + "properties": { + "HTA-2_0": { + "type": "string" }, - { - "name": "dotfield", - "in": "query", - "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default true.", - "required": false, + "HG-U133_Plus_2": { + "items": { "type": "string" + }, + "type": "array" }, - { - "name": "email", - "in": "query", - "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", - "required": false, - "type": "string" - } - ], - "description": "Retrieve gene annotation based on Entrez or Ensembl gene id, support\nJSONP and CORS as well.\n", - "operationId": "getAnnotation", - "responses": { - "200": { - "schema": { - "properties": { - "reporter": { - "properties": { - "HTA-2_0": { - "type": "string" - }, - "HG-U133_Plus_2": { - "items": { - "type": "string" - }, - "type": "array" - }, - "HuEx-1_0": { - "type": "integer" - }, - "HuGene-1_1": { - "type": "integer" - }, - "HuGene-2_1": { - "type": "integer" - }, - "HG-U95Av2": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "prosite": { - "type": "string" - }, - "summary": { - "type": "string" - }, - "exons": { - "type": "object" - }, - "symbol": { - "type": "string" - }, - "genomic_pos": { - "properties": { - "chr": { - "type": "integer" - }, - "strand": { - "type": "integer" - }, - "end": { - "type": "integer" - }, - "start": { - "type": "integer" - } - }, - "type": "object" - }, - "homologene": { - "properties": { - "id": { - "type": "integer" - }, - "genes": { - "items": { - "type": "integer" - }, - "type": "array" - } - }, - "type": "object" - }, - "taxid": { - "type": "integer" - }, - "pathway": { - "properties": { - "kegg": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "wikipathways": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "pid": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "netpath": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "reactome": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "biocarta": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - } - }, - "type": "object" - }, - "Vega": { - "type": "string" - }, - "entrezgene": { - "type": "string" - }, - "pfam": { - "type": "string" - }, - "ec": { - "type": "string" - }, - "refseq": { - "properties": { - "genomic": { - "items": { - "type": "string" - }, - "type": "array" - }, - "rna": { - "items": { - "type": "string" - }, - "type": "array" - }, - "protein": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "wikipedia": { - "properties": { - "url_stub": { - "type": "string" - } - }, - "type": "object" - }, - "ensembl": { - "properties": { - "transcript": { - "items": { - "type": "string" - }, - "type": "array" - }, - "gene": { - "type": "string" - } - }, - "type": "object" - }, - "accession": { - "properties": { - "genomic": { - "items": { - "type": "string" - }, - "type": "array" - }, - "rna": { - "items": { - "type": "string" - }, - "type": "array" - }, - "protein": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "MIM": { - "type": "integer" - }, - "HPRD": { - "type": "integer" - }, - "unigene": { - "items": { - "type": "string" - }, - "type": "array" - }, - "pharmgkb": { - "type": "string" - }, - "genomic_pos_hg19": { - "properties": { - "chr": { - "type": "integer" - }, - "strand": { - "type": "integer" - }, - "end": { - "type": "integer" - }, - "start": { - "type": "integer" - } - }, - "type": "object" - }, - "HGNC": { - "type": "integer" - }, - "type_of_gene": { - "type": "string" - }, - "pir": { - "type": "string" - }, - "_id": { - "type": "string" - }, - "pdb": { - "items": { - "type": "string" - }, - "type": "array" - }, - "name": { - "type": "string" - }, - "map_location": { - "type": "string" - }, - "go": { - "properties": { - "BP": { - "items": { - "properties": { - "evidence": { - "type": "string" - }, - "id": { - "type": "string" - }, - "term": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "CC": { - "items": { - "properties": { - "evidence": { - "type": "string" - }, - "id": { - "type": "string" - }, - "term": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "MF": { - "items": { - "properties": { - "evidence": { - "type": "string" - }, - "id": { - "type": "string" - }, - "term": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - } - }, - "type": "object" - }, - "reagent": { - "properties": { - "GNF_hs_LentiORF-HA-MYC": { - "properties": { - "id": { - "type": "string" - }, - "relationship": { - "type": "string" - } - }, - "type": "object" - }, - "GNF_hs-Origene": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_Qia_hs-genome_v1_siRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_hs_LentiORF-Jred": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "GNF_hs-druggable_siRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_hs-ORFeome1_1_reads": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "Invitrogen_IVTHSSIPKv2": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_hs-druggable_lenti-shRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_mm+hs-MGC": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "GNF_hs-pkinase_IDT-siRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "GNF_hs-druggable_plasmid-shRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "NOVART_hs-genome_siRNA": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "relationonship": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "NIBRI_hs-Secretome_pDEST": { - "properties": { - "id": { - "type": "string" - }, - "relationship": { - "type": "string" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "interpro": { - "items": { - "properties": { - "id": { - "type": "string" - }, - "description": { - "type": "string" - }, - "short_desc": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "ipi": { - "items": { - "type": "string" - }, - "type": "array" - }, - "alias": { - "items": { - "type": "string" - }, - "type": "array" - }, - "generif": { - "items": { - "properties": { - "pubmed": { - "type": "string" - }, - "text": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "uniprot": { - "properties": { - "Swiss-Prot": { - "type": "string" - }, - "TrEMBL": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "description": "Successful response", - "responseValueType": [ - { - "path": "ec", - "valueType": "http://identifiers.org/ec-code/" - }, - { - "path": "ensembl.gene", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "ensembl.translation.protein", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "ensembl.translation.rna", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "entrezgene", - "valueType": "http://identifiers.org/ncbigene/" - }, - { - "path": "generif.pubmed", - "valueType": "http://identifiers.org/pubmed/" - }, - { - "path": "go.bp.evidence", - "valueType": "http://identifiers.org/eco/" - }, - { - "path": "go.bp.id", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.bp.pubmed", - "valueType": "http://identifiers.org/pubmed/" - }, - { - "path": "go.bp.term", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.cc.evidence", - "valueType": "http://identifiers.org/eco/" - }, - { - "path": "go.cc.id", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.cc.pubmed", - "valueType": "http://identifiers.org/pubmed/" - }, - { - "path": "go.cc.term", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.mf.evidence", - "valueType": "http://identifiers.org/eco/" - }, - { - "path": "go.mf.id", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.mf.pubmed", - "valueType": "http://identifiers.org/pubmed/" - }, - { - "path": "go.mf.qualifier", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "go.mf.term", - "valueType": "http://identifiers.org/go/" - }, - { - "path": "hgnc", - "valueType": "http://identifiers.org/hgnc/" - }, - { - "path": "homologene.id", - "valueType": "http://identifiers.org/homologene/" - }, - { - "path": "interpro.desc", - "valueType": "http://identifiers.org/interpro/" - }, - { - "path": "interpro.id", - "valueType": "http://identifiers.org/interpro/" - }, - { - "path": "interpro.short_desc", - "valueType": "http://identifiers.org/interpro/" - }, - { - "path": "mim", - "valueType": "http://identifiers.org/omim/" - }, - { - "path": "pathway.biocarta.id", - "valueType": "http://identifiers.org/biocarta.pathway/" - }, - { - "path": "pathway.biocarta.name", - "valueType": "http://identifiers.org/biocarta.pathway/" - }, - { - "path": "pathway.kegg.id", - "valueType": "http://identifiers.org/kegg.pathway/" - }, - { - "path": "pathway.kegg.name", - "valueType": "http://identifiers.org/kegg.pathway/" - }, - { - "path": "pathway.pid.id", - "valueType": "http://identifiers.org/pid.pathway/" - }, - { - "path": "pathway.pid.name", - "valueType": "http://identifiers.org/pid.pathway/" - }, - { - "path": "pathway.reactome.id", - "valueType": "http://identifiers.org/reactome/" - }, - { - "path": "pathway.reactome.name", - "valueType": "http://identifiers.org/reactome/" - }, - { - "path": "pathway.wikipathways.id", - "valueType": "http://identifiers.org/wikipathways/" - }, - { - "path": "pathway.wikipathways.name", - "valueType": "http://identifiers.org/wikipathways/" - }, - { - "path": "pfam", - "valueType": "http://identifiers.org/pfam/" - }, - { - "path": "pharmgkb", - "valueType": "http://identifiers.org/pharmgkb.pathways/" - }, - { - "path": "prosite", - "valueType": "http://identifiers.org/prosite/" - }, - { - "path": "refseq.translation.protein", - "valueType": "http://identifiers.org/refseq/" - }, - { - "path": "refseq.translation.rna", - "valueType": "http://identifiers.org/refseq/" - }, - { - "path": "taxid", - "valueType": "http://identifiers.org/taxonomy/" - }, - { - "path": "uniprot.swiss-prot", - "valueType": "http://identifiers.org/uniprot/" - }, - { - "path": "wikipedia.url_stub", - "valueType": "http://identifiers.org/wikipedia.en/" - } - ] - } - } - } - }, - "/gene": { - "post": { - "tags": [ - "gene" - ], - "parameters": [ - { - "name": "ids", - "in": "query", - "description": "multiple geneids seperated by comma, e.g., \"ids=1017,1018\" or \"ids=695,ENSG00000123374\". Note that currently we only take the input ids up to 1000 maximum, the rest will be omitted.", - "required": true, - "type": "string" + "HuEx-1_0": { + "type": "integer" }, - { - "name": "fields", - "in": "query", - "description": "a comma-separated fields to limit the fields returned from the matching gene hits. The supported field names can be found from any gene object (e.g. http://mygene.info/v2/gene/1017). Note that it supports dot notation as well, e.g., you can pass \"refseq.rna\". If \"fields=all\", all available fields will be returned. Default \"symbol,name,taxid,entrezgene,ensemblgene\".", - "required": false, - "type": "string" + "HuGene-1_1": { + "type": "integer" }, - { - "name": "species", - "in": "query", - "description": "Optional, can be used to limit the gene hits from given species. You can use \"common names\" for nine common species (human, mouse, rat, fruitfly, nematode, zebrafish, thale-cress, frog and pig). All other species, you can provide their taxonomy ids. Multiple species can be passed using comma as a separator. Default all.", - "required": false, - "type": "string" + "HuGene-2_1": { + "type": "integer" }, - { - "name": "dotfield", - "in": "query", - "description": "control the format of the returned fields when passed \"fields\" parameter contains dot notation, e.g. \"fields=refseq.rna\". If \"true\" or \"1\", the returned data object contains a single \"refseq.rna\" field, otherwise (\"false\" or \"0\"), a single \"refseq\" field with a sub-field of \"rna\". Default true.", - "required": false, + "HG-U95Av2": { + "items": { "type": "string" - }, - { - "name": "email", - "in": "query", - "description": "If you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.", - "required": false, - "type": "string" - } - ], - "description": "Make gene queries in batch for a list of Entrez or Ensembl gene ids.\n", - "operationId": "getGenes", - "responses": { - "200": { - "schema": { - "items": { - "properties": { - "name": { - "type": "string" - }, - "entrezgene": { - "type": "integer" - }, - "symbol": { - "type": "string" - }, - "taxid": { - "type": "integer" - }, - "query": { - "type": "string" - }, - "_id": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "description": "Successful response" + }, + "type": "array" } + }, + "type": "object" } - } + } + }, + "description": "Successful response", + "x-responseValueType": [ + { + "path": "ec", + "valueType": "http://identifiers.org/ec-code/" + }, + { + "path": "ensembl.gene", + "valueType": "http://identifiers.org/ensembl/" + }, + { + "path": "ensembl.translation.protein", + "valueType": "http://identifiers.org/ensembl/" + }, + { + "path": "ensembl.translation.rna", + "valueType": "http://identifiers.org/ensembl/" + }, + { + "path": "entrezgene", + "valueType": "http://identifiers.org/ncbigene/" + }, + { + "path": "generif.pubmed", + "valueType": "http://identifiers.org/pubmed/" + } + ] + } } + } } + } } From 1dc643c9b5d29ecdb2776e1a7a3175508b780f6f Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Tue, 18 Jul 2017 16:57:45 +0200 Subject: [PATCH 046/104] Update mygene.info.v3.compliant --- versions/mygene.info.v3.compliant | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/versions/mygene.info.v3.compliant b/versions/mygene.info.v3.compliant index f2cde9ba8b..51559acc4d 100644 --- a/versions/mygene.info.v3.compliant +++ b/versions/mygene.info.v3.compliant @@ -7,7 +7,7 @@ "termsOfService": "http://example.com/terms/", "contact": { "name": "Chunlei Wu", - "x-role": "responsibleDeveloper", + "x-role": "responsible developer", "email": "help@mygene.info", "x-id": "http://orcid.org/0000-0002-2629-6124" }, @@ -126,6 +126,7 @@ "/query": { "get": { "description": "Makes gene query and returns matching gene list.", + "summary": "Makes gene query and returns matching gene list.", "x-accessRestriction": "free", "parameters": [ { @@ -142,11 +143,11 @@ "http://identifiers.org/refseq", "http://identifiers.org/unigene", "http://identifiers.org/uniprot", - "http://identifiers.org/pdb" + "http://identifiers.org/pdb' x-defaultValue: CDK2 x-exampleValue: CDK2 operationId: queryGene responses: responses: " ] } ], - "operationId": "queryGene", + "operationId": "add operation id here", "responses": { "200": { "description": "Successful response.", @@ -167,7 +168,7 @@ } } } - } + } }, "/gene/{geneid}": { "get": { @@ -180,20 +181,23 @@ "in": "path", "description": "Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired Entrez Gene id works too if it is replaced by a new one, e.g., 245794", "required": true, - "type": "string", "x-parameterType": "InputParameter", "x-valueType": [ "http://identifiers.org/ncbigene", "http://identifiers.org/ensembl" ], - "x-defaultValue": null, + "x-defaultValue": "add default", "x-exampleValue": "1017" } ], "operationId": "getAnnotation", + "summary": "add summary", "responses": { "200": { - "schema": { + "description": "Successful response", + "content": { + "application/json": { + "x-responseSchema": { "properties": { "reporter": { "properties": { @@ -226,7 +230,7 @@ } } }, - "description": "Successful response", + "x-responseValueType": [ { "path": "ec", @@ -256,6 +260,8 @@ } } } - } + } + } } + } } From 74d9a7ede6666de6c63fda244148e5735ddb28b2 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Tue, 18 Jul 2017 18:10:51 +0200 Subject: [PATCH 047/104] Update 3.0.md minor fixes --- versions/3.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index bc5eea9899..5413133831 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -202,7 +202,7 @@ Field Name | Type | Description security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. -externalResources | [External Resource Object](#externalResourceObject) | Additional external resources. +externalResources | [[External Resource Object]](#externalResourceObject) | Additional external resources. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -231,7 +231,7 @@ Field Name | Type | Description termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. x-maturity | `enum` | Maturity of the API. Values to use: development, production. -x-accessRestriction | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, free. +x-accessRestriction | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. x-implementationLanguage | `string` | Language the API was written in. ##### Info Object Example: @@ -883,7 +883,7 @@ This object can be extended with [Specification Extensions](#specificationExtens Field Name | Type | Description ---|:---:|--- summary | `string` | **REQUIRED** See above. -x-accessRestriction | `enum` | Access restrictions to invoke the operation. values: none, limited, free. +x-accessRestriction | `enum` | Access restrictions to invoke the operation. values: none, limited, fee. ##### Operation Object Example From cc592696dc6209059b4ed4fff19c218d8c1afc55 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Tue, 18 Jul 2017 18:21:26 +0200 Subject: [PATCH 048/104] Update mygene.info.v3.compliant typo fixed --- versions/mygene.info.v3.compliant | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/mygene.info.v3.compliant b/versions/mygene.info.v3.compliant index 51559acc4d..e114eff483 100644 --- a/versions/mygene.info.v3.compliant +++ b/versions/mygene.info.v3.compliant @@ -143,7 +143,7 @@ "http://identifiers.org/refseq", "http://identifiers.org/unigene", "http://identifiers.org/uniprot", - "http://identifiers.org/pdb' x-defaultValue: CDK2 x-exampleValue: CDK2 operationId: queryGene responses: responses: " + "http://identifiers.org/pdb" ] } ], From a65849eec21e12233bebd8f293fce53688d7badc Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Tue, 18 Jul 2017 18:26:19 +0200 Subject: [PATCH 049/104] Update 3.0.md x-path, x-valueType --- versions/3.0.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 5413133831..8f8c465692 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1776,7 +1776,7 @@ Field Name | Type | Description ---|:---:|--- content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. x-responseSchema| `URI` | Conformance to a particular schema/format. -x-responseValueType | `array of responseValueType object` | To specify the types of objects in the response. The responseValueType object consists of a required `valueType` that should provide URI values to the type of object, and an optional `path` to specify to location in the response for that valueType. +x-responseValueType | `array of responseValueType object` | To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. ##### Response Object Examples @@ -1907,10 +1907,10 @@ responses: - application/ld+json: x-responseProfile: http://www.w3.org/ns/anno.jsonld x-responseValueType: - - path: a.id - valueType: http://example.org/a.id - - path: a.b.c.id - valueType: http://example.org/c.id + - x-path: a.id + x-valueType: http://example.org/a.id + - x-path: a.b.c.id + x-valueType: http://example.org/c.id ``` #### Callback Object From b77854a7c5a9c63bac29fc83518a858b753bd4f0 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Tue, 18 Jul 2017 18:29:50 +0200 Subject: [PATCH 050/104] Update 3.0.md x-id --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 8f8c465692..8ca035b805 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2271,7 +2271,7 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. The name of the tag. Recommend that you use URI to specify the concept. +x-id | `URI` | The name of the tag. Recommend that you use URI to specify the concept. This object can be extended with [Specification Extensions](#specificationExtensions). From 15cc7e51fd2d487876285ecbaeafad8c16bc661c Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Tue, 18 Jul 2017 18:41:57 +0200 Subject: [PATCH 051/104] Update 3.0.md added x-JSONLDContext --- versions/3.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 8ca035b805..70c89c076a 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -49,7 +49,7 @@ Additional utilities, such as testing tools, can also use the files. - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) - - [Response Object](#responseObject) + - [tt](#responseObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) @@ -1777,6 +1777,7 @@ Field Name | Type | Description content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. x-responseSchema| `URI` | Conformance to a particular schema/format. x-responseValueType | `array of responseValueType object` | To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. +x-JSONLDContext | `URI` | JSON LD context. ##### Response Object Examples From 7d2684ede6428b0c8f08f486883284f846e44913 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Wed, 19 Jul 2017 17:10:18 +0200 Subject: [PATCH 052/104] Update 3.0.md indicate that there is a list of external resources in the openapi object --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 70c89c076a..4df1973350 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -202,7 +202,7 @@ Field Name | Type | Description security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. -externalResources | [[External Resource Object]](#externalResourceObject) | Additional external resources. +externalResources | [[External Resource Object]](#externalResourceObject) | A list of external resources pertinent to the API. This object can be extended with [Specification Extensions](#specificationExtensions). From 8639138aa0454c710b8845d6e7d85ee74c456b27 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Wed, 19 Jul 2017 17:12:04 +0200 Subject: [PATCH 053/104] Update 3.0.md added external brackets --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 4df1973350..f2260ede28 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -201,8 +201,8 @@ Field Name | Type | Description components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. -externalResources | [[External Resource Object]](#externalResourceObject) | A list of external resources pertinent to the API. +externalDocs | [[External Documentation Object](#externalDocumentationObject)] | Additional external documentation. +externalResources | [[External Resource Object]](#externalResourceObject)] | A list of external resources pertinent to the API. This object can be extended with [Specification Extensions](#specificationExtensions). From 708da0af0276b1a417092a0968d1ddb441404b7c Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Wed, 19 Jul 2017 17:20:11 +0200 Subject: [PATCH 054/104] Update 3.0.md moved external resources into its own smartAPI block --- versions/3.0.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index f2260ede28..5627160d9c 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -202,7 +202,11 @@ Field Name | Type | Description security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [[External Documentation Object](#externalDocumentationObject)] | Additional external documentation. -externalResources | [[External Resource Object]](#externalResourceObject)] | A list of external resources pertinent to the API. + +##### smartAPI Fields +Field Name | Type | Description +---|:---:|--- +externalResources | [[External Resource Object](#externalResourceObject)] | A list of external resources pertinent to the API. This object can be extended with [Specification Extensions](#specificationExtensions). From 9379fb0c5f75547bad2d90d5e3049da3389fc90d Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 27 Jul 2017 18:02:45 +0200 Subject: [PATCH 055/104] Update 3.0.md added the vendor extension to externalResources --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 5627160d9c..3c273602dc 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -206,7 +206,7 @@ Field Name | Type | Description ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -externalResources | [[External Resource Object](#externalResourceObject)] | A list of external resources pertinent to the API. +x-externalResources | [[External Resource Object](#externalResourceObject)] | A list of external resources pertinent to the API. This object can be extended with [Specification Extensions](#specificationExtensions). From fddb56a42e8edb5148207c3ad1c7c3a315bbf681 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 27 Jul 2017 18:05:06 +0200 Subject: [PATCH 056/104] Update mygene.info.v3.compliant --- versions/mygene.info.v3.compliant | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/mygene.info.v3.compliant b/versions/mygene.info.v3.compliant index e114eff483..629159b3b3 100644 --- a/versions/mygene.info.v3.compliant +++ b/versions/mygene.info.v3.compliant @@ -19,7 +19,7 @@ "description": "Find more info here", "url": "https://example.com" }, - "x-externalResource": [ + "x-externalResources": [ { "x-url": "http://example.org/api/docs", "x-type": "api documentation" From d9b2df7b4726d9da435459f41853099abee47669 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 28 Jul 2017 15:14:20 +0200 Subject: [PATCH 057/104] Update 3.0.md removed extraneous tt in table of contents, reverted external documentation to single object --- versions/3.0.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 3c273602dc..c73eb3b575 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -49,7 +49,6 @@ Additional utilities, such as testing tools, can also use the files. - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) - - [tt](#responseObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) @@ -201,15 +200,15 @@ Field Name | Type | Description components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. -externalDocs | [[External Documentation Object](#externalDocumentationObject)] | Additional external documentation. +externalDocs | [External Documentation Object(#externalDocumentationObject)] | Additional external documentation. + +This object can be extended with [Specification Extensions](#specificationExtensions). ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- x-externalResources | [[External Resource Object](#externalResourceObject)] | A list of external resources pertinent to the API. -This object can be extended with [Specification Extensions](#specificationExtensions). - #### Info Object The object provides metadata about the API. @@ -1780,7 +1779,7 @@ Field Name | Type | Description ---|:---:|--- content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. x-responseSchema| `URI` | Conformance to a particular schema/format. -x-responseValueType | `array of responseValueType object` | To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. +x-responseValueType | [`responseValueType object`] | To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. x-JSONLDContext | `URI` | JSON LD context. ##### Response Object Examples @@ -1909,13 +1908,13 @@ description: object created ```yaml responses: - content: - - application/ld+json: - x-responseProfile: http://www.w3.org/ns/anno.jsonld + - 'application/ld+json': + x-responseProfile: 'http://www.w3.org/ns/anno.jsonld' x-responseValueType: - x-path: a.id - x-valueType: http://example.org/a.id + x-valueType: 'http://example.org/a.id' - x-path: a.b.c.id - x-valueType: http://example.org/c.id + x-valueType: 'http://example.org/c.id' ``` #### Callback Object From cc4a926af82ae6785c2c44bc73020ab43bd00952 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Sun, 30 Jul 2017 00:12:43 +0200 Subject: [PATCH 058/104] Update 3.0.md Fixed bracket issues with external documentation and external resources --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index c73eb3b575..c618d29092 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -200,14 +200,14 @@ Field Name | Type | Description components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object(#externalDocumentationObject)] | Additional external documentation. +externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. This object can be extended with [Specification Extensions](#specificationExtensions). ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -x-externalResources | [[External Resource Object](#externalResourceObject)] | A list of external resources pertinent to the API. +x-externalResources |[[External Resource Object](#externalResourceObject)] | A list of external resources pertinent to the API. #### Info Object From d0449d2d1f6035b9efda26a51094f66bca6b6fbe Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Mon, 31 Jul 2017 16:56:29 +0200 Subject: [PATCH 059/104] Update 3.0.md parameter object example --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index c618d29092..7d5a1cf03d 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1192,7 +1192,7 @@ A path parameter of a string value: } } ``` - +A parameter with the smartAPI extension: ```yaml name: username in: path From b8d49bc5929162c22d151b696406197d3dcfc34b Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Tue, 1 Aug 2017 08:26:18 +0200 Subject: [PATCH 060/104] Update 3.0.md free - fee --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 7d5a1cf03d..a2f03ed7af 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -960,7 +960,7 @@ tags: - pet summary: Updates a pet in the store with form data operationId: updatePetWithForm -x-accessRestriction: free +x-accessRestriction: fee parameters: - name: petId in: path From d5832dc5c86d8a1f3626a32fc5444bcd9624ea57 Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Tue, 1 Aug 2017 08:27:17 +0200 Subject: [PATCH 061/104] Update mygene.info.v3.compliant free - fee --- versions/mygene.info.v3.compliant | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/mygene.info.v3.compliant b/versions/mygene.info.v3.compliant index 629159b3b3..2e85b64b62 100644 --- a/versions/mygene.info.v3.compliant +++ b/versions/mygene.info.v3.compliant @@ -127,7 +127,7 @@ "get": { "description": "Makes gene query and returns matching gene list.", "summary": "Makes gene query and returns matching gene list.", - "x-accessRestriction": "free", + "x-accessRestriction": "fee", "parameters": [ { "name": "q", From 347e98654345f6f20862b12a6ed106d5b7207fa6 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 1 Aug 2017 18:10:47 +0200 Subject: [PATCH 062/104] Update 3.0.md updated tag object ot use the x-id --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index a2f03ed7af..56e5483220 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2295,8 +2295,8 @@ This object can be extended with [Specification Extensions](#specificationExtens ``` ##### Tag Object smartAPI Examples ```yaml -- name: http://purl.bioontology.org/ontology/MESH/D057805 - description: Pets +- id: http://purl.bioontology.org/ontology/MESH/D057805 + name: Pets ``` #### Examples Object From 9eb96c8cad136cca57a661ec362b51f7b3ae838b Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 1 Aug 2017 18:18:26 +0200 Subject: [PATCH 063/104] Update mygene.info.v3.compliant update the tag --- versions/mygene.info.v3.compliant | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/mygene.info.v3.compliant b/versions/mygene.info.v3.compliant index 2e85b64b62..4e7ef8f2c0 100644 --- a/versions/mygene.info.v3.compliant +++ b/versions/mygene.info.v3.compliant @@ -41,8 +41,8 @@ }], "tags": [ { - "name": "http://purl.bioontology.org/ontology/MESH/D005796", - "description": "Genes" + "x-id": "http://purl.bioontology.org/ontology/MESH/D005796", + "name": "Genes" } ], "components": { From 293d4b8636e28a005a6d59ed026b3baed7b05e8a Mon Sep 17 00:00:00 2001 From: Amrapali Zaveri Date: Fri, 4 Aug 2017 12:47:44 +0200 Subject: [PATCH 064/104] Update mygene.info.v3.compliant updated acc. to Shima's changes --- versions/mygene.info.v3.compliant | 445 ++++++++++++------------------ 1 file changed, 178 insertions(+), 267 deletions(-) diff --git a/versions/mygene.info.v3.compliant b/versions/mygene.info.v3.compliant index 4e7ef8f2c0..1090cdddaf 100644 --- a/versions/mygene.info.v3.compliant +++ b/versions/mygene.info.v3.compliant @@ -1,267 +1,178 @@ -{ - "openapi": "string", - "info": { - "version": "3.0.0.2", - "title": "MyGene.info API", - "description": "Documentation of the MyGene.info Gene Query web services. Learn more about [MyGene.info](http://mygene.info/)", - "termsOfService": "http://example.com/terms/", - "contact": { - "name": "Chunlei Wu", - "x-role": "responsible developer", - "email": "help@mygene.info", - "x-id": "http://orcid.org/0000-0002-2629-6124" - }, - "x-accessRestriction": "none", - "x-maturity": "production", - "x-implementationLanguage": "python" - }, - "externalDocs": { - "description": "Find more info here", - "url": "https://example.com" - }, - "x-externalResources": [ - { - "x-url": "http://example.org/api/docs", - "x-type": "api documentation" - }, - { - "x-url": "https://doi.org/10.1093/nar/gks1114", - "x-type": "publication", - "x-description": "BioGPS and MyGene.info: organizing online, gene-centric information" - }, - { - "x-url": "http://twitter.com/mygeneinfo", - "x-type": "social media" - } - ], - "servers": [{ - "url": "http://mygene.info", - "description": "Development server", - "x-location": "California, USA" - }], - "tags": [ - { - "x-id": "http://purl.bioontology.org/ontology/MESH/D005796", - "name": "Genes" - } - ], - "components": { - "schemas": { - "Category": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - } - }, - "Tag": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - } - } - }, - "parameters": { - "skipParam": { - "name": "skip", - "in": "query", - "description": "number of items to skip", - "required": true, - "schema": { - "type": "integer", - "format": "int32" - } - }, - "limitParam": { - "name": "limit", - "in": "query", - "description": "max records to return", - "required": true, - "schema": { - "type": "integer", - "format": "int32" - } - } - }, - "responses": { - "NotFound": { - "description": "Entity not found." - }, - "IllegalInput": { - "description": "Illegal input for operation." - } - }, - "securitySchemes": { - "api_key": { - "type": "apiKey", - "name": "api_key", - "in": "header" - }, - "petstore_auth": { - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "http://example.org/api/oauth/dialog", - "scopes": { - "write:pets": "modify genes in your account", - "read:pets": "read your genes" - } - } - } - } - } - }, - "paths": { - "/query": { - "get": { - "description": "Makes gene query and returns matching gene list.", - "summary": "Makes gene query and returns matching gene list.", - "x-accessRestriction": "fee", - "parameters": [ - { - "name": "q", - "in": "query", - "description": "Query string. Examples \"CDK2\", \"NM_052827\", \"204639_at\". The detailed query syntax can be found at http://docs.mygene.info/en/latest/doc/query_service.html", - "required": true, - "schema": { - "type": "string" - }, - "x-parameterType": "InputParameter", - "x-valueType": [ - "http://identifiers.org/hgnc.symbol", - "http://identifiers.org/refseq", - "http://identifiers.org/unigene", - "http://identifiers.org/uniprot", - "http://identifiers.org/pdb" - ] - } - ], - "operationId": "add operation id here", - "responses": { - "200": { - "description": "Successful response.", - "content": { - "application/json": { - "x-responseProfile": "http://www.w3.org/ns/anno.jsonld", - "x-responseValueType": [ - { - "path": "a.id", - "valueType": "http://example.org/a.id" - }, - { - "path": "a.b.c.id", - "valueType": "http://example.org/c.id" - } - ] - } - } - } - } - } - }, - "/gene/{geneid}": { - "get": { - "tags": [ - "gene" - ], - "parameters": [ - { - "name": "geneid", - "in": "path", - "description": "Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired Entrez Gene id works too if it is replaced by a new one, e.g., 245794", - "required": true, - "x-parameterType": "InputParameter", - "x-valueType": [ - "http://identifiers.org/ncbigene", - "http://identifiers.org/ensembl" - ], - "x-defaultValue": "add default", - "x-exampleValue": "1017" - } - ], - "operationId": "getAnnotation", - "summary": "add summary", - "responses": { - "200": { - "description": "Successful response", - "content": { - "application/json": { - "x-responseSchema": { - "properties": { - "reporter": { - "properties": { - "HTA-2_0": { - "type": "string" - }, - "HG-U133_Plus_2": { - "items": { - "type": "string" - }, - "type": "array" - }, - "HuEx-1_0": { - "type": "integer" - }, - "HuGene-1_1": { - "type": "integer" - }, - "HuGene-2_1": { - "type": "integer" - }, - "HG-U95Av2": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - } - } - }, - - "x-responseValueType": [ - { - "path": "ec", - "valueType": "http://identifiers.org/ec-code/" - }, - { - "path": "ensembl.gene", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "ensembl.translation.protein", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "ensembl.translation.rna", - "valueType": "http://identifiers.org/ensembl/" - }, - { - "path": "entrezgene", - "valueType": "http://identifiers.org/ncbigene/" - }, - { - "path": "generif.pubmed", - "valueType": "http://identifiers.org/pubmed/" - } - ] - } - } - } - } - } - } - } -} +openapi: '3.0' +info: + version: 3.0.0.2 + title: MyGene.info API + description: >- + Documentation of the MyGene.info Gene Query web services. Learn more about + [MyGene.info](http://mygene.info/) + termsOfService: 'http://example.com/terms/' + contact: + name: Chunlei Wu + x-role: responsible developer + email: help@mygene.info + x-id: 'http://orcid.org/0000-0002-2629-6124' + x-accessRestriction: none + x-maturity: production + x-implementationLanguage: python +externalDocs: + description: Find more info here + url: 'https://example.com' +x-externalResources: + - x-url: 'http://example.org/api/docs' + x-type: api documentation + - x-url: 'https://doi.org/10.1093/nar/gks1114' + x-type: publication + x-description: 'BioGPS and MyGene.info: organizing online, gene-centric information' + - x-url: 'http://twitter.com/mygeneinfo' + x-type: social media +servers: + - url: 'http://mygene.info' + description: Development server + x-location: 'California, USA' +tags: + - x-id: 'http://purl.bioontology.org/ontology/MESH/D005796' + name: Genes +components: + schemas: + Category: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + Tag: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + parameters: + skipParam: + name: skip + in: query + description: number of items to skip + required: true + schema: + type: integer + format: int32 + limitParam: + name: limit + in: query + description: max records to return + required: true + schema: + type: integer + format: int32 + responses: + NotFound: + description: Entity not found. + IllegalInput: + description: Illegal input for operation. + securitySchemes: + api_key: + type: apiKey + name: api_key + in: header + petstore_auth: + type: oauth2 + flows: + implicit: + authorizationUrl: 'http://example.org/api/oauth/dialog' + scopes: + 'write:pets': modify genes in your account + 'read:pets': read your genes +paths: + /query: + get: + tags: + - query + description: Makes gene query and returns matching gene list. + summary: Makes gene query and returns matching gene list. + x-accessRestriction: fee + parameters: + - name: q + in: query + description: >- + Query string. Examples "CDK2", "NM_052827", "204639_at". The + detailed query syntax can be found at + http://docs.mygene.info/en/latest/doc/query_service.html + required: true + schema: + type: string + x-parameterType: InputParameter + x-valueType: + - 'http://identifiers.org/hgnc.symbol' + - 'http://identifiers.org/refseq' + - 'http://identifiers.org/unigene' + - 'http://identifiers.org/uniprot' + - 'http://identifiers.org/pdb' + operationId: add operation id here + responses: + '200': + description: Successful response. + content: + application/json: + x-responseProfile: 'http://www.w3.org/ns/anno.jsonld' + '/gene/{geneid}': + get: + tags: + - gene + parameters: + - name: geneid + in: path + description: >- + Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired + Entrez Gene id works too if it is replaced by a new one, e.g., + 245794 + required: true + x-parameterType: InputParameter + x-valueType: + - 'http://identifiers.org/ncbigene' + - 'http://identifiers.org/ensembl' + x-defaultValue: add default + x-exampleValue: '1017' + operationId: getAnnotation + summary: add summary + responses: + '200': + description: Successful response + content: + application/json: + x-responseSchema: + properties: + reporter: + properties: + HTA-2_0: + type: string + HG-U133_Plus_2: + items: + type: string + type: array + HuEx-1_0: + type: integer + HuGene-1_1: + type: integer + HuGene-2_1: + type: integer + HG-U95Av2: + items: + type: string + type: array + type: object + x-responseValueType: + - path: ec + valueType: 'http://identifiers.org/ec-code/' + - path: ensembl.gene + valueType: 'http://identifiers.org/ensembl/' + - path: ensembl.translation.protein + valueType: 'http://identifiers.org/ensembl/' + - path: ensembl.translation.rna + valueType: 'http://identifiers.org/ensembl/' + - path: entrezgene + valueType: 'http://identifiers.org/ncbigene/' + - path: generif.pubmed + valueType: 'http://identifiers.org/pubmed/' From fd658f151cf4adfad57e16de67681ce39b65780e Mon Sep 17 00:00:00 2001 From: Ron Date: Mon, 21 Aug 2017 12:04:16 -0700 Subject: [PATCH 065/104] no more active --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 301161dfb1..01254b3b8c 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,16 @@ ![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) + +# Note + +This is not an active work branch anymore but is currently kept around. For details on how to contribute next, review our [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/master/DEVELOPMENT.md). + + + +--- + + The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service. From ad6dfed289c7fc45a44b54ccaa429d8caef30a3e Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 10:48:41 +0900 Subject: [PATCH 066/104] removed merge comments --- versions/3.0.0.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 1b23b3ca38..52382be5bf 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -354,7 +354,6 @@ Field Name | Type | Description 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. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. -<<<<<<< HEAD:versions/3.0.md ##### smartAPi Fields Field Name | Type | Description @@ -2273,7 +2272,6 @@ Field Name | Type | Description description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. -<<<<<<< HEAD:versions/3.0.md ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- From 19fe55bf5f79f57d96760fc35d61135aec2d24e8 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 10:49:37 +0900 Subject: [PATCH 067/104] removed extra colon in predicate --- versions/3.0.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 52382be5bf..0c900582f3 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -287,8 +287,8 @@ This object MAY be extended with [Specification Extensions](#specificationExtens Field Name | Type | Description ---|:---:|--- -x-role: | `enum` | **REQUIRED** Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. -x-id: | `string` | **SHOULD** Provide a unique identifier for the contact. +x-role | `enum` | **REQUIRED** Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. +x-id | `string` | **SHOULD** Provide a unique identifier for the contact. ##### Contact Object Example: From 9e3b2452adae0b3e23887cff31b5ae7528dfa0d1 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 11:34:53 +0900 Subject: [PATCH 068/104] Create smartapi-list.md --- versions/smartapi-list.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 versions/smartapi-list.md diff --git a/versions/smartapi-list.md b/versions/smartapi-list.md new file mode 100644 index 0000000000..20b96278ef --- /dev/null +++ b/versions/smartapi-list.md @@ -0,0 +1,25 @@ +Object | Field | Recommendation | Datatype | Description +---|:---:|:---:|:---:|--- +OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. +Info Object|description|SHOULD| string |See above. +Info Object|termsOfService|REQUIRED| URL |See above. +Info Object|version|REQUIRED| string |The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. +Info Object|x-maturity|| enum |Maturity of the API. Values to use: development, production. +Info Object|x-accessRestriction|| enum |Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. +Info Object|x-implementationLanguage|| string |Language the API was written in. +Contact Object|x-role|REQUIRED| enum |Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. +Contact Object|x-id|SHOULD| string |Provide a unique identifier for the contact. +Operation Object|summary|REQUIRED| string |See above. +Operation Object|x-accessRestriction|| enum |Access restrictions to invoke the operation. values: none, limited, fee. +External Resource Object [smartAPI extension]|x-url|REQUIRED| string |. The URL for the target documentation. Value MUST be in the format of a URL. +External Resource Object [smartAPI extension]|x-type|REQUIRED| enum |values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` +External Resource Object [smartAPI extension]|x-description|| string |A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +Parameter Object|x-parameterType|SHOULD| uri |A concept URI to describe the type of parameter. +Parameter Object|x-valueType|SHOULD| [uri] |A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from +Parameter Object|x-defaultValue|| string |Default value. +Parameter Object|x-exampleValue|| string |Example value. +Response Object|content|| Map[string, [Media Type Object](#mediaTypeObject)] |A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. +Response Object|x-responseSchema|| URI |Conformance to a particular schema/format. +Response Object|x-responseValueType|| [responseValueType object] |To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. +Response Object|x-JSONLDContext|| URI |JSON LD context. +Tag Object|x-id|| URI |The name of the tag. Recommend that you use URI to specify the concept. From 9e7c35f2b6b4a1fff31b46a54afb6a3b43179883 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 11:38:28 +0900 Subject: [PATCH 069/104] initial import --- versions/smartapi-list.php | 81 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 versions/smartapi-list.php diff --git a/versions/smartapi-list.php b/versions/smartapi-list.php new file mode 100644 index 0000000000..8ab2c17b3f --- /dev/null +++ b/versions/smartapi-list.php @@ -0,0 +1,81 @@ +<\/a>/",$str, -1); // OpenAPI Object +array_shift($list); +array_shift($list); +array_shift($list); +array_shift($list); +array_shift($list); +foreach($list as $item) { + $a = explode("\n",$item, 2); + $object_label = trim($a[0]); + +//echo $object_label.PHP_EOL; + + // now find the smartapi section + $record = false; + $buf = ''; + $a = explode("\n",$a[1]); + foreach($a AS $b) { + // echo "line: $b".PHP_EOL; + + if($record === true) { + //if(strlen(trim($b)) == 0) $record = false; + if(strstr($b,"####")) $record = false; + else { + $buf .= $b.PHP_EOL; + + if(strstr($b,"(.*)/",$cols[0],$m); + $field = trim($m[1]); + + // recommendation + preg_match('/\*\*([^\*]+)/',$desc,$m); //([^*]+)**/',$desc,$m); + $rec = ''; + if(isset($m[1])) { + $rec = $m[1]; + $desc = substr($desc, strlen($rec)+5); + } + $mylist[$object_label][$field]['rec'] = $rec; + $mylist[$object_label][$field]['desc'] = trim($desc); + $mylist[$object_label][$field]['datatype'] = $datatype; + } + } + } + if(strstr($b,"##### smartAPI") !== FALSE) { + $record = true; + } + } + +} + + +// markdown +$file = "smartapi-list.md"; +$fp = fopen($file,"w"); +fwrite($fp,"Object | Field | Recommendation | Datatype | Description".PHP_EOL); +fwrite($fp,"---|:---:|:---:|:---:|---".PHP_EOL); +foreach($mylist AS $object => $o) { + foreach($o as $field => $field_desc) { + fwrite($fp,$object + ."|".$field + ."|".$field_desc['rec'] + ."|".$field_desc['datatype'] + ."|".$field_desc['desc'] + .PHP_EOL); + } +} +fclose($fp); + +echo "$file generated".PHP_EOL; \ No newline at end of file From 1d25b754964bba6992c356c269b716c2abae0134 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 14:14:42 +0900 Subject: [PATCH 070/104] replaced old link --- versions/smartapi-list.md | 6 +++--- versions/smartapi-list.php | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/versions/smartapi-list.md b/versions/smartapi-list.md index 20b96278ef..573a2d9c59 100644 --- a/versions/smartapi-list.md +++ b/versions/smartapi-list.md @@ -1,15 +1,15 @@ Object | Field | Recommendation | Datatype | Description ---|:---:|:---:|:---:|--- OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. -Info Object|description|SHOULD| string |See above. -Info Object|termsOfService|REQUIRED| URL |See above. +Info Object|description|SHOULD| string |See above. +Info Object|termsOfService|REQUIRED| URL |See above. Info Object|version|REQUIRED| string |The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. Info Object|x-maturity|| enum |Maturity of the API. Values to use: development, production. Info Object|x-accessRestriction|| enum |Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. Info Object|x-implementationLanguage|| string |Language the API was written in. Contact Object|x-role|REQUIRED| enum |Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. Contact Object|x-id|SHOULD| string |Provide a unique identifier for the contact. -Operation Object|summary|REQUIRED| string |See above. +Operation Object|summary|REQUIRED| string |See above. Operation Object|x-accessRestriction|| enum |Access restrictions to invoke the operation. values: none, limited, fee. External Resource Object [smartAPI extension]|x-url|REQUIRED| string |. The URL for the target documentation. Value MUST be in the format of a URL. External Resource Object [smartAPI extension]|x-type|REQUIRED| enum |values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` diff --git a/versions/smartapi-list.php b/versions/smartapi-list.php index 8ab2c17b3f..0e9044cc45 100644 --- a/versions/smartapi-list.php +++ b/versions/smartapi-list.php @@ -47,6 +47,8 @@ $rec = $m[1]; $desc = substr($desc, strlen($rec)+5); } + $desc = str_replace("https://github.com/WebsmartAPI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#","https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md", $desc); + $mylist[$object_label][$field]['rec'] = $rec; $mylist[$object_label][$field]['desc'] = trim($desc); $mylist[$object_label][$field]['datatype'] = $datatype; From 743263d2d9ddc50652b01600fb32ae070f72ccf3 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 14:33:49 +0900 Subject: [PATCH 071/104] added links to parent document for smartAPI fields --- versions/smartapi-list.md | 46 +++++++++++++++++++------------------- versions/smartapi-list.php | 15 ++++++++----- 2 files changed, 32 insertions(+), 29 deletions(-) diff --git a/versions/smartapi-list.md b/versions/smartapi-list.md index 573a2d9c59..adaf3b25a9 100644 --- a/versions/smartapi-list.md +++ b/versions/smartapi-list.md @@ -1,25 +1,25 @@ Object | Field | Recommendation | Datatype | Description ---|:---:|:---:|:---:|--- -OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. -Info Object|description|SHOULD| string |See above. -Info Object|termsOfService|REQUIRED| URL |See above. -Info Object|version|REQUIRED| string |The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. -Info Object|x-maturity|| enum |Maturity of the API. Values to use: development, production. -Info Object|x-accessRestriction|| enum |Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. -Info Object|x-implementationLanguage|| string |Language the API was written in. -Contact Object|x-role|REQUIRED| enum |Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. -Contact Object|x-id|SHOULD| string |Provide a unique identifier for the contact. -Operation Object|summary|REQUIRED| string |See above. -Operation Object|x-accessRestriction|| enum |Access restrictions to invoke the operation. values: none, limited, fee. -External Resource Object [smartAPI extension]|x-url|REQUIRED| string |. The URL for the target documentation. Value MUST be in the format of a URL. -External Resource Object [smartAPI extension]|x-type|REQUIRED| enum |values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` -External Resource Object [smartAPI extension]|x-description|| string |A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -Parameter Object|x-parameterType|SHOULD| uri |A concept URI to describe the type of parameter. -Parameter Object|x-valueType|SHOULD| [uri] |A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from -Parameter Object|x-defaultValue|| string |Default value. -Parameter Object|x-exampleValue|| string |Example value. -Response Object|content|| Map[string, [Media Type Object](#mediaTypeObject)] |A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. -Response Object|x-responseSchema|| URI |Conformance to a particular schema/format. -Response Object|x-responseValueType|| [responseValueType object] |To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. -Response Object|x-JSONLDContext|| URI |JSON LD context. -Tag Object|x-id|| URI |The name of the tag. Recommend that you use URI to specify the concept. +OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. +Info Object|description|SHOULD| string |See above. +Info Object|termsOfService|REQUIRED| URL |See above. +Info Object|version|REQUIRED| string |The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. +Info Object|x-maturity|| enum |Maturity of the API. Values to use: development, production. +Info Object|x-accessRestriction|| enum |Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. +Info Object|x-implementationLanguage|| string |Language the API was written in. +Contact Object|x-role|REQUIRED| enum |Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. +Contact Object|x-id|SHOULD| string |Provide a unique identifier for the contact. +Operation Object|summary|REQUIRED| string |See above. +Operation Object|x-accessRestriction|| enum |Access restrictions to invoke the operation. values: none, limited, fee. +External Resource Object [smartAPI extension]|x-url|REQUIRED| string |. The URL for the target documentation. Value MUST be in the format of a URL. +External Resource Object [smartAPI extension]|x-type|REQUIRED| enum |values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` +External Resource Object [smartAPI extension]|x-description|| string |A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +Parameter Object|x-parameterType|SHOULD| uri |A concept URI to describe the type of parameter. +Parameter Object|x-valueType|SHOULD| [uri] |A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from +Parameter Object|x-defaultValue|| string |Default value. +Parameter Object|x-exampleValue|| string |Example value. +Response Object|content|| Map[string, [Media Type Object](#mediaTypeObject)] |A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. +Response Object|x-responseSchema|| URI |Conformance to a particular schema/format. +Response Object|x-responseValueType|| [responseValueType object] |To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. +Response Object|x-JSONLDContext|| URI |JSON LD context. +Tag Object|x-id|| URI |The name of the tag. Recommend that you use URI to specify the concept. diff --git a/versions/smartapi-list.php b/versions/smartapi-list.php index 0e9044cc45..c5fb192a6b 100644 --- a/versions/smartapi-list.php +++ b/versions/smartapi-list.php @@ -1,6 +1,7 @@ <\/a>/",$str, -1); // OpenAPI Object @@ -12,8 +13,6 @@ foreach($list as $item) { $a = explode("\n",$item, 2); $object_label = trim($a[0]); - -//echo $object_label.PHP_EOL; // now find the smartapi section $record = false; @@ -36,9 +35,12 @@ preg_match("/\[\[([^\]]+)\]/",$datatype,$m); if(isset($m[1])) $datatype = $m[1]; } - $desc = $cols[2]; - preg_match("/a>(.*)/",$cols[0],$m); - $field = trim($m[1]); + $desc = $cols[2]; + + // field + preg_match("/<\/a>(.*)/",$cols[0],$m); + $link = trim($m[1]); + $field = trim($m[2]); // recommendation preg_match('/\*\*([^\*]+)/',$desc,$m); //([^*]+)**/',$desc,$m); @@ -52,6 +54,7 @@ $mylist[$object_label][$field]['rec'] = $rec; $mylist[$object_label][$field]['desc'] = trim($desc); $mylist[$object_label][$field]['datatype'] = $datatype; + $mylist[$object_label][$field]['link'] = $link; } } } @@ -71,7 +74,7 @@ foreach($mylist AS $object => $o) { foreach($o as $field => $field_desc) { fwrite($fp,$object - ."|".$field + ."|".''.$field.'' ."|".$field_desc['rec'] ."|".$field_desc['datatype'] ."|".$field_desc['desc'] From 4fdaeea672cabbc62745b7d6be72305368657b01 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 14:51:24 +0900 Subject: [PATCH 072/104] added links to parent document objects --- versions/smartapi-list.md | 46 +++++++++++++++++++------------------- versions/smartapi-list.php | 22 +++++++++++++----- 2 files changed, 40 insertions(+), 28 deletions(-) diff --git a/versions/smartapi-list.md b/versions/smartapi-list.md index adaf3b25a9..d6f743f33c 100644 --- a/versions/smartapi-list.md +++ b/versions/smartapi-list.md @@ -1,25 +1,25 @@ Object | Field | Recommendation | Datatype | Description ---|:---:|:---:|:---:|--- -OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. -Info Object|description|SHOULD| string |See above. -Info Object|termsOfService|REQUIRED| URL |See above. -Info Object|version|REQUIRED| string |The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. -Info Object|x-maturity|| enum |Maturity of the API. Values to use: development, production. -Info Object|x-accessRestriction|| enum |Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. -Info Object|x-implementationLanguage|| string |Language the API was written in. -Contact Object|x-role|REQUIRED| enum |Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. -Contact Object|x-id|SHOULD| string |Provide a unique identifier for the contact. -Operation Object|summary|REQUIRED| string |See above. -Operation Object|x-accessRestriction|| enum |Access restrictions to invoke the operation. values: none, limited, fee. -External Resource Object [smartAPI extension]|x-url|REQUIRED| string |. The URL for the target documentation. Value MUST be in the format of a URL. -External Resource Object [smartAPI extension]|x-type|REQUIRED| enum |values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` -External Resource Object [smartAPI extension]|x-description|| string |A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -Parameter Object|x-parameterType|SHOULD| uri |A concept URI to describe the type of parameter. -Parameter Object|x-valueType|SHOULD| [uri] |A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from -Parameter Object|x-defaultValue|| string |Default value. -Parameter Object|x-exampleValue|| string |Example value. -Response Object|content|| Map[string, [Media Type Object](#mediaTypeObject)] |A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. -Response Object|x-responseSchema|| URI |Conformance to a particular schema/format. -Response Object|x-responseValueType|| [responseValueType object] |To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. -Response Object|x-JSONLDContext|| URI |JSON LD context. -Tag Object|x-id|| URI |The name of the tag. Recommend that you use URI to specify the concept. +OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. +Info Object|description|SHOULD| string |See above. +Info Object|termsOfService|REQUIRED| URL |See above. +Info Object|version|REQUIRED| string |The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. +Info Object|x-maturity|| enum |Maturity of the API. Values to use: development, production. +Info Object|x-accessRestriction|| enum |Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. +Info Object|x-implementationLanguage|| string |Language the API was written in. +Contact Object|x-role|REQUIRED| enum |Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. +Contact Object|x-id|SHOULD| string |Provide a unique identifier for the contact. +Operation Object|summary|REQUIRED| string |See above. +Operation Object|x-accessRestriction|| enum |Access restrictions to invoke the operation. values: none, limited, fee. +External Resource Object [smartAPI extension]|x-url|REQUIRED| string |. The URL for the target documentation. Value MUST be in the format of a URL. +External Resource Object [smartAPI extension]|x-type|REQUIRED| enum |values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` +External Resource Object [smartAPI extension]|x-description|| string |A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +Parameter Object|x-parameterType|SHOULD| uri |A concept URI to describe the type of parameter. +Parameter Object|x-valueType|SHOULD| [uri] |A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from +Parameter Object|x-defaultValue|| string |Default value. +Parameter Object|x-exampleValue|| string |Example value. +Response Object|content|| Map[string, [Media Type Object](#mediaTypeObject)] |A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. +Response Object|x-responseSchema|| URI |Conformance to a particular schema/format. +Response Object|x-responseValueType|| [responseValueType object] |To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. +Response Object|x-JSONLDContext|| URI |JSON LD context. +Tag Object|x-id|| URI |The name of the tag. Recommend that you use URI to specify the concept. diff --git a/versions/smartapi-list.php b/versions/smartapi-list.php index c5fb192a6b..4670a31195 100644 --- a/versions/smartapi-list.php +++ b/versions/smartapi-list.php @@ -1,25 +1,36 @@ <\/a>/",$str, -1); // OpenAPI Object +preg_match_all("/#### <\/a>([^\n]+)/",$str, $header_labels); +foreach($header_labels[2] AS $id => $label) {$header_labels[2][$id] = trim($label);} +function getHeaderLink($label) +{ + global $header_labels; + echo $label.PHP_EOL; + $id = array_search($label, $header_labels[2]); + return $header_labels[1][$id]; +} +$list = preg_split("/#### <\/a>/",$str, -1); + array_shift($list); array_shift($list); array_shift($list); array_shift($list); array_shift($list); -foreach($list as $item) { +foreach($list as $i => $item) { $a = explode("\n",$item, 2); $object_label = trim($a[0]); - + // now find the smartapi section $record = false; $buf = ''; $a = explode("\n",$a[1]); foreach($a AS $b) { - // echo "line: $b".PHP_EOL; if($record === true) { //if(strlen(trim($b)) == 0) $record = false; @@ -73,7 +84,8 @@ fwrite($fp,"---|:---:|:---:|:---:|---".PHP_EOL); foreach($mylist AS $object => $o) { foreach($o as $field => $field_desc) { - fwrite($fp,$object + fwrite($fp, + ''.$object.'' ."|".''.$field.'' ."|".$field_desc['rec'] ."|".$field_desc['datatype'] From ea7a4f732a5a556ca9d2d0b199173662f9adab8f Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 14:53:20 +0900 Subject: [PATCH 073/104] added explanation --- versions/smartapi-list.md | 1 + versions/smartapi-list.php | 1 + 2 files changed, 2 insertions(+) diff --git a/versions/smartapi-list.md b/versions/smartapi-list.md index d6f743f33c..faf2aea406 100644 --- a/versions/smartapi-list.md +++ b/versions/smartapi-list.md @@ -1,3 +1,4 @@ +smartAPI specific elements automatically generated from parent document Object | Field | Recommendation | Datatype | Description ---|:---:|:---:|:---:|--- OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. diff --git a/versions/smartapi-list.php b/versions/smartapi-list.php index 4670a31195..de647d53a0 100644 --- a/versions/smartapi-list.php +++ b/versions/smartapi-list.php @@ -80,6 +80,7 @@ function getHeaderLink($label) // markdown $file = "smartapi-list.md"; $fp = fopen($file,"w"); +fwrite($fp,"smartAPI specific elements automatically generated from parent document".PHP_EOL); fwrite($fp,"Object | Field | Recommendation | Datatype | Description".PHP_EOL); fwrite($fp,"---|:---:|:---:|:---:|---".PHP_EOL); foreach($mylist AS $object => $o) { From b2f1feb1379fd0328b00f654a3b7607104afdcd2 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 12 Sep 2017 15:20:35 +0900 Subject: [PATCH 074/104] added header --- versions/smartapi-list.md | 1 + versions/smartapi-list.php | 4 +--- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/versions/smartapi-list.md b/versions/smartapi-list.md index faf2aea406..4a4370dafc 100644 --- a/versions/smartapi-list.md +++ b/versions/smartapi-list.md @@ -1,4 +1,5 @@ smartAPI specific elements automatically generated from parent document + Object | Field | Recommendation | Datatype | Description ---|:---:|:---:|:---:|--- OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. diff --git a/versions/smartapi-list.php b/versions/smartapi-list.php index de647d53a0..696a7f5878 100644 --- a/versions/smartapi-list.php +++ b/versions/smartapi-list.php @@ -11,7 +11,6 @@ function getHeaderLink($label) { global $header_labels; - echo $label.PHP_EOL; $id = array_search($label, $header_labels[2]); return $header_labels[1][$id]; } @@ -76,11 +75,10 @@ function getHeaderLink($label) } - // markdown $file = "smartapi-list.md"; $fp = fopen($file,"w"); -fwrite($fp,"smartAPI specific elements automatically generated from parent document".PHP_EOL); +fwrite($fp,"smartAPI specific elements automatically generated from parent document".PHP_EOL.PHP_EOL); fwrite($fp,"Object | Field | Recommendation | Datatype | Description".PHP_EOL); fwrite($fp,"---|:---:|:---:|:---:|---".PHP_EOL); foreach($mylist AS $object => $o) { From 9c6ea2d9c03559427c19c697e6a25fb2c30eed2e Mon Sep 17 00:00:00 2001 From: Chunlei Wu Date: Wed, 13 Sep 2017 15:57:57 +0900 Subject: [PATCH 075/104] added smartapi_schema.json file --- schemas/smartapi_schema.json | 1402 ++++++++++++++++++++++++++++++++++ 1 file changed, 1402 insertions(+) create mode 100644 schemas/smartapi_schema.json diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json new file mode 100644 index 0000000000..a0e0f4090e --- /dev/null +++ b/schemas/smartapi_schema.json @@ -0,0 +1,1402 @@ +{ + "title": "A JSON Schema for OpenAPI 3.0.", + "id": "http://openapis.org/v3/schema.json#", + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "This is the root document object of the OpenAPI definition file.", + "required": [ + "openapi", + "info", + "paths" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "openapi": { + "type": "string" + }, + "info": { + "$ref": "#/definitions/info" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/server" + }, + "uniqueItems": true + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "components": { + "$ref": "#/definitions/components" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/definitions/securityRequirement" + }, + "uniqueItems": true + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/tag" + }, + "uniqueItems": true + }, + "externalDocs": { + "$ref": "#/definitions/externalDocs" + }, + "x-externalResources": { + "type": "array", + "items": { + "$ref": "#/definitions/externalResource" + }, + "uniqueItems": true + } + }, + "definitions": { + "info": { + "type": "object", + "description": "The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience.", + "required": [ + "title", + "version" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "title": { + "type": "string" + }, + "description": { + "type": "string" + }, + "termsOfService": { + "type": "string" + }, + "contact": { + "$ref": "#/definitions/contact" + }, + "license": { + "$ref": "#/definitions/license" + }, + "version": { + "type": "string" + }, + "x-accessRestriction": { + "type": "string", + "enum": [ + "none", + "limited", + "fee" + ], + "description": "Indicate whether there are restrictions to using the API. Values to use: none, limited, fee." + }, + "x-implementationLanguage": { + "type": "string", + "description": "API Implementation Language" + }, + "x-maturity": { + "type": "string", + "enum": [ + "development", + "production" + ], + "description": "Maturity of the API. Values to use: development, production." + } + } + }, + "contact": { + "type": "object", + "description": "Contact information for the exposed API.", + "required": [ + "name", + "email", + "x-role" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string", + "format": "url" + }, + "email": { + "type": "string", + "format": "email" + }, + "x-role": { + "type": "string", + "enum": [ + "responsible organization", + "responsible developer", + "contributor", + "support" + ], + "description": "The role of the contact person. Values can be: responsible organization,responsible developer,contributor,support." + }, + "x-id": { + "type": "string", + "description": "The identifier of of the contact person (e.g. orchid Id)" + } + } + }, + "license": { + "type": "object", + "description": "License information for the exposed API.", + "required": [ + "name" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string" + } + } + }, + "server": { + "type": "object", + "description": "An object representing a Server.", + "required": [ + "url" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "url": { + "type": "string" + }, + "description": { + "type": "string" + }, + "variables": { + "$ref": "#/definitions/serverVariables" + }, + "x-location": { + "type": "string", + "description": "Location, city and country of the server hosting the API." + } + } + }, + "serverVariable": { + "type": "object", + "description": "An object representing a Server Variable for server URL template substitution.", + "required": [ + "default" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "enum": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "default": { + "type": "string" + }, + "description": { + "type": "string" + } + } + }, + "components": { + "type": "object", + "description": "Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "schemas": { + "$ref": "#/definitions/schemasOrReferences" + }, + "responses": { + "$ref": "#/definitions/responsesOrReferences" + }, + "parameters": { + "$ref": "#/definitions/parametersOrReferences" + }, + "examples": { + "$ref": "#/definitions/examplesOrReferences" + }, + "requestBodies": { + "$ref": "#/definitions/requestBodiesOrReferences" + }, + "headers": { + "$ref": "#/definitions/headersOrReferences" + }, + "securitySchemes": { + "$ref": "#/definitions/securitySchemesOrReferences" + }, + "links": { + "$ref": "#/definitions/linksOrReferences" + }, + "callbacks": { + "$ref": "#/definitions/callbacksOrReferences" + } + } + }, + "paths": { + "type": "object", + "description": "Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the `Server Object` in order to construct the full URL. The Paths MAY be empty, due to ACL constraints.", + "additionalProperties": false, + "patternProperties": { + "^/": { + "$ref": "#/definitions/pathItem" + }, + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + } + }, + "pathItem": { + "type": "object", + "description": "Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "$ref": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "get": { + "$ref": "#/definitions/operation" + }, + "put": { + "$ref": "#/definitions/operation" + }, + "post": { + "$ref": "#/definitions/operation" + }, + "delete": { + "$ref": "#/definitions/operation" + }, + "options": { + "$ref": "#/definitions/operation" + }, + "head": { + "$ref": "#/definitions/operation" + }, + "patch": { + "$ref": "#/definitions/operation" + }, + "trace": { + "$ref": "#/definitions/operation" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/server" + }, + "uniqueItems": true + }, + "parameters": { + "type": "array", + "items": { + "$ref": "#/definitions/parameterOrReference" + }, + "uniqueItems": true + } + } + }, + "operation": { + "type": "object", + "description": "Describes a single API operation on a path.", + "required": [ + "responses", + "summary" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/definitions/externalDocs" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "type": "array", + "items": { + "$ref": "#/definitions/parameter" + }, + "uniqueItems": true + }, + "requestBody": { + "$ref": "#/definitions/requestBodyOrReference" + }, + "responses": { + "$ref": "#/definitions/responses" + }, + "callbacks": { + "$ref": "#/definitions/callbacksOrReferences" + }, + "deprecated": { + "type": "boolean" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/definitions/securityRequirement" + }, + "uniqueItems": true + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/server" + }, + "uniqueItems": true + }, + "x-accessRestriction": { + "type": "string", + "description": "Access restrictions to invoke the operation. values: none, limited, fee.", + "enum": [ + "none", + "limited", + "fee" + ] + } + } + }, + "externalDocs": { + "type": "object", + "description": "Allows referencing an external resource for extended documentation.", + "required": [ + "url" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "description": { + "type": "string" + }, + "url": { + "type": "string" + } + } + }, + "externalResource": { + "type": "object", + "additionalProperties": false, + "description": "information about external documentation", + "required": [ + "x-url", + "x-type" + ], + "properties": { + "x-description": { + "type": "string", + "description": "A short description of the target documentation. CommonMark syntax can be used for rich text representation." + }, + "x-url": { + "type": "string", + "format": "url" + }, + "x-type": { + "type": "string", + "enum": [ + "api documentation", + "website", + "developer forum", + "mailing list", + "social media", + "publication" + ] + } + }, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + } + }, + "parameter": { + "type": "object", + "additionalProperties": false, + "description": "Describes a single operation parameter. A unique parameter is defined by a combination of a name and location.", + "required": [ + "name", + "in" + ], + "properties": { + "name": { + "type": "string" + }, + "in": { + "type": "string" + }, + "description": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "deprecated": { + "type": "boolean" + }, + "allowEmptyValue": { + "type": "boolean" + }, + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean" + }, + "schema": { + "$ref": "#/definitions/schemaOrReference" + }, + "example": { + "$ref": "#/definitions/any" + }, + "examples": { + "$ref": "#/definitions/examplesOrReferences" + }, + "content": { + "$ref": "#/definitions/mediaTypes" + }, + "x-parameterType": { + "type": "string", + "description": "Type of parameter, e.g. InputParameter, NumberOfResultsReturned, OffsetParameter, SortParameter." + }, + "x-valueType": { + "type": "array", + "description": "a list of semantic identifiers of the parameter from identifiers.org, e.g. [http://identifiers.org/ncbigene/]", + "items": { + "type": "string", + "format": "url" + }, + "uniqueItems": true + }, + "x-defaultValue": { + "type": "string" + }, + "x-exampleValue": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + } + }, + "requestBody": { + "type": "object", + "description": "Describes a single request body.", + "required": [ + "content" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "description": { + "type": "string" + }, + "content": { + "$ref": "#/definitions/mediaTypes" + }, + "required": { + "type": "boolean" + } + } + }, + "mediaType": { + "type": "object", + "description": "Each Media Type Object provides schema and examples for the media type identified by its key.", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "schema": { + "$ref": "#/definitions/schemaOrReference" + }, + "example": { + "$ref": "#/definitions/any" + }, + "examples": { + "$ref": "#/definitions/examplesOrReferences" + }, + "encoding": { + "$ref": "#/definitions/encodings" + } + } + }, + "encoding": { + "type": "object", + "description": "A single encoding definition applied to a single schema property.", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "contentType": { + "type": "string" + }, + "headers": { + "$ref": "#/definitions/headers" + }, + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean" + } + } + }, + "responses": { + "type": "object", + "description": "A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call.", + "additionalProperties": false, + "patternProperties": { + "^([0-9X]{3})$": { + "$ref": "#/definitions/responseOrReference" + }, + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "default": { + "$ref": "#/definitions/responseOrReference" + } + } + }, + "response": { + "type": "object", + "description": "Describes a single response from an API Operation, including design-time, static `links` to operations based on the response.", + "required": [ + "description" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "description": { + "type": "string" + }, + "headers": { + "$ref": "#/definitions/headersOrReferences" + }, + "content": { + "$ref": "#/definitions/mediaTypes" + }, + "links": { + "$ref": "#/definitions/linksOrReferences" + }, + "x-responseValueType": { + "type": "array", + "items": { + "$ref": "#/definitions/responseItems" + } + }, + "x-responseSchema": { + "type": "string", + "format": "url", + "description": "Conformance to a particular schema/format" + }, + "x-JSONLDContext": { + "type": "string", + "format": "url", + "description": "JSON LD context" + } + } + }, + "responseItems": { + "type": "object", + "properties": { + "elementPath": { + "type": "string" + }, + "datatype": { + "type": "string" + } + } + }, + "callback": { + "type": "object", + "description": "A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.", + "additionalProperties": false, + "patternProperties": { + "^": { + "$ref": "#/definitions/pathItem" + }, + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + } + }, + "example": { + "type": "object", + "description": "", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "value": { + "$ref": "#/definitions/any" + }, + "externalValue": { + "type": "string" + } + } + }, + "link": { + "type": "object", + "description": "The `Link object` represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "operationRef": { + "type": "string" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "$ref": "#/definitions/parameter" + }, + "requestBody": { + "$ref": "#/definitions/anyOrExpression" + }, + "description": { + "type": "string" + }, + "server": { + "$ref": "#/definitions/server" + } + } + }, + "header": { + "type": "object", + "description": "The Header Object follows the structure of the Parameter Object with the following changes: 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, `style`).", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "description": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "deprecated": { + "type": "boolean" + }, + "allowEmptyValue": { + "type": "boolean" + }, + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean" + }, + "schema": { + "$ref": "#/definitions/schemaOrReference" + }, + "example": { + "$ref": "#/definitions/any" + }, + "examples": { + "$ref": "#/definitions/examplesOrReferences" + }, + "content": { + "$ref": "#/definitions/mediaTypes" + } + } + }, + "tag": { + "type": "object", + "description": "Adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.", + "required": [ + "name" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/definitions/externalDocs" + }, + "x-id": { + "type": "string", + "description": "The name of the tag. Recommend that you use URI to specify the concept." + } + } + }, + "examples": { + "type": "object", + "description": "", + "additionalProperties": false + }, + "reference": { + "type": "object", + "description": "A simple object to allow referencing other components in the specification, internally and externally. The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules. For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.", + "required": [ + "$ref" + ], + "additionalProperties": false, + "properties": { + "$ref": { + "type": "string" + } + } + }, + "schema": { + "type": "object", + "description": "The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00. For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "nullable": { + "type": "boolean" + }, + "discriminator": { + "$ref": "#/definitions/discriminator" + }, + "readOnly": { + "type": "boolean" + }, + "writeOnly": { + "type": "boolean" + }, + "xml": { + "$ref": "#/definitions/xml" + }, + "externalDocs": { + "$ref": "#/definitions/externalDocs" + }, + "example": { + "$ref": "#/definitions/any" + }, + "deprecated": { + "type": "boolean" + }, + "title": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/title" + }, + "multipleOf": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/multipleOf" + }, + "maximum": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/maximum" + }, + "exclusiveMaximum": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMaximum" + }, + "minimum": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/minimum" + }, + "exclusiveMinimum": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMinimum" + }, + "maxLength": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/maxLength" + }, + "minLength": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/minLength" + }, + "pattern": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/pattern" + }, + "maxItems": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/maxItems" + }, + "minItems": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/minItems" + }, + "uniqueItems": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/uniqueItems" + }, + "maxProperties": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/maxProperties" + }, + "minProperties": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/minProperties" + }, + "required": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/required" + }, + "enum": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/enum" + }, + "type": { + "type": "string" + }, + "allOf": { + "type": "array", + "items": { + "$ref": "#/definitions/schemaOrReference" + }, + "minItems": 1 + }, + "oneOf": { + "type": "array", + "items": { + "$ref": "#/definitions/schemaOrReference" + }, + "minItems": 1 + }, + "anyOf": { + "type": "array", + "items": { + "$ref": "#/definitions/schemaOrReference" + }, + "minItems": 1 + }, + "not": { + "$ref": "#/definitions/schema" + }, + "items": { + "anyOf": [ + { + "$ref": "#/definitions/schemaOrReference" + }, + { + "type": "array", + "items": { + "$ref": "#/definitions/schemaOrReference" + }, + "minItems": 1 + } + ] + }, + "properties": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/schemaOrReference" + } + }, + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/schemaOrReference" + }, + { + "type": "boolean" + } + ] + }, + "default": { + "$ref": "#/definitions/defaultType" + }, + "description": { + "type": "string" + }, + "format": { + "type": "string" + } + } + }, + "discriminator": { + "type": "object", + "description": "When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. When using the discriminator, _inline_ schemas will not be considered.", + "required": [ + "propertyName" + ], + "additionalProperties": false, + "properties": { + "propertyName": { + "type": "string" + }, + "mapping": { + "$ref": "#/definitions/strings" + } + } + }, + "xml": { + "type": "object", + "description": "A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior.", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string" + }, + "prefix": { + "type": "string" + }, + "attribute": { + "type": "boolean" + }, + "wrapped": { + "type": "boolean" + } + } + }, + "securityScheme": { + "type": "object", + "description": "Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code).", + "required": [ + "type" + ], + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "type": { + "type": "string" + }, + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "in": { + "type": "string" + }, + "scheme": { + "type": "string" + }, + "bearerFormat": { + "type": "string" + }, + "flows": { + "$ref": "#/definitions/oauthFlows" + }, + "openIdConnectUrl": { + "type": "string" + } + } + }, + "oauthFlows": { + "type": "object", + "description": "Allows configuration of the supported OAuth Flows.", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "implicit": { + "$ref": "#/definitions/oauthFlow" + }, + "password": { + "$ref": "#/definitions/oauthFlow" + }, + "clientCredentials": { + "$ref": "#/definitions/oauthFlow" + }, + "authorizationCode": { + "$ref": "#/definitions/oauthFlow" + } + } + }, + "oauthFlow": { + "type": "object", + "description": "Configuration details for a supported OAuth Flow", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "authorizationUrl": { + "type": "string" + }, + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/definitions/strings" + } + } + }, + "securityRequirement": { + "type": "object", + "description": "Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object. Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the Open API object or Operation Object, only one of Security Requirement Objects in the list needs to be satisfied to authorize the request.", + "additionalProperties": false, + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + } + } + }, + "anyOrExpression": { + "oneOf": [ + { + "$ref": "#/definitions/any" + }, + { + "$ref": "#/definitions/expression" + } + ] + }, + "callbackOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/callback" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "exampleOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/example" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "headerOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/header" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "linkOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/link" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "parameterOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/parameter" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "requestBodyOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/requestBody" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "responseOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/response" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "schemaOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/schema" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "securitySchemeOrReference": { + "oneOf": [ + { + "$ref": "#/definitions/securityScheme" + }, + { + "$ref": "#/definitions/reference" + } + ] + }, + "anysOrExpressions": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/anyOrExpression" + } + }, + "callbacksOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/callbackOrReference" + } + }, + "encodings": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/encoding" + } + }, + "examplesOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/exampleOrReference" + } + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/header" + } + }, + "headersOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/headerOrReference" + } + }, + "linksOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/linkOrReference" + } + }, + "mediaTypes": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/mediaType" + } + }, + "parametersOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/parameterOrReference" + } + }, + "requestBodiesOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/requestBodyOrReference" + } + }, + "responsesOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/responseOrReference" + } + }, + "schemasOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/schemaOrReference" + } + }, + "securitySchemesOrReferences": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/securitySchemeOrReference" + } + }, + "serverVariables": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/serverVariable" + } + }, + "strings": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "object": { + "type": "object", + "additionalProperties": true + }, + "any": { + "additionalProperties": true + }, + "expression": { + "type": "object", + "additionalProperties": true + }, + "specificationExtension": { + "description": "Any property starting with x- is valid.", + "oneOf": [ + { + "type": "null" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "string" + }, + { + "type": "object" + }, + { + "type": "array" + } + ] + }, + "defaultType": { + "oneOf": [ + { + "type": "null" + }, + { + "type": "array" + }, + { + "type": "object" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "string" + } + ] + } + } +} From 9cb1f22c52db692263bd3bbf47705c949e34dab2 Mon Sep 17 00:00:00 2001 From: Chunlei Wu Date: Mon, 18 Sep 2017 14:13:00 -0700 Subject: [PATCH 076/104] allow x-id to be an array or just a single string. --- schemas/smartapi_schema.json | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index a0e0f4090e..6bf4887a2f 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -153,7 +153,17 @@ "description": "The role of the contact person. Values can be: responsible organization,responsible developer,contributor,support." }, "x-id": { - "type": "string", + "oneOf": [ + { + "type": "array", + "item": { + "type": "string" + } + }, + { + "type": "string" + } + ], "description": "The identifier of of the contact person (e.g. orchid Id)" } } From cc715b13acb2058671bca89de723f7b673095717 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 17:36:23 +0200 Subject: [PATCH 077/104] updated documentation to allow for one or more identifiers to be provided for a contact --- versions/3.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 0c900582f3..41b8245b97 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -288,7 +288,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens Field Name | Type | Description ---|:---:|--- x-role | `enum` | **REQUIRED** Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. -x-id | `string` | **SHOULD** Provide a unique identifier for the contact. +x-id | [`string`] | **SHOULD** One or more unique identifiers for the contact. ##### Contact Object Example: From 88389513aeea5ff02b219c8469e59ea1c9894f1a Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 20:24:24 +0200 Subject: [PATCH 078/104] removed absolute paths in favour of local paths for anchors --- versions/3.0.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 41b8245b97..452ed09f22 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -225,8 +225,8 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -description | `string` | **SHOULD** See above. -termsOfService | `URL` | **REQUIRED** See above. +description | `string` | **SHOULD** See above. +termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. x-maturity | `enum` | Maturity of the API. Values to use: development, production. x-accessRestriction | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. @@ -879,7 +879,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens Field Name | Type | Description ---|:---:|--- -summary | `string` | **REQUIRED** See above. +summary | `string` | **REQUIRED** See above. x-accessRestriction | `enum` | Access restrictions to invoke the operation. values: none, limited, fee. ##### Operation Object Example From f076006b6b7ed4f3c8f56b715ab62d5e48872861 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 21:18:14 +0200 Subject: [PATCH 079/104] moved maturity to server object --- schemas/smartapi_schema.json | 17 +++++++++-------- versions/3.0.0.md | 10 +++++----- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 6bf4887a2f..858e985ecf 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -105,14 +105,6 @@ "x-implementationLanguage": { "type": "string", "description": "API Implementation Language" - }, - "x-maturity": { - "type": "string", - "enum": [ - "development", - "production" - ], - "description": "Maturity of the API. Values to use: development, production." } } }, @@ -214,6 +206,15 @@ "x-location": { "type": "string", "description": "Location, city and country of the server hosting the API." + }, + "x-maturity": { + "type": "string", + "enum": [ + "development", + "staging", + "production" + ], + "description": "Maturity of the API. Values to use: development, staging, production." } } }, diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 452ed09f22..f9af478bdf 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -225,10 +225,9 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -description | `string` | **SHOULD** See above. -termsOfService | `URL` | **REQUIRED** See above. +description | `string` | **SHOULD** See above. +termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. -x-maturity | `enum` | Maturity of the API. Values to use: development, production. x-accessRestriction | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. x-implementationLanguage | `string` | Language the API was written in. @@ -354,11 +353,12 @@ Field Name | Type | Description 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. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. -##### smartAPi Fields +##### smartAPI Fields Field Name | Type | Description ---|:---:|--- x-location | `string` | Location, city and country of the server hosting the API. +x-maturity | `enum` | Maturity of the API. Values to use: development, staging, production. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -879,7 +879,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens Field Name | Type | Description ---|:---:|--- -summary | `string` | **REQUIRED** See above. +summary | `string` | **REQUIRED** See above. x-accessRestriction | `enum` | Access restrictions to invoke the operation. values: none, limited, fee. ##### Operation Object Example From 12c185e281c66adfd6f6621cc18aab0cb9e985d1 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 21:20:50 +0200 Subject: [PATCH 080/104] change back list of ids to a single one --- schemas/smartapi_schema.json | 14 ++------------ versions/3.0.0.md | 2 +- 2 files changed, 3 insertions(+), 13 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 858e985ecf..881b51009a 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -145,18 +145,8 @@ "description": "The role of the contact person. Values can be: responsible organization,responsible developer,contributor,support." }, "x-id": { - "oneOf": [ - { - "type": "array", - "item": { - "type": "string" - } - }, - { - "type": "string" - } - ], - "description": "The identifier of of the contact person (e.g. orchid Id)" + "type": "string", + "description": "An HTTP identifier for the contact (e.g. orcid id github id)" } } }, diff --git a/versions/3.0.0.md b/versions/3.0.0.md index f9af478bdf..2376cf7ebe 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -287,7 +287,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens Field Name | Type | Description ---|:---:|--- x-role | `enum` | **REQUIRED** Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. -x-id | [`string`] | **SHOULD** One or more unique identifiers for the contact. +x-id | `string` | **SHOULD** A unique identifiers for the contact. ##### Contact Object Example: From a83538ce32ea0f0c4d18e665bb4757b7313bbfb9 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 21:29:09 +0200 Subject: [PATCH 081/104] added otherContacts --- schemas/smartapi_schema.json | 8 +++++++- versions/3.0.0.md | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 881b51009a..61d0c8ea1c 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -92,6 +92,12 @@ }, "version": { "type": "string" + }, + "x-otherContacts": { + "type": "array", + "items": { + "$ref": "#/definitions/contact" + } }, "x-accessRestriction": { "type": "string", @@ -146,7 +152,7 @@ }, "x-id": { "type": "string", - "description": "An HTTP identifier for the contact (e.g. orcid id github id)" + "description": "A resolvable HTTP URI that uniqely identifies the contact (e.g. orcid id github id)" } } }, diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 2376cf7ebe..779ce6b746 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -228,6 +228,7 @@ Field Name | Type | Description description | `string` | **SHOULD** See above. termsOfService | `URL` | **REQUIRED** See above. version | `string` | **REQUIRED** The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. +contacts | [[Contact Object](#contactObject)] | A list of other contacts. x-accessRestriction | `enum` | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. x-implementationLanguage | `string` | Language the API was written in. @@ -289,7 +290,6 @@ Field Name | Type | Description x-role | `enum` | **REQUIRED** Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. x-id | `string` | **SHOULD** A unique identifiers for the contact. - ##### Contact Object Example: ```json From 2aeb3d3cf338e0c39da13984ba1df5f9f2a8f008 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 21:31:56 +0200 Subject: [PATCH 082/104] removed x-default and x-example in favor of using the schema object --- schemas/smartapi_schema.json | 6 ------ versions/3.0.0.md | 4 ++-- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 61d0c8ea1c..184efbd15c 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -546,12 +546,6 @@ "format": "url" }, "uniqueItems": true - }, - "x-defaultValue": { - "type": "string" - }, - "x-exampleValue": { - "type": "string" } }, "patternProperties": { diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 779ce6b746..b88e06d08e 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -1136,8 +1136,8 @@ Field Name | Type | Description ---|:---:|--- x-parameterType | `uri` | **SHOULD** A concept URI to describe the type of parameter. x-valueType | [`uri`] | **SHOULD** A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from -x-defaultValue | `string` | Default value. -x-exampleValue | `string` | Example value. + | | Use the Schema object to define a default value. + | | Use the Schema object to define an example. ##### Parameter Object Examples From 410c3859352469ccfe1f344142139b13d9754ab8 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 21:34:17 +0200 Subject: [PATCH 083/104] use boldface for emphasis --- versions/3.0.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index b88e06d08e..3b9831af6f 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -1136,8 +1136,8 @@ Field Name | Type | Description ---|:---:|--- x-parameterType | `uri` | **SHOULD** A concept URI to describe the type of parameter. x-valueType | [`uri`] | **SHOULD** A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from - | | Use the Schema object to define a default value. - | | Use the Schema object to define an example. + | | **defaults** Use the Schema object to define a default value. + | | **examples** Use the Schema object to define examples. ##### Parameter Object Examples From 8935b7aa113cafe20c5d22fb05ce976d10ec636a Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 21:41:37 +0200 Subject: [PATCH 084/104] cleaned up the text on content-type map --- versions/3.0.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 3b9831af6f..bfa2942e3d 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -265,7 +265,6 @@ license: url: http://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 x-accessRestriction: none -x-maturity: production x-implementationLanguage: python ``` @@ -378,6 +377,7 @@ A single server would be described as: url: https://development.gigantic-server.com/v1 description: Development server x-location: California, USA +x-maturity: production ``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): @@ -1777,7 +1777,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ##### smartAPI Fields Field Name | Type | Description ---|:---:|--- -content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. +content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **SHOULD** Use media type definitions listed at RFC6838. x-responseSchema| `URI` | Conformance to a particular schema/format. x-responseValueType | [`responseValueType object`] | To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. x-JSONLDContext | `URI` | JSON LD context. From af130be314f7ab9b5bdc9e976a1d6f8bdfd3baa6 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 21:42:01 +0200 Subject: [PATCH 085/104] moved x-maturity from info to server --- versions/3.0.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index bfa2942e3d..1ed13dc50d 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -369,7 +369,8 @@ A single server would be described as: { "url": "https://development.gigantic-server.com/v1", "description": "Development server", - "x-location": "California, USA" + "x-location": "California, USA", + "x-maturity": "production" } ``` From 193fea6fc9f1ce51415631143ecb9b4c31083e18 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Thu, 26 Oct 2017 21:43:12 +0200 Subject: [PATCH 086/104] changed example for default and example value --- versions/3.0.0.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 1ed13dc50d..31910fccde 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -1194,10 +1194,11 @@ description: username to fetch required: true schema: type: string + example: bob1234 + default: anonymous x-parameterType: http://example.org/username x-valueType: http://example.org/facebookid -x-defaultValue: -x-exampleValue: bob + ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: From c97dcaea1878f247d2dcc0a8d9b132d6e03a0f58 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 27 Oct 2017 15:00:09 +0200 Subject: [PATCH 087/104] updated the list of smartapi --- versions/smartapi-list.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/versions/smartapi-list.md b/versions/smartapi-list.md index 4a4370dafc..8d098a089e 100644 --- a/versions/smartapi-list.md +++ b/versions/smartapi-list.md @@ -3,24 +3,25 @@ smartAPI specific elements automatically generated from OpenAPI Object|x-externalResources||External Resource Object|A list of external resources pertinent to the API. -Info Object|description|SHOULD| string |See above. -Info Object|termsOfService|REQUIRED| URL |See above. +Info Object|description|SHOULD| string |See above. +Info Object|termsOfService|REQUIRED| URL |See above. Info Object|version|REQUIRED| string |The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. -Info Object|x-maturity|| enum |Maturity of the API. Values to use: development, production. +Info Object|contacts||Contact Object|A list of other contacts. Info Object|x-accessRestriction|| enum |Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. Info Object|x-implementationLanguage|| string |Language the API was written in. Contact Object|x-role|REQUIRED| enum |Indicate the role of the contact. Values can be: `responsible organization`,`responsible developer`,`contributor`,`support`. -Contact Object|x-id|SHOULD| string |Provide a unique identifier for the contact. -Operation Object|summary|REQUIRED| string |See above. +Contact Object|x-id|SHOULD| string |A unique identifiers for the contact. +Server Object|x-location|| string |Location, city and country of the server hosting the API. +Server Object|x-maturity|| enum |Maturity of the API. Values to use: development, staging, production. +Operation Object|summary|REQUIRED| string |See above. Operation Object|x-accessRestriction|| enum |Access restrictions to invoke the operation. values: none, limited, fee. External Resource Object [smartAPI extension]|x-url|REQUIRED| string |. The URL for the target documentation. Value MUST be in the format of a URL. External Resource Object [smartAPI extension]|x-type|REQUIRED| enum |values: `api documentation`, `website`,`developer forum`,`mailing list`,`social media`,`publication` External Resource Object [smartAPI extension]|x-description|| string |A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. Parameter Object|x-parameterType|SHOULD| uri |A concept URI to describe the type of parameter. Parameter Object|x-valueType|SHOULD| [uri] |A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from -Parameter Object|x-defaultValue|| string |Default value. -Parameter Object|x-exampleValue|| string |Example value. -Response Object|content|| Map[string, [Media Type Object](#mediaTypeObject)] |A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.The media type definitions should be in compliance with RFC6838. +Parameter Object||examples| |Use the Schema object to define examples. +Response Object|content|SHOULD| Map[string, [Media Type Object](#mediaTypeObject)] |Use media type definitions listed at RFC6838. Response Object|x-responseSchema|| URI |Conformance to a particular schema/format. Response Object|x-responseValueType|| [responseValueType object] |To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. Response Object|x-JSONLDContext|| URI |JSON LD context. From a2962b38d9ebd1ad0ccaefdca2895b32014bd97e Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 27 Oct 2017 20:45:24 +0200 Subject: [PATCH 088/104] refactored the json-ld + schema parts --- versions/3.0.0.md | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 31910fccde..272fedf975 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -1780,9 +1780,9 @@ This object MAY be extended with [Specification Extensions](#specificationExtens Field Name | Type | Description ---|:---:|--- content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **SHOULD** Use media type definitions listed at RFC6838. -x-responseSchema| `URI` | Conformance to a particular schema/format. -x-responseValueType | [`responseValueType object`] | To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. -x-JSONLDContext | `URI` | JSON LD context. + | `URI` | Specify the json schema using a Reference Object, or use "x-uri" as an additional property in the schema field to point to an external location for an XML, RDF, etc schema. +x-responseValueType | [`responseValueType`] \| [Reference Object](#referenceObject)] | Specify the types of objects and relations in the response using either a reference to the JSON-LD context file or to a [Response Value Type](responseValueType). + ##### Response Object Examples @@ -1906,19 +1906,33 @@ Response with no return value: ```yaml description: object created ``` -##### Response Object smartAPI Examples + + + + + +#### Response Value Type [smartAPI extension] + + that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. + + +##### smartAPI Fields + +Field Name | Type | Description +---|:---:|--- +x-path | `string` | The path using dot notation to the element of interest. e.g. friend.name to follow the path from root object to the name attribute to the name field +x-valueType | `string` | The value type for the field. e.g. + +##### Response Value Type Object smartAPI Example + ```yaml -responses: - - content: - - 'application/ld+json': - x-responseProfile: 'http://www.w3.org/ns/anno.jsonld' - x-responseValueType: - - x-path: a.id - x-valueType: 'http://example.org/a.id' - - x-path: a.b.c.id - x-valueType: 'http://example.org/c.id' +- x-path: ncbigene.id + x-valueType: http://identifiers.org/ncbigene:12345 + ``` + + #### Callback Object A map of possible out-of band callbacks related to the parent operation. From f9d2da3a947fe950e8530f1e4d82f93888c87cbb Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 27 Oct 2017 20:53:58 +0200 Subject: [PATCH 089/104] added response value type object --- versions/3.0.0.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 272fedf975..cd502bff86 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -45,6 +45,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) + - [Response Value Type Object](#responseValueTypeObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) @@ -1781,7 +1782,7 @@ Field Name | Type | Description ---|:---:|--- content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **SHOULD** Use media type definitions listed at RFC6838. | `URI` | Specify the json schema using a Reference Object, or use "x-uri" as an additional property in the schema field to point to an external location for an XML, RDF, etc schema. -x-responseValueType | [`responseValueType`] \| [Reference Object](#referenceObject)] | Specify the types of objects and relations in the response using either a reference to the JSON-LD context file or to a [Response Value Type](responseValueType). +x-responseValueType | [Response Value Type Object](#responseValueTypeObject) \| [Reference Object](#referenceObject)] | Specify the types of objects and relations in the response using either a reference to the JSON-LD context file or to a [Response Value Type Object](responseValueTypeObject). ##### Response Object Examples @@ -1911,7 +1912,7 @@ description: object created -#### Response Value Type [smartAPI extension] +#### Response Value Type Object [smartAPI extension] that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. From a4d7774dc64c39b99a34588e40bc6f58f0638652 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 27 Oct 2017 20:59:52 +0200 Subject: [PATCH 090/104] smartAPI only schema --- schemas/smartapi_schema.json | 1297 +--------------------------------- 1 file changed, 33 insertions(+), 1264 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 184efbd15c..8af0fa99a9 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -1,99 +1,21 @@ { - "title": "A JSON Schema for OpenAPI 3.0.", - "id": "http://openapis.org/v3/schema.json#", + "title": "The smartAPI extension to OpenAPI 3.0.", + "id": "http://smart-api.info/schema/smartapi-oas3.0.0.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "description": "This is the root document object of the OpenAPI definition file.", - "required": [ - "openapi", - "info", - "paths" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, + "description": "This is the root document object of the smartAPI definition file.", "properties": { - "openapi": { - "type": "string" - }, - "info": { - "$ref": "#/definitions/info" - }, - "servers": { - "type": "array", - "items": { - "$ref": "#/definitions/server" - }, - "uniqueItems": true - }, - "paths": { - "$ref": "#/definitions/paths" - }, - "components": { - "$ref": "#/definitions/components" - }, - "security": { - "type": "array", - "items": { - "$ref": "#/definitions/securityRequirement" - }, - "uniqueItems": true - }, - "tags": { - "type": "array", - "items": { - "$ref": "#/definitions/tag" - }, - "uniqueItems": true - }, - "externalDocs": { - "$ref": "#/definitions/externalDocs" - }, - "x-externalResources": { + "x-externalResources": { "type": "array", "items": { "$ref": "#/definitions/externalResource" - }, - "uniqueItems": true - } + } + } }, "definitions": { "info": { - "type": "object", - "description": "The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience.", - "required": [ - "title", - "version" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, "properties": { - "title": { - "type": "string" - }, - "description": { - "type": "string" - }, - "termsOfService": { - "type": "string" - }, - "contact": { - "$ref": "#/definitions/contact" - }, - "license": { - "$ref": "#/definitions/license" - }, - "version": { - "type": "string" - }, - "x-otherContacts": { + "x-otherContacts": { "type": "array", "items": { "$ref": "#/definitions/contact" @@ -115,31 +37,7 @@ } }, "contact": { - "type": "object", - "description": "Contact information for the exposed API.", - "required": [ - "name", - "email", - "x-role" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, "properties": { - "name": { - "type": "string" - }, - "url": { - "type": "string", - "format": "url" - }, - "email": { - "type": "string", - "format": "email" - }, "x-role": { "type": "string", "enum": [ @@ -148,7 +46,6 @@ "contributor", "support" ], - "description": "The role of the contact person. Values can be: responsible organization,responsible developer,contributor,support." }, "x-id": { "type": "string", @@ -156,49 +53,8 @@ } } }, - "license": { - "type": "object", - "description": "License information for the exposed API.", - "required": [ - "name" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "name": { - "type": "string" - }, - "url": { - "type": "string" - } - } - }, "server": { - "type": "object", - "description": "An object representing a Server.", - "required": [ - "url" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, "properties": { - "url": { - "type": "string" - }, - "description": { - "type": "string" - }, - "variables": { - "$ref": "#/definitions/serverVariables" - }, "x-location": { "type": "string", "description": "Location, city and country of the server hosting the API." @@ -210,215 +66,11 @@ "staging", "production" ], - "description": "Maturity of the API. Values to use: development, staging, production." - } - } - }, - "serverVariable": { - "type": "object", - "description": "An object representing a Server Variable for server URL template substitution.", - "required": [ - "default" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "enum": { - "type": "array", - "items": { - "type": "string" - }, - "uniqueItems": true - }, - "default": { - "type": "string" - }, - "description": { - "type": "string" - } - } - }, - "components": { - "type": "object", - "description": "Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "schemas": { - "$ref": "#/definitions/schemasOrReferences" - }, - "responses": { - "$ref": "#/definitions/responsesOrReferences" - }, - "parameters": { - "$ref": "#/definitions/parametersOrReferences" - }, - "examples": { - "$ref": "#/definitions/examplesOrReferences" - }, - "requestBodies": { - "$ref": "#/definitions/requestBodiesOrReferences" - }, - "headers": { - "$ref": "#/definitions/headersOrReferences" - }, - "securitySchemes": { - "$ref": "#/definitions/securitySchemesOrReferences" - }, - "links": { - "$ref": "#/definitions/linksOrReferences" - }, - "callbacks": { - "$ref": "#/definitions/callbacksOrReferences" - } - } - }, - "paths": { - "type": "object", - "description": "Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the `Server Object` in order to construct the full URL. The Paths MAY be empty, due to ACL constraints.", - "additionalProperties": false, - "patternProperties": { - "^/": { - "$ref": "#/definitions/pathItem" - }, - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - } - }, - "pathItem": { - "type": "object", - "description": "Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "$ref": { - "type": "string" - }, - "summary": { - "type": "string" - }, - "description": { - "type": "string" - }, - "get": { - "$ref": "#/definitions/operation" - }, - "put": { - "$ref": "#/definitions/operation" - }, - "post": { - "$ref": "#/definitions/operation" - }, - "delete": { - "$ref": "#/definitions/operation" - }, - "options": { - "$ref": "#/definitions/operation" - }, - "head": { - "$ref": "#/definitions/operation" - }, - "patch": { - "$ref": "#/definitions/operation" - }, - "trace": { - "$ref": "#/definitions/operation" - }, - "servers": { - "type": "array", - "items": { - "$ref": "#/definitions/server" - }, - "uniqueItems": true - }, - "parameters": { - "type": "array", - "items": { - "$ref": "#/definitions/parameterOrReference" - }, - "uniqueItems": true } } }, "operation": { - "type": "object", - "description": "Describes a single API operation on a path.", - "required": [ - "responses", - "summary" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, "properties": { - "tags": { - "type": "array", - "items": { - "type": "string" - }, - "uniqueItems": true - }, - "summary": { - "type": "string" - }, - "description": { - "type": "string" - }, - "externalDocs": { - "$ref": "#/definitions/externalDocs" - }, - "operationId": { - "type": "string" - }, - "parameters": { - "type": "array", - "items": { - "$ref": "#/definitions/parameter" - }, - "uniqueItems": true - }, - "requestBody": { - "$ref": "#/definitions/requestBodyOrReference" - }, - "responses": { - "$ref": "#/definitions/responses" - }, - "callbacks": { - "$ref": "#/definitions/callbacksOrReferences" - }, - "deprecated": { - "type": "boolean" - }, - "security": { - "type": "array", - "items": { - "$ref": "#/definitions/securityRequirement" - }, - "uniqueItems": true - }, - "servers": { - "type": "array", - "items": { - "$ref": "#/definitions/server" - }, - "uniqueItems": true - }, "x-accessRestriction": { "type": "string", "description": "Access restrictions to invoke the operation. values: none, limited, fee.", @@ -430,32 +82,12 @@ } } }, - "externalDocs": { - "type": "object", - "description": "Allows referencing an external resource for extended documentation.", - "required": [ - "url" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "description": { - "type": "string" - }, - "url": { - "type": "string" - } - } - }, "externalResource": { "type": "object", "additionalProperties": false, "description": "information about external documentation", "required": [ + "x-description", "x-url", "x-type" ], @@ -487,53 +119,7 @@ } }, "parameter": { - "type": "object", - "additionalProperties": false, - "description": "Describes a single operation parameter. A unique parameter is defined by a combination of a name and location.", - "required": [ - "name", - "in" - ], "properties": { - "name": { - "type": "string" - }, - "in": { - "type": "string" - }, - "description": { - "type": "string" - }, - "required": { - "type": "boolean" - }, - "deprecated": { - "type": "boolean" - }, - "allowEmptyValue": { - "type": "boolean" - }, - "style": { - "type": "string" - }, - "explode": { - "type": "boolean" - }, - "allowReserved": { - "type": "boolean" - }, - "schema": { - "$ref": "#/definitions/schemaOrReference" - }, - "example": { - "$ref": "#/definitions/any" - }, - "examples": { - "$ref": "#/definitions/examplesOrReferences" - }, - "content": { - "$ref": "#/definitions/mediaTypes" - }, "x-parameterType": { "type": "string", "description": "Type of parameter, e.g. InputParameter, NumberOfResultsReturned, OffsetParameter, SortParameter." @@ -548,856 +134,39 @@ "uniqueItems": true } }, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - } }, - "requestBody": { - "type": "object", - "description": "Describes a single request body.", - "required": [ - "content" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, + "mediaType": { "properties": { - "description": { - "type": "string" - }, - "content": { - "$ref": "#/definitions/mediaTypes" - }, - "required": { - "type": "boolean" + "x-responseValueType" { + "$ref": "#/definitions/responseValueType" + } + } + }, + "responseValueType": { + "properties": { + "x-path": { + "type": "string", + "description": "The path, using dot notation, to the element of interest" + }, + "x-valueType": { + "type": "string", + "description": "The value type as specified by a concept URI for the element of interest" + } + } + }, + "tag": { + "x-id": { + "type": "string", + "description": "The name of the tag. Recommend that you use URI to specify the concept." } } }, - "mediaType": { - "type": "object", - "description": "Each Media Type Object provides schema and examples for the media type identified by its key.", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, + "schema": { "properties": { - "schema": { - "$ref": "#/definitions/schemaOrReference" - }, - "example": { - "$ref": "#/definitions/any" - }, - "examples": { - "$ref": "#/definitions/examplesOrReferences" - }, - "encoding": { - "$ref": "#/definitions/encodings" - } - } - }, - "encoding": { - "type": "object", - "description": "A single encoding definition applied to a single schema property.", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "contentType": { - "type": "string" - }, - "headers": { - "$ref": "#/definitions/headers" - }, - "style": { - "type": "string" - }, - "explode": { - "type": "boolean" - }, - "allowReserved": { - "type": "boolean" - } - } - }, - "responses": { - "type": "object", - "description": "A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call.", - "additionalProperties": false, - "patternProperties": { - "^([0-9X]{3})$": { - "$ref": "#/definitions/responseOrReference" - }, - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "default": { - "$ref": "#/definitions/responseOrReference" - } - } - }, - "response": { - "type": "object", - "description": "Describes a single response from an API Operation, including design-time, static `links` to operations based on the response.", - "required": [ - "description" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "description": { - "type": "string" - }, - "headers": { - "$ref": "#/definitions/headersOrReferences" - }, - "content": { - "$ref": "#/definitions/mediaTypes" - }, - "links": { - "$ref": "#/definitions/linksOrReferences" - }, - "x-responseValueType": { - "type": "array", - "items": { - "$ref": "#/definitions/responseItems" - } - }, - "x-responseSchema": { - "type": "string", - "format": "url", - "description": "Conformance to a particular schema/format" - }, - "x-JSONLDContext": { - "type": "string", - "format": "url", - "description": "JSON LD context" - } - } - }, - "responseItems": { - "type": "object", - "properties": { - "elementPath": { - "type": "string" - }, - "datatype": { - "type": "string" - } - } - }, - "callback": { - "type": "object", - "description": "A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.", - "additionalProperties": false, - "patternProperties": { - "^": { - "$ref": "#/definitions/pathItem" - }, - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - } - }, - "example": { - "type": "object", - "description": "", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "summary": { - "type": "string" - }, - "description": { - "type": "string" - }, - "value": { - "$ref": "#/definitions/any" - }, - "externalValue": { - "type": "string" - } - } - }, - "link": { - "type": "object", - "description": "The `Link object` represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "operationRef": { - "type": "string" - }, - "operationId": { - "type": "string" - }, - "parameters": { - "$ref": "#/definitions/parameter" - }, - "requestBody": { - "$ref": "#/definitions/anyOrExpression" - }, - "description": { - "type": "string" - }, - "server": { - "$ref": "#/definitions/server" - } - } - }, - "header": { - "type": "object", - "description": "The Header Object follows the structure of the Parameter Object with the following changes: 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, `style`).", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "description": { - "type": "string" - }, - "required": { - "type": "boolean" - }, - "deprecated": { - "type": "boolean" - }, - "allowEmptyValue": { - "type": "boolean" - }, - "style": { - "type": "string" - }, - "explode": { - "type": "boolean" - }, - "allowReserved": { - "type": "boolean" - }, - "schema": { - "$ref": "#/definitions/schemaOrReference" - }, - "example": { - "$ref": "#/definitions/any" - }, - "examples": { - "$ref": "#/definitions/examplesOrReferences" - }, - "content": { - "$ref": "#/definitions/mediaTypes" - } - } - }, - "tag": { - "type": "object", - "description": "Adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.", - "required": [ - "name" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "externalDocs": { - "$ref": "#/definitions/externalDocs" - }, - "x-id": { + "x-url": { "type": "string", - "description": "The name of the tag. Recommend that you use URI to specify the concept." + "description": "The URL to a non-JSON schema." } } - }, - "examples": { - "type": "object", - "description": "", - "additionalProperties": false - }, - "reference": { - "type": "object", - "description": "A simple object to allow referencing other components in the specification, internally and externally. The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules. For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.", - "required": [ - "$ref" - ], - "additionalProperties": false, - "properties": { - "$ref": { - "type": "string" - } - } - }, - "schema": { - "type": "object", - "description": "The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00. For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "nullable": { - "type": "boolean" - }, - "discriminator": { - "$ref": "#/definitions/discriminator" - }, - "readOnly": { - "type": "boolean" - }, - "writeOnly": { - "type": "boolean" - }, - "xml": { - "$ref": "#/definitions/xml" - }, - "externalDocs": { - "$ref": "#/definitions/externalDocs" - }, - "example": { - "$ref": "#/definitions/any" - }, - "deprecated": { - "type": "boolean" - }, - "title": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/title" - }, - "multipleOf": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/multipleOf" - }, - "maximum": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/maximum" - }, - "exclusiveMaximum": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMaximum" - }, - "minimum": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/minimum" - }, - "exclusiveMinimum": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMinimum" - }, - "maxLength": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/maxLength" - }, - "minLength": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/minLength" - }, - "pattern": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/pattern" - }, - "maxItems": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/maxItems" - }, - "minItems": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/minItems" - }, - "uniqueItems": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/uniqueItems" - }, - "maxProperties": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/maxProperties" - }, - "minProperties": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/minProperties" - }, - "required": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/required" - }, - "enum": { - "$ref": "http://json-schema.org/draft-04/schema#/properties/enum" - }, - "type": { - "type": "string" - }, - "allOf": { - "type": "array", - "items": { - "$ref": "#/definitions/schemaOrReference" - }, - "minItems": 1 - }, - "oneOf": { - "type": "array", - "items": { - "$ref": "#/definitions/schemaOrReference" - }, - "minItems": 1 - }, - "anyOf": { - "type": "array", - "items": { - "$ref": "#/definitions/schemaOrReference" - }, - "minItems": 1 - }, - "not": { - "$ref": "#/definitions/schema" - }, - "items": { - "anyOf": [ - { - "$ref": "#/definitions/schemaOrReference" - }, - { - "type": "array", - "items": { - "$ref": "#/definitions/schemaOrReference" - }, - "minItems": 1 - } - ] - }, - "properties": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/schemaOrReference" - } - }, - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/definitions/schemaOrReference" - }, - { - "type": "boolean" - } - ] - }, - "default": { - "$ref": "#/definitions/defaultType" - }, - "description": { - "type": "string" - }, - "format": { - "type": "string" - } - } - }, - "discriminator": { - "type": "object", - "description": "When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. When using the discriminator, _inline_ schemas will not be considered.", - "required": [ - "propertyName" - ], - "additionalProperties": false, - "properties": { - "propertyName": { - "type": "string" - }, - "mapping": { - "$ref": "#/definitions/strings" - } - } - }, - "xml": { - "type": "object", - "description": "A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior.", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "name": { - "type": "string" - }, - "namespace": { - "type": "string" - }, - "prefix": { - "type": "string" - }, - "attribute": { - "type": "boolean" - }, - "wrapped": { - "type": "boolean" - } - } - }, - "securityScheme": { - "type": "object", - "description": "Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code).", - "required": [ - "type" - ], - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "type": { - "type": "string" - }, - "description": { - "type": "string" - }, - "name": { - "type": "string" - }, - "in": { - "type": "string" - }, - "scheme": { - "type": "string" - }, - "bearerFormat": { - "type": "string" - }, - "flows": { - "$ref": "#/definitions/oauthFlows" - }, - "openIdConnectUrl": { - "type": "string" - } - } - }, - "oauthFlows": { - "type": "object", - "description": "Allows configuration of the supported OAuth Flows.", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "implicit": { - "$ref": "#/definitions/oauthFlow" - }, - "password": { - "$ref": "#/definitions/oauthFlow" - }, - "clientCredentials": { - "$ref": "#/definitions/oauthFlow" - }, - "authorizationCode": { - "$ref": "#/definitions/oauthFlow" - } - } - }, - "oauthFlow": { - "type": "object", - "description": "Configuration details for a supported OAuth Flow", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "authorizationUrl": { - "type": "string" - }, - "tokenUrl": { - "type": "string" - }, - "refreshUrl": { - "type": "string" - }, - "scopes": { - "$ref": "#/definitions/strings" - } - } - }, - "securityRequirement": { - "type": "object", - "description": "Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object. Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the Open API object or Operation Object, only one of Security Requirement Objects in the list needs to be satisfied to authorize the request.", - "additionalProperties": false, - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "type": "array", - "items": { - "type": "string" - }, - "uniqueItems": true - } - } - }, - "anyOrExpression": { - "oneOf": [ - { - "$ref": "#/definitions/any" - }, - { - "$ref": "#/definitions/expression" - } - ] - }, - "callbackOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/callback" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "exampleOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/example" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "headerOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/header" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "linkOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/link" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "parameterOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/parameter" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "requestBodyOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/requestBody" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "responseOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/response" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "schemaOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/schema" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "securitySchemeOrReference": { - "oneOf": [ - { - "$ref": "#/definitions/securityScheme" - }, - { - "$ref": "#/definitions/reference" - } - ] - }, - "anysOrExpressions": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/anyOrExpression" - } - }, - "callbacksOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/callbackOrReference" - } - }, - "encodings": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/encoding" - } - }, - "examplesOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/exampleOrReference" - } - }, - "headers": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/header" - } - }, - "headersOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/headerOrReference" - } - }, - "linksOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/linkOrReference" - } - }, - "mediaTypes": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/mediaType" - } - }, - "parametersOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/parameterOrReference" - } - }, - "requestBodiesOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/requestBodyOrReference" - } - }, - "responsesOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/responseOrReference" - } - }, - "schemasOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/schemaOrReference" - } - }, - "securitySchemesOrReferences": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/securitySchemeOrReference" - } - }, - "serverVariables": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/serverVariable" - } - }, - "strings": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "object": { - "type": "object", - "additionalProperties": true - }, - "any": { - "additionalProperties": true - }, - "expression": { - "type": "object", - "additionalProperties": true - }, - "specificationExtension": { - "description": "Any property starting with x- is valid.", - "oneOf": [ - { - "type": "null" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "string" - }, - { - "type": "object" - }, - { - "type": "array" - } - ] - }, - "defaultType": { - "oneOf": [ - { - "type": "null" - }, - { - "type": "array" - }, - { - "type": "object" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "string" - } - ] } - } } From 37f71136b3bf912735c472f3ebc55ae576cd6fca Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 27 Oct 2017 21:01:59 +0200 Subject: [PATCH 091/104] fixed syntax errors --- schemas/smartapi_schema.json | 328 +++++++++++++++++------------------ 1 file changed, 164 insertions(+), 164 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 8af0fa99a9..9aa4cbf777 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -1,172 +1,172 @@ { - "title": "The smartAPI extension to OpenAPI 3.0.", - "id": "http://smart-api.info/schema/smartapi-oas3.0.0.json#", - "$schema": "http://json-schema.org/draft-04/schema#", - "type": "object", - "description": "This is the root document object of the smartAPI definition file.", - "properties": { - "x-externalResources": { - "type": "array", - "items": { - "$ref": "#/definitions/externalResource" - } - } - }, - "definitions": { - "info": { - "properties": { - "x-otherContacts": { + "title": "The smartAPI extension to OpenAPI 3.0.", + "id": "http://smart-api.info/schema/smartapi-oas3.0.0.json#", + "$schema": "http://json-schema.org/draft-06/schema#", + "type": "object", + "description": "This is the root document object of the smartAPI definition file.", + "properties": { + "x-externalResources": { "type": "array", "items": { - "$ref": "#/definitions/contact" + "$ref": "#/definitions/externalResource" } - }, - "x-accessRestriction": { - "type": "string", - "enum": [ - "none", - "limited", - "fee" - ], - "description": "Indicate whether there are restrictions to using the API. Values to use: none, limited, fee." - }, - "x-implementationLanguage": { - "type": "string", - "description": "API Implementation Language" - } - } - }, - "contact": { - "properties": { - "x-role": { - "type": "string", - "enum": [ - "responsible organization", - "responsible developer", - "contributor", - "support" - ], - }, - "x-id": { - "type": "string", - "description": "A resolvable HTTP URI that uniqely identifies the contact (e.g. orcid id github id)" - } - } - }, - "server": { - "properties": { - "x-location": { - "type": "string", - "description": "Location, city and country of the server hosting the API." - }, - "x-maturity": { - "type": "string", - "enum": [ - "development", - "staging", - "production" - ], - } - } - }, - "operation": { - "properties": { - "x-accessRestriction": { - "type": "string", - "description": "Access restrictions to invoke the operation. values: none, limited, fee.", - "enum": [ - "none", - "limited", - "fee" - ] - } - } - }, - "externalResource": { - "type": "object", - "additionalProperties": false, - "description": "information about external documentation", - "required": [ - "x-description", - "x-url", - "x-type" - ], - "properties": { - "x-description": { - "type": "string", - "description": "A short description of the target documentation. CommonMark syntax can be used for rich text representation." - }, - "x-url": { - "type": "string", - "format": "url" - }, - "x-type": { - "type": "string", - "enum": [ - "api documentation", - "website", - "developer forum", - "mailing list", - "social media", - "publication" - ] - } - }, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - } - }, - "parameter": { - "properties": { - "x-parameterType": { - "type": "string", - "description": "Type of parameter, e.g. InputParameter, NumberOfResultsReturned, OffsetParameter, SortParameter." - }, - "x-valueType": { - "type": "array", - "description": "a list of semantic identifiers of the parameter from identifiers.org, e.g. [http://identifiers.org/ncbigene/]", - "items": { - "type": "string", - "format": "url" - }, - "uniqueItems": true - } - }, - }, - "mediaType": { - "properties": { - "x-responseValueType" { - "$ref": "#/definitions/responseValueType" } - } - }, - "responseValueType": { - "properties": { - "x-path": { - "type": "string", - "description": "The path, using dot notation, to the element of interest" + }, + "definitions": { + "info": { + "properties": { + "x-otherContacts": { + "type": "array", + "items": { + "$ref": "#/definitions/contact" + } + }, + "x-accessRestriction": { + "type": "string", + "enum": [ + "none", + "limited", + "fee" + ], + "description": "Indicate whether there are restrictions to using the API. Values to use: none, limited, fee." + }, + "x-implementationLanguage": { + "type": "string", + "description": "API Implementation Language" + } + } + }, + "contact": { + "properties": { + "x-role": { + "type": "string", + "enum": [ + "responsible organization", + "responsible developer", + "contributor", + "support" + ] + }, + "x-id": { + "type": "string", + "description": "A resolvable HTTP URI that uniqely identifies the contact (e.g. orcid id github id)" + } + } + }, + "server": { + "properties": { + "x-location": { + "type": "string", + "description": "Location, city and country of the server hosting the API." + }, + "x-maturity": { + "type": "string", + "enum": [ + "development", + "staging", + "production" + ] + } + } + }, + "operation": { + "properties": { + "x-accessRestriction": { + "type": "string", + "description": "Access restrictions to invoke the operation. values: none, limited, fee.", + "enum": [ + "none", + "limited", + "fee" + ] + } + } + }, + "externalResource": { + "type": "object", + "additionalProperties": false, + "description": "information about external documentation", + "required": [ + "x-description", + "x-url", + "x-type" + ], + "properties": { + "x-description": { + "type": "string", + "description": "A short description of the target documentation. CommonMark syntax can be used for rich text representation." + }, + "x-url": { + "type": "string", + "format": "url" + }, + "x-type": { + "type": "string", + "enum": [ + "api documentation", + "website", + "developer forum", + "mailing list", + "social media", + "publication" + ] + } + }, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/specificationExtension" + } + } }, - "x-valueType": { - "type": "string", - "description": "The value type as specified by a concept URI for the element of interest" + "parameter": { + "properties": { + "x-parameterType": { + "type": "string", + "description": "Type of parameter, e.g. InputParameter, NumberOfResultsReturned, OffsetParameter, SortParameter." + }, + "x-valueType": { + "type": "array", + "description": "a list of semantic identifiers of the parameter from identifiers.org, e.g. [http://identifiers.org/ncbigene/]", + "items": { + "type": "string", + "format": "url" + }, + "uniqueItems": true + } + } + }, + "mediaType": { + "properties": { + "x-responseValueType": { + "$ref": "#/definitions/responseValueType" + } + } + }, + "responseValueType": { + "properties": { + "x-path": { + "type": "string", + "description": "The path, using dot notation, to the element of interest" + }, + "x-valueType": { + "type": "string", + "description": "The value type as specified by a concept URI for the element of interest" + } + } + }, + "tag": { + "x-id": { + "type": "string", + "description": "The name of the tag. Recommend that you use URI to specify the concept." + } } - } }, - "tag": { - "x-id": { - "type": "string", - "description": "The name of the tag. Recommend that you use URI to specify the concept." - } - } - }, - "schema": { - "properties": { - "x-url": { - "type": "string", - "description": "The URL to a non-JSON schema." - } - } - } -} + "schema": { + "properties": { + "x-url": { + "type": "string", + "description": "The URL to a non-JSON schema." + } + } + } +} \ No newline at end of file From 439d8dfde13b5a2e437c9fb08d1f38aa16caedd9 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 27 Oct 2017 21:11:14 +0200 Subject: [PATCH 092/104] fixed missing specificationExtension reference --- schemas/smartapi_schema.json | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 9aa4cbf777..455bfb4009 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -1,6 +1,6 @@ { "title": "The smartAPI extension to OpenAPI 3.0.", - "id": "http://smart-api.info/schema/smartapi-oas3.0.0.json#", + "id": "https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/OpenAPI.next/schemas/smartapi_schema.json#", "$schema": "http://json-schema.org/draft-06/schema#", "type": "object", "description": "This is the root document object of the smartAPI definition file.", @@ -159,6 +159,28 @@ "type": "string", "description": "The name of the tag. Recommend that you use URI to specify the concept." } + }, + "specificationExtension": { + "description": "Any property starting with x- is valid.", + "oneOf": [{ + "type": "null" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "string" + }, + { + "type": "object" + }, + { + "type": "array" + } + ] } }, "schema": { From 9690943d4b80d6377d9d5e8435d576d62dbd0ca6 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 27 Oct 2017 21:12:38 +0200 Subject: [PATCH 093/104] fix to id --- schemas/smartapi_schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 455bfb4009..577af2983f 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -1,6 +1,6 @@ { "title": "The smartAPI extension to OpenAPI 3.0.", - "id": "https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/OpenAPI.next/schemas/smartapi_schema.json#", + "$id": "https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/OpenAPI.next/schemas/smartapi_schema.json", "$schema": "http://json-schema.org/draft-06/schema#", "type": "object", "description": "This is the root document object of the smartAPI definition file.", From 4f62ad3937a3e790c8ed71b33576c4ec72b02af6 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Fri, 27 Oct 2017 21:22:53 +0200 Subject: [PATCH 094/104] moved schema into definitions; fixed tag --- schemas/smartapi_schema.json | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 577af2983f..4edabeba32 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -1,6 +1,6 @@ { "title": "The smartAPI extension to OpenAPI 3.0.", - "$id": "https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/OpenAPI.next/schemas/smartapi_schema.json", + "id": "https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/OpenAPI.next/schemas/smartapi_schema.json2#", "$schema": "http://json-schema.org/draft-06/schema#", "type": "object", "description": "This is the root document object of the smartAPI definition file.", @@ -155,9 +155,21 @@ } }, "tag": { - "x-id": { - "type": "string", - "description": "The name of the tag. Recommend that you use URI to specify the concept." + "properties": { + + "x-id": { + "type": "string", + "description": "The name of the tag. Recommend that you use URI to specify the concept." + } + } + }, + + "schema": { + "properties": { + "x-url": { + "type": "string", + "description": "The URL to a non-JSON schema." + } } }, "specificationExtension": { @@ -182,13 +194,5 @@ } ] } - }, - "schema": { - "properties": { - "x-url": { - "type": "string", - "description": "The URL to a non-JSON schema." - } - } } } \ No newline at end of file From c33a771c44f2eb9b3257841c5a2780485381244a Mon Sep 17 00:00:00 2001 From: Chunlei Wu Date: Sat, 28 Oct 2017 08:08:35 -0500 Subject: [PATCH 095/104] cleaned up smartapi schema, should validate nested fields correctly now --- schemas/smartapi_schema.json | 411 ++++++++++++++++++----------------- 1 file changed, 214 insertions(+), 197 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 4edabeba32..9a763c9541 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -1,198 +1,215 @@ { - "title": "The smartAPI extension to OpenAPI 3.0.", - "id": "https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/OpenAPI.next/schemas/smartapi_schema.json2#", - "$schema": "http://json-schema.org/draft-06/schema#", - "type": "object", - "description": "This is the root document object of the smartAPI definition file.", - "properties": { - "x-externalResources": { - "type": "array", - "items": { - "$ref": "#/definitions/externalResource" - } - } - }, - "definitions": { - "info": { - "properties": { - "x-otherContacts": { - "type": "array", - "items": { - "$ref": "#/definitions/contact" - } - }, - "x-accessRestriction": { - "type": "string", - "enum": [ - "none", - "limited", - "fee" - ], - "description": "Indicate whether there are restrictions to using the API. Values to use: none, limited, fee." - }, - "x-implementationLanguage": { - "type": "string", - "description": "API Implementation Language" - } - } - }, - "contact": { - "properties": { - "x-role": { - "type": "string", - "enum": [ - "responsible organization", - "responsible developer", - "contributor", - "support" - ] - }, - "x-id": { - "type": "string", - "description": "A resolvable HTTP URI that uniqely identifies the contact (e.g. orcid id github id)" - } - } - }, - "server": { - "properties": { - "x-location": { - "type": "string", - "description": "Location, city and country of the server hosting the API." - }, - "x-maturity": { - "type": "string", - "enum": [ - "development", - "staging", - "production" - ] - } - } - }, - "operation": { - "properties": { - "x-accessRestriction": { - "type": "string", - "description": "Access restrictions to invoke the operation. values: none, limited, fee.", - "enum": [ - "none", - "limited", - "fee" - ] - } - } - }, - "externalResource": { - "type": "object", - "additionalProperties": false, - "description": "information about external documentation", - "required": [ - "x-description", - "x-url", - "x-type" - ], - "properties": { - "x-description": { - "type": "string", - "description": "A short description of the target documentation. CommonMark syntax can be used for rich text representation." - }, - "x-url": { - "type": "string", - "format": "url" - }, - "x-type": { - "type": "string", - "enum": [ - "api documentation", - "website", - "developer forum", - "mailing list", - "social media", - "publication" - ] - } - }, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/specificationExtension" - } - } - }, - "parameter": { - "properties": { - "x-parameterType": { - "type": "string", - "description": "Type of parameter, e.g. InputParameter, NumberOfResultsReturned, OffsetParameter, SortParameter." - }, - "x-valueType": { - "type": "array", - "description": "a list of semantic identifiers of the parameter from identifiers.org, e.g. [http://identifiers.org/ncbigene/]", - "items": { - "type": "string", - "format": "url" - }, - "uniqueItems": true - } - } - }, - "mediaType": { - "properties": { - "x-responseValueType": { - "$ref": "#/definitions/responseValueType" - } - } - }, - "responseValueType": { - "properties": { - "x-path": { - "type": "string", - "description": "The path, using dot notation, to the element of interest" - }, - "x-valueType": { - "type": "string", - "description": "The value type as specified by a concept URI for the element of interest" - } - } - }, - "tag": { - "properties": { - - "x-id": { - "type": "string", - "description": "The name of the tag. Recommend that you use URI to specify the concept." - } - } - }, - - "schema": { - "properties": { - "x-url": { - "type": "string", - "description": "The URL to a non-JSON schema." - } - } - }, - "specificationExtension": { - "description": "Any property starting with x- is valid.", - "oneOf": [{ - "type": "null" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "string" - }, - { - "type": "object" - }, - { - "type": "array" - } - ] - } - } -} \ No newline at end of file + "title": "The smartAPI extension to OpenAPI 3.0.", + "$schema": "http://json-schema.org/draft-06/schema#", + "$id": "", + "type": "object", + "description": "This is the root document object of the smartAPI definition file.", + "properties": { + "x-externalResources": { + "type": "array", + "items": { + "$ref": "#/definitions/externalResource" + } + }, + "info": { + "$ref": "#/definitions/info" + }, + "paths": { + "type": "object", + "patternProperties": { + "^\\/": { + "type": "object", + "patternProperties": { + ".": { + "type": "object", + "properties": { + "parameters": { + "type": "array", + "items": { + "$ref": "#/definitions/Parameter" + } + }, + "responses": { + "type": "object", + "patternProperties": { + "[1-5](?:\\d{2}|XX)": { + "type": "object", + "properties": { + "x-responseValueType": { + "type": "array", + "items": { + "$ref": "#/definitions/responseValueType" + } + } + } + } + } + }, + "x-accessRestriction": { + "type": "string", + "description": "Access restrictions to invoke the operation. values: none, limited, fee.", + "enum": [ + "none", + "limited", + "fee" + ] + } + } + } + } + } + } + } + }, + "definitions": { + "Reference": { + "type": "object", + "required": [ + "$ref" + ], + "properties": { + "$ref": { + "type": "string", + "format": "uri-reference" + } + } + }, + "info": { + "properties": { + "x-otherContacts": { + "type": "array", + "items": { + "$ref": "#/definitions/contact" + } + }, + "x-accessRestriction": { + "type": "string", + "enum": [ + "none", + "limited", + "fee" + ], + "description": "Indicate whether there are restrictions to using the API. Values to use: none, limited, fee." + }, + "x-implementationLanguage": { + "type": "string", + "description": "API Implementation Language" + }, + "contact": { + "$ref": "#/definitions/contact" + } + } + }, + "contact": { + "properties": { + "x-role": { + "type": "string", + "enum": [ + "responsible organization", + "responsible developer", + "contributor", + "support" + ] + }, + "x-id": { + "type": "string", + "description": "A resolvable HTTP URI that uniqely identifies the contact (e.g. orcid id github id)" + } + } + }, + "server": { + "properties": { + "x-location": { + "type": "string", + "description": "Location, city and country of the server hosting the API." + }, + "x-maturity": { + "type": "string", + "enum": [ + "development", + "staging", + "production" + ] + } + } + }, + "Parameter": { + "properties": { + "x-valueType": { + "type": "array", + "description": "a list of semantic identifiers of the parameter from identifiers.org, e.g. [http://identifiers.org/ncbigene/]", + "items": { + "type": "string", + "format": "url" + }, + "uniqueItems": true + }, + "x-parameterType": { + "type": "string", + "description": "Type of parameter, e.g. InputParameter, NumberOfResultsReturned, OffsetParameter, SortParameter." + } + } + }, + "externalResource": { + "type": "object", + "additionalProperties": false, + "description": "information about external documentation", + "required": [ + "x-description", + "x-url", + "x-type" + ], + "properties": { + "x-description": { + "type": "string", + "description": "A short description of the target documentation. CommonMark syntax can be used for rich text representation." + }, + "x-url": { + "type": "string", + "format": "url" + }, + "x-type": { + "type": "string", + "enum": [ + "api documentation", + "website", + "developer forum", + "mailing list", + "social media", + "publication" + ] + } + } + }, + "responseValueType": { + "required": [ + "path", + "valueType" + ], + "properties": { + "path": { + "type": "string", + "description": "The path, using dot notation, to the element of interest" + }, + "valueType": { + "type": "string", + "description": "The value type as specified by a concept URI for the element of interest" + } + } + }, + "tag": { + "x-id": { + "type": "string", + "description": "The name of the tag. Recommend that you use URI to specify the concept." + } + }, + "schema": { + "properties": { + "x-url": { + "type": "string", + "description": "The URL to a non-JSON schema." + } + } + } + } +} From d252652eb45fd3db6da711e0593f8e000c0a3e4d Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 7 Nov 2017 18:21:30 +0100 Subject: [PATCH 096/104] fixed responseValueTypeObject --- versions/3.0.0.md | 6 +++--- versions/smartapi-list.md | 7 ++++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index cd502bff86..4693e0b66c 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -1782,7 +1782,7 @@ Field Name | Type | Description ---|:---:|--- content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **SHOULD** Use media type definitions listed at RFC6838. | `URI` | Specify the json schema using a Reference Object, or use "x-uri" as an additional property in the schema field to point to an external location for an XML, RDF, etc schema. -x-responseValueType | [Response Value Type Object](#responseValueTypeObject) \| [Reference Object](#referenceObject)] | Specify the types of objects and relations in the response using either a reference to the JSON-LD context file or to a [Response Value Type Object](responseValueTypeObject). +x-responseValueType | [Response Value Type Object](#responseValueTypeObject) \| [Reference Object](#referenceObject)] | Specify the types of objects and relations in the response using either a reference to the JSON-LD context file or to a [Response Value Type Object](#responseValueTypeObject). ##### Response Object Examples @@ -1922,13 +1922,13 @@ description: object created Field Name | Type | Description ---|:---:|--- x-path | `string` | The path using dot notation to the element of interest. e.g. friend.name to follow the path from root object to the name attribute to the name field -x-valueType | `string` | The value type for the field. e.g. +x-valueType | `string` | The value type for the field. e.g. http://identifiers.org/ncbigene indicates that the field type is from the NCBI Gene database ##### Response Value Type Object smartAPI Example ```yaml - x-path: ncbigene.id - x-valueType: http://identifiers.org/ncbigene:12345 + x-valueType: http://identifiers.org/ncbigene ``` diff --git a/versions/smartapi-list.md b/versions/smartapi-list.md index 8d098a089e..65075a223d 100644 --- a/versions/smartapi-list.md +++ b/versions/smartapi-list.md @@ -22,7 +22,8 @@ Object | Field | Recommendation | Datatype | Description Parameter Object|x-valueType|SHOULD| [uri] |A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from Parameter Object||examples| |Use the Schema object to define examples. Response Object|content|SHOULD| Map[string, [Media Type Object](#mediaTypeObject)] |Use media type definitions listed at RFC6838. -Response Object|x-responseSchema|| URI |Conformance to a particular schema/format. -Response Object|x-responseValueType|| [responseValueType object] |To specify the types of objects in the response. The responseValueType object consists of a required `x-valueType` that should provide URI values to the type of object, and an optional `x-path` to specify to location in the response for that valueType. -Response Object|x-JSONLDContext|| URI |JSON LD context. +Response Object||| URI |Specify the json schema using a Reference Object, or use "x-uri" as an additional property in the schema field to point to an external location for an XML, RDF, etc schema. +Response Object|x-responseValueType|| [Response Value Type Object](#responseValueTypeObject) \|[Reference Object](#referenceObject)] +Response Value Type Object [smartAPI extension]|x-path|| string |The path using dot notation to the element of interest. e.g. friend.name to follow the path from root object to the name attribute to the name field +Response Value Type Object [smartAPI extension]|x-valueType|| string |The value type for the field. e.g. http://identifiers.org/ncbigene indicates that the field type is from the NCBI Gene database Tag Object|x-id|| URI |The name of the tag. Recommend that you use URI to specify the concept. From 79e6e497e0d1172b97475238be834cb753e2d3bd Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 10 Nov 2017 13:01:42 -0500 Subject: [PATCH 097/104] Changes as per Ron and Marsh --- MAINTAINERS.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 5a5ab82e15..05849e61f5 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,6 +1,9 @@ +## Active * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) -* Jason Harmon [@jharmn](https://github.com/jharmn) * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) * Ron Ratovsky [@webron](https://github.com/webron) + +## Emeritus +* Jason Harmon [@jharmn](https://github.com/jharmn) * Tony Tam [@fehguy](https://github.com/fehguy) From 782b242fbec9619d68e1cb60f2a3df2709a02bcd Mon Sep 17 00:00:00 2001 From: Chunlei Wu Date: Mon, 13 Nov 2017 16:09:49 -0800 Subject: [PATCH 098/104] updating smartapi specific json schema --- schemas/smartapi_schema.json | 57 ++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 19 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 9a763c9541..db91258b38 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -5,14 +5,26 @@ "type": "object", "description": "This is the root document object of the smartAPI definition file.", "properties": { + "info": { + "$ref": "#/definitions/info" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/server" + } + }, "x-externalResources": { "type": "array", "items": { "$ref": "#/definitions/externalResource" } }, - "info": { - "$ref": "#/definitions/info" + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/tag" + } }, "paths": { "type": "object", @@ -75,6 +87,9 @@ } }, "info": { + "required": [ + "termsOfService" + ], "properties": { "x-otherContacts": { "type": "array", @@ -97,6 +112,10 @@ }, "contact": { "$ref": "#/definitions/contact" + }, + "termsOfService": { + "type": "string", + "format": "url" } } }, @@ -133,23 +152,6 @@ } } }, - "Parameter": { - "properties": { - "x-valueType": { - "type": "array", - "description": "a list of semantic identifiers of the parameter from identifiers.org, e.g. [http://identifiers.org/ncbigene/]", - "items": { - "type": "string", - "format": "url" - }, - "uniqueItems": true - }, - "x-parameterType": { - "type": "string", - "description": "Type of parameter, e.g. InputParameter, NumberOfResultsReturned, OffsetParameter, SortParameter." - } - } - }, "externalResource": { "type": "object", "additionalProperties": false, @@ -181,6 +183,23 @@ } } }, + "Parameter": { + "properties": { + "x-valueType": { + "type": "array", + "description": "a list of semantic identifiers of the parameter from identifiers.org, e.g. [http://identifiers.org/ncbigene/]", + "items": { + "type": "string", + "format": "url" + }, + "uniqueItems": true + }, + "x-parameterType": { + "type": "string", + "description": "Type of parameter, e.g. InputParameter, NumberOfResultsReturned, OffsetParameter, SortParameter." + } + } + }, "responseValueType": { "required": [ "path", From 18c08c0861414e5025e4c4cac648eff7e43fb7b3 Mon Sep 17 00:00:00 2001 From: Chunlei Wu Date: Mon, 13 Nov 2017 17:43:45 -0800 Subject: [PATCH 099/104] fixed a schema error and switched to draft04 --- schemas/smartapi_schema.json | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index db91258b38..51fa9a130b 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -1,7 +1,6 @@ { "title": "The smartAPI extension to OpenAPI 3.0.", - "$schema": "http://json-schema.org/draft-06/schema#", - "$id": "", + "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "description": "This is the root document object of the smartAPI definition file.", "properties": { @@ -11,7 +10,7 @@ "servers": { "type": "array", "items": { - "$ref": "#/definitions/server" + "$ref": "#/definitions/server" } }, "x-externalResources": { @@ -23,7 +22,7 @@ "tags": { "type": "array", "items": { - "$ref": "#/definitions/tag" + "$ref": "#/definitions/tag" } }, "paths": { @@ -88,7 +87,7 @@ }, "info": { "required": [ - "termsOfService" + "termsOfService" ], "properties": { "x-otherContacts": { @@ -114,8 +113,8 @@ "$ref": "#/definitions/contact" }, "termsOfService": { - "type": "string", - "format": "url" + "type": "string", + "format": "uri" } } }, @@ -168,7 +167,7 @@ }, "x-url": { "type": "string", - "format": "url" + "format": "uri" }, "x-type": { "type": "string", @@ -190,7 +189,7 @@ "description": "a list of semantic identifiers of the parameter from identifiers.org, e.g. [http://identifiers.org/ncbigene/]", "items": { "type": "string", - "format": "url" + "format": "uri" }, "uniqueItems": true }, @@ -217,9 +216,11 @@ } }, "tag": { - "x-id": { - "type": "string", - "description": "The name of the tag. Recommend that you use URI to specify the concept." + "properties": { + "x-id": { + "type": "string", + "description": "The name of the tag. Recommend that you use URI to specify the concept." + } } }, "schema": { From 88c3683402e1c851091370f6aa5ae2c5820dbf6f Mon Sep 17 00:00:00 2001 From: Chunlei Wu Date: Fri, 17 Nov 2017 17:29:48 -0800 Subject: [PATCH 100/104] updated smartapi schema --- schemas/smartapi_schema.json | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 51fa9a130b..7ed35dbd3e 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -33,7 +33,13 @@ "patternProperties": { ".": { "type": "object", + "required": [ + "summary" + ], "properties": { + "summary": { + "type": "string" + }, "parameters": { "type": "array", "items": { @@ -131,6 +137,7 @@ }, "x-id": { "type": "string", + "format": "uri", "description": "A resolvable HTTP URI that uniqely identifies the contact (e.g. orcid id github id)" } } @@ -156,7 +163,6 @@ "additionalProperties": false, "description": "information about external documentation", "required": [ - "x-description", "x-url", "x-type" ], From 00e1a0536b57aeb38bb91ccde61181ef5cf4bdd4 Mon Sep 17 00:00:00 2001 From: Chunlei Wu Date: Fri, 17 Nov 2017 20:54:39 -0800 Subject: [PATCH 101/104] updated smartapi schema --- schemas/smartapi_schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/smartapi_schema.json b/schemas/smartapi_schema.json index 7ed35dbd3e..b3e5979b6d 100644 --- a/schemas/smartapi_schema.json +++ b/schemas/smartapi_schema.json @@ -31,7 +31,7 @@ "^\\/": { "type": "object", "patternProperties": { - ".": { + "get|put|post|delete|options|head|patch|trace": { "type": "object", "required": [ "summary" From ba5d0bf5ba3193d1076b844540d7a77f9eb55348 Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 19 Dec 2017 16:43:19 +0530 Subject: [PATCH 102/104] Update 3.0.0.md renamed to smartAPI specificiation. added introduction section to also point to smartAPI specific elements and to the website. --- versions/3.0.0.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index 4693e0b66c..e6c8b929ab 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -1,6 +1,6 @@ -# OpenAPI Specification +# smartAPI Specification -#### Version 3.0.0 [adapted for smartAPI] +#### Version 3.0.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. @@ -8,6 +8,8 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa ## Introduction +The smartAPI Specification (smartAPI) is a community-based extension of the OpenAPI specification. It features new metadata elements and value sets to promote the interoperability of web-based APIs. This document seamlessly integrates smartAPI specific extensions with the OpenAPI specification. However, a list of the smartAPI specific elements has been [automatically generated](smartapi-list.md). More information about the smartAPI initiative can be found on its [website](http://smart-api.info). + The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. From e79294b8f5176157838a33122df2186b5799769b Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Tue, 19 Dec 2017 22:15:19 +0530 Subject: [PATCH 103/104] Update 3.0.0.md minor rephrasing --- versions/3.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.0.md b/versions/3.0.0.md index e6c8b929ab..751caf40f5 100644 --- a/versions/3.0.0.md +++ b/versions/3.0.0.md @@ -8,7 +8,7 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa ## Introduction -The smartAPI Specification (smartAPI) is a community-based extension of the OpenAPI specification. It features new metadata elements and value sets to promote the interoperability of web-based APIs. This document seamlessly integrates smartAPI specific extensions with the OpenAPI specification. However, a list of the smartAPI specific elements has been [automatically generated](smartapi-list.md). More information about the smartAPI initiative can be found on its [website](http://smart-api.info). +The smartAPI Specification (smartAPI) is a community-based extension of the OpenAPI specification. It features new metadata elements and value sets to promote the interoperability of web-based APIs. This document seamlessly integrates smartAPI specific extensions with the OpenAPI specification. A list of the smartAPI specific elements can be found in a separate [document](smartapi-list.md). More information about the smartAPI initiative can be found on its [website](http://smart-api.info). The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. From 498a6beac234f028ef25f3cf482121a15c696277 Mon Sep 17 00:00:00 2001 From: Marco Cano Date: Wed, 12 Jul 2023 09:48:48 -0700 Subject: [PATCH 104/104] Update README.md make relative links absolute to fix routing issues rendering on external web app --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 01254b3b8c..6382601b06 100644 --- a/README.md +++ b/README.md @@ -27,35 +27,35 @@ Here you will find the information you need about the OpenAPI Specification, sim ## Current Version - 3.0 -The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.0.md). +The current version of the OpenAPI specification is [OpenAPI Specification 3.0](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md). ### Previous Versions -This repository also contains the [OpenAPI Specification 2.0](versions/2.0), which is identical to the Swagger 2.0 specification before it was renamed to “OpenAPI Specification”, +This repository also contains the [OpenAPI Specification 2.0](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/2.0), which is identical to the Swagger 2.0 specification before it was renamed to “OpenAPI Specification”, as well as the Swagger 1.2 and Swagger 2.0 specifications. -Each folder in this repository, such as [examples](examples) and [schemas](schemas), should contain folders pertaining to the current and previous versions of the specification. +Each folder in this repository, such as [examples](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/examples) and [schemas](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/schemas), should contain folders pertaining to the current and previous versions of the specification. ## See It in Action -If you just want to see it work, check out the [list of current examples](examples/v3.0). +If you just want to see it work, check out the [list of current examples](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/examples/v3.0). ## Tools and Libraries Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing -[list of 3.0 Implementations](IMPLEMENTATIONS.md). +[list of 3.0 Implementations](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/IMPLEMENTATIONS.md). ## Participation The current process for development of the OpenAPI Specification is described in -[Development Guidelines](DEVELOPMENT.md). +[Development Guidelines](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md). Development of the next version of the OpenAPI Specification is guided by the [Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master. The Open API Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions: -* Review the [current specification](versions/3.0.0.md). The human-readable markdown file _is the source of truth_ for the specification. -* Review the [development](DEVELOPMENT.md) process so you understand how the spec is evolving. +* Review the [current specification](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md). The human-readable markdown file _is the source of truth_ for the specification. +* Review the [development](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md) process so you understand how the spec is evolving. * Check the [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by adding a comment to the existing issue or PR. * Create an issue to describe a new concern. If possible, propose a solution.