Include mission statement on the home page

[Relequestual]

Resolves json-schema-org/community#97

[netlify]

✅ Deploy Preview for condescending-hopper-c3ed30 ready!

Name	Link
🔨 Latest commit	7a877ff
🔍 Latest deploy log	https://app.netlify.com/sites/condescending-hopper-c3ed30/deploys/6363cfdc1f5522000946e826
😎 Deploy Preview	https://deploy-preview-423--condescending-hopper-c3ed30.netlify.app/
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[jdesrosiers]

I don't think "vocabulary" is the right word here. Maybe something more like this?

Suggested change

	**JSON Schema** is a vocabulary that allows you to **annotate** and **validate** JSON documents. It enables the confident and reliable use of the JSON data format.
	**JSON Schema** is a JSON document that allows you to define rules to **annotate** and **validate** JSON documents. It enables the confident and reliable use of the JSON data format.

[Relequestual]

I would argue that "A JSON Schema" is a "JSON document", while "JSON Schema" the specification defines a vocabulary for use within "a JSON Schema JSON document"

[Relequestual]

Also, this is not something that has changed in this PR.
This PR adds to that line, but mainly it's about the additional "mission" section.

[jdesrosiers]

I'm fine if you don't want to change this now. It's just something that bothers me every time I see it and this seemed like a good opportunity to fix it. What does "vocabulary" even mean in this context? I'm pretty sure it has nothing to do with JSON Schema Vocabularies, but I can't be sure. It's just way too generic a word to be meaningful.

As I seem to be saying a lot lately, I like to describe JSON Schema as a declarative ___domain specific language for validating and annotating JSON-compatible data. I suggest we used those words, but whatever you choose is fine even if you choose to do nothing for now and come back to it later.

[Julian]

It's being used in a non technical sense I suspect. And very likely predates any technical thing called vocabularies in JSON Schema. It doesn't bother me a ton but I agree it doesn't seem like the best way to describe us either so I'm definitely not opposed to changing it either.

[Relequestual]

Indeed. I intended it in the generic term.
Maybe "lexicon" might be more accurate? Feels a little garish though. It's less commonly used.

"JSON Schema (the specifications) is a vocabulary (set of keywords with specific semantics) that allows you to..." is how I see it.

While WE here know of a JSON Schema Vocabulary, most people will not. This headline / tagline section is very much aimed at those stumbling onto the site for the first time.

[awwright]

This strikes me as a bit wordy. It doesn't help me understand if I'm the target audience or not.

declarative ___domain specific grammar and syntax

This is too many adjectives for me. Describing the technical basis of JSON Schema is a good idea, but they can be split out into a separate sentence that defines the lingo. For example

JSON Schema is declarative, where you make assertions about what JSON is expected to look like.

"___domain specific" is redundant (we say it's only for JSON, that's it's "___domain"). And "grammar and syntax" I don't think is accurate (the grammar is JSON, we don't define our own grammar, we define an existing grammar's semantics).

JSON Schema enables the confident and reliable use of the JSON data format.

This doesn't help me understand if I'm the target audience or not. If we absolutely have to, describe the impact on actual developers, like "Developers use JSON Schema as a reliable alternative to hard-coding validation rules in code."

[jdesrosiers]

"___domain specific" is redundant (we say it's only for JSON, that's it's "___domain")

The ___domain is JSON validation and annotation, but I agree that "___domain specific" is not useful for anyone who isn't familiar with the concept of a ___domain specific language (DSL). Would this be better?

JSON Schema is a declarative language that allows you to annotate and validate JSON documents.

[awwright]

JSON Schema is a declarative language that allows you to annotate and validate JSON documents.

💯

[awwright]

The only reason I would prefer "vocabulary" or some similar term over "language" is because "language" to me includes both the grammar/syntax and the vocabulary. JSON Schema does not define any syntax, only the vocabulary.

But it also seems to me "language" is a more accessible term than "vocabulary", here.

[handrews]

I would like to add something to this that mentions annotation by name, because the spec should ensure interoperability around producing and consuming annotations. The phrase "supporting use cases beyond validation" is vague and completely open-ended. Annotations are how additional use cases are supported, and that's what the JSON Schema project is concerned with.

Perhaps just this would do:

Our mission is to enable the definition of interoperable contracts for JSON data in the form of schemas, using constraints-based validation rules, while enabling and supporting further use cases through annotation.

I think that makes it clear that both validation and annotation are part of the interoperable contracts.

[Relequestual]

Good point. Thinking on this though, I consider the use case where a schema is taken "as is" without an instance, and something is created, like a class or a database table (or 2). Are they still annotations?

I wonder if there's a new class of keywords for new vocabularies which are intended to be used without an instance in mind... maybe "declaration". I guess that could be seen as we're saying it's a "declarative" language. We have the duality being used both with and without an instance. Without an instance, it sort of becomes declarative, but still constraints based.

[handrews]

Thinking on this though, I consider the use case where a schema is taken "as is" without an instance, and something is created, like a class or a database table (or 2). Are they still annotations?

Ooooh... excellent question! Yeah, I've tended to think of that as a different way of making use of the existing keyword classes (not just annotations - assertions like type and applicators like properties are part of such cases as well). But that way of declaring things with a schema is worth calling out explicitly. I think of these as "generative" use cases (generating an instance from a schema- not necessarily generating a JSON instance but usually a code generator or whatever is still working with the JSON data model which is translated further into Java, SQL, etc.

Definitely worth further thought and clear language.

[handrews]

I'm marking this "request changes" because the discussions seem to have stalled with several open questions despite the approval from earlier.

[Relequestual]

While the first part of the change makes senes, I'm not sure the "mission" part does right now.

I'll move the first part of this PR to a new PR, and close this PR, in favour of further investigation on vision and planning with a deliverable being a charter and mission statement.

[Relequestual]

Closed in favour of #487