Metadata

Metadata Spec

The best way to learn it, is to view it (https://soarpkgs.pkgforge.dev/metadata/METADATA.json) & and then read the sections below:

Fields

//The Structure is like:
 [
  {
   // ${Entries}
  }
 ]

The metadata doesn't have all the fields (Most are empty/placeholders) as these are autofilled after a build is successful.

// @string --> Single String Value
// @array --> Multiple (array) String Values
// @array|@string --> Can be either, check & handle accordingly

//Denotes if this pkg is disabled (currently broken, SHOULD NOT BE INSTALLED)
disabled: false, //if true, then this pkg is marked disabled

//Contains the Name of the $PKG itself, this is NOT what it will/should be Installed as
pkg: "@string",

//Contains the Main Family, the package is a part of
pkg_family: "@string",

//Contains the Application ID, generated from source URL [Otherwise Empty/Non-Existent]
//IF THIS IS MISSING, assume pkg_id==app_id
pkg_id: "@string",

//Contains the real name, the $PKG will be installed as, IF THIS IS MISSING, use .pkg
pkg_name: "@string",

//Contains the Application ID, usually from appstream files, [Otherwise Empty/Non-Existent]
//IF THIS IS MISSING, assume app_id==pkg_id
app_id: "@string"

//Contains the Description of the $PKG/$PKG_FAMILY [Otherwise Empty/Non-Existent]
description: "@string",

//Contains Additional Notes,Refs,Info the user need to be aware of, [Otherwise Empty/Non-Existent]
note: "@string|@array",

//Contains the version of the $PKG <AUTOGENERATED>
version: "@string",

//Contains the Raw Direct Download URL of the $PKG <AUTOGENERATED>
download_url: "@string",

//Contains the Total Size of the $PKG <AUTOGENERATED> in KiB MiB GiB BUT written as KB MB GB (Example: 9.01 MB)
size: "@string",

//Contains the Exact Blake3sum of the $PKG <AUTOGENERATED>
bsum: "@string",

//Contains the Exact Sha256sum of the $PKG <AUTOGENERATED>
shasum: "@string",

//Contains the Exact Date the $PKG was Built/Fetched & Uploaded
//Format in YYYY-MM-DDTHH:MM:SS (example: 2024-10-08T01:19:56)
build_date: "@string",

//Contains Repology Metadata from /api/v1/project/{$PKG/$PKG_FAMILY} [Otherwise Empty/Non-Existent]
repology: "@string|@array",

//Contains the Github/Gitlab/$GIT_SRC URL of the $PKG/$PKG_FAMILY [Otherwise Empty/Non-Existent]
src_url: "@string|@array",

//Contains the Website/Project Page URL of the $PKG/$PKG_FAMILY [Otherwise Empty/Non-Existent]
homepage: "@string|@array",

//Contains the Actual Script the $BINARY was Built(Fetched) With <AUTOGENERATED>
build_script: "@string",

//Contains the link to view the Actual CI BUILD LOG of the $BINARY <AUTOGENERATED>
build_log: "@string",

//Contains the URL to Appstream ({AppData/Metainfo}.xml) File of the $PKG/$PKG_FAMILY 
//This MAY BE INACCURATE [Otherwise Empty/Non-Existent]
appstream: "@string",

//Contains the $PKG/$PKG_FAMILY's Category in FreeDesktopSpec [Fallbacks to Utility]
category: "@string|@array",

//Contains the URL to .Desktop File of the $PKG/$PKG_FAMILY
//This MAY BE INACCURATE, [Otherwise Empty/Non-Existent]
desktop: "@string",

//Contains the Logo/Icon File of the $PKG/$PKG_FAMILY (MAY BE INACCURATE) [Fallbacks to Generic Icon]
icon: "@string",

//Contains the License for the $PKG/$PKG_FAMILY (MAY BE INACCURATE) [Otherwise Empty/Non-Existent]
license: "@string|@array",

//Contains names of related binaries [COMMA SEPARATED]
//Only if they belong to same $PKG_FAMILY, of the $PKG/$PKG_FAMILY [Otherwise Empty/Non-Existent]
provides: "@string",

//Contains an Array of Screenshots of the $PKG/$PKG_FAMILY (MAY BE INACCURATE) [Otherwise Empty/Non-Existent]
screenshots: "@array",

//Contains an Array of Snapshots (Last 3 Version) of the $PKG/$PKG_FAMILY [Otherwise Empty/Non-Existent]
snapshots: "@array",

//Contains Tags describing/categorizing the $PKG/$PKG_FAMILY [Otherwise Empty/Non-Existent]
tag: "@array"

---

URLs

• Add (at end) .xz OR .zstd to get Compressed Versions

• Add (at end).bsum to get Checksums, useful to check if Remote has Changed

Metadata File is Stored on GitHub (99% Uptime)

• https://soarpkgs.pkgforge.dev/${PATH} is just a redirect to https://raw.githubusercontent.com/pkgforge/soarpkgs/refs/heads/main/${PATH}

https://soarpkgs.pkgforge.dev/metadata/METADATA.json
https://raw.githubusercontent.com/pkgforge/soarpkgs/refs/heads/main/metadata/METADATA.json

---

JQ

This is a basic example demonstrating how easy it is to work with the Metadata

#Append `| jq -r '.[].$PROPERTY'` to filter them
#Simple example to: list all Pkgs in .pkg
curl -qfsSL "https://soarpkgs.pkgforge.dev/metadata/METADATA.json" \
| jq -r '
  .[] 
  | .pkg
'

#Example to list in .pkg (.pkg_type) [.pkg_id]
curl -qfsSL "https://soarpkgs.pkgforge.dev/metadata/METADATA.json" \
| jq -r '
    .[] | 
    "\(.pkg) (\(.pkg_type)) [\(.pkg_id)]"
' \
| sort -u 

#To pretty print anything that matches vlc from .pkg
curl -qfsSL "https://soarpkgs.pkgforge.dev/metadata/METADATA.json" \
| jq -r '
  .[] 
  | select(.pkg | test("vlc"; "i")) 
  | "---------------------------\n" + (
      . 
      | to_entries 
      | map("\(.key): \(.value)") 
      | join("\n")
    )
'