# `application`

This library provides the `application_common` category and the `application_protocol` protocol for declaring application metadata, including optional git-related facts such as repository URL, branch, commit, author, and commit message, plus optional package and archive identifiers. Application metadata is typically consumed by tools such as `sbom`.

The library distinguishes two kinds of information:

- release metadata, such as name, version, description, license, distribution location, package identifier, release date, and validity date

- optional source provenance metadata, such as repository URL, branch, commit, commit date, author, commit message, and archive identifiers

Source provenance predicates are explicit facts declared by the application. They are not a reflection of the current status of a local git checkout and should not be assumed to identify a released artifact unless the application author chooses to state them for that purpose.

## API documentation

Open the ../../apis/library_index.html#application link in a web browser.

## Loading

To load all entities in this library, load the `loader.lgt` file:

    | ?- logtalk_load(application(loader)).

## Testing

To test this library predicates, load the `tester.lgt` file:

    | ?- logtalk_load(application(tester)).

## Usage

Define an application metadata object importing the `application_common` category and declaring the metadata that is known explicitly. For example:

    :- object(my_application,
        imports(application_common)).

        name(my_application).
        version('1.2.3').
        description('Example application metadata object').
        license('Apache-2.0').
        homepage('https://example.com/my_application').
        distribution('https://example.com/my_application/releases/download/v1.2.3/my_application.tgz').
        package('pkg:generic/my_application@1.2.3').
        creators(['Tool: Build pipeline', 'Person: Alice']).
        supplier('Organization: Example Application').
        originator('Organization: Upstream Project').
        repository('https://example.com/my_application.git').
        repository_branch(main).
        repository_commit('0123456789abcdef0123456789abcdef01234567').
        git_object_identifier('gitoid:commit:sha1:0123456789abcdef0123456789abcdef01234567').
        software_heritage_identifier('swh:1:rev:0123456789abcdef0123456789abcdef01234567').
        repository_commit_author('Alice').

    :- end_object.

The library distinguishes between creators and originator using two predicates:

- `creators/1` identifies the people, organizations, or tools credited with creating the application or preparing its release metadata

- `originator/1` identifies the original source of the software when that is relevant and distinct from the creators

For example, an internal application might use the same party for both `creators/1` and `originator/1`. A packaged or redistributed application may use `creators/1` for the team or toolchain preparing the release metadata and `originator/1` for the original upstream source.

The imported category provides a default definition for the `loader_file/1` predicate and derived external references that use the same vocabulary as the corresponding first-class predicates:

- `external_reference(homepage, URL)` from `homepage/1`

- `external_reference(distribution, URL)` from `distribution/1`

- `external_reference(package, Identifier)` from `package/1`

- `external_reference(repository, URL)` from `repository/1`

- `external_reference(git_object_identifier, Identifier)` from `git_object_identifier/1`

- `external_reference(software_heritage_identifier, Identifier)` from `software_heritage_identifier/1`

The following predicates are intended to help tools such as `sbom` export stronger standardized references:

- `package/1` Stores an application package identifier as a PURL. This is distinct from `distribution/1`, which stores a download location URL. Tools such as `sbom` can use `package/1` to export a package identity reference instead of only a release download location. Example: `package('pkg:generic/my_application@1.2.3')`.

- `git_object_identifier/1` Stores a standardized Git object identifier as a gitoid. This is distinct from `repository_commit/1`, which stores the raw commit hash as provenance metadata. Tools such as `sbom` can use `git_object_identifier/1` to export a stronger provenance reference. Example: `git_object_identifier('gitoid:commit:sha1:0123456789abcdef0123456789abcdef01234567')`.

- `software_heritage_identifier/1` Stores a Software Heritage identifier (SWHID) for an archived release or revision. Tools such as `sbom` can use it to export a stable archived source provenance reference when one is known. Example: `software_heritage_identifier('swh:1:rev:0123456789abcdef0123456789abcdef01234567')`.

Git-related predicates are optional source provenance facts, not reflection over the current state of a local repository checkout.

Release-oriented metadata typically includes:

- `name/1`

- `version/1`

- `description/1`

- `license/1`

- `homepage/1`

- `distribution/1`

- `package/1`

- `creators/1`

- `supplier/1`

- `originator/1`

- `built_date/1`

- `release_date/1`

- `valid_until_date/1`

- `external_reference/2`

Optional source provenance metadata typically includes:

- `repository/1`

- `repository_branch/1`

- `repository_commit/1`

- `repository_commit_abbreviated/1`

- `repository_commit_date/1`

- `repository_commit_author/1`

- `repository_commit_message/1`

- `git_object_identifier/1`

- `software_heritage_identifier/1`