[📝 Docs]: The Bundling Section of The Structuring doc needs updating for v2012

[theory]

What Docs changes are you proposing?

It looks like the Bundling section of the Structuring doc needs updating for v2020-12. Proposed changes:

• Use full $id in sub-schemas
• Use sub-schema $id string for $defs keys
• Note this change from 2019 in a new Draft-specific info tab

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[github-actions[bot]]

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.

[keys-i]

Hi theory!

[theory]

Hi yourself :-)

[keys-i]

Could I help with this too? :)

[theory]

I wouldn't complain.

[jdesrosiers]

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.

[theory]

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

[jdesrosiers]

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?

[Dule-martins]

@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

[theory]

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

[benjagm]

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

[Dule-martins]

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

[Dule-martins]

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

Thanks

[benjagm]

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

[Dule-martins]

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.

[jdesrosiers]

@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.

[github-actions[bot]]

Hello! :wave:

This issue has been automatically marked as stale due to inactivity :sleeping:

It will be closed in 180 days if no further activity occurs. To keep it active, please add a comment with more details.

There can be many reasons why a specific issue has no activity. The most probable cause is a lack of time, not a lack of interest.

Let us figure out together how to push this issue forward. Connect with us through our slack channel : https://json-schema.org/slack

Thank you for your patience :heart:

[theory]

How's it coming, @Dule-martins?

[Dule-martins]

Hello David Sorry for the long break, I have been on holiday I just resume work so am ready to be more active in the community

Can I still pick up from where I drop off?

On Thu, 6 Jun 2024 at 02:09, David E. Wheeler @.***> wrote:

How's it coming, @Dule-martins https://github.com/Dule-martins?

— Reply to this email directly, view it on GitHub https://github.com/json-schema-org/website/issues/647#issuecomment-2151210709, or unsubscribe https://github.com/notifications/unsubscribe-auth/AH4ASUUNFSF2YTGI5JMAOFDZF6ZDDAVCNFSM6AAAAABGCXBDFCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNJRGIYTANZQHE . You are receiving this because you were mentioned.Message ID: @.***>

[theory]

Hello David Sorry for the long break, I have been on holiday I just resume work so am ready to be more active in the community Can I still pick up from where I drop off?

I don't see why not. :-)

[Dule-martins]

Alright, sure I will take a look at it late a night. Thank you

On Thu, 6 Jun 2024 at 15:33, David E. Wheeler @.***> wrote:

Hello David Sorry for the long break, I have been on holiday I just resume work so am ready to be more active in the community Can I still pick up from where I drop off?

I don't see why not. :-)

— Reply to this email directly, view it on GitHub https://github.com/json-schema-org/website/issues/647#issuecomment-2152696152, or unsubscribe https://github.com/notifications/unsubscribe-auth/AH4ASUTR7V6UQFIYSQNN23DZGBXNNAVCNFSM6AAAAABGCXBDFCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNJSGY4TMMJVGI . You are receiving this because you were mentioned.Message ID: @.***>

[theory]

🎉