{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://metaone01.github.io/agent-forge/package.schema.json",
  "title": "Agent Forge Package Metadata v2",
  "description": "A metadata-only record for one package version. It does not contain or verify executable artifacts.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schemaVersion", "id", "name", "version", "type", "description", "license", "targets"],
  "properties": {
    "schemaVersion": { "const": 2, "description": "Breaking-version identifier for this JSON contract." },
    "id": { "$ref": "#/$defs/identifier", "description": "Stable logical package identifier across versions and Agent projections." },
    "name": { "$ref": "#/$defs/packageName", "description": "Human-facing package name or source-local slug." },
    "displayName": { "type": "string", "minLength": 1, "maxLength": 300 },
    "version": { "type": "string", "minLength": 1, "description": "Original upstream version string; Agent Forge never rewrites it." },
    "versionScheme": { "type": "string", "enum": ["semver", "npm", "pep440", "calver", "date", "custom", "unknown"], "description": "Optional comparison convention for version and ranges." },
    "description": { "type": "string", "minLength": 1, "maxLength": 4000 },
    "releaseNotes": { "type": "string", "maxLength": 10000 },
    "license": { "$ref": "#/$defs/stringOrArray", "description": "Publisher-supplied license identifier or text; it is recorded, not legally verified." },
    "media": {"$ref":"#/$defs/media","description":"Optional declared image references for display only. Assets are neither fetched nor verified by the catalog."},
    "links": { "$ref": "#/$defs/links", "description": "URLs for project pages and documents. README and LICENSE are links only." },
    "keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "uniqueItems": true, "maxItems": 100 },
    "maintainers": { "type": "array", "items": { "$ref": "#/$defs/maintainer" }, "uniqueItems": true, "maxItems": 100 },
    "platform": { "$ref": "#/$defs/platform", "description": "Optional runtime platform hints, not an installation guarantee." },
    "type": { "type": "string", "enum": ["mcp", "plugin", "skill", "general", "bundle"], "description": "One Agent Forge publication type." },
    "subtype": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "One administrator-defined subtype, or null when no subtype is assigned." },
    "mcpDetails": { "$ref": "#/$defs/mcpDetails" },
    "pluginDetails": { "$ref": "#/$defs/pluginDetails" },
    "skillDetails": { "$ref": "#/$defs/skillDetails" },
    "generalDetails": { "$ref": "#/$defs/generalDetails" },
    "bundleDetails": { "$ref": "#/$defs/bundleDetails" },
    "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/agentTarget" }, "uniqueItems": true, "description": "Agent-specific compatibility and target metadata." },
    "distributions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/distribution" }, "uniqueItems": true, "description": "Candidate locations for obtaining this package version; Agent Forge does not proxy or verify them." },
    "dependencies": { "type": "array", "items": { "$ref": "#/$defs/dependency" }, "uniqueItems": true },
    "conflicts": { "type": "array", "items": { "$ref": "#/$defs/dependency" }, "uniqueItems": true },
    "provides": { "type": "array", "items": { "$ref": "#/$defs/dependency" }, "uniqueItems": true },
    "replaces": { "type": "array", "items": { "$ref": "#/$defs/dependency" }, "uniqueItems": true },
    "facets": { "$ref": "#/$defs/facetSet", "description": "Administrator-controlled facet labels, not guarantees." },
    "customFacets": { "$ref": "#/$defs/customFacetSet", "description": "User-defined facet labels kept separate from administrator vocabulary." },
    "lifecycle": { "$ref": "#/$defs/lifecycle" },
    "createdAt": { "$ref": "#/$defs/timestamp" },
    "updatedAt": { "$ref": "#/$defs/timestamp" },
    "publishedAt": { "$ref": "#/$defs/timestamp" },
    "_meta": { "$ref": "#/$defs/extensionMeta", "description": "Namespaced extension data preserved without interpretation." }
  },
  "allOf": [
    {
      "if": { "properties": { "type": { "enum": ["mcp", "plugin", "skill", "general"] } }, "required": ["type"] },
      "then": { "required": ["distributions"] }
    },
    { "if": { "properties": { "type": { "const": "mcp" } }, "required": ["type"] }, "then": { "required": ["mcpDetails"], "not": { "anyOf": [{ "required": ["pluginDetails"] }, { "required": ["skillDetails"] }, { "required": ["generalDetails"] }, { "required": ["bundleDetails"] }] } } },
    { "if": { "properties": { "type": { "const": "plugin" } }, "required": ["type"] }, "then": { "required": ["pluginDetails"], "not": { "anyOf": [{ "required": ["mcpDetails"] }, { "required": ["skillDetails"] }, { "required": ["generalDetails"] }, { "required": ["bundleDetails"] }] } } },
    { "if": { "properties": { "type": { "const": "skill" } }, "required": ["type"] }, "then": { "required": ["skillDetails"], "not": { "anyOf": [{ "required": ["mcpDetails"] }, { "required": ["pluginDetails"] }, { "required": ["generalDetails"] }, { "required": ["bundleDetails"] }] } } },
    { "if": { "properties": { "type": { "const": "general" } }, "required": ["type"] }, "then": { "required": ["generalDetails"], "not": { "anyOf": [{ "required": ["mcpDetails"] }, { "required": ["pluginDetails"] }, { "required": ["skillDetails"] }, { "required": ["bundleDetails"] }] } } },
    { "if": { "properties": { "type": { "const": "bundle" } }, "required": ["type"] }, "then": { "required": ["bundleDetails"], "not": { "anyOf": [{ "required": ["mcpDetails"] }, { "required": ["pluginDetails"] }, { "required": ["skillDetails"] }, { "required": ["generalDetails"] }] } } }
  ],
  "$defs": {
    "identifier": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^[^\\s\\u0000-\\u001f\\u007f\\\\]+$", "description": "Stable identity; supports Unicode and reversible UTF-8 percent escapes. Controls, whitespace, and literal backslashes are forbidden." },
    "packageName": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$", "description": "Original Unicode package name. Encoding filesystem or URL paths must not rewrite this value." },
    "url": { "type": "string", "format": "uri", "minLength": 1 },
    "timestamp": { "type": "string", "format": "date-time" },
    "stringOrArray": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } ] },
    "links": {
      "type": "object", "additionalProperties": false,
      "properties": {
        "repository": { "$ref": "#/$defs/url" }, "homepage": { "$ref": "#/$defs/url" }, "readme": { "$ref": "#/$defs/url" },
        "license": { "$ref": "#/$defs/url" }, "documentation": { "$ref": "#/$defs/url" }, "changelog": { "$ref": "#/$defs/url" }, "issues": { "$ref": "#/$defs/url" }
      }
    },
    "maintainer": {
      "type": "object", "required": ["name"], "additionalProperties": false,
      "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "$ref": "#/$defs/url" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["author", "maintainer", "contributor", "security"] } }
    },
    "platform": {
      "type": "object", "additionalProperties": false,
      "properties": {
        "os": { "$ref": "#/$defs/stringList" }, "arch": { "$ref": "#/$defs/stringList" }, "libc": { "$ref": "#/$defs/stringList" }, "runtime": { "$ref": "#/$defs/stringList" }
      }
    },
    "mcpDetails": {
      "type": "object", "required": ["registryType", "identifier"], "additionalProperties": false,
      "properties": {
        "registryType": { "type": "string", "enum": ["npm", "pypi", "nuget", "cargo", "oci", "mcpb", "git", "other"] }, "registryBaseUrl": { "$ref": "#/$defs/url" }, "identifier": { "type": "string", "minLength": 1 },
        "transport": { "type": "string", "enum": ["stdio", "streamable-http", "sse", "other"] }, "environmentVariables": { "$ref": "#/$defs/stringList" },
        "remotes": { "type": "array", "items": { "type": "object", "required": ["url", "transport"], "additionalProperties": false, "properties": { "url": { "$ref": "#/$defs/url" }, "transport": { "type": "string", "enum": ["streamable-http", "sse"] } } }, "uniqueItems": true }
      }
    },
    "pluginDetails": {
      "type": "object", "required": ["manifestPath"], "additionalProperties": false,
      "properties": { "manifestPath": { "type": "string", "minLength": 1 }, "sourceType": { "type": "string", "enum": ["github-repo", "npm-pkg", "pypi-pkg", "nuget-pkg", "crates-pkg", "github-mcpb", "gitlab-mcpb", "mcpb-pkg", "git", "archive", "registry", "local", "other"] }, "marketplaceUrl": { "$ref": "#/$defs/url" }, "entrypoint": { "type": "string", "minLength": 1 }, "permissions": { "$ref": "#/$defs/stringList" } }
    },
    "skillDetails": {
      "type": "object", "required": ["skillPath"], "additionalProperties": false,
      "properties": { "skillPath": { "type": "string", "minLength": 1 }, "allowedTools": { "$ref": "#/$defs/stringList" }, "compatibilityNotes": { "type": "string", "maxLength": 2000 }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } }
    },
    "generalDetails": {
      "type": "object", "required": ["toolType", "agentUse"], "additionalProperties": false,
      "properties": { "toolType": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nature of the general Agent tool, such as prompt-library or evaluation-harness." }, "agentUse": { "type": "string", "minLength": 1, "maxLength": 2000 }, "inputFormats": { "$ref": "#/$defs/stringList" }, "outputFormats": { "$ref": "#/$defs/stringList" } }
    },
    "agentTarget": {
      "type": "object", "required": ["agentId", "compatibilityStatus"], "additionalProperties": false,
      "properties": {
        "agentId": { "type": "string", "minLength": 1, "maxLength": 100 }, "agentVersionRange": { "type": ["string", "null"], "minLength": 1, "description": "Null means no parseable upstream Agent range was supplied." },
        "versionScheme": { "type": "string", "enum": ["semver", "npm", "pep440", "calver", "date", "custom", "unknown"] }, "compatibilityStatus": { "type": "string", "enum": ["known", "unknown"] }, "compatibilityNote": { "type": "string", "maxLength": 2000 },
        "targetMetadata": { "type": "object", "additionalProperties": true }, "installMetadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": ["active", "deprecated", "unavailable", "experimental"] }
      },
      "allOf": [
        { "if": { "properties": { "compatibilityStatus": { "const": "unknown" } }, "required": ["compatibilityStatus"] }, "then": { "properties": { "agentVersionRange": { "type": "null" } }, "required": ["compatibilityNote"] } },
        { "if": { "properties": { "compatibilityStatus": { "const": "known" } }, "required": ["compatibilityStatus"] }, "then": { "required": ["agentVersionRange"] } }
      ]
    },
    "distribution": {
      "type": "object", "required": ["id", "type", "url"], "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/identifier" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable distribution name." }, "type": { "type": "string", "enum": ["github-repo", "npm-pkg", "pypi-pkg", "nuget-pkg", "crates-pkg", "ghcr-image", "dockerhub-image", "quay-image", "gcp-artifact-image", "oci-image", "github-mcpb", "gitlab-mcpb", "mcpb-pkg", "mcp-endpoint", "git", "release", "archive", "registry", "oci", "package", "other"], "description": "Platform and artifact kind. Repository sources use ref; registry packages use version and registry; image sources use OCI semantics; MCPB sources are downloadable archives; mcp-endpoint is a remote service. Generic values remain valid for unclassified or legacy sources." }, "url": { "$ref": "#/$defs/url" }, "agentIds": { "$ref": "#/$defs/stringList" }, "version": { "type": "string", "minLength": 1 }, "ref": { "type": "string", "minLength": 1 }, "registry": { "type": "string", "minLength": 1 }, "priority": { "type": "integer", "minimum": 0 }, "regions": { "$ref": "#/$defs/stringList" }, "checksum": { "$ref": "#/$defs/checksum" }, "signature": { "$ref": "#/$defs/signature" }, "install": { "$ref": "#/$defs/install" }, "notes": { "type": "string", "maxLength": 2000 }
      }
    },
    "checksum": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "sha256": { "type": "string", "pattern": "^[A-Fa-f0-9]{64}$" }, "sha512": { "type": "string", "pattern": "^[A-Fa-f0-9]{128}$" }, "blake2b": { "type": "string", "minLength": 1 } } },
    "signature": { "type": "object", "required": ["url"], "additionalProperties": false, "properties": { "url": { "$ref": "#/$defs/url" }, "type": { "type": "string", "enum": ["gpg", "pgp", "minisign", "sigstore", "cosign", "other"] }, "keyId": { "type": "string", "minLength": 1 }, "keyUrl": { "$ref": "#/$defs/url" } } },
    "install": {
      "type": "object", "additionalProperties": false,
      "properties": { "type": { "type": "string", "enum": ["command", "url", "api", "script", "registry"] }, "url": { "$ref": "#/$defs/url" }, "command": { "type": "string", "minLength": 1 }, "scriptIntegrity": { "type": "string", "minLength": 1 }, "requires": { "$ref": "#/$defs/stringList" }, "notes": { "type": "string", "maxLength": 2000 } },
      "allOf": [
        { "if": { "properties": { "type": { "const": "command" } }, "required": ["type"] }, "then": { "required": ["command"] } },
        { "if": { "properties": { "type": { "enum": ["url", "api", "registry"] } }, "required": ["type"] }, "then": { "required": ["url"] } },
        { "if": { "properties": { "type": { "const": "script" } }, "required": ["type"] }, "then": { "required": ["url", "scriptIntegrity"] } }
      ]
    },
    "dependency": { "type": "object", "required": ["id"], "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/identifier" }, "versionRange": { "type": "string", "minLength": 1 }, "versionScheme": { "type": "string", "enum": ["semver", "npm", "pep440", "calver", "date", "custom", "unknown"] }, "agentId": { "type": "string", "minLength": 1 }, "optional": { "type": "boolean" }, "reason": { "type": "string", "maxLength": 1000 } } },
    "facetSet": { "type": "object", "additionalProperties": false, "properties": { "capabilities": { "$ref": "#/$defs/stringList" }, "effects": { "$ref": "#/$defs/stringList" }, "dataPractices": { "$ref": "#/$defs/stringList" }, "permissions": { "$ref": "#/$defs/stringList" }, "runtime": { "$ref": "#/$defs/stringList" }, "integrations": { "$ref": "#/$defs/stringList" } } },
    "customFacetSet": { "type": "object", "additionalProperties": false, "properties": { "capabilities": { "$ref": "#/$defs/stringList" }, "effects": { "$ref": "#/$defs/stringList" }, "dataPractices": { "$ref": "#/$defs/stringList" }, "permissions": { "$ref": "#/$defs/stringList" }, "runtime": { "$ref": "#/$defs/stringList" }, "integrations": { "$ref": "#/$defs/stringList" }, "other": { "$ref": "#/$defs/stringList" } } },
    "bundleDetails": { "type": "object", "required": ["members"], "additionalProperties": false, "properties": { "members": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/bundleMember" }, "uniqueItems": true }, "effectiveTargets": { "type": "array", "items": { "$ref": "#/$defs/effectiveTarget" }, "uniqueItems": true }, "facetUnion": { "$ref": "#/$defs/facetSet" }, "customFacetUnion": { "$ref": "#/$defs/customFacetSet" }, "calculationRevision": { "type": "string", "minLength": 1 } } },
    "bundleMember": { "type": "object", "required": ["memberType", "memberId"], "additionalProperties": false, "properties": { "memberType": { "type": "string", "enum": ["package", "bundle"] }, "memberId": { "$ref": "#/$defs/identifier" }, "versionRange": { "type": "string", "minLength": 1 }, "versionScheme": { "type": "string", "enum": ["semver", "npm", "pep440", "calver", "date", "custom", "unknown"] }, "agentId": { "type": "string", "minLength": 1 }, "override": { "$ref": "#/$defs/bundleOverride" } } },
    "bundleOverride": { "type": "object", "required": ["agentVersionRange", "reason"], "additionalProperties": false, "properties": { "agentVersionRange": { "type": "string", "minLength": 1 }, "versionScheme": { "type": "string", "enum": ["semver", "npm", "pep440", "calver", "date", "custom", "unknown"] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "createdAt": { "$ref": "#/$defs/timestamp" }, "createdBy": { "type": "string", "minLength": 1 } } },
    "effectiveTarget": { "type": "object", "required": ["agentId", "compatibilityStatus"], "additionalProperties": false, "properties": { "agentId": { "type": "string", "minLength": 1 }, "agentVersionRange": { "type": ["string", "null"], "minLength": 1 }, "versionScheme": { "type": "string", "enum": ["semver", "npm", "pep440", "calver", "date", "custom", "unknown"] }, "compatibilityStatus": { "type": "string", "enum": ["known", "unknown", "conflict"] }, "rangeSource": { "type": "string", "enum": ["intersection", "override", "unknown"] }, "conflictNote": { "type": "string", "maxLength": 2000 } } },
    "lifecycle": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": ["active", "deprecated", "archived", "yanked", "experimental"] }, "reason": { "type": "string", "maxLength": 2000 }, "replacementId": { "$ref": "#/$defs/identifier" }, "since": { "$ref": "#/$defs/timestamp" } } },
    "versionRangeType": { "type": "string", "enum": ["semver", "npm", "pep440", "calver", "date", "custom", "unknown"] },
    "advisory": {
      "type": "object", "required": ["id"], "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1 }, "aliases": { "$ref": "#/$defs/stringList" },
        "severity": { "type": "string", "enum": ["none", "low", "medium", "high", "critical", "unknown"] },
        "summary": { "type": "string", "maxLength": 4000 }, "impact": { "type": "string", "maxLength": 4000 },
        "references": { "type": "array", "items": { "$ref": "#/$defs/url" }, "uniqueItems": true },
        "affected": { "type": "object", "additionalProperties": false, "properties": { "range": { "type": "string", "minLength": 1 }, "versionScheme": { "$ref": "#/$defs/versionRangeType" }, "introduced": { "type": "string", "minLength": 1 }, "fixed": { "type": "string", "minLength": 1 }, "lastAffected": { "type": "string", "minLength": 1 } } },
        "fixedIn": { "type": "string", "minLength": 1 }, "publishedAt": { "$ref": "#/$defs/timestamp" }, "updatedAt": { "$ref": "#/$defs/timestamp" },
        "status": { "type": "string", "enum": ["confirmed", "unconfirmed", "disputed", "rejected", "fixed"] }, "source": { "type": "string", "minLength": 1 }, "sourceUrl": { "$ref": "#/$defs/url" }
      }
    },
    "stringList": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "uniqueItems": true, "maxItems": 200 },
    "imageUrl": {"type":"string","format":"uri","minLength":1,"maxLength":4096,"pattern":"^https://[^\\s/@?#\\\\\\x00-\\x1f\\x7f]+(?:[/?#][^\\s<>\"{}|\\\\^`\\x00-\\x1f\\x7f]*)?$"},
    "imageAsset": {"type":"object","required":["url","alt"],"additionalProperties":false,"properties":{"url":{"$ref":"#/$defs/imageUrl"},"alt":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S"}}},
    "previewAsset": {"type":"object","required":["url","alt"],"additionalProperties":false,"properties":{"url":{"$ref":"#/$defs/imageUrl"},"alt":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S"},"theme":{"type":"string","enum":["light","dark","system"],"description":"Declared preview theme, not a runtime compatibility claim."}}},
    "media": {"type":"object","minProperties":1,"additionalProperties":false,"properties":{"icon":{"$ref":"#/$defs/imageAsset"},"previews":{"type":"array","minItems":1,"maxItems":12,"uniqueItems":true,"items":{"$ref":"#/$defs/previewAsset"},"description":"Ordered static images. The first preview is the default thumbnail; no interactive skin code is loaded."}}},
    "mediaSummary": {"type":"object","minProperties":1,"additionalProperties":false,"properties":{"icon":{"$ref":"#/$defs/imageAsset"},"previews":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"$ref":"#/$defs/previewAsset"},"description":"At most the first preview from the selected package version. Load its record for the complete gallery."}}},
    "extensionMeta": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9]*(\\.[a-z0-9-]+)+(/[a-z0-9-]+)?$" }, "additionalProperties": true }
  }
}