PackageVersionAttributes

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/snyk/main/json-schema/snyk-package-version-attributes-schema.json",
  "title": "PackageVersionAttributes",
  "description": "Attributes for a package version resource",
  "x-generated": "2026-10-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/snyk-package-version-api-openapi.yml#/components/schemas/PackageVersionAttributes",
  "allOf": [
    {
      "$ref": "#/$defs/BasePackageAttributes"
    },
    {
      "properties": {
        "latest_version_indicator": {
          "description": "Whether this is the latest version of the package",
          "type": "boolean"
        },
        "package_details": {
          "$ref": "#/$defs/PackageVersionDetails"
        },
        "package_version": {
          "description": "The specific version string of this package",
          "type": "string"
        },
        "package_version_id": {
          "description": "Package version identifier in PURL format (e.g., pkg:npm/express@4.19.2)",
          "type": "string"
        },
        "published_at": {
          "description": "Timestamp when this version was published",
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "package_version_id",
        "package_version",
        "latest_version_indicator"
      ],
      "type": "object"
    }
  ],
  "$defs": {
    "BasePackageAttributes": {
      "description": "Common attributes shared between package and package version resources",
      "properties": {
        "description": {
          "description": "Package description from the registry (max 255 characters)",
          "type": "string"
        },
        "ecosystem": {
          "description": "The package ecosystem",
          "enum": [
            "npm",
            "pypi",
            "maven",
            "nuget",
            "golang"
          ],
          "type": "string"
        },
        "keywords": {
          "description": "Searchable terms defined by the package maintainer in the registry (e.g., in package.json for npm). Used for package discovery (max 20 keywords).",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "language": {
          "description": "Primary programming language of the package",
          "type": "string"
        },
        "owner_details": {
          "$ref": "#/$defs/OwnerDetails"
        },
        "package_health": {
          "$ref": "#/$defs/PackageHealth"
        },
        "package_id": {
          "description": "Package identifier in PURL format",
          "type": "string"
        },
        "package_name": {
          "description": "Name of the package",
          "type": "string"
        }
      },
      "required": [
        "package_id",
        "ecosystem",
        "package_name",
        "language"
      ],
      "type": "object"
    },
    "CommunityDetails": {
      "additionalProperties": false,
      "description": "Community health signals for the package",
      "properties": {
        "description": {
          "description": "Human-readable explanation of the community rating",
          "type": "string"
        },
        "has_code_of_conduct_file": {
          "description": "Whether the repository has a CODE_OF_CONDUCT file",
          "type": "boolean"
        },
        "has_contributing_file": {
          "description": "Whether the repository has a CONTRIBUTING file",
          "type": "boolean"
        },
        "has_funding_file": {
          "description": "Whether the repository has a FUNDING file",
          "type": "boolean"
        },
        "has_readme_file": {
          "description": "Whether the repository has a README file",
          "type": "boolean"
        },
        "rating": {
          "description": "Overall community health level, reflecting how active and engaged the package's community appears to be",
          "enum": [
            "Active",
            "Sustainable",
            "Limited"
          ],
          "type": "string"
        },
        "stargazers_count": {
          "description": "Number of GitHub stars (>= 0)",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "has_code_of_conduct_file",
        "has_contributing_file",
        "has_funding_file",
        "has_readme_file",
        "stargazers_count"
      ],
      "type": "object"
    },
    "DirectVulnerabilitiesCounts": {
      "additionalProperties": false,
      "description": "Breakdown of direct vulnerabilities by Snyk severity level",
      "properties": {
        "critical": {
          "description": "Number of critical severity vulnerabilities (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "high": {
          "description": "Number of high severity vulnerabilities (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "low": {
          "description": "Number of low severity vulnerabilities (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "medium": {
          "description": "Number of medium severity vulnerabilities (>= 0)",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "critical",
        "high",
        "medium",
        "low"
      ],
      "type": "object"
    },
    "MaintenanceDetails": {
      "additionalProperties": false,
      "description": "Maintenance health signals for the package as a whole, based on repository-level activity. These signals reflect the overall project status. They do not represent the maintenance state of specific versions or version lines.",
      "properties": {
        "description": {
          "description": "Human-readable explanation of the maintenance rating",
          "type": "string"
        },
        "first_release_published_at": {
          "description": "Timestamp of the first release",
          "format": "date-time",
          "type": "string"
        },
        "forks_count": {
          "description": "Number of repository forks (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "is_archived": {
          "description": "Whether the source repository is archived. This is a repository-level signal. It does not represent the maintenance state of specific versions or version lines.",
          "type": "boolean"
        },
        "is_forked": {
          "description": "Whether the repository is a fork",
          "type": "boolean"
        },
        "latest_release_number": {
          "description": "Latest release version string",
          "type": "string"
        },
        "latest_release_published_at": {
          "description": "Timestamp of the latest release",
          "format": "date-time",
          "type": "string"
        },
        "lifecycle": {
          "description": "Package-level lifecycle status as reported by the registry. Reflects the overall package state. It does not represent the maintenance state of specific versions or version lines.",
          "enum": [
            "active",
            "archived",
            "deprecated",
            "removed",
            "unpublished"
          ],
          "type": "string"
        },
        "rating": {
          "description": "Package-level maintenance health, reflecting how actively the package repository is being developed and updated. This applies to the project as a whole. It does not represent the maintenance state of specific versions or version lines.",
          "enum": [
            "Healthy",
            "Sustainable",
            "Inactive"
          ],
          "type": "string"
        },
        "total_versions_count": {
          "description": "Total number of versions published (>= 0)",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "is_archived",
        "is_forked",
        "total_versions_count",
        "forks_count"
      ],
      "type": "object"
    },
    "OwnerDetails": {
      "additionalProperties": false,
      "description": "Details about the package owner/maintainer",
      "properties": {
        "followers_count": {
          "description": "Number of followers the package owner has on the source platform (e.g., GitHub) (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "location": {
          "description": "Owner location",
          "type": "string"
        },
        "name": {
          "description": "Owner/maintainer name",
          "type": "string"
        },
        "repositories_count": {
          "description": "Number of repositories owned by the package owner on the source platform (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "total_stars": {
          "description": "Total number of stars across all repositories owned by the package owner (>= 0)",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "followers_count",
        "repositories_count",
        "total_stars"
      ],
      "type": "object"
    },
    "PackageDetails": {
      "description": "Base package details with URLs",
      "properties": {
        "homepage_url": {
          "description": "Package homepage URL",
          "type": "string"
        },
        "registry_url": {
          "description": "Package registry URL",
          "type": "string"
        },
        "repository_url": {
          "description": "Source repository URL",
          "type": "string"
        }
      },
      "type": "object"
    },
    "PackageHealth": {
      "additionalProperties": false,
      "description": "Overall health assessment of the package based on multiple signals",
      "properties": {
        "community": {
          "$ref": "#/$defs/CommunityDetails"
        },
        "description": {
          "description": "Human-readable explanation of the overall rating",
          "type": "string"
        },
        "maintenance": {
          "$ref": "#/$defs/MaintenanceDetails"
        },
        "overall_rating": {
          "description": "Overall health assessment of the package based on security, maintenance, community, and popularity signals",
          "enum": [
            "Healthy",
            "Review recommended",
            "Not recommended",
            "Not enough data to compute health status"
          ],
          "type": "string"
        },
        "popularity": {
          "$ref": "#/$defs/PopularityDetails"
        },
        "security": {
          "$ref": "#/$defs/SecurityDetails"
        }
      },
      "type": "object"
    },
    "PackageVersionDetails": {
      "allOf": [
        {
          "$ref": "#/$defs/PackageDetails"
        },
        {
          "properties": {
            "download_url": {
              "description": "Direct download URL for this version",
              "type": "string"
            },
            "registry_version_url": {
              "description": "Registry URL for this specific version",
              "type": "string"
            }
          },
          "type": "object"
        }
      ]
    },
    "PopularityDetails": {
      "additionalProperties": false,
      "description": "Popularity signals for the package",
      "properties": {
        "dependent_packages_count": {
          "description": "Number of packages that depend on this package (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "dependent_repos_count": {
          "description": "Number of repositories that depend on this package (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "description": {
          "description": "Human-readable explanation of the popularity rating",
          "type": "string"
        },
        "downloads": {
          "description": "Download count (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "rating": {
          "description": "Popularity rating based on downloads and ecosystem usage",
          "enum": [
            "Limited",
            "Small",
            "Recognized",
            "Popular",
            "Influential project",
            "Key ecosystem project"
          ],
          "type": "string"
        }
      },
      "required": [
        "dependent_packages_count",
        "dependent_repos_count",
        "downloads"
      ],
      "type": "object"
    },
    "SecurityDetails": {
      "additionalProperties": false,
      "description": "Security signals for the package",
      "properties": {
        "description": {
          "description": "Human-readable explanation of the security rating",
          "type": "string"
        },
        "direct_vulnerabilities": {
          "description": "Whether the package has direct vulnerabilities",
          "type": "boolean"
        },
        "direct_vulnerabilities_counts": {
          "$ref": "#/$defs/DirectVulnerabilitiesCounts"
        },
        "direct_vulnerabilities_total": {
          "description": "Total count of direct vulnerabilities (>= 0)",
          "minimum": 0,
          "type": "integer"
        },
        "rating": {
          "description": "Security rating based on known vulnerabilities",
          "enum": [
            "No known security issues",
            "Minor security issues found",
            "Security issues found"
          ],
          "type": "string"
        }
      },
      "required": [
        "direct_vulnerabilities",
        "direct_vulnerabilities_total"
      ],
      "type": "object"
    }
  }
}