JSight Schema Go Library

 

⭐ Star us on GitHub — it motivates us a lot! ⭐

 

JSight Schema Go Library is a library that parses schemas written in JSight Schema language.

JSight Schema language — you have never described your data so fast. We mean it. Compare JSight Schema with JSON Schema..

JSight Schema language specification on the official website: https://jsight.io/docs/jsight-schema-0-3.
JSight Schema language specification on GitHub: https://github.com/jsightapi/specification/tree/main/versions/JSight%20Schema.

The JSight Schema Go Library is currently used as part of the JSight Server and JSight Online Editor applications.

 

📖   Table of Contents

• Getting Started
• JSight Schema language
• Versioning
• Dependencies
• Tests
• Contributing
• Bugs and Feature Requests
• Support
• License
• Resources
• Partners
• Acknowledgments

 

🚀   Getting Started

Prerequisites

• Go >= 1.18 — install.

Installing

Download the JSight Schema Go Library source code:	git clone https://github.com/jsightapi/jsight-schema-core
Go to the repository folder:	cd ./jsight-schema-core/
Install development dependencies: (Ensure $GOPATH/bin is in the $PATH)	make deps
Download all dependencies:	go mod download
Run automated tests. If the tests are successful, then everything is fine, and the library is working.	go test -cover ./...

 

⚠️ SUPPORT: If you have any problems while launching the JSight Schema Go Library, do not hesitate to contact our support, we respond quickly:
Email: [email protected]
Telegram: https://t.me/jsight_support

 

📜   JSight Schema language

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

{ "id" : 123, // {min: 1} "name": "Tom" } 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!

{ "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "examples": [{ "id": 123, "name": "Tom" }] }

Example 2. Nested arrays and objects

JSight Schema 0.3

JSON Schema 2020-12

{ "productId": 1, "productName": "An ice sculpture", "price": 12.50, // {min: 0, exclusiveMinimum: true} "tags": [ // {minItems: 1, optional: true} "cold", "ice" ], "dimensions": { // {optional: true} "length": 7.0, "width": 12.0, "height": 9.5 } } 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: EXAMPLE requirements for object PROPERTIES, EXAMPLE requirements for array ELEMENTS. ⭐ Star us on GitHub — it motivates us a lot!

{ "type": "object", "properties": { "productId": { "type": "integer" }, "productName": { "type": "string" }, "price": { "type": "number", "exclusiveMinimum": 0 }, "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] } }, "required": ["productId","productName","price"], "examples": [{ "productId": 1, "productName": "An ice sculpture", "price": 12.50, "tags": [ "cold", "ice" ], "dimensions": { "length": 7.0, "width": 12.0, "height": 9.5 } }] } 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

{ // A product from Acme's catalog. "productId": 1, // The unique id. "productName": "An ice sculpture", // Name of the product. "price": 12.50, /* { min: 0, exclusiveMinimum: true } - The price. */ "tags": [ /* {minItems: 1, optional: true} - Tags for the product. */ "cold", "ice" ], "dimensions": { // {optional: true} - The dimensions. "length": 7.0, "width": 12.0, "height": 9.5 } } 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!

{ "type": "object", "description": "A product from Acme's catalog.", "properties": { "productId": { "description": "The unique id.", "type": "integer" }, "productName": { "description": "Name of the product.", "type": "string" }, "price": { "description": "The price.", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product.", "type": "array", "items": { "type": "string" }, "minItems": 1 }, "dimensions": { "description": "The dimensions.", "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": ["length", "width", "height"] } }, "required": ["productId","productName","price"], "examples": [{ "productId": 1, "productName": "An ice sculpture", "price": 12.50, "tags": [ "cold", "ice" ], "dimensions": { "length": 7.0, "width": 12.0, "height": 9.5 } }] }

Example 4. Built-in data types

JSight Schema 0.3

JSON Schema 2020-12

{ "id" : 123, "name" : "Tom", "email" : "[email protected]", // {type: "email" } "website" : "http://tom.cats.com", // {type: "uri" } "birthday" : "2006-01-02", // {type: "date" } "registered": "2021-01-02T07:23:12+03:00", // {type: "datetime"} "uuid": "550e8400-e29b-41d4-a716-446655440000" // {type: "uuid"} } 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!

{ "type": "object", "properties": { "id": { "type": "integer", "examples": [123] }, "name": { "type": "string", "examples": ["Tom"] }, "email": { "type": "string", "format": "email", "examples": ["[email protected]"] }, "website": { "type": "string", "format": "uri", "examples": ["http://tom.cats.com"] }, "birthday": { "type": "string", "format": "date", "examples": ["2006-01-02"] }, "registered": { "type": "string", "format": "date-time", "examples": ["2021-01-02T07:23:12+03:00"] }, "uuid": { "type": "string", "format": "uuid", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] } }, "required": [ "id", "name", "email", "website", "birthday", "registered", "uuid" ] }

 

📑   Versioning

JSight Schema Go Library releases are versioned according to the Semantic Versioning 2.0.0 standard.

{MAJOR version}.{MINOR version}.{PATCH version}

Releases are located in the branch main, and are tagged with a version number, for example, v1.0.0.

The JSight Schema Go Library release history can be seen here: https://github.com/jsightapi/jsight-schema-core/releases.

 

📔   Dependencies

JSight Schema Go Library dependencies are described in the file go.mod.

 

🧪   Tests

To run automated tests, run the following command in the repository root folder:

go test -cover ./...

 

😎   Contributing

Contributing is more than just coding. 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.

 

Contributors

 

💬   Bugs and Feature Requests

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

 

❔   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

 

🧾   License

This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.

 

📖   Resources

• JSight Official Website: https://jsight.io.

Documents:

• JSight Schema language specification on the official website: https://jsight.io/docs/jsight-schema-0-3.
• JSight Schema language specification on GitHub: https://github.com/jsightapi/specification/tree/main/versions/JSight%20Schema.

Applications that use the JSight Schema Go Library:

• 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.

Publications:

• 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.

Others:

• All JSight repositories: https://github.com/jsightapi.
• GitHub discussions: https://github.com/jsightapi/jsight-schema-core/discussions.

 

🤝   Partners

• We have successfully completed class #29 of the Alchemist Accelerator.

 

🏆   Acknowledgments

We sincerely thank all those without whom this project would not have been possible:

• Alchemist Accelerator,
• Lucas Jones for his reggen library,
• Dave Collins for his go-spew library,
• Stretchr company for Testify and Objx libraries,
• Patrick Mézard for his go-difflib library.

⭐ Star us on GitHub — it motivates us a lot! ⭐