Technical issues with JSON API Dump v2

Bug Reports Studio Bugs
,
1

There are some issues and missing bits of information between v1 and v2 of the JSON API Dump which have prevented me from migrating to v2. These have existed for a couple years now, and I’ve refrained from reporting them because I wasn’t sure if they were considered internal or not.

Now that Roblox is documenting the command line options for creating both versions of the API Dump, I feel inclined to report this.

Wrong Object/Instance type in function args/results

In the arguments of functions, callbacks, and events, the Object/Instance type does not get downcasted to its refined type (if one was defined)

Example 1:

In version 1, Players.PlayerAdded is declared as:

{
    "Capabilities": [
        "Players"
    ],
    "MemberType": "Event",
    "Name": "PlayerAdded",
    "Parameters": [
        {
            "Name": "player",
            "Type": {
                "Category": "Class",
                "Name": "Player"
            }
        }
    ],
    "Security": "None",
    "ThreadSafety": "Unsafe"
}

In version 2, it is declared as:

{
    "name": "PlayerAdded",
    "isUserFacing": true,
    "memberType": "Event",
    "type": {
        "name": "function",
        "arguments": [
            {
                "type": "Instance",
                "isEnum": false,
                "identifier": "player"
            }
        ],
        "results": [
            {
                "type": "null",
                "isEnum": false
            }
        ]
    },
    "isPublic": true,
    "security": "None",
    "capabilities": [
        "Players"
    ]
}

The player arg has a type of Instance instead of Player in v2.

Example 2:

In version 1, AssetService:CreateEditableMesh is declared as:

{
    "Capabilities": [
        "DynamicGeneration"
    ],
    "MemberType": "Function",
    "Name": "CreateEditableMesh",
    "Parameters": [
        {
            "Name": "editableMeshOptions",
            "Type": {
                "Category": "Group",
                "Name": "Dictionary?"
            }
        }
    ],
    "ReturnType": {
        "Category": "Class",
        "Name": "EditableMesh"
    },
    "Security": "None",
    "ThreadSafety": "Unsafe"
}

In version 2, it is declared as:

{
    "name": "CreateEditableMesh",
    "isUserFacing": true,
    "memberType": "Function",
    "type": {
        "name": "function",
        "arguments": [
            {
                "type": "Dictionary?",
                "isEnum": false,
                "identifier": "editableMeshOptions"
            }
        ],
        "results": [
            {
                "type": "Object",
                "isEnum": false
            }
        ]
    },
    "isYieldable": false,
    "isCustom": false,
    "security": "None",
    "threadSafety": "Unsafe",
    "simulationAccess": false,
    "capabilities": [
        "DynamicGeneration"
    ]
}

The returned type is Object instead of EditableMesh in v2.

Inconsistency of type format in v2

In v2, it’s implied that all type objects will have an inner string field named type to describe the name of their type:

"type": {
	"type": "Vector3",
	"isEnum": false,
	"defaultValue": "1, 0, 0"
},

Each API member has a type object, and thus you may expect member.type.type to be the name of whatever type the member is.
But when a function type is declared (e.g. methods, events, callbacks), it uses name instead of type:

{
    (...)

    "type": {
        "name": "function",
        "arguments": [],
        "results": [
            {
                "type": "Instances",
                "isEnum": false
            }
        ]
    }

    (...)
}

This makes type declarations awkward, because suddenly you have to account for either type or name being null depending on whether it’s a function or any other type. This particular annoyance has made it uncomfortable to adopt v2 because of how rough the typing gets in Luau.

type IType<Type, Name> = {
    type: Type,
    name: Name,
}

type BaseType = IType<string, nil> & BaseType<nil, "function">
-- ...etc
2 Likes