AMZN-alexpete
commented
9 months ago 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
- provide a single endpoint to retrieve all the data for every object (and object versions) available in a repository
- avoid the consumer (project manager) having to retrieve that data from hundreds/thousands of requests which is slow and...
- provides a way for repo providers to only have to expose a single data file and not host hundreds or thousands of extra
gem.jsonfiles 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.
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:
What are the advantages of the suggestion?
What are the disadvantages of the suggestion?
Are there any alternatives to this suggestion?
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...