Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 3e55305

Browse files
committed
Generative use case guidance
This is going to be a powerful technique for generative use cases, which have been observed either requiring references (as opposed to subschemas) in certain places, or implementing various sorts of inferencing around references on their own or in conjunction with other keywords. For example, one OpenAPI documentation tool assumes that in an "allOf" of several references, the first is a base class of some sort. While this is not correct behavior by either JSON Schema or OpenAPI, it demonstrates a feature built by making implicit assumptions about certain references. This section provides a recommendation for making such behavior explicit, and also guides writers of such tools to the concept of extension vocabularies and annotations.
1 parent 27338fe commit 3e55305

File tree

1 file changed

+62
-0
lines changed

1 file changed

+62
-0
lines changed

‎jsonschema-core.xml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3589,6 +3589,68 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
35893589
</section>
35903590
</section>
35913591

3592+
<section title="References and generative use cases">
3593+
<t>
3594+
While the presence of references is expected to be transparent
3595+
to validation results, generative use cases such as code generators
3596+
and UI renderers often consider references to be semantically significant.
3597+
</t>
3598+
<t>
3599+
To make such use case-specific semantics explicit, the best practice
3600+
is to create an annotation keyword can be created for use in the same
3601+
schema object alongside of a reference keyword such as "$ref".
3602+
</t>
3603+
<figure>
3604+
<preamble>
3605+
For example, here is a hypothetical keyword for determining
3606+
whether a code generator should consider the reference
3607+
target to be a distinct class, and how those classes are related.
3608+
Note that this example is solely for illustrative purposes, and is
3609+
not intended to propose a functional code generation keyword.
3610+
</preamble>
3611+
<artwork>
3612+
<![CDATA[
3613+
{
3614+
"allOf": [
3615+
{
3616+
"classRelation": "is-a",
3617+
"$ref": "classes/base.json"
3618+
},
3619+
{
3620+
"$ref": "fields/common.json"
3621+
}
3622+
],
3623+
"properties": {
3624+
"foo": {
3625+
"classRelation": "has-a",
3626+
"$ref": "classes/foo.json"
3627+
},
3628+
"date": {
3629+
"$ref": "types/dateStruct.json",
3630+
}
3631+
}
3632+
}
3633+
]]>
3634+
</artwork>
3635+
</figure>
3636+
<t>
3637+
Here, this schema represents some sort of object-oriented class.
3638+
The first reference in the "allOf" is noted as the base class.
3639+
The second is not assigned a class relationship, meaning that the
3640+
code generator should combine the target's definition with this
3641+
one as if no reference were involved.
3642+
</t>
3643+
<t>
3644+
Looking at the properties, "foo" is flagged as object composition,
3645+
while the "date" property is not. It is simply a field with
3646+
sub-fields, rather than an instance of a distinct class.
3647+
</t>
3648+
<t>
3649+
This style of usage requires the annotation to be in the same object
3650+
as the reference, which must be recognizable as a reference.
3651+
</t>
3652+
</section>
3653+
35923654
<section title="Acknowledgments">
35933655
<t>
35943656
Thanks to

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /