fix: side effects in tag references

[baywet]

This fixes multiple issues:

• tag references are not like other component references. The tag in the operation is just a string. We had a lot of special casing, etc...
• lot of side effects where we were impacting the source tag by assigning things to the reference. As discussed in v2 - security - correct the proxy design implementation #1998
• fixes references not being resolvable in a lot of contexts due to a missing document reference.

We should still break the inheritance, and use a base abstract class as well.

[darrelmiller]

I'm not sure I agree with this. Tag references are very similar to using $id to reference a Schema, where the target object is implicitly created. I agree that it was a bit of a stretch when $refs could only use locators, but now that we need to support $refs as identifiers, I think there is a strong parallel.

[baywet]

The previous model results in tons of side effects.
I get the fact that we want to facilitate the readers life, but anybody making changes and not paying attention to the underlying specification is in for troubles.

A simple example:

• parse a description with tags
• on an operation, grab a tag
• add an extension to it
• you've now updated that tag for the whole document.

Same goes for the description, the tag name etc...

[sonarqubecloud]

Quality Gate failed

Failed conditions
75.9% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

[darrelmiller]

A simple example:

parse a description with tags
on an operation, grab a tag
add an extension to it
you've now updated that tag for the whole document.
Same goes for the description, the tag name etc..

Isn't that the expected behaviour?

[baywet]

A simple example:
parse a description with tags
on an operation, grab a tag
add an extension to it
you've now updated that tag for the whole document.
Same goes for the description, the tag name etc..

Isn't that the expected behaviour?

From a proxy design pattern, sure. But from a functional point of view, I'd say it's pretty confusing/could lead to nasty production bug since the object model is the same, and the behaviour was different. The message I'm trying to convey here is that we're in control of what properties (or operations) can be proxied, IMHO we should allow reads, and then ask people to go through the Target property for writes. That of course leaves a big question for collections.

[darrelmiller]

Why does this need to implement IOpenApiReferenceable? None of the other proxy objects do.

[darrelmiller]

Apparently it is a bug in every other reference class because the walker expects all references to implement IOpenApiReferencable /cc @MaggieKimani1

[darrelmiller]

Sorry, I was being slow. I agree that editing the reference should not edit the target. I agree with your changes.

[baywet]

Sorry, I was being slow. I agree that editing the reference should not edit the target. I agree with your changes.

That just means the vacations were good!