Welcome to the JSON Schema Community. We are so excited you are here! Thanks a lot for reporting your first issue!! 🎉🎉 Please make sure to take a look to our contributors guide if you plan on opening a pull request. For more details check out README.md file.

Hi theory!

Hi yourself :-)

Could I help with this too?
:)

I wouldn't complain.

I actually rewrote this entire page as part of the 2020-12 updates. So, it's up-to-date with the latest specification.

• Use full $id in sub-schemas

Non-relative URIs aren't required in $id. What's required is that they resolve to a non-relative URI. The $ids in embedded schemas resolve against the identifier of the schema they're embedded in. I used the relative URI on purpose to illustrate that behavior.

• Use sub-schema $id string for $defs keys

Using the URI for the $defs key is a recommendation. It has no effect whatsoever on behavior, so it's a little odd to make a recommendation about this at all. The page could be updated to use the recommendation, but it is correct as is. The reason I didn't use a URI was to avoid the confusion that that value matters. By using something that doesn't match the $id, I was illustrating that that value could be anything.

• Note this change from 2019 in a new Draft-specific info tab

Not much really changed from 2019-09 to 2020-12. The recommendation about using URIs for embedded schemas in $defs is new. The ability to embedded a schema of a different dialect than the parent schema is new. The latter is probably worth mentioning in a "Draft-specific info" block.

I used the relative URI on purpose to illustrate that behavior.

I can see that but since I was looking into how to bundle schemas, I found this a little confusing, because it appeared to require a change to the $id. But it's not required --- and indeed I think it would be clearer, when talking about bundling, for the bundled sub-schemas to be identical to their previous structure, including the ID. Maybe note that they have have to resolve to the base URI.

Using the URI for the $defs key is a recommendation.

Okay, good to know. I was a little confused because it only worked for me to use the ID as the object key (using the boon library). It's possible I did something wrong, will try again.

The latter is probably worth mentioning in a "Draft-specific info" block.

+1

Ok. Let's change the embedded $ids to be the full URI and add a "Draft-specific info" block to call out that support for mixing drafts was added in 2020-12.

@radhesh1, it sounds like you would you like to work on this one? Unless @theory wanted to do it himself?

@theory if what you are proposing which is adding a Draft-specific info is the fix to this issue, can it be assigned to me for completion?

@benjagm what do you think?

I used the relative URI on purpose to illustrate that behavior.

I can see that but since I was looking into how to bundle schemas, I found this a little confusing, because it appeared to require a change to the $id. But it's not required --- and indeed I think it would be clearer, when talking about bundling, for the bundled sub-schemas to be identical to their previous structure, including the ID. Maybe note that they have to resolve to the base URI.

Using the URI for the $defs key is a recommendation.

Okay, good to know. I was a little confused because it only worked for me to use the ID as the object key (using the boon library). It's possible I did something wrong, will try again.

The latter is probably worth mentioning in a "Draft-specific info" block.

+1

Going with @theory on this one, because every documentation aims to provide clarity to the user, where there is clarity there is no confusion it is a seamless journey to implementation.

If we define the $id to be the unique identity every other user coming on the doc understands that yes this is the URI for the subschema and would not experience what @theory just experienced.

I think we can implement a more consistent approach towards using the $id

while going through the documentation in Draft-specific info Draft 4 specifies that id without the $ is just id which if I understand that correctly, means it is not a keyword in a subschema but when an id is used with the $ it indicates an embedded schema, show a keyword for example city.

where "$id": "https://example.com/schemas/city", showing the user the specific keyword value.

using $def defines an entire schema URI but it does not specify the keyword that could be queried

I do not have permission to assign people on this project.

Thanks everyone! Who is finally going to implement the solution? Happy to assign the issue to them.

@benjagm I updated my comment and I am open to work on this

@theory and @jdesrosiers please I left a comment on slack in #contributor channel can you take a look and give me feedback

Thanks

Hi @Dule-martins ! Can you please add here the same question you shared in Slack?

Okay, @benjagm

In the page section for "understanding-json-schema/structuring#bundling" to be sure I understand what and where the change is required to be implemented is it expected of a contributor to update the JSON sample code on the page by using the full $id URI in the root object for the sub-schema?

Within my drafted PR, the question I ask is what I did, but I am not sure if that is the correct thing to do.

@Dule-martins, the answer is here

• The $defs keys should remain the same.
• All $ids should to be changed to absolute URIs.
• Add a Draft-specific Info block to say that support for changing dialects in an embedded schema (using $schema with a different value than the parent schema) was added in 2020-12. This topic is covered in the last paragraph and Draft-specific Info box. You should just have to add another Draft-specific Info box at the end explaining the difference in 2019-09 because the difference for draft-04/6/7 is already covered.