Maybe we need a new keyword instead of $dynamic*

[gregsdennis]

From https://github.com/orgs/json-schema-org/discussions/362

a regular $ref is it allowed to access a $dynamicAnchor ? - @SorinGFS

Technically, yes, but there's is no good reason for a schema author to do so. I expect that to change in a future release so that you can only reference a dynamic anchor with a dynamic reference. - @jdesrosiers

I have issue with the assumption that there's not a good reason to use a $ref to resolved to a $dynamicAnchor. We don't want to assume our users' needs or that they won't find ways to take advantage of functionality that we've published.

Currently, such references are allowed. A user can do this:

{
  "$defs": {
    "foo": {
      "$dynamicAnchor": "foo",
      "type": "string"
    }
  },
  "type": "object",
  "if": {
    "properties":{
      "allow-dynamic": { "const": true }
    },
    "required": [ "allow-dynamic" ]
  },
  "then": {
    "properties": {
      "foo": {
        "$dymamicRef": "#foo"
      }
    }
  },
  "else": {
    "properties": {
      "foo": {
        "$ref": "#foo"
      }
    }
  }
}

Thus, the data, by optionally including allow-dynamic: true, determines whether the dynamic reference is followed. This is just a scenario that I came up with off the top of my head. I'm sure that there's someone out there who has a more legitimate need for this behavior.

This works because $dynamicAnchor also produces a referenceable anchor, like $anchor does. The difference is that the dynamic one is usable by $dynamicRef while $anchor is not. If we isolate $dynamic* from the $anchor/$id/$ref referencing mechanism (which is the second part of Jason's comment), then this use case is broken.

The schema would have to explicitly include an $anchor in order to get the same result.

{
  "$defs": {
    "foo": {
      "$anchor": "foo",
      "$dynamicAnchor": "foo",
      "type": "string"
    }
  },
  // ...
}

It's not a big change, but I'm not sure that we want to break this behavior, especially since this behavior was intended and not just an "insufficiently specified" bug.

If isolating these referencing mechanisms is a goal, then I think it may be more appropriate to create a new keyword and deprecate $dynamic*.

I'm not saying that $dynamic* should or should not work this way. I'm just saying that it does, and changing it would break users who are taking advantage of this behavior.

This also has bearing on https://github.com/orgs/json-schema-org/discussions/472.
Also ref: json-schema-org/json-schema-spec#1056

[SorinGFS]

My 100% working solution (in my own project) to this problem was to collapse $dynamic* functionalities into their corresponding keywords ($ref and $anchor) and to mark dynamic intent by adding an _ prefix to them. This way there is no workaround left to avoid the specs. Moreover, by having a single reference keyword would simplify the whole picture. Plus, this is not the only reason for collapsing the $dynamicRef functionality into $ref: if the dynamic reference is a reference to another domain name, then $dynamicRef should behave similar to $ref for the first part of the uri, the only dynamic part is the fragment!

Note: I know that @jdesrosiers does not agree to collapsing the $dynamicRef functionality into $ref, but no matter how much I was trying to find a good reason to have separate keywords I couldn't find one.

[jdesrosiers]

That's certainly not a case that's ever occurred to me, but I still think it falls into the category of things you can do with dynamic references but shouldn't. There's no good reason that $ref should be pointing to a $dynamicAnchor. I would have used "#/$defs/foo", but your example of using an $anchor is fine too.

I'm confident in saying that there's no good reason for a $ref to point to a $dynamicAnchor because you can always express the same thing using normal referencing. No matter how creative schema authors get, that fact doesn't change. Using dynamic keywords to do something that could be done with regular referencing is always using the wrong tool for the job.

However, you're definitely right that this would technically be a breaking change. Even if there's no good reason to use dynamic keywords when normal referencing will do, that doesn't mean that people aren't doing it. I'm not too worried about that for a few reasons.

(1) We haven't yet committed to the $dynamic* keywords being stable, so changes should be allowed. Ideally we don't want to have to make changes and especially not breaking changes, but that sort of thing is sometimes necessary at this stage of a new keyword's evolution.

(2) Anyone using dynamic references properly will not be affected.

(3) Anyone not using dynamic reference properly will be forced to change their schemas, but they'll be forced to change it to do what they should have been doing in the first place. That's as positive an outcome from a breaking change than there possibly could be.

(4) Dynamic references serve a very niche use case, are not well understood, not well supported by implementations, and not well documented. Given all of these factors, the dynamic keywords are not widely used and those few users are going to be predominantly power users. So, I think it's reasonable to assume that the few that have overcome all of those hurdles to using dynamic references are very likely to be savvy enough that their unlikely to be using those keywords in a way that they would be affected by this change.

(5) If we decide that we need to introduce a new keyword to make this minor change, in order to update to the next release, everyone using the dynamic keywords correctly will need to change the keyword name they use in their schemas even though they behaviors haven't changed for them at all. I think it's a bigger and less desirable to impact everyone using these keywords rather than just impact the few that aren't using the keywords as intended.

[gregsdennis]

So after the OCWM call this week it looks like we want to remove the bookending and initial resolution requirements and keep the name for the stable spec. This means that if for some reason we need different behavior, we'll need to follow the deprecation process.