OAuth Flow required fields + validation

[char0n]

Hi everybody,

I'm currently working on some tooling regarding OAS 3.0.0 and found a situation where I'd need some clarification. Spec defines OAuth Flow Object as an object with following fields required:

• authorizationUrl
• tokenUrl
• scopes

This is crystal clear so far. Next I'm using JSON Schema provided in this repo to validate the OAS 3.0.0 definition. But looking into the JSON Schema document reveals that none of the OAuth Flow objects require above define fields to be required. Some OAuthFlow objects requires just one field, other two. I'm not sure if this is intended (for particular type of OAuth Flow to have only certain fields required) or this is something we should fixed.

Update
I completely missed Applies To column of OAuth Flow Object. That clarifies things out. But scopes are required in ImplicitOAuthFlow only, even though they should be required in all flow types. In this case is the spec or the JSON Schema the source of truth?

  ImplicitOAuthFlow:
    type: object
    required:
      - authorizationUrl
      - scopes
    properties:
      authorizationUrl:
        type: string
        format: uri-reference
      refreshUrl:
        type: string
        format: uri-reference
      scopes:
        type: object
        additionalProperties:
          type: string
    patternProperties:
      '^x-': {}
    additionalProperties: false

  PasswordOAuthFlow:
    type: object
    required:
      - tokenUrl
    properties:
      tokenUrl:
        type: string
        format: uri-reference
      refreshUrl:
        type: string
        format: uri-reference
      scopes:
        type: object
        additionalProperties:
          type: string
    patternProperties:
      '^x-': {}
    additionalProperties: false

  ClientCredentialsFlow:
    type: object
    required:
      - tokenUrl
    properties:
      tokenUrl:
        type: string
        format: uri-reference
      refreshUrl:
        type: string
        format: uri-reference
      scopes:
        type: object
        additionalProperties:
          type: string
    patternProperties:
      '^x-': {}
    additionalProperties: false

  AuthorizationCodeOAuthFlow:
    type: object
    required:
      - authorizationUrl
      - tokenUrl
    properties:
      authorizationUrl:
        type: string
        format: uri-reference
      tokenUrl:
        type: string
        format: uri-reference
      refreshUrl:
        type: string
        format: uri-reference
      scopes:
        type: object
        additionalProperties:
          type: string
    patternProperties:
      '^x-': {}
    additionalProperties: false

Thanks for any clarification to this!

[MikeRalphson]

In this case is the spec or the JSON Schema the source of truth?

The markdown spec is always the source of truth.

Pinging @jdesrosiers for the meta-schema issue.

[jdesrosiers]

I'm not too familiar with the 3.0 schema, but I'll take a look. Sounds like it's just missing a required somewhere.

[webron]

The confusion might be from missing the Applies To column in the spec. The fields are only applicable to specific flows, and only if they are applicable they'd be required. That's why the different flows in the JSON Schema has different ones required for different flows (based on the aforementioned column).

[char0n]

I'm not too familiar with the 3.0 schema, but I'll take a look. Sounds like it's just missing a required somewhere.

@jdesrosiers I can issue a PR with JSON Schema conforming the to the spec.

The confusion might be from missing the Applies To column in the spec. The fields are only applicable to specific flows, and only if they are applicable they'd be required. That's why the different flows in the JSON Schema has different ones required for different flows (based on the aforementioned column).

@webron yeah might as well be. When I first reported this, I missed the Applies To as well. Then a minute later when I've discovered it I've appended another section labelled Update to the issue description.

[webron]

That should teach me not to only read email notifications ;) Yeah, that should be a fairly simple fix, just add the scopes to the required list in the other workflows. Thanks, @char0n!

[char0n]

Pull request has been issued against main branch: #2673

[char0n]

After merging #2673 we've noticed that json and yaml schemas are now different (https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.0). According to the README the json should be generated but it wasn't. It can cause problems for anybody pulling the schema into their tool assuming that yaml and json versions are the same.

[MikeRalphson]

@char0n thanks - I'm working on the GitHub action to regenerate and republish the schemas when they change but it has taken longer than expected. I'll raise a PR to resync manually.

[LasneF]

@MikeRalphson , @jdesrosiers
there is may be a full resynch to do , as 3.0 is out of synch as well as 3.1

i would suggest to may be abandon the synch and keep only one source of truth
(preferably the Json one as more standard for tooling)

duplication of information is source of confusion and complication

[handrews]

@LasneF we already have issues tracking the myriad problems with the schemas and their deployment. The should be included on in Automation & Infrastructure project and are just waiting for someone with time and inclination to sort it out.

BTW, we manually edit the YAML schema (because it's human-friendly) and then auto-generate the JSON one. In theory, anyway.

[handrews]

Since the only problem here is the deployment and we have issues tracking that (see previous comment), I'm going to close this.