Skip to content

Best practices for generative use cases adding semantics to references #789

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.

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

Closed
wants to merge 1 commit into from

Conversation

handrews
Copy link
Contributor

Note that this was at one point going to be part of #788,
but it turned out they could be done separately.

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.

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.
@handrews
Copy link
Contributor Author

I'm taking this down to re-post it with a better-organized best practices section.

@handrews handrews closed this Aug 24, 2019
@handrews handrews deleted the sem-ref branch May 15, 2020 18:45
@gregsdennis gregsdennis added clarification Items that need to be clarified in the specification and removed Type: Maintenance labels Jul 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
clarification Items that need to be clarified in the specification core
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants