add description and examples for $anchor keyword

[AgniveshChaubey]

This PR addresses #53.

[jviotti]

Good take! I left some comments but indeed grasp the idea of anchors very well!

[jviotti]

Is this actually the case? I guess any valid URI fragment would do, but I might be wrong. i.e. 1234 or even something that looks like a JSON Pointer might in the theory do.

Can you cross check this with a few implementations and with the URI RFC?

[AgniveshChaubey]

Okay, let me verify

[AgniveshChaubey]

https://json-schema.org/draft/2019-09/json-schema-core#rfc.section.8.2.3

I tried with hyperhump schema validator which allows any string values (including special characters) without checking any format (which I think is not an expected behavior), whereas json everything strictly follows the above rule and only allows the $achors with above-mentioned format.

[jviotti]

Ah, great

[jdesrosiers]

If I remember correctly (and if it matters) this constraint didn't always exist. I think it was added in 2019-09. Sorry, for not looking it up myself.

[jviotti]

I think another point worth mentioning is that defining two equal anchors on the SAME schema resource is considered to be an error.

However, defining two equal anchors on DIFFERENT schema resources (i.e. subschemas with their own $id) is valid. Maybe show an example of that?

[AgniveshChaubey]

You mean something like this? ---
Valid:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/base",
  "properties": {
    "foo": {
      "$id": "one",
      "$anchor": "bar",
      "type": "integer"
    },
    "bar": {
      "$id": "two",
      "$anchor": "bar",
      "type": "string"
    }
  }
}

Invalid:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/base",
  "properties": {
    "foo": {
      "$anchor": "bar",
      "type": "integer"
    },
    "bar": {
      "$anchor": "bar",
      "type": "string"
    }
  }
}

However, the implementations do not throw any error for the second schema and the fragmented URI reference is resolved to the last $anchor

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/base",
  "properties": {
    "foo": {
      "$anchor": "bar",
      "type": "integer"
    },
    "bar": {
      "$anchor": "bar",
      "type": "string"
    },
    "baz": {
      "$ref": "#bar"
    }
  }

Instance: {"foo": 22, "bar": "aaaa", "baz": "aaaa" }

[jviotti]

However, the implementations do not throw any error for the second schema and the fragmented URI reference is resolved to the last $anchor

That's strange. Which implementations are you testing with?

[jviotti]

@jdesrosiers Shouldn't Hyperjump fail for the latter schema? i.e. same anchor twice in the same schema resource?

[jdesrosiers]

Having duplicate anchors doesn't make the schema invalid. It's just nonsense to do so and the behavior is undefined. It's like having a JSON value with duplicate properties ({ "a": 1, "a": 2 }). It's not invalid JSON, but you can't count on different implementations handling it the same way.

So, definitely tell users not to do that, but don't tell them they should expect an error.

[jviotti]

Ah, interesting. I thought it would result in an error. Then probably fine to ignore all this @AgniveshChaubey

[AgniveshChaubey]

Apologies for the delayed response. I've been dealing with some family issues, which is making me a bit distracted.

[jviotti]

No hurries at all! Take your time :)

[jviotti]

Approving it already, and we can sort out the case with conflicting anchors separately?

[AgniveshChaubey]

Sure! 👍