JSight API and JSight Schema languages — you have never specified APIs and data schemas so fast! We mean it.
- 2–4 times less code.
- APIs and data schemas designing is 2–3 times faster.
- The describing process does not detract from the design.
- It is incredibly convenient to jointly design an API with the whole team in one go. No more multiple design iterations and edits required. All you need is to share the screen between the participants and come up with an API together right in the JSight Online Editor.
- All this is possible thanks to the compactness and simplicity of the JSight API and JSight Schema
languages.
Compare JSight API with Open API.
Compare JSight Schema with JSON Schema.
Supported standards: HTTP REST, JSON-RPC 2.0.
“JSight is as much simpler than OpenAPI as Markdown is simpler than HTML. At the same time, JSight is just as powerful.”
Constantine M., JSight CRDO.
JSight API and JSight Schema are two independent languages, while the JSight Schema language is a part of the JSight API language.
JSight Schema language is designed to describe data schemas, regardless of the serialization format.
JSight API language is designed to describe APIs of different standards. Currently, HTTP REST API is supported. Other types of APIs will be supported in the future. The JSight API language uses the JSight Schema language to describe input and output data.
You can always try the JSight API language (and JSight Schema) in the JSight Online Editor: https://editor.jsight.io.
- JSight API Language
- JSight Schema Language
- Roadmap
- Versioning
- Dependencies
- Contributing
- Bugs and Feature Requests
- Support
- License
- Resources
- Partners
- Acknowledgments
The JSight API language allows you to specify REST and JSON-RPC APIs with incredible speed and convenience. More information can be found in the Quick Tutorial or in the language specification. Here we give examples of the same API described using JSight API and Open API.
Example 1. The simplest
JSight API 0.3 | OpenAPI 3.0.1 (Swagger) |
---|---|
Pay attention to the main feature of the JSight API language. The basis for a data schema is an example of valid data. Additional data requirements are specified in C-like comments. This approach greatly simplifies the data schema and makes it intuitively clear. Practice shows that such schema is very simple to create, read and edit. Learn more about the JSight language: Quick Tutorial. ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 2: User Types
JSight API 0.3 | OpenAPI 3.0.1 (Swagger) |
---|---|
Pay attention to how convenient it is to work with user types in JSight API. The type name is simply inserted where the type should be in the data schema. Everything is the same as in conventional programming languages. More about user types: Quick Tutorial. Lesson 2. User types. ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 3: Schema
JSight API 0.3 | OpenAPI 3.0.1 (Swagger) |
---|---|
Details that are not obvious from the example of valid data are provided in small JSON objects in C-like comments. This approach allows you to write data schemas of any complexity, while keeping them compact and intuitive. More about JSight Schema: Quick Tutorial. Lesson 4. Schemas. ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 4. POST
JSight API 0.3 | OpenAPI 3.0.1 (Swagger) |
---|---|
Please note that the POST request and the three response options are written in a clear and concise manner. More about requests and responses: Quick Tutorial. Lesson 6. Requests and Responses. ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 5: Inheritance
JSight API 0.3 | OpenAPI 3.0.1 (Swagger) |
---|---|
This example shows how simple it is to inherit one type from another in JSight using the rule
Learn more: JSight Schema Specification. Rule "allOf". ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 6. Full-fledged CRUD API
JSight API 0.3 | OpenAPI 3.0.1 (Swagger) |
---|---|
A full-fledged CRUD API took only 25 lines. ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 7. Macros
JSight API 0.3 | OpenAPI 3.0.1 (Swagger) |
---|---|
Macros are a powerful feature of the JSight API language. It allows you to reuse parts of code as many times as you like. More about macros: Quick Tutorial. Magic directive MACRO. ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 8: Large REST API
JSight API 0.3 | OpenAPI 3.0.1 (Swagger) |
---|---|
|
We did not describe this API in OpenAPI. It is too complicated and very long… ⭐ Star us on GitHub — it motivates us a lot! |
Example 9. JSON-RPC 2.0
JSight API 0.3 | OpenRPC 1.2.1 |
---|---|
The JSON-RPC API is as simple to describe as the REST API. More about JSON-RPC 2.0 support: Quick Tutorial. JSON-RPC 2.0 support. ⭐ Star us on GitHub — it motivates us a lot! |
|
The JSight Schema language allows you to describe any data structures with incredible speed and convenience. You can read more about it in the JSight Schema Language Specification.
The JSight Schema language is actively used by the JSight API language, which is designed to describe API. For more information about JSight Schema within the JSight API, see the Quick Tutorial.
Mentioned below are examples of the same data schemas described using JSight Schema and JSON Schema.
Example 1. The simplest
JSight Schema 0.3 | JSON Schema 2020-12 |
---|---|
Pay attention to the main feature of the JSight Schema language. The basis for a data schema is an example of valid data. Additional data requirements are specified in C-like comments. This approach greatly simplifies the data schema and makes it intuitively clear. Practice shows that such schema is very simple to create, read and edit. For details, see the JSight Schema Language Specification, in the section “EXAMPLE”. ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 2. Nested arrays and objects
JSight Schema 0.3 | JSON Schema 2020-12 |
---|---|
The JSight Schema language is especially useful when describing nested objects and arrays, which are very common in real life. You simply give an example of a valid array or object, and add small clarifying comments. It is much more complicated in JSON Schema and other languages. For details, see the JSight Schema Language Specification, sections: ⭐ Star us on GitHub — it motivates us a lot! |
This example was created based on the official Getting Started instructions of the JSON-Schema standard. |
Example 3. Property description
JSight Schema 0.3 | JSON Schema 2020-12 |
---|---|
Here is the same schema as in the previous example, only property descriptions have been added. Property descriptions are written in C-like comments. If there are rules in the comments, then the property descriptions are separated by a hyphen. For details, see the JSight Schema Language Specification, section “Text notes to RULES”. ⭐ Star us on GitHub — it motivates us a lot! |
|
Example 4. Built-in data types
JSight Schema 0.3 | JSON Schema 2020-12 |
---|---|
JSight Schema supports several additional built-in data types that are required for actual work. Read more about built-in data types in the JSight Schema Language Specification, section “RULE "type"”. ⭐ Star us on GitHub — it motivates us a lot! |
|
- Support for other types of API: gRPC, Kafka, RabbitMQ, WebSocket.
If you have ideas and suggestions, please write to us:
- Email: [email protected]
- Telegram: @jsight_support
JSight API language and JSight Schema language releases are versioned according to the Semantic Versioning 2.0.0 standard:
{MAJOR version}.{MINOR version}.{PATCH version}
The releases are located in the branch main
in the ./versions/JSight Schema/
and ./versions/JSight API/
,
respectively. Each new specification release is published into a separate file with a version
number, for example ./versions/JSight Schema/0.3.0.md
or ./versions/JSight API/0.3.0.md
.
The JSight Schema language specification does not depend on anything.
The JSight API language specification depends on the version of the JSight Schema language. This dependency is listed in the JSight API language specification in the section “Dependences”.
Contributing is more than just developing a language specification. You can help the project in many ways, and we will be very happy to accept your contribution to our project.
Details of how you can help the project are described in the CONTRIBUTING.md document.
Do you have a bug report or a feature request?
Please feel free to add a new issue or write to us in support:
- Email: [email protected]
- Telegram: @jsight_support
If something is unclear to you, please contact support; we try to respond within 24 hours. Moreover, it is critical for us to understand what is unclear from the first instance.
- Email: [email protected]
- Telegram: @jsight_support
This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.
- JSight Official Website: https://jsight.io.
- JSight API Language Quick Tutorial: https://jsight.io/docs/jsight-api-0-3-quick-tutorial.
- JSight Schema language specification on the official website: https://jsight.io/docs/jsight-schema-0-3.
- JSight API language specification on the official website: https://jsight.io/docs/jsight-api-0-3.
- JSight Online Editor: https://editor.jsight.io.
- JSight Online Editor repo: https://github.com/jsightapi/online-editor-frontend.
- JSight Server repo: https://github.com/jsightapi/jsight-server.
- JSight blog: https://jsight.io/blog.
- Official Facebook page: https://www.facebook.com/jsightapi.
- Official Twitter: https://twitter.com/jsightapi.
- Official Linkedin: https://www.linkedin.com/company/jsightapi.
- All JSight repositories: https://github.com/jsightapi.
- GitHub discussions: https://github.com/jsightapi/specification/discussions.
- We have successfully completed class #29 of the Alchemist Accelerator.
We sincerely thank all those without whom this project would not have been possible:
⭐ Star us on GitHub — it motivates us a lot! ⭐