Adjust uri to uri-reference for security schema fixed fields

[markrzen]

Resolves #4327

Tick one of the following options:

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[mikekistler]

Why not change all the format: uri to format: uri-reference. I could not find any fields defined as URIs and forbid relative references (but I am surprised that the OAuth ones allow them).

[markrzen]

I didn't make that change initially only because I didn't have time to consume the whole specification to confirm that all the uri references didn't have specification that explicitly forbid relative.

I am happy to update the PR if someone more knowledgable than I can confirm that is accurate.

My hesitation came from the following, which planted the "seed of doubt" that there may be some exclusion hidden away on one of the uri usages.:

Unless specified otherwise, all fields that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.

[handrews]

The XML Object namespace MUST be non-relative. That's the only one I can find.

[handrews]

@markrzen Update from today's TDC call: If you're up for changing the other format: uri to format: uri-reference except the XML Object's namespace field, please go ahead and do so. If not, let us know and we can take this as-is and one of us will do a follow-up PR.

[markrzen]

@handrews On it right now.

[markrzen]

@handrews I could only find the xml object in the meta.yaml, and that document already looked correct.

[karenetheridge]

I found one change that should be reverted; the others look ok to me (not sure about the security ones though).

[karenetheridge]

This one is the twin to JSON Schema's $schema keyword, and therefore cannot be a uri-reference.

[handrews]

@karenetheridge philosophically I agree with you, but the way the OAS field is written unfortunately allows a relative URI-reference. Of course you'd have to resolve that before you could use it as a dialect URI, and the only way that might work is with a custom dialect, but there's no reason it couldn't work that way.

I do agree that it should have been written as requiring a non-relative URI.

[markrzen]

Happy to make the change if needed. Waiting for maintainer to come to an agreement.

[karenetheridge]

@handrews what do you mean "the way the OAS field is written unfortunately allows a relative URI-reference"? What are you referencing here?

[handrews]

@karenetheridge It's the combination of two things:

§4.6.7 states:

Unless specified otherwise, all fields that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.

while the fixed fields description for jsonSchemaDialect says:

The default value for the $schema keyword within Schema Objects contained within this OAS document. This MUST be in the form of a URI.

Strictly speaking, this text allows a URI reference. The value used with $schema of course must be a full URI, but that can be produced by resolving the relative URI-reference normally, just as with any other field that the OAS says "MUST be in the form of a URI". What is used with $schema is the resolved value, not the literal text.

At least that is my interpretation. We can always kick it up to @OAI/tsc for a ruling if you disagree. Again, I prefer your reading (and really dislike that we don't just explicitly say "URI-reference" and instead say "URI means URI-reference unless otherwise stated") but that's what we have to work with.

[karenetheridge]

At the very least we need to tighten up the language that leaves this vague. It is not reasonable to say in one place that a value is a URI, and then at the top say "actually that means URI-reference" because now there's no way to say that no, really, this actually has to be a fully-resolved URI.

Also, in any place where we do allow a URI-reference, we should be explicit as to how that value will be resolved -- whether it's against the URI used to identify the entry document, the current document, or the Host header on the current HTTP request under consideration (when relevant) -- I can see places where each of these might be the appropriate choice for URI resolution.

[handrews]

@karenetheridge take a look at the XML Object's namespace field for how we say a field is a fully-resolve URI (again, I agree we should use the correct terminology per RFC3986 and not what we're doing now, but we do have ways to say we don't want a non-relative reference). We are very explicit about how OAD URI-referencess and API URL-references are resolved. Each of those topics gets a full section in the 3.1 specification. In any event, this is drifting outside of the scope of this PR and should continue in a discussion or issue.

[mikekistler]

Looks good. 👍

[handrews]

@karenetheridge it sounded like you accepted my reading of the spec for jsonSchemaDialect in the last comment, so I'm going to go ahead and merge this. If I'm wrong, lmk and we'll sort it out.

[handrews]

@karenetheridge or not... can you remove your "changes requested"?

[handrews]

Oh this is because there's only one approval- it's too early in the morning for me to be doing code reviews apparently. @karenetheridge or @mikekistler if either of you is willing to give an approval that will do it.

[mikekistler]

Looks good! 👍

[seriousme]

Apparently it needs explicit approval from @karenetheridge as the two approvals from @mikekistler and @handrews are in but the flow is still blocked.

[markrzen]

Someone with write access to the repo can likely dismiss the request for change.

[handrews]

I'll check with @karenetheridge on this directly to resolve, she might just not have seen this in the last few days.

Apparently we don't explicitly disallow uri-reference for jsonSchemaDialect, so we have to allow it for now.

We should still amend the spec to make this more clear, and specify which uri this uri-reference should resolve against (I suppose it would have to be the uri of the containing document itself).

[ralfhandl]

@markrzen Thanks for your contribution, and extra thanks for your patience 😊

[seriousme]

Thanks to all for making this work!
Sorry if the question is inappropriate here, but can you indicate when the v3.1-dev will be "officially released" as update to v3.1 in the gh-pages branch?

Reason for asking is that I maintain tooling that builds on the "officially released" schema's and I'd like to offer @markrzen the update merged in this PR in my tooling. (see Mark's initial post in #4327)

Kind regards,
Hans