OpenAPI v3 JSON Schema #1236

timburks · 2017-06-28T17:07:37Z

From the README:

This PR contains a JSON Schema for OpenAPI v3.

It was generated using a tool that scraped the Markdown text of the OpenAPI Specification and made several semi-automated refinements. This tool is part of the gnostic project, which generates type-safe models of OpenAPI v2 and v3 directly from their JSON Schemas.

The v3 JSON Schema was significantly reviewed and improved by Mike Ralphson and Tanya Fesenko and has been tested with automated schema validators.

The source for this schema is in the gnostic project in openapi-3.0.json which will also contain the latest revision.

RobDolinMS · 2017-06-30T16:15:59Z

versions/3.0.md

@@ -1979,7 +1979,7 @@ Field Name  |  Type  | Description
 ---|:---:|---
 <a name="linkOperationRef"></a>operationRef | `string` | A relative or absolute reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject).
 <a name="linkOperationId"></a>operationId  | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive of the `operationRef` field.  Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OAS.
-<a name="linkParameters"></a>parameters   | Map[`string`, Any \| [{expression}](#runtimeExpression) | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation.  The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id).
+<a name="linkParameters"></a>parameters   | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation.  The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id).


@timburks Can the bonus character be separated into its own PR?

That commit is in a PR that's ahead of this one and accidentally got included here. If you need a PR without it, I'll try to revise this one.

RobDolinMS · 2017-06-30T16:24:55Z

#TDC: @darrelmiller Would like to see some wording to clearly state that:

Schema only provides partial validation (validation against schema is necessary but not sufficient)
Source of truth is the spec, not the schema
Maybe add this in the ReadMe in the Schema folder

#TDC: Additional discussion:

Should people recognized in the Schema/ReadMe.md just get recognized in the Contributors file?
A few options for Schema:
- Put into Examples folder
- Put into its own repo
We may want to provide some use cases for the JSON schema:
- This is a good first step to check if (mostly) structurally valid (but then must do semantic validation)

timburks · 2017-06-30T22:10:14Z

@RobDolinMS I'm happy to revise this or file a new PR based on these and other suggested changes. Please let me know when you feel there's enough feedback to clarify what's needed in that update.

EDIT: Regarding alternate locations for the schema: this PR follows the directory pattern used for earlier versions of the spec. Based on past precedents, to me it seems like an abdication to not put a schema in the main repo.

RobDolinMS · 2017-07-07T16:25:46Z

ACTION: @webron and @whitlockjc, please review the schema.

#TDC: We agree this is not a blocker for releasing the spec; but it would be really, really nice to have at launch.

darrelmiller · 2017-07-11T16:39:46Z

schemas/v3.0/schema.json

+      "items": {
+        "$ref": "#/definitions/server"
+      },
+      "uniqueItems": true


The uniqueItems constraint brings up an interesting set of issues. This constraint isn't in the spec. What is the reason for adding it in the Schema? It seems like it is common sense that the URLs should be unique. Should that wording be added to the spec? Can JSON schema validate that the just URLs are unique?

When I was writing the schema generator, I found that the uniqueItems property was generally set for arrays in the v2 schema, so I applied it by default to arrays in the generated 3.0 schema. So in this case, it's present by accident for the "servers" array.

I'd like to continue to be able to generate the schema automatically from the 3.0 text, so the simplest solution would be to drop "uniqueItems" for all arrays, but I see that the text description for the tags field of the root object includes the phrase "MUST be unique". Based on the presence of that phrase, I could add the uniqueItems property for the array value of the tags field, but no others.

darrelmiller · 2017-07-11T16:45:23Z

schemas/v3.0/schema.json

+          "type": "string"
+        },
+        "termsOfService": {
+          "type": "string"


Should format: uriref be added to termsOfService?

There are four instances of the phrase "MUST be in the format of a URL" in the 3.0 spec. I can add format: uriref for all of them - is "uriref" the proper value to use for this? I don't find that word specifically used anywhere in the 3.0 spec. I do find it in this document, but there it seems to have been deprecated in favor of uri-ref.

The OpenAPI V3.0.0 spec is currently pinned to the draft 00 version of JSON Schema, so we are stuck with using the uriref term.

You might want to consider using uri-reference which is what uriref became in the next draft. Since formats are extensible, you would not be violating draft-wright-00 (a.k.a. draft-05) by doing this, and would be future-proofing your approach. While we are seeing implementations of draft-wright-01 (draft-06) in the wild, I'm not aware of any validators implementing uriref from draft-05. uriref did not fit the pattern for format names which is why it was changed.

KES777 · 2018-03-29T19:52:34Z

When it will be officially released?

handrews · 2018-11-13T19:06:41Z

Note that I have started building on PR #1270, beginning with PR #1744 with more to come. Perhaps we should close this so that there is only one line of open PRs?

It's my understanding that #1270 already incorporates ideas from here- @timburks please let me know if you think there are things that I should incorporate that are present here but not in #1270.

webron · 2019-04-18T14:43:08Z

Closing as #1270 was merged. Thanks for the help, @timburks!

timburks added 2 commits June 27, 2017 14:28

Add a missing ].

c6bb40d

First draft of OpenAPI v3 JSON Schema, generated from 3.0.md.

5f3a9a7

timburks mentioned this pull request Jun 28, 2017

JSON Schema for the OpenAPI 3.0 Specification #1032

Closed

RobDolinMS reviewed Jun 30, 2017

View reviewed changes

RobDolinMS requested review from webron and whitlockjc June 30, 2017 16:28

RobDolinMS added this to the Ancillary milestone Jun 30, 2017

RobDolinMS assigned webron and whitlockjc Jun 30, 2017

darrelmiller reviewed Jul 11, 2017

View reviewed changes

webron mentioned this pull request Jul 14, 2017

[WIP] Alternative OAS3 JSON Schema #1270

Merged

darrelmiller mentioned this pull request Jul 27, 2017

Official 3.0 schema? #1301

Closed

blortfish mentioned this pull request Oct 5, 2017

adding openAPI 3.0.0 support kogosoftwarellc/openapi-schema-validation#1

Merged

MikeRalphson mentioned this pull request Oct 25, 2017

Finish JSON Schema work #1348

Closed

philsturgeon mentioned this pull request Dec 18, 2017

Validate Postman Input and Outut luckymarmot/API-Flow#154

Open

MikeRalphson mentioned this pull request Feb 27, 2018

OAS 3.1 - The Big List of Possibilities #1466

Closed

13 tasks

MikeRalphson mentioned this pull request Mar 23, 2018

Relative URL for openIdConnectUrl fails validation Mermade/oas-kit#60

Closed

1 task

FRDavid mentioned this pull request May 28, 2018

Update/0.0.11 jmcanterafonseca/ETSI_CIM_Swagger#1

Merged

MikeRalphson mentioned this pull request Nov 1, 2018

Reinstate validation of JSON Schemas (and examples) in build process #1739

Closed

MikeRalphson mentioned this pull request Nov 16, 2018

Initial batch of minor schema fixes #1744

Merged

MikeRalphson mentioned this pull request Feb 25, 2019

JSON-Metaschema #1846

Closed

webron closed this Apr 18, 2019

MikeRalphson mentioned this pull request Jun 13, 2019

Add field descriptions to JSON schema #1948

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenAPI v3 JSON Schema #1236

OpenAPI v3 JSON Schema #1236

timburks commented Jun 28, 2017

RobDolinMS Jun 30, 2017

timburks Jun 30, 2017 •

edited

Loading

RobDolinMS commented Jun 30, 2017 •

edited

Loading

timburks commented Jun 30, 2017 •

edited

Loading

RobDolinMS commented Jul 7, 2017

darrelmiller Jul 11, 2017

timburks Jul 12, 2017

darrelmiller Jul 11, 2017

timburks Jul 12, 2017

darrelmiller Jul 12, 2017

handrews Oct 25, 2017

KES777 commented Mar 29, 2018

handrews commented Nov 13, 2018

webron commented Apr 18, 2019

OpenAPI v3 JSON Schema #1236

OpenAPI v3 JSON Schema #1236

Conversation

timburks commented Jun 28, 2017

RobDolinMS Jun 30, 2017

Choose a reason for hiding this comment

timburks Jun 30, 2017 • edited Loading

Choose a reason for hiding this comment

RobDolinMS commented Jun 30, 2017 • edited Loading

timburks commented Jun 30, 2017 • edited Loading

RobDolinMS commented Jul 7, 2017

darrelmiller Jul 11, 2017

Choose a reason for hiding this comment

timburks Jul 12, 2017

Choose a reason for hiding this comment

darrelmiller Jul 11, 2017

Choose a reason for hiding this comment

timburks Jul 12, 2017

Choose a reason for hiding this comment

darrelmiller Jul 12, 2017

Choose a reason for hiding this comment

handrews Oct 25, 2017

Choose a reason for hiding this comment

KES777 commented Mar 29, 2018

handrews commented Nov 13, 2018

webron commented Apr 18, 2019

timburks Jun 30, 2017 •

edited

Loading

RobDolinMS commented Jun 30, 2017 •

edited

Loading

timburks commented Jun 30, 2017 •

edited

Loading