Skip to content
This repository was archived by the owner on Nov 2, 2023. It is now read-only.

Include mission statement on the home page #423

Closed
wants to merge 4 commits into from
Closed

Include mission statement on the home page #423

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f768743
Include mission statement on the home page
Relequestual Dec 8, 2021
96e28c4
Update index.md
Relequestual Dec 9, 2021
e747392
Modify initial definition to more accurately describe JSON Schema
Relequestual Mar 10, 2022
7a877ff
Use "language"
Relequestual Nov 3, 2022
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
5 changes: 4 additions & 1 deletion index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,11 @@ permalink: /
---


**JSON Schema** is a vocabulary that allows you to **annotate** and **validate** JSON documents.
**JSON Schema** is a declarative ___domain specific language that allows you to **annotate** and **validate** JSON documents. JSON Schema enables the confident and reliable use of the JSON data format.

## Mission

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 use cases beyond validation.
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

Choose a reason for hiding this comment

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

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.


## Benefits

Expand Down