Schema 2.0.0 for O3DE objects

[byrcolin]

Summary:

I believe we need to upgrade the object json to better and more clearly define our objects.

What is the motivation for this suggestion?

We need to enforce uniformity on the object json system across types. Currently the fields meanings are not uniform between object types, they are not clear as to what the fields mean/used for and do not provide for needed information.

Schema 1.0.0 improved on 0.0.0 this with its version sections quite a bit but lacked a few needed improvements such as lists for licensing, repo formats, etc. It also conflated repo.json which is a object type json with the advertisements json used by the "Program manager". This was not Schema 1.0.0 fault but 0.0.0's fault as it used the same name "repo.json" to describe an object type as well as a Program manager advertisement. Schema 1.0.0 also introduced a mechanism of coping the contents of the objects into the parent object such as "gems_data" and "templates_data" which breaks OOD in that objects should only describe themselves. This goes against the very spirit of the object system and should be removed/deprecated in 2.0.0.

All references to URL should be changed to the more correct URI (https://danielmiessler.com/p/difference-between-uri-url/)

Suggestion design description:

• Remove all references to schema 1.0.0 by upgrading all object json to strictly use schema 2.0.0

What are the advantages of the suggestion?

• This promotes modularity and code mobility. It will also formally standardizes the object json format across all type and its fields meanings and disambiguates repo.json from O3DE.exe advertisements.

What are the disadvantages of the suggestion?

• A lot of work to upgrade all objects to schema 2.0.0

Are there any alternatives to this suggestion?

• Honestly I don't think we can continue to use schema 1.0.0's "_data" sections. Its a time bomb waiting to go off.

Example changes in schema 2.0.0

0.0.0 is assumed if there is no "$schemaVersion"
"$schemaVersion": "1.0.0", => "$schemaVersion": "2.0.0",
"gems_data": [ => removed
"templates_data": [ => removed
"projects_data": [ => removed
etc.
"origin" is just the display text of person or organization responsible for this object
"origin_url" =>"origin_uri" is the link to the person or organization responsible for this object, not the object itself
"license" and "license_url" => moved to
"licenses" : [
{
"license": "O3DE",
"license_path": "LICENSE.txt"
},
{
"license": "CC-BY-4.0",
"license_path": "LICENSE-CC-BY-4.0.txt",
"license_uri": "https://spdx.org/licenses/CC-BY-4.0.html"
}
]
"source_control_uri": "https://github.com/o3de/o3de-multiplayersample-assets.git", #this is the repo where this objects lives
"source_control_path": "Gems/landscape_mps", #if this object is a child of a repo, this is the relative path from the repo root goes here
"source_control_branch": "development", #optional if the repo wants to declare a branch
"source_control_ref": "", #optional if the repo wants to declare a reference point like a tag
"documentation_path": "README.md", #optional if the repo itself has documentation, its relative path
"documentation_uri": "", #optional if the documentation lives on a web site
"icon_path": "preview.png", #optional if the repo itself has an icon for use by O3DE.exe "Program manger"
"icon_uri": "", #optional if the repo uses a web based icon. This is the icon which will appear in O3DE.exe "Program Manager" when the object is not yet downloaded i.e. remote.
"versions_data": [
{
"version": "Latest",
"source_control_branch": "development",
},
{
"version": "2.18.4",
"source_control_ref": "v2.18.4",
"download_source_uri": "https://github.com/PopcornFX/O3DEPopcornFXPlugin/archive/refs/tags/v2.18.4.zip"
},
{
"version": "2.18.3",
"source_control_ref": "v2.18.3",
"download_source_uri": "https://github.com/PopcornFX/O3DEPopcornFXPlugin/archive/refs/tags/v2.18.3.zip"
},
etc...

[AMZN-alexpete]

Schema 1.0.0 also introduced a mechanism of coping the contents of the objects into the parent object such as "gems_data" and "templates_data" which breaks OOD in that objects should only describe themselves. This goes against the very spirit of the object system and should be removed/deprecated in 2.0.0.

The _data sections introduced by 1.0.0 address a few practical needs from repo.json

1. provide a single endpoint to retrieve all the data for every object (and object versions) available in a repository
2. avoid the consumer (project manager) having to retrieve that data from hundreds/thousands of requests which is slow and...
3. provides a way for repo providers to only have to expose a single data file and not host hundreds or thousands of extra gem.json files or endpoints.

The other design goal of including as much of the necessary data in one file as possible is to allow for a simpler transition to a future scalable API design that supports endpoints backed by databases that support pagination and querying. This way, consumers can access all the repo data through a traditional service-like API, e.g. https://canonical.o3de.org/repo?page=3 and query/filter the data e.g. https://canonical.o3de.org/repo?q=animal%20gems&page=234

But for now, we just provide everything in one file which should scale OK into the hundreds, maybe low thousands or objects/versions. It's really the templates that take the most data and that could be addressed by making that format simpler.

[ShaunaGordon]

All references to URL should be changed to the more correct URI (https://danielmiessler.com/p/difference-between-uri-url/)

According to that link, and based on the example schema, URL is the more correct, because your examples all have protocols on them.