Skip to content

Define compound schema documents (#936) #977

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 22 commits into from
Oct 25, 2020
Merged

Define compound schema documents (#936) #977

Changes from 1 commit
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
2a788d8
First attempt to resolve #936
Relequestual Aug 29, 2020
67c00d2
Update jsonschema-core.xml
Relequestual Sep 27, 2020
2dc975a
Update jsonschema-core.xml
Relequestual Sep 27, 2020
d3f6274
Use correct termonology 'by-reference applicator'
Relequestual Sep 27, 2020
ac9ec4f
Don't mention 'derferenced' schemas in the section related to compoun…
Relequestual Sep 27, 2020
3c99506
Rephrase definition of Compound Schema Document to only be about tran…
Relequestual Sep 28, 2020
7beb355
Move some content of use of schema within Compound Document resources…
Relequestual Sep 28, 2020
c44829d
Rephrase recomended validation process for processing a schema docume…
Relequestual Sep 28, 2020
959fb2b
Fix invalid XML
Relequestual Sep 28, 2020
375cb26
Fix bad reference
Relequestual Sep 29, 2020
08e9e60
Rephrase process of schema bundling to make clear that existing refer…
Relequestual Sep 29, 2020
f82ee55
Clarify that the bundling process is not the only way to create a Com…
Relequestual Oct 6, 2020
6cf7022
Document root is only SHOULD for $id.
Relequestual Oct 6, 2020
976a6fb
Use correct terms for bundling process of Compound Schema Documents
Relequestual Oct 6, 2020
49d77b2
Fix grammar
Relequestual Oct 6, 2020
5d36e17
Small gramatical changes
Relequestual Oct 6, 2020
4eacfe3
Better specify the process of validating a Compound Schema Document
Relequestual Oct 6, 2020
b27a703
Remove non-required phrasing
Relequestual Oct 7, 2020
9f51c19
Fix typos
Relequestual Oct 20, 2020
0409c72
Specifically mention that bundling is done in such a way so as to avo…
Relequestual Oct 20, 2020
13867cd
Specifically mention why referenes MUST NOT be changed when creating …
Relequestual Oct 20, 2020
20e1910
Add Compound Schema Document to changelog
Relequestual Oct 25, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
First attempt to resolve #936 
Define Compound Schema Document and associated concerns
  • Loading branch information
@Relequestual
Relequestual committed Oct 6, 2020
commit 2a788d869bbe0c0c72b1a222f87a0c03145eb677
42 changes: 42 additions & 0 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1845,6 +1845,48 @@
</section>
</section>

<section title="Compound Documents">
<t>
A Compound Schema Document is defined as JSON document (sometimes called a "dereferenced" or
"bundled" schema) which has multiple embedded JSON Schema Resources bundled into the same
document to ease transportation.
</t>
<t>
Each embedded Schema Resource MUST be treated as an individual Schema Resource, following standard
schema loading and processing requirements, including determining voacbulary support.
</t>
<section title="Bundling">
<t>
A Compound Schema Document is created by replacing references (such as "$ref") with an
embedded version of the referenced Schema Resource.
</t>
<t>
Each embedded JSON Schema Resource (and the document's root) MUST identify itself
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically the document's root is only a SHOULD for $id, although the embedded resources are indeed a MUST. We probably just want to talk about the embedded ones here as the document root is covered under $id.

with an absolute URI using the "$id" keyword, and SHOULD make use of the "$schema"
keyword to identify the dialect it is using, in the root of the schema resource.
</t>
<t>
When a reference applicator is dereferenced as part of the bundling process, the Schema Resource
MUST NOT be embedded by replacing the schema object from which it was referenced, or by wrapping
in other applicator keywords. In stead, a bundled Schema Resource MUST be located in `$defs`,
where the key is the `$id` of the Schema Resource, which MUST then be referenced using `$ref`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is easier if you just say that the original reference MUST be left unchanged (but could later be changed through dereferencing, which is defined separately).

</t>
</section>
<section title="Validating">
<t>
Given a Compound Schema Document may have embedded resources which idenfiy as using different
dialects, it is NOT RECOMMENDED that these documents are validated by applying a meta-schema
to the Compound Schema Document as an instance. It is RECOMMENDED that an alternate
validation process be provided in order to validate Compound Schema Documents
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this need to be an alternate for compound schema documents, or just an alternate for schema documents (schemas against meta-schemas) in general? You should always be able to tell whether a given schema is compound, so if you know your instance is a schema that is enough.

We don't want to encourage two different meta-schema functions, because if someone validating a non-bundled schema with the "regular" meta-schema validation function, but then that schema got changed to a bundled schema, it would now require a code change to be handled correctly. We never want to require a code change to keep validation working.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The consensus in the associated issue was that a compound document would be transport only, in that you can't validate it by applying a meta schema to it as an instance.
Check the issue for the reasoning and justification.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Relequestual I think @handrews was just concerned that this could be misunderstood to mean that you need a separate process to validate a schema than you do to validate a compound schema. The process for validating schema documents is the process for validating compound schema documents.

I think the suggestion would be to do something like ...

It is RECOMMENDED that an alternate validation process be provided in order to validate Compound Schema Documents

The "Compound" part is implied because all schemas are potentially compound.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Relequestual yes, what @jdesrosiers said.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, we are on the same page now. I don't disagree.
But, I'm now not sure about a few things. I'm saying the following having not reviewed the issue again (because this is a quick comment in a few mins spare time).

I thought in the issue we said it wouldn't be possible to identify a compound schema document vs a normal schema document, although that may have been in context of being an instance.

I'm going to HAVE to review the issue discussion again. It's fine =]

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought in the issue we said it wouldn't be possible to identify a compound schema document vs a normal schema document, although that may have been in context of being an instance.

Yes, that was in the context of being an instance. It's not possible to identify an instance as a schema (compound or otherwise).

(such as a differnet function).
</t>
<t>
A Compound Schema Document in which all embedded resources idenfity as using the same
dialect MAY be validated by applying the appropriate meta-schema.
</t>
</section>
</section>

<section title="Caveats">
<section title="Guarding Against Infinite Recursion">
<t>
Expand Down