Annex A (normative) PURL Type Definition

This Annex provides a copy of the current Package-URL Type Definition Schema. The format is JSON Schema version draft-07.

The schema shown below is available in electronic form at: https://github.com/package-url/purl-spec/blob/main/schemas/purl-type-definition.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://packageurl.org/schemas/purl-type-definition.schema-1.0.json",
  "title": "Package-URL Type Definition",
  "description": "Schema to specify a Package-URL (PURL) type as a structured definition.",
  "type": "object",
  "additionalProperties": false,
  "definitions": {
    "optional_requirement": {
      "title": "Component optional requirement",
      "description": "States that this PURL component is optional for a PURL type.",
      "type": "string",
      "const": "optional"
    },
    "required_requirement": {
      "title": "Component required requirement",
      "description": "States that this PURL component is required for a PURL type.",
      "type": "string",
      "const": "required"
    },
    "prohibited_requirement": {
      "title": "Component prohibited requirement",
      "description": "States that this PURL component is prohibited for a PURL type.",
      "type": "string",
      "const": "prohibited"
    },
    "purl_component_definition": {
      "title": "PURL component definition",
      "description": "PURL component definition properties that apply to most PURL components",
      "type": "object",
      "properties": {
        "permitted_characters": {
          "title": "Permitted characters in this PURL component",
          "description": "A regular expression (ECMA-262 dialect) defining the 'Permitted characters' for this component of this Package-URL type. If provided, this shall be a subset of the 'Permitted characters' defined in the PURL specification.",
          "type": "string",
          "format": "regex"
        },
        "case_sensitive": {
          "title": "Case sensitive",
          "description": "true if this PURL component is case sensitive. If false, the canonical form shall be lowercased.",
          "type": "boolean",
          "default": true
        },
        "normalization_rules": {
          "title": "Normalization rules",
          "description": "List of rules to normalize this component for this PURL type. These are plain text, unstructured rules as some require programming and cannot be enforced only with a schema. Tools are expected to apply these rules programmatically.",
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string"
          }
        },
        "native_name": {
          "title": "Native name",
          "description": "The native name of this PURL component in the package ecosystem. For instance, the 'namespace' for the 'maven' type is 'groupId', and 'scope' for the 'npm' PURL type.",
          "type": "string"
        },
        "note": {
          "title": "Note",
          "description": "Extra note text.",
          "type": "string"
        }
      }
    }
  },
  "required": [
    "$id",
    "type",
    "type_name",
    "description",
    "repository",
    "namespace_definition",
    "name_definition",
    "examples"
  ],
  "properties": {
    "$schema": {
      "title": "JSON schema",
      "description": "Contains the URL of the JSON schema for Package-URL type definition.",
      "const": "https://packageurl.org/schemas/purl-type-definition.schema-1.0.json",
      "format": "uri"
    },
    "$id": {
      "title": "PURL type definition id",
      "description": "The unique identifier URI for this PURL type definition.",
      "type": "string",
      "pattern": "^https:\\/\\/packageurl\\.org/types/[a-z0-9-]+-definition\\.json$"
    },
    "type": {
      "title": "PURL type",
      "description": "The type string for this Package-URL type.",
      "type": "string",
      "pattern": "^[a-z][a-z0-9-\\.]+$",
      "examples": [
        "maven",
        "npm",
        "pypi"
      ]
    },
    "type_name": {
      "title": "Type name",
      "description": "The name for this PURL type.",
      "type": "string",
      "examples": [
        "Apache Maven",
        "Python Package"
      ]
    },
    "description": {
      "title": "Description",
      "description": "The description of this PURL type.",
      "type": "string"
    },
    "repository": {
      "title": "Repository",
      "description": "The package repository usage for this PURL type.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "use_repository"
      ],
      "properties": {
        "use_repository": {
          "title": "Use repository",
          "description": "true if this PURL type uses a public package repository.",
          "type": "boolean",
          "default": false
        },
        "default_repository_url": {
          "title": "Default repository URL",
          "description": "The default public repository URL for this PURL type",
          "type": "string",
          "format": "uri"
        },
        "note": {
          "title": "Note",
          "description": "Extra note text.",
          "type": "string"
        }
      }
    },
    "namespace_definition": {
      "title": "Namespace definition",
      "description": "Definition of the namespace component for this PURL type. The PURL namespace component shall be required, optional or prohibited for a specific PURL type definition.",
      "type": "object",
      "required": [
        "requirement"
      ],
      "properties": {
        "requirement": {
          "title": "Namespace requirement",
          "description": "States that the PURL namespace component is optional, required or prohibited for a PURL type.",
          "type": "string",
          "oneOf": [
            {
              "$ref": "#/definitions/optional_requirement"
            },
            {
              "$ref": "#/definitions/required_requirement"
            },
            {
              "$ref": "#/definitions/prohibited_requirement"
            }
          ]
        }
      },
      "allOf": [
        {
          "$ref": "#/definitions/purl_component_definition"
        }
      ]
    },
    "name_definition": {
      "title": "Name definition",
      "description": "Definition of the name component for this PURL type. The PURL name component is required for all PURL type definitions.",
      "type": "object",
      "required": [
        "requirement"
      ],
      "properties": {
        "requirement": {
          "title": "Name component requirement",
          "description": "States that the PURL name component is always required.",
          "type": "string",
          "oneOf": [
            {
              "$ref": "#/definitions/required_requirement"
            }
          ]
        }
      },
      "allOf": [
        {
          "$ref": "#/definitions/purl_component_definition"
        }
      ]
    },
    "version_definition": {
      "title": "Version definition",
      "description": "Definition of the version component for this PURL type. The PURL version component is optional for a specific PURL type definition.",
      "type": "object",
      "required": [
        "requirement"
      ],
      "properties": {
        "requirement": {
          "title": "Version requirement",
          "description": "States that the PURL version is optional.",
          "type": "string",
          "oneOf": [
            {
              "$ref": "#/definitions/optional_requirement"
            }
          ]
        }
      },
      "allOf": [
        {
          "$ref": "#/definitions/purl_component_definition"
        }
      ]
    },
    "qualifiers_definition": {
      "title": "Qualifiers definition",
      "description": "Definition of the qualifiers specific to this PURL type. The PURL qualifiers component is optional for a specific PURL type, but a qualifiers key or keys may be required for a specific PURL type.",
      "type": "array",
      "additionalItems": false,
      "uniqueItems": true,
      "items": {
        "title": "Qualifiers definition",
        "description": "The definition of a qualifier specific to this PURL type.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "key",
          "description"
        ],
        "properties": {
          "key": {
            "title": "Qualifier key",
            "description": "The key for the qualifier.",
            "type": "string"
          },
          "requirement": {
            "title": "Qualifier key requirement",
            "description": "States that a PURL qualifier key is optional or required for a PURL type.",
            "type": "string",
            "oneOf": [
              {
                "$ref": "#/definitions/optional_requirement"
              },
              {
                "$ref": "#/definitions/required_requirement"
              }
            ]
          },
          "description": {
            "title": "Description",
            "description": "The description of this qualifier.",
            "type": "string"
          },
          "default_value": {
            "title": "Default value",
            "description": "The optional default value of this qualifier if not provided.",
            "type": "string"
          },
          "native_name": {
            "title": "Native name",
            "description": "The equivalent native name for this qualifier key.",
            "type": "string"
          }
        }
      }
    },
    "subpath_definition": {
      "title": "Subpath definition",
      "description": "The definition for the subpath for this PURL type. The PURL subpath component is optional for a specific PURL type definition.",
      "type": "object",
      "required": [
        "requirement"
      ],
      "properties": {
        "requirement": {
          "title": "Subpath requirement",
          "description": "States that the PURL subpath is optional.",
          "type": "string",
          "oneOf": [
            {
              "$ref": "#/definitions/optional_requirement"
            }
          ]
        }
      },
      "allOf": [
        {
          "$ref": "#/definitions/purl_component_definition"
        }
      ]
    },
    "examples": {
      "title": "PURL examples",
      "description": "Example of valid, canonical PURLs for this package type.",
      "type": "array",
      "uniqueItems": true,
      "minItems": 1,
      "items": {
        "type": "string",
        "pattern": "^pkg:[a-z][a-z0-9-\\.]+/.*$"
      }
    },
    "note": {
      "title": "Note",
      "description": "Note about this PURL type.",
      "type": "string"
    },
    "reference_urls": {
      "title": "Reference URLs",
      "description": "Optional list of informational reference URLs about this PURL type.",
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "format": "uri"
      }
    }
  }
}

