Question: $id keyword and dereferencing

[char0n]

Hello everybody,

I have a question related to $id keyword and deferencing. Let's say I have the following OpenAPI 3.1 definition containing pair of top-level JSON Schema Object - User and UserProfile. On the following definition I'm using $anchor to reference UserProfile from User.profile property.

Using $anchor:

{
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "login": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "profile": {
            "$ref": "#user-profile"
          }
        }
      },
      "UserProfile": {
        "$anchor": "user-profile",
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          }
        }
      }
    }
  }
}

Now to my question; if I understand the JSON Spec correctly I can use $id keyword to achieve the same as $anchor?

Using $id:

{
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "login": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "profile": {
            "$ref": "https://very-arbitrary-url.com/path"
          }
        }
      },
      "UserProfile": {
        "$id": "https://very-arbitrary-url.com/path",
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          }
        }
      }
    }
  }
}

When dereferencing this definition, we first search for JSON Schema identified with $id=https://very-arbitrary-url.com/path, and only if not found in current document, we resolve the URL(https://very-arbitrary-url.com/path) and assume that the JSON Schema is the result of fetching this URL?

Thank you very much!

[jdesrosiers]

That's mostly correct, although there's a lot more to $id than that.

only if not found in current document, we resolve the URL [] and assume that the JSON Schema is the result of fetching this URL?

That depends on what you mean by "fetch". In JSON Schema, references are never expected to be fetch other the network or filesystem. An implementation could do that, but most don't. Generally, you load any external schemas into the validator and then the implementation uses that to fetch schemas. So, some pseudocode for an OpenAPI parser might look something like this,

OasParser.addSchema({
  "$id": "https://very-arbitrary-url.com/path",
  "properties": {
    "firstName": { "type": "string" },
    "lastName": { "type": "string" }
  }
});

OasParser.parse({
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "login": { "type": "string" },
          "password": { "type": "string" },
          "profile": { "$ref": "https://very-arbitrary-url.com/path" }
        }
      }
    }
  }
});

The addSchema method uses the $id keyword to associate the https://very-arbitrary-url.com/path URI with the schema and makes it available to be referenced in other schemas.

I suggest having a look over Understanding JSON Schema - Structuring a Complex Schema. It covers everything about schema identification and referencing. I think you'll find it useful.

[char0n]

That's mostly correct, although there's a lot more to $id than that.

Sure I realize that, it's a very complicated topic ;]

That depends on what you mean by "fetch". In JSON Schema, references are never expected to be fetch other the network or filesystem.

I mean exactly that - given that there isn't a JSON Schema in the internal database identified by referenced $id, the only other thing left to do is to try to fetch the URI if the URI is an URL (HTTP/filesystem/mongo database/whatever...).

So building on my example:

{
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "login": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "profile": {
            "$ref": "https://very-arbitrary-url.com/user-profile"
          }
        }
      }
    }
  }
}

...I would expect the implementation to try and fetch the https://very-arbitrary-url.com/user-profile URL and assume the response under this URL is a JSON Schema.

An implementation could do that, but most don't.

Well that's a good news, at least I know now that I'm not doing something very wrong. My goal is to make life of implementation user as easy as possible. I'm trying to construct internal schema database for him/her and make it as much complete as possible.

Generally, you load any external schemas into the validator and then the implementation uses that to fetch schemas.

That's what I've seem for example with ajv JavaScript validator. As mentioned above, I'm trying to automate this step of manually adding schemas.

Understanding JSON Schema - Structuring a Complex Schema

I've read it before and now read it again, I think I do understand the concept properly (well at least I hope I do;)

Thanks for you answer!