Grammar: when are prop names abbreviated?

[flekschas]

I noticed that sometimes props are heavily abbreviated and sometimes they are spelled out. For instance, xe seems to be an abbreviation for xEnd. In other cases the props are spelled out like strokeWidth (I assume there's no strokew).

From a user perspective, is there rule that's being followed when props are abbreviated vs when they are not?

Related to this, is it technically possible to define aliases? I really like abbreviations because they support pro-users in writing the specification more efficiently but for newcomers abbreviations can be confusing. For instance, xe only made sense to me because I saw it in the context of links and I thinking: they probably mean the endpoint. Allowing users to either write xe or xEnd could make both happy. Kind of like CLI offer short and long arguments (-i vs --install).

[sehilyi]

This is a good point. Most of the props in Gosling are spelled out except several ones, like xe and its friends (x1 and x1e for band connections). (It was originally taken from Vega-Lite's x1 and y1 props).

But, as you pointed out, I think spelling out these props are better than xe, x1, x1e which would make them easier to be remembered by users. So, perhaps x, xEnd, x2, xEnd2?

[flekschas]

I like x1 (or just x for simplicity) and x2. I would only propose x2End instead of xEnd2 because the 2 sort of acts as a modifier or identifier of x not of End. Or in other words. x doesn't have two different end points but there are two different x intervals and both have a start and end point :)

[sehilyi]

I really like the alias idea. As a user myself, I would want to use the abbreviated props.

Quick search on the TypeScript did not show a simple way of doing this, and I would need to investigate this more.

[flekschas]

I am curious, how do you currently parse the grammar? :) Did you implement your own parser or it utilizing an existing tool?

[sehilyi]

It is just a TypeScript.

The grammar of Gosling is defined in a single file called gosling.schema.ts. And a users' JSON spec is converted (i.e., JSON.parse({...})) into the root-level type called GoslingSpec if the spec is valid according to the definition of our grammar. "gosling.schema.json" which is auto-generated upon updating "gosling.schema.ts" is used to check the validity of the users' JSON spec.

There are several additional steps to fix users' specs programmatically, but the parsing part is pretty much like it.

[flekschas]

Cool thanks! :) If I understand correctly, you're using gosling.schema.ts to auto-generate a JSON schema? I had a quick look and found the following approach for defining property aliases:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
    
  "definitions": {
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum":180,
      "exclusiveMinimum": false,
      "exclusiveMaximum": false
    },
    "latitude": {
      "type": "number",
      "minimum": -180,
      "maximum":180,
      "exclusiveMinimum": false,
      "exclusiveMaximum": false
    }
  },
  
  "type": "object",
    
  "title": "coordinates",

  "properties": {
    "lon": { "$ref": "#/definitions/longitude" },
    "longitude": { "$ref": "#/definitions/longitude" },
    "lat": { "$ref": "#/definitions/latitude" },
    "latitude": { "$ref": "#/definitions/latitude" }
  },
    
  "allOf": [
    {
      "oneOf": [
        { "required": ["lon"] },
        { "required": ["longitude"] }
      ]
    },
    {
      "oneOf": [
        { "required": ["lat"] },
        { "required": ["latitude"] }
      ]
    }
  ]
}

In this example I am defining that all requires of either lon/longitude and lat/latitude are defined. However, whether the user choses lon over longitude is up to them. So technically it should work. Here's a live demo: https://www.jsonschemavalidator.net/s/gRA0K0s8

So at least technically JSON schema itself supports property aliasing. But having said all that, I am not sure how easy it is to translate into such a format from TypeScript :) (since I am a TypeScript n00p)

Source: https://stackoverflow.com/questions/21970210/json-schema-property-aliasing