search

minetest / contentdb

A content database for Minetest mods, games, and more
https://content.minetest.net
GNU Affero General Public License v3.0
92 stars 45 forks source link

Provide JSON Schema for `.cdb.json` validation in editors #393

Closed AFCMS closed 1 year ago

AFCMS commented 1 year ago

Problem

There is no official (and I didn't found any unofficial ones) JSON schema availlable for the .cdb.json file.

Its very useful as it allows to validate and autocomplete the file in VSCode and other compatible editors.

It would prevent problems like https://github.com/minetest/contentdb/issues/298

Solutions

Add an official schema and perhaps add it to https://www.schemastore.org

I started making one from the CDB documentation, but still require some work.

{
  "description": "CDB Config",
  "properties": {
    "type": {
      "description": "Package Type",
      "enum": ["MOD", "GAME", "TXP"],
      "enumDescriptions": ["Mod", "Game", "Texture Pack"]
    },
    "title": {
      "description": "Human-readable title",
      "type": "string"
    },
    "name": {
      "description": "Technical name (needs permission if already approved).",
      "type": "string"
    },
    "short_description": {
      "description": "Package Short Description",
      "type": ["string", "null"]
    },
    "dev_state": {
      "description": "Development State",
      "enum": [
        "WIP",
        "BETA",
        "ACTIVELY_DEVELOPED",
        "MAINTENANCE_ONLY",
        "AS_IS",
        "DEPRECATED",
        "LOOKING_FOR_MAINTAINER"
      ]
    },
    "tags": {
      "description": "Package Tags",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "content_warnings": {
      "description": "Package Content Warnings",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "license": {
      "description": "Package License",
      "enum": ["GPL-3.0-or-later"],
      "enumDescriptions": ["GPL v3"]
    },
    "media_license": {
      "description": "Package Media License",
      "enum": ["CC-BY-4.0"],
      "enumDescriptions": ["CC-BY-4.0"]
    },
    "long_description": {
      "description": "Package Long Description",
      "type": ["string", "null"]
    },
    "website": {
      "description": "Website URL",
      "type": ["string", "null"]
    },
    "issue_tracker": {
      "description": "Issue Tracker URL",
      "type": ["string", "null"]
    },
    "forums": {
      "description": "Forum Topic ID",
      "type": ["string", "null"]
    },
    "video_url": {
      "description": "URL to a Video",
      "type": ["string", "null"]
    }
  },
  "title": "setting",
  "type": "object"
}

IDK how to fill the license* fields, maybe its possible to make a dynamic schema which loads the api endpoint?

Alternatives

None

Additional context

None

rubenwardy commented 1 year ago

IDK how to fill the license* fields, maybe its possible to make a dynamic schema which loads the api endpoint?

I think it's fine to hard code the list of licenses / tags for now

rubenwardy commented 1 year ago

Another related thing would be Swagger/OpenAPI documentation

AFCMS commented 1 year ago

Will make a PR.

Are all the fields except the license/tags ones allowing null as value?

AFCMS commented 1 year ago

Where should I put the file when I will make the PR?

In the doc folder?

AFCMS commented 1 year ago

I made a python script to update the licenses/tags/content_warnings automatically using the API of content.minetest.net

It can be run on Github Actions to commit the file when needed.

AFCMS commented 1 year ago

I got the following:

{
  "title": "CDB Config",
  "description": "Package Configuration",
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "license": {
      "enum": [
        "AFL-1.1",
        "AFL-1.2",
        "AFL-2.0",
        "AFL-2.1",
        "AFL-3.0",
        "AGPL-2.0-only",
        "AGPL-3.0-only",
        "AGPL-3.0-or-later",
        "Apache-1.1",
        "Apache-2.0",
        "APSL-2.0",
        "Artistic-2.0",
        "BSD-2-Clause-FreeBSD",
        "BSD-3-Clause",
        "BSL-1.0",
        "CC0-1.0",
        "CC-BY-3.0",
        "CC-BY-4.0",
        "CC-BY-NC-SA-3.0",
        "CC-BY-SA-3.0",
        "CC-BY-SA-4.0",
        "CDDL-1.0",
        "CPAL-1.0",
        "CPL-1.0",
        "ECL-2.0",
        "EFL-2.0",
        "EPL-1.0",
        "EPL-2.0",
        "EUDatagrid",
        "EUPL-1.1",
        "EUPL-1.2",
        "GPL-2.0-only",
        "GPL-2.0-or-later",
        "GPL-3.0-only",
        "GPL-3.0-or-later",
        "HPND",
        "Intel",
        "IPA",
        "IPL-1.0",
        "ISC",
        "LGPL-2.1-only",
        "LGPL-2.1-or-later",
        "LGPL-3.0-only",
        "LGPL-3.0-or-later",
        "LPL-1.02",
        "MIT",
        "MPL-1.1",
        "MPL-2.0",
        "MS-PL",
        "MS-RL",
        "NCSA",
        "Nokia",
        "NPOSL-3.0",
        "OFL-1.1",
        "OSL-1.0",
        "OSL-2.0",
        "OSL-2.1",
        "OSL-3.0",
        "Other (Free/Open)",
        "Other (Non-free/Closed)",
        "PHP-3.01",
        "Python-2.0",
        "QPL-1.0",
        "RPSL-1.0",
        "SISSL",
        "Sleepycat",
        "SPL-1.0",
        "Unlicense",
        "UPL-1.0",
        "W3C",
        "WTFPL",
        "Zlib",
        "ZPL-2.0",
        "ZPL-2.1"
      ],
      "enumDescriptions": [
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "NON-FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "NON-FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS",
        "FOSS"
      ]
    }
  },
  "properties": {
    "type": {
      "description": "Package Type",
      "enum": ["MOD", "GAME", "TXP"],
      "enumDescriptions": ["Mod", "Game", "Texture Pack"]
    },
    "title": {
      "description": "Human-readable title",
      "type": "string"
    },
    "name": {
      "description": "Technical name (needs permission if already approved).",
      "type": "string",
      "pattern": "^[a-z_]+$"
    },
    "short_description": {
      "description": "Package Short Description",
      "type": ["string", "null"]
    },
    "dev_state": {
      "description": "Development State",
      "enum": [
        "WIP",
        "BETA",
        "ACTIVELY_DEVELOPED",
        "MAINTENANCE_ONLY",
        "AS_IS",
        "DEPRECATED",
        "LOOKING_FOR_MAINTAINER"
      ]
    },
    "tags": {
      "description": "Package Tags",
      "type": "array",
      "items": {
        "enum": [
          "chat",
          "magic",
          "world_tools",
          "mtg",
          "featured",
          "april_fools",
          "library",
          "mini-game",
          "environment",
          "jam_game_2021",
          "building",
          "gui",
          "seasonal",
          "jam_weekly_2021",
          "jam_combat_mod",
          "simulation",
          "128px",
          "mapgen",
          "sound_music",
          "16px",
          "education",
          "pve",
          "complex_installation",
          "jam_weekly_2022",
          "commerce",
          "mobs",
          "server_tools",
          "inventory",
          "oneofakind__original",
          "food",
          "less_than_px",
          "storage",
          "player_effects",
          "shooter",
          "hud",
          "strategy_rts",
          "crafting",
          "technology",
          "adventure__rpg",
          "singleplayer",
          "puzzle",
          "creative",
          "decorative",
          "sports",
          "plants_and_farming",
          "multiplayer",
          "32px",
          "64px",
          "developer_tools",
          "pvp",
          "transport",
          "tools",
          "survival"
        ],
        "enumDescriptions": [
          "Chat / Commands: Focus on player chat/communication or who's primary function is interacting with the console.",
          "Magic / Enchanting",
          "World Maintenance and Tools: Tools to manage the world",
          "Minetest Game improved: Forks of MTG",
          "Featured: Package has been chosen to be Featured on ContentDB by editors. Normal users cannot add this tag to their packages",
          "Joke / April Fools: For humorous content, meant as a novelty or joke, not to be taken seriously, and that is not meant to be used seriously or long-term. April Fools jokes.",
          "API / Library: Primarily adds an API for other mods to use",
          "Mini-game: Adds a mini-game to be played within Minetest",
          "Environment / Weather / Ambience: Improves the world, adding weather, ambient sounds, or other environment mechanics",
          "Jam / Game 2021: Entries to the 2021 Minetest Game Jam",
          "Building: Focuses on building, such as adding new materials or nodes",
          "GUI: For content whose main utility / feature is in GUI/formspec form",
          "Seasonal: For content generally themed around a certain season or holiday",
          "Jam / Weekly Challenges 2021: For mods created for the Discord \"Weekly Challenges\" modding event in 2021",
          "Jam / Combat 2020: For mods created for the Discord \"Combat\" modding event in 2020",
          "Sims: Mods and games that aim to simulate real life activity. Similar to SimCity/TheSims/OpenTTD/etc",
          "128px+: For 128px or higher texture packs",
          "Mapgen / Biomes / Decoration: New mapgen or changes mapgen",
          "Sounds / Music: Focuses on or adds new sounds or musical things",
          "16px: For 16px texture packs",
          "Education: Either has educational value, or is a tool to help teachers ",
          "Player vs Environment (PvE): For content designed for one or more players that focus on combat against the world, mobs, or NPCs.",
          "Complex installation: Requires futher installation steps, such as installing luarocks or editing the trusted mod setting",
          "Jam / Weekly Challenges 2022: For mods created for the Discord \"Weekly Challenges\" modding event in 2022",
          "Commerce / Economy: Related to economies, money, and trading",
          "Mobs / Animals / NPCs: Adds mobs, animals, and NPCs",
          "Server Moderation and Tools: Helps with server maintenance and moderation",
          "Inventory: Changes the inventory GUI",
          "One-of-a-kind / Original: For games and such that are of their own kind, distinct and original in nature to others of the same category.",
          "Food / Drinks",
          "<16px: Less than 16px",
          "Storage: Adds or improves item storage mechanics",
          "Player Effects / Power Ups: For content that changes player effects, including physics, for example: speed, jump height or gravity.",
          "Shooter: First person shooters (FPS) and more",
          "HUD: For mods that grant the player extra information in the HUD",
          "Strategy / RTS: Games and mods with a heavy strategy component, whether real-time or turn-based",
          "Crafting: Big changes to crafting gameplay",
          "Machines / Electronics: Adds machines useful in automation, tubes, or power.",
          "Adventure / RPG",
          "Singleplayer-focused: Content that can be played alone",
          "Puzzle: Focus on puzzle solving instead of combat",
          "Creative: For content written specifically (and often exclusively) for use in creative mode. These mods may add a large amount of decorative content, or content without crafting recipes",
          "Decorative: Adds nodes with no other purpose than for use in building",
          "Sports",
          "Plants and Farming: Adds new plants or other farmable resources.",
          "Multiplayer-focused: Can/should only be used in multiplayer",
          "32px: For 32px texture packs",
          "64px: For 64px texture packs",
          "Developer Tools: Tools for game and mod developers",
          "Player vs Player (PvP): Designed to be played competitively against other players",
          "Transport: Adds or changes transportation methods. Includes teleportation, vehicles, and ridable mobs",
          "Tools / Weapons / Armor: Adds or changes tools, weapons, and armor",
          "Survival: Written specifically for survival gameplay. For example, they might focus on game-balance or increase the difficulty level"
        ]
      },
      "uniqueItems": true
    },
    "content_warnings": {
      "description": "Package Content Warnings",
      "type": "array",
      "items": {
        "enum": [
          "gore",
          "gambling",
          "drugs",
          "violence",
          "horror",
          "bad_language",
          "alcohol_tobacco"
        ],
        "enumDescriptions": [
          "Gore: Blood, etc",
          "Gambling: Games of chance, gambling games, etc",
          "Drugs: Contains illegal drugs, such as marijuana",
          "Violence: Non-cartoon violence. May be towards fantasy or  human-like characters",
          "Fear / Horror: Shocking and scary content. May scare young children",
          "Bad Language: Contains swearing",
          "Alcohol / Tobacco: Contains alcohol and/or tobacco"
        ]
      },
      "uniqueItems": true
    },
    "license": {
      "description": "Package License",
      "$ref": "#/$defs/license"
    },
    "media_license": {
      "description": "Package Media License",
      "$ref": "#/$defs/license"
    },
    "long_description": {
      "description": "Package Long Description",
      "type": ["string", "null"]
    },
    "repo": {
      "description": "Git Repository URL",
      "type": "string",
      "format": "uri"
    },
    "website": {
      "description": "Website URL",
      "type": ["string", "null"],
      "format": "uri"
    },
    "issue_tracker": {
      "description": "Issue Tracker URL",
      "type": ["string", "null"],
      "format": "uri"
    },
    "forums": {
      "description": "Forum Topic ID",
      "type": ["integer", "null"],
      "minimum": 0
    },
    "video_url": {
      "description": "URL to a Video",
      "type": ["string", "null"],
      "format": "uri"
    }
  },
  "additionalProperties": false
}
AFCMS commented 1 year ago

Opened #425