diff --git a/purl-types-index.json b/purl-types-index.json index c956935b..467d4e13 100644 --- a/purl-types-index.json +++ b/purl-types-index.json @@ -27,6 +27,7 @@ "npm", "nuget", "oci", + "otp", "pub", "pypi", "qpkg", diff --git a/tests/types/otp-test.json b/tests/types/otp-test.json new file mode 100644 index 00000000..74648ceb --- /dev/null +++ b/tests/types/otp-test.json @@ -0,0 +1,120 @@ +{ + "$schema": "https://packageurl.org/schemas/purl-test.schema-0.1.json", + "tests": [ + { + "description": "Parse test for PURL", + "test_group": "base", + "test_type": "parse", + "input": "pkg:otp/asn1@5.4.1?arch=amd64&platform=linux&repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Ferlang%2Fotp.git#src/asn1ct.erl", + "expected_output": { + "type": "otp", + "namespace": null, + "name": "asn1", + "version": "5.4.1", + "qualifiers": { + "platform": "linux", + "arch": "amd64", + "repository_url": "https://github.com/erlang/otp", + "vcs_url": "git+https://github.com/erlang/otp.git" + }, + "subpath": "src/asn1ct.erl" + }, + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "Roundtrip test for PURL", + "test_group": "base", + "test_type": "roundtrip", + "input": "pkg:otp/asn1@5.4.1?arch=amd64&platform=linux&repository_url=https://github.com/erlang/otp&vcs_url=git%2Bhttps://github.com/erlang/otp.git#src/asn1ct.erl", + "expected_output": "pkg:otp/asn1@5.4.1?arch=amd64&platform=linux&repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Ferlang%2Fotp.git#src/asn1ct.erl", + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "Build test for PURL", + "test_group": "base", + "test_type": "build", + "input": { + "type": "otp", + "namespace": null, + "name": "asn1", + "version": "5.4.1", + "qualifiers": { + "platform": "linux", + "arch": "amd64", + "repository_url": "https://github.com/erlang/otp", + "vcs_url": "git+https://github.com/erlang/otp.git" + }, + "subpath": "src/asn1ct.erl" + }, + "expected_output": "pkg:otp/asn1@5.4.1?arch=amd64&platform=linux&repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Ferlang%2Fotp.git#src/asn1ct.erl", + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "Parse test for PURL", + "test_group": "base", + "test_type": "parse", + "input": "pkg:otp/hex@2.1.1", + "expected_output": { + "type": "otp", + "namespace": null, + "name": "hex", + "version": "2.1.1", + "qualifiers": null, + "subpath": null + }, + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "Roundtrip test for PURL", + "test_group": "base", + "test_type": "roundtrip", + "input": "pkg:otp/hex@2.1.1", + "expected_output": "pkg:otp/hex@2.1.1", + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "Build test for PURL", + "test_group": "base", + "test_type": "build", + "input": { + "type": "otp", + "namespace": null, + "name": "hex", + "version": "2.1.1", + "qualifiers": null, + "subpath": null + }, + "expected_output": "pkg:otp/hex@2.1.1", + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "Parse test for PURL", + "test_group": "base", + "test_type": "parse", + "input": "pkg:otp/namespace/hex@2.1.1", + "expected_failure": true, + "expected_failure_reason": "Should fail to parse an OTP PURL containing a prohibited namespace component" + }, + { + "description": "Build test for PURL", + "test_group": "base", + "test_type": "build", + "input": { + "type": "otp", + "namespace": "namespace", + "name": "hex", + "version": "2.1.1", + "qualifiers": null, + "subpath": null + }, + "expected_failure": true, + "expected_failure_reason": "Should fail to build an OTP PURL containing a prohibited namespace component" + } + ] +} diff --git a/types-doc/otp-definition.md b/types-doc/otp-definition.md new file mode 100644 index 00000000..7d4d8feb --- /dev/null +++ b/types-doc/otp-definition.md @@ -0,0 +1,68 @@ + + +# PURL Type Definition: otp + +- **Type Name:** BEAM/OTP Application +- **Description:** BEAM/OTP applications written in Elixir, Erlang, Gleam and other BEAM languages +- **Schema ID:** `https://packageurl.org/types/otp-definition.json` + +## PURL Syntax + +The structure of a PURL for this package type is: + + pkg:otp/@?# + +## Repository Information + +- **Use Repository:** No + +## Namespace definition + +- **Requirement:** Prohibited +- **Note:** `The component is unused and MUST be empty` + +## Name definition + +- **Requirement:** Required +- **Native Label:** name +- **Note:** `The OTP application name from the `.app` file; it is case-insensitive and MUST be lower-cased.` + +## Version definition + +- **Requirement:** Optional +- **Native Label:** version +- **Note:** `The OTP application version (the `vsn` attribute).` + +## Subpath definition + +- **Requirement:** Optional +- **Native Label:** May be added to reference a specific file or directory inside the OTP application. + +## Qualifiers Definition + +| Key | Requirement | Native name | Default Value | Description | +|------|-------------|-------------|---------------|-------------| +| repository_url | Optional | Repository URL | | The canonical origin of the OTP application source. This qualifier is optional, but it should be included whenever the origin is known, and should point to a trusted source repository. | +| platform | Optional | platform | | The target operating system for native code (e.g. ``linux``, ``darwin``, ``freebsd``, ``sunos``, ``win32``; case-insensitive). | +| arch | Optional | arch | | The arch is the qualifiers key for a package architecture. | + +## Examples + +- `pkg:otp/erts@10.6.3?platform=linux&arch=amd64&repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%20https:%2F%2Fgithub.com%2Ferlang%2Fotp.git` +- `pkg:otp/stdlib@3.11.2?repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%20https:%2F%2Fgithub.com%2Ferlang%2Fotp.git` +- `pkg:otp/crypto@4.6.4?platform=darwin&arch=x86_64&repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%20https:%2F%2Fgithub.com%2Ferlang%2Fotp.git` +- `pkg:otp/elixir@1.10.0?repository_url=https:%2F%2Fgithub.com%2Felixir-lang%2Felixir&vcs_url=git%20https:%2F%2Fgithub.com%2Felixir-lang%2Felixir.git` +- `pkg:otp/eex@1.10.0?repository_url=https:%2F%2Fgithub.com%2Felixir-lang%2Felixir&vcs_url=git%20https:%2F%2Fgithub.com%2Felixir-lang%2Felixir.git` +- `pkg:otp/logger@1.10.0?repository_url=https:%2F%2Fgithub.com%2Felixir-lang%2Felixir&vcs_url=git%20https:%2F%2Fgithub.com%2Felixir-lang%2Felixir.git` +- `pkg:otp/rebar@3.13.0?repository_url=https:%2F%2Fgithub.com%2Ferlang%2Frebar3&vcs_url=git%20https:%2F%2Fgithub.com%2Ferlang%2Frebar3.git` +- `pkg:otp/hex@2.1.1?repository_url=https:%2F%2Fgithub.com%2Fhexpm%2Fhex&vcs_url=git%20https:%2F%2Fgithub.com%2Fhexpm%2Fhex.git` + +## Note + +- If the component was fetched from a Hex repository, prefer a ``hex`` purl + because Hex provides a global, collision-free namespace that uniquely ties + the version to the published source. +- There is no default package repository. When the application can be + fetched from a known location, add a general qualifier such as + `repository_url`, `download_url` or `vcs_url`. diff --git a/types/otp-definition.json b/types/otp-definition.json new file mode 100644 index 00000000..59c542e5 --- /dev/null +++ b/types/otp-definition.json @@ -0,0 +1,61 @@ +{ + "$schema": "https://packageurl.org/schemas/purl-type-definition.schema-1.0.json", + "$id": "https://packageurl.org/types/otp-definition.json", + "type": "otp", + "type_name": "BEAM/OTP Application", + "description": "BEAM/OTP applications written in Elixir, Erlang, Gleam and other BEAM languages", + "note": "- If the component was fetched from a Hex repository, prefer a ``hex`` purl\n because Hex provides a global, collision-free namespace that uniquely ties\n the version to the published source.\n- There is no default package repository. When the application can be\n fetched from a known location, add a general qualifier such as\n `repository_url`, `download_url` or `vcs_url`.", + "repository": { + "use_repository": false + }, + "namespace_definition": { + "requirement": "prohibited", + "note": "The component is unused and MUST be empty" + }, + "name_definition": { + "case_sensitive": false, + "native_name": "name", + "note": "The OTP application name from the `.app` file; it is case-insensitive and MUST be lower-cased.", + "requirement": "required" + }, + "version_definition": { + "native_name": "version", + "note": "The OTP application version (the `vsn` attribute).", + "requirement": "optional" + }, + "subpath_definition": { + "case_sensitive": false, + "native_name": "May be added to reference a specific file or directory inside the OTP application.", + "requirement": "optional" + }, + "qualifiers_definition": [ + { + "key": "repository_url", + "requirement": "optional", + "native_name": "Repository URL", + "description": "The canonical origin of the OTP application source. This qualifier is optional, but it should be included whenever the origin is known, and should point to a trusted source repository." + }, + { + "key": "platform", + "requirement": "optional", + "native_name": "platform", + "description": "The target operating system for native code (e.g. ``linux``, ``darwin``, ``freebsd``, ``sunos``, ``win32``; case-insensitive)." + }, + { + "key": "arch", + "requirement": "optional", + "native_name": "arch", + "description": "The arch is the qualifiers key for a package architecture." + } + ], + "examples": [ + "pkg:otp/erts@10.6.3?platform=linux&arch=amd64&repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Ferlang%2Fotp.git", + "pkg:otp/stdlib@3.11.2?repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Ferlang%2Fotp.git", + "pkg:otp/crypto@4.6.4?platform=darwin&arch=x86_64&repository_url=https:%2F%2Fgithub.com%2Ferlang%2Fotp&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Ferlang%2Fotp.git", + "pkg:otp/elixir@1.10.0?repository_url=https:%2F%2Fgithub.com%2Felixir-lang%2Felixir&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Felixir-lang%2Felixir.git", + "pkg:otp/eex@1.10.0?repository_url=https:%2F%2Fgithub.com%2Felixir-lang%2Felixir&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Felixir-lang%2Felixir.git", + "pkg:otp/logger@1.10.0?repository_url=https:%2F%2Fgithub.com%2Felixir-lang%2Felixir&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Felixir-lang%2Felixir.git", + "pkg:otp/rebar@3.13.0?repository_url=https:%2F%2Fgithub.com%2Ferlang%2Frebar3&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Ferlang%2Frebar3.git", + "pkg:otp/hex@2.1.1?repository_url=https:%2F%2Fgithub.com%2Fhexpm%2Fhex&vcs_url=git%2Bhttps:%2F%2Fgithub.com%2Fhexpm%2Fhex.git" + ] +}