3 posts tagged with "JSightVsOpenAPI"

There is no more difficult choice than choosing between two equally good options.

We had to make hundreds of such decisions when developing the JSight language. Making a decision entails more than just choosing between two alternatives. It's not so much about the decision, as about the criteria for making decisions. Firstly, you need to understand why the existing decision criteria do not help you choose the right option. Then, you need to modify these criteria. After that, making the decision itself is no longer difficult.

Today we are going to share about one of such cases.

In most data structures, certain fields are mandatory while others are optional. This needs to be somehow marked in the data schema. In our case, there were two possible solutions: add either a rule required or a rule optional to the language:

{
  "id": 123     // {required: true}
  "name": "Tom" // {required: false}
}

Or this way:

{
  "id": 123     // {optional: false}
  "name": "Tom" // {optional: true}
}

The second question following the first is what should be the default value: required: true or required: false? And accordingly in the case of optional, optional: true or optional: false? When I see a property in an example of valid data, it intuitively seems to me that this property “should be”, unless otherwise stated. This means that by default, required: true or optional: false is correct. Then we have the following options:

{
  "id": 123
  "name": "Tom" // {required: false}
}

Or this way:

{
  "id": 123
  "name": "Tom" // {optional: true}
}

Which option do you prefer? Please write in the comments to this post, we are interested!

After comparing both options, we decided to rely on this criteria: which at first glance is perceived as faster and more in line with intuition?

The brain is used to interpret information in the simplest way. When we see the word required..., our initial assumption is that this property is required, since that is what the word required means. Then, reading the rule till the end required: false, we experience cognitive dissonance. We initially assumed that the field is required, but it turns out that required: false.

There is no cognitive dissonance in the case of optional: true. We see the word optional... and we automatically assume that this property is optional. Then we read the rule till the end optional: true and find confirmation of our initial thought.

So, considering how quickly the schema is intuitively perceived, optional fits better than required. However, another strong criteria works in favor of required: this word is more familiar to us, it is used, for example, in JSON-Schema, OpenAPI, RAML.

What is more important: convenience or habit? After long debates, we concluded that since we were creating a completely new language, convenience is more important, therefore we went with optional. Time will tell whether we were right or not.

Programmers are already lazy enough. Typing extra text is not their thing. Less code with more benefits!

Programmers are aesthetes. The code must be lovely. Beautiful code is inexplicable and must be experienced.

We are programmers. And have done everything we could to make the JSight language concise and beautiful. And finally, it looks like we’ve got it!

For example, see what a simple API on JSight looks like:

JSIGHT 0.3

GET /cats/{id}
  200
    {
      "id"   : 123,   // {min: 0}
      "name" : "Tom"
    }

Any programmer, without requiring any explanation, will immediately and unmistakably understand what this API is about. Nothing superfluous! Every word, every letter has an important and precise sense.

Compare the same API on OpenAPI (Swagger):

openapi: 3.0.3
info:
  title: ""
  version: ""
paths:
  /cats/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true
        schema: {}
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                type: object
                required: [id, name]
                properties:
                  id:
                    type: integer
                    minimum: 0
                    example: 123
                  name:
                    type: string
                    example: "Tom"

Doesn't this code seem redundant, to put it mildly?

We’re not criticizing OpenAPI. We’ve previously used it a lot and truly love it. But the world is moving forward and outdated technologies have to give way to new ones. It's time to move on to JSight, which is both concise and beautiful.

You can try out the JSight language right now: editor.jsight.io!

Learn more about JSight in a quick tutorial and in the official specification.

We’re starting a series of posts about the key features of the JSight language, which set it apart from all other API description languages and make describing API easier and faster.

Today, we’ll discuss the main feature, which we refer to as “Example as a schema”.

Any API description language describes data schemas in one way or another. For example, WSDL uses XSD to describe data, Blueprint API uses JSON Schema, and OpenAPI uses Schema Object.

The JSight API language uses the JSight Schema language to describe data. The JSight Schema approach, on the other hand, is fundamentally different from any other method of describing schemas. Now we'll tell you about this difference.

In 2020, Swagger interviewed over 3,000 IT specialists, asking them to name the top 5 most important things they seek in API documentation. What do you think the most popular ones were among the respondents? 70% of the respondents answered that they need EXAMPLES.

Unlike all other languages, the JSight Schema language primarily focuses on sample data. And this is completely justified. Programmers love examples! After all, most of the time, just looking at the example is enough to figure out what the data structure is.

In the JSight Schema language, the data example is already a data schema. For example, here is the simplest schema for you:

{
    "id": 123,
    "name": "Tom"
}

It is obvious from this schema that the data must be an object with an “id” property of type integer and a “name” property of type string. And if you need to add additional requirements to the schema that are not obvious from the sample data, then these requirements can be placed in a small JSON in the comments to the property:

{
    "id": 123, // {min: 1}
    "name": "Tom"
}

In the given diagram, it is added that the value of the “id" property must be greater than or equal to one.

For comparison, a similar schema in the OpenAPI language will look like this:

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

Do you notice any differences?

On JSight, the schema is simpler, shorter and more appealing to the eye.

You can learn more about JSight Schema in our tutorial and in language specification.