Giters

jsightapi / jsight-schema-core

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

 

JSight

JSight Schema Go Library

Golang Telegram support PRs Welcome License JSight on Facebook JSight on LinkedIn Twitter Follow

Alchemist Accelerator

 

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

 
Try now!

📖   Table of Contents

 

🚀   Getting Started

Prerequisites

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: support@jsight.io
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:

⭐ 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"     : "tom@cats.com",              // {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": ["tom@cats.com"]
    },
    "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:

 

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

 

🧾   License

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

 

📖   Resources

Documents:

Applications that use the JSight Schema Go Library:

Publications:

Others:

 

🤝   Partners

 

🏆   Acknowledgments

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

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

About

License:Apache License 2.0

Languages

Language:Go 100.0%Language:Makefile 0.0%