Bibliography

• ECMA-262, ECMAScript® language specification, 16^th Edition. Annex A.8: Grammar Summary for Regular Expressions
  https://262.ecma-international.org/16.0/index.html#sec-regular-expressions
• ECMA-404, The JSON data interchange syntax
  https://www.ecma-international.org/publications-and-standards/standards/ecma-404/
• INCITS 4-1986 [R2022], Information Systems - Coded Character Sets - 7-Bit Standard Code for Information Interchange (7-Bit ASCII)
  https://webstore.ansi.org/standards/incits/incits1986r2022
• IETF Draft, March 2018, JSON Schema Validation: A Vocabulary for Structural Validation of JSON (Draft-07)
  https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-validation-01

Colophon

This Standard is authored on GitHub in a plaintext source format called Ecmarkup. Ecmarkup is an HTML and Markdown dialect that provides a framework and toolset for authoring ECMA specifications in plaintext and processing the specification into a full-featured HTML rendering that follows the editorial conventions for this document. Ecmarkup builds on and integrates a number of other formats and technologies including Grammarkdown for defining syntax and Ecmarkdown for authoring algorithm steps. PDF renderings of this Standard are produced using a print stylesheet which takes advantage of the CSS Paged Media specification and is converted using PrinceXML.

We extend our gratitude to TC39 for their exceptional work in developing Ecmarkup, which has greatly facilitated TC54's successful adoption of this tool for the preparation and maintenance of our technical specifications.

Copyright & Software License

Ecma International

Rue du Rhone 114

CH-1204 Geneva

Tel: +41 22 849 6000

Fax: +41 22 849 6001

Web: https://ecma-international.org/

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.