feat(schemas): enhance schemas

Author: Leawind

lib/schemas/ParcelMeta.ts

@@ -1,49 +1,97 @@
 import { $schema } from './utils.ts'
 
 type ParcelFormat = {
-	/**
-	 * Parcel format ID
-	 */
+  /**
+   * Parcel format ID
+   */
   id: string
-	/**
-	 * Parcel format version
-	 */
+  /**
+   * Parcel format version
+   */
   version: number
 }
 
-type ModDependency = {
-  id: string
-  /** Minimum version (SemVer) */
-  min?: string
-  /** Maximum version (SemVer) */
-  max?: string
-}
+type ModDependency =
+  | '*'
+  | {
+    /**
+     * Minimum version (SemVer)
+     */
+    min?: string
+    /**
+     * Maximum version (SemVer)
+     */
+    max?: string
+  }
 
+/**
+ * The meta file of a Parcel
+ *
+ * This file should be in the root directory of a parcel
+ */
 export type ParcelMeta = $schema & {
-  /** The format of parcel */
+  /**
+   * The format of parcel
+   */
   format: ParcelFormat
-  /** Minecraft data version */
+  /**
+   * Minecraft data version
+   *
+   * Refer to [Minecraft WIKI - Data version: List of data versions](https://minecraft.wiki/w/Data_version#List_of_data_versions)
+   */
   dataVersion: number
-  /** Size of parcel in X,Y,Z */
+  /**
+   * Size of parcel in `X`, `Y`, `Z`.
+   *
+   * Must be positive integers.
+   */
   size: [number, number, number]
+  /**
+   * Display name of the parcel
+   *
+   * It doesn't need to be unique. It's used for display purposes only.
+   */
   name?: string
+  /**
+   * Description of the parcel
+   */
   description?: string
-  /** Tags for searching */
+  /**
+   * Tags for categorizing
+   */
   tags?: string[]
   /**
    * List of mods that are allowed to be used in the parcel
+   *
+   * - Key is the mod ID, usually in lowercase with underscore separator.
+   * - Value is the mod dependency, `"*"` means any version
+   *
+   * ### Example
+   *
+   * ```json
+   * {
+   *   "mod_1": "*"
+   *   "mod_2": { "min": "1.0.0", "max": "2.0.0" },
+   *   "mod_3": { "min": "1.0.0" },
+   *   "mod_4": { "max": "1.0.0" }
+   * }
+   * ```
    */
-  mods?: ModDependency[]
+  mods?: Record<string, ModDependency>
   /**
    * Whether to include blocks
    *
-   * @default true
+   * Default is `true`
+   *
+   * If `false`, the parcel will not save or load blocks, and existing block data will be cleared when saving.
    */
   includeBlock?: boolean
   /**
    * Whether to include entities
    *
-   * @default false
+   * Default is `true`
+   *
+   * If `false`, the parcel will not save or load entities, and existing entity data will be cleared when saving.
    */
   includeEntity?: boolean
 }

lib/schemas/RepoMeta.ts

@@ -3,9 +3,12 @@ import { $schema } from './utils.ts'
 type ParcelPath = string
 
 /**
- * RepoMeta is the schema for the meta file of a Git Parcel repository.
+ * The meta file of a Git Parcel repository.
  *
- * It lists all parcels in the repository.
+ * This file:
+ * 
+ * - should be in the root directory of the repository.
+ * - lists all the parcels in this repository.
  */
 export type RepoMeta = $schema & {
   /**

test/schema/ParcelMeta.test.json

@@ -1,9 +1,16 @@
 {
-  "$schema": "../../dist/schema/ParcelMeta.json",
+  "$schema": "../../dist/schemas/ParcelMeta.json",
   "format": {
     "id": "parcel",
     "version": 1
   },
   "dataVersion": 1536,
-  "size": [4, 4, 4]
+  "size": [4, 4, 4],
+  "mods": {
+    "mod_1": "*",
+    "mod_2": { "min": "1.0.0", "max": "2.0.0" },
+    "mod_3": { "min": "1.0.0" },
+    "mod_4": { "max": "1.0.0" }
+  },
+  "includeBlock": true
 }