Skip to content
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

Add some paragraphs to Overview to put some context to "vocabulary" #1244

Closed
wants to merge 1 commit into from
Closed

Add some paragraphs to Overview to put some context to "vocabulary" #1244

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
37 changes: 27 additions & 10 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,19 +127,36 @@

<section title="Overview">
<t>
This document proposes a new media type "application/schema+json" to identify a JSON
Schema for describing JSON data.
It also proposes a further optional media type, "application/schema-instance+json",
to provide additional integration features.
This document specifies the media type "application/schema+json" which
can describe a set of JSON documents, classify documents as instances of this set,
and to generate annotations about a given instance.
It also specifies "application/schema-instance+json",
to describe JSON documents known to be instances of a particular schema.
JSON Schemas are themselves JSON documents.
This, and related specifications, define keywords allowing authors to describe JSON
data in several ways.
</t>
<t>
JSON Schema uses keywords to assert constraints on JSON instances or annotate those
instances with additional information. Additional keywords are used to apply
assertions and annotations to more complex JSON data structures, or based on
some sort of condition.
A JSON Schema document consists of a set of keywords,
typically encoded as properties in a JSON object.
The name of the keyword is used as the property name,
and any arguments to the keyword are provided as the value.
Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think the the spec uses the term "arguments" like this anywhere else. I'm not sure it's the best word for keyword values - it does make sense to me, but wording that's more consistent with the rest of the spec would be better.

Copy link
Member Author

Choose a reason for hiding this comment

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

I don't believe there's a formal term for these otherwise I would put that here... If we did have a term, I think it'd still be helpful to say it's an argument, the same way that functions have arguments. Do you have an idea for a better term?

</t>
<t>
Each keyword provides an assertion and/or annotations about the instance.
Assertions add constraints that instances must conform to.
Given a schema and an instance, the schema "accepts" an instance whenever all the assertions are met,
and the schema "rejects" when any of the assertions fail.
Schemas may also be used to build a set of JSON documents:
Copy link
Member

Choose a reason for hiding this comment

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

"build a set" sounds like you're entering data generation territory, which is not something we've discussed anywhere. (Yeah, I have a library that does that, but it's my design, not really based on any conversation here.)

Copy link
Member Author

Choose a reason for hiding this comment

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

I intend to mean "build" as in "set-builder notation" that JSON Schema closely resembles, e.g. {x | x is an even positive integer}. Is there a better phrasing? I think it's worth it to point out that describing requirements also can be used as a description of a set of members meeting those requirements.

Copy link
Member

Choose a reason for hiding this comment

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

I think maybe "define" or "denote" instead of "build" might be better?

Copy link
Member

Choose a reason for hiding this comment

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

I think this should end with a . rather than a :.

Suggested change
Schemas may also be used to build a set of JSON documents:
Schemas may also be used to build a set of JSON documents.

The "valid set" of a schema consists of all instances that the schema accepts,
and the "invalid set" of a schema consists of all instances that the schema rejects.
In a schema without any assertion keywords, the set of all instances is the set of all JSON documents.
Comment on lines +148 to +151
Copy link
Member

Choose a reason for hiding this comment

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

How necessary is it to bifurcate JSON documents into sets (explicitly)? It seems like this is an understood consequence of a schema passing or failing an instance.

Copy link
Member Author

Choose a reason for hiding this comment

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

Would it be better to take out "invalid set"? It might not warrant explaining, at least not in this section.

Copy link
Member

Choose a reason for hiding this comment

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

I'm wondering why the sets are mentioned at all. This statement doesn't seem to add anything beyond a definition.

Copy link
Member Author

Choose a reason for hiding this comment

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

I think the overview is a natural place to show how JSON Schema relates formal language theory to JSON. I can try to rework it so it doesn't sound like a definition, but I'd like to emphasize this is a logical consequence of how formal languages work, not a use case that we're meeting.

Copy link
Member

Choose a reason for hiding this comment

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

I agree that the intro is the right place, but I question its necessity.

Schemas defining sets of JSON instances isn't a concept that's discussed anywhere else in the document. As such, presenting this concept at all seems confusing.

If it were referenced somewhere else or provided a framework to explain some other idea, I could understand its inclusion, but not on its own.

Copy link
Member Author

Choose a reason for hiding this comment

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

You have a fair point, I'm trying to figure out if there's a better way to convey what this is intending to convey.

I'm not defining a concept that's going to be used by the rest of the document; rather it's describing a feature from formal languages that JSON Schema provides.

I have two alternate ideas I want to try...

</t>
<t>
Schemas may also provide "annotations" to instances:
metadata that describes the instance.
Comment on lines +154 to +155
Copy link
Member

Choose a reason for hiding this comment

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

I find this sentence awkward and I'm not sure this is a correct use of :. It's clear what you're saying, but I had to read it twice and slowly to follow it. I suggest breaking it into two sentences to make it easier for readers.

Suggested change
Schemas may also provide "annotations" to instances:
metadata that describes the instance.
Schemas may also provide "annotations" to instances. Annotations are
metadata that describe the instance.

For example, you can document the meaning of a property,
suggest a default value for new instances,
generate a list of hyperlinks from the instance,
or declare relationships between data.
</t>
<t>
To facilitate re-use, keywords can be organized into vocabularies. A vocabulary
Expand Down