New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OpenAPI v3 JSON Schema #1236

Open
wants to merge 2 commits into
from

Conversation

@timburks
Contributor

timburks commented Jun 28, 2017

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.

@@ -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).

This comment has been minimized.

@RobDolinMS

RobDolinMS Jun 30, 2017

Contributor

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

@RobDolinMS

RobDolinMS Jun 30, 2017

Contributor

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

This comment has been minimized.

@timburks

timburks Jun 30, 2017

Contributor

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.

@timburks

timburks Jun 30, 2017

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@RobDolinMS

RobDolinMS Jun 30, 2017

Contributor

#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)
Contributor

RobDolinMS commented Jun 30, 2017

#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)

@RobDolinMS RobDolinMS requested review from webron and whitlockjc Jun 30, 2017

@RobDolinMS RobDolinMS added this to the Ancillary milestone Jun 30, 2017

@timburks

This comment has been minimized.

Show comment
Hide comment
@timburks

timburks Jun 30, 2017

Contributor

@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.

Contributor

timburks commented Jun 30, 2017

@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

This comment has been minimized.

Show comment
Hide comment
@RobDolinMS

RobDolinMS Jul 7, 2017

Contributor

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.

Contributor

RobDolinMS commented Jul 7, 2017

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.

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

This comment has been minimized.

@darrelmiller

darrelmiller Jul 11, 2017

Member

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?

@darrelmiller

darrelmiller Jul 11, 2017

Member

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?

This comment has been minimized.

@timburks

timburks Jul 12, 2017

Contributor

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.

@timburks

timburks Jul 12, 2017

Contributor

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.

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

This comment has been minimized.

@darrelmiller

darrelmiller Jul 11, 2017

Member

Should format: uriref be added to termsOfService?

@darrelmiller

darrelmiller Jul 11, 2017

Member

Should format: uriref be added to termsOfService?

This comment has been minimized.

@timburks

timburks Jul 12, 2017

Contributor

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.

@timburks

timburks Jul 12, 2017

Contributor

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.

This comment has been minimized.

@darrelmiller

darrelmiller Jul 12, 2017

Member

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.

@darrelmiller

darrelmiller Jul 12, 2017

Member

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.

This comment has been minimized.

@handrews

handrews Oct 25, 2017

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.

@handrews

handrews Oct 25, 2017

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

This comment has been minimized.

Show comment
Hide comment
@KES777

KES777 Mar 29, 2018

When it will be officially released?

KES777 commented Mar 29, 2018

When it will be officially released?

@FRDavid FRDavid referenced this pull request May 28, 2018

Merged

Update/0.0.11 #1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment