# Pentaho web package

Pentaho detects and manages [OSGi](https://www.osgi.org/) bundles that contain Pentaho web packages, collecting the information needed to build the AMD/RequireJS configuration and to set up the mappings needed to serve the package resources through HTTP. A package is described by a `package.json` file, based upon the [package.json spec](https://docs.npmjs.com/files/package.json) and is mostly compatible with files generated by the [npm](https://www.npmjs.com/) tool.

You create a web package to define your configurations and mappings through the following supported fields:

* `name` and `version`
* `paths`
* `dependencies`
* `config`

## The name and version fields

You must specify the `name` and `version` fields. These fields are the most important in the `package.json` file. The package will not install without these fields.

These fields must adhere to the following rules:

* The `name` must be shorter than 214 characters, including the scope, for scoped packages.
* The `name` cannot start with a dot or an underscore.
* The `name` should not have uppercase letters.
* The `name` will end up being part of an URL. You must avoid any non-URL-safe characters, except forward-slashes (`/`) are permitted.
* The `version` must follow the Semantic Versioning Specification (<http://semver.org/>).

The `name` and `version` fields together form a unique system identifier for the package. This unique system identifier is used internally as the base AMD/RequireJS module identifier and as part of the HTTP location where the resources are served.

### Example

The following lines of code are an example of specifying the mandatory `name` and `version` fields:

```json
{
  "name": "my-viz-lib",
  "version": "1.0.0"
}

```

You can specify an organization in the `name` field, as shown in the following sample lines of code:

```json
{
  "name": "@my-org/viz-lib",
  "version": "1.0.0"
}

```

## The paths field

You can use the `paths` field to expose the resources of a given package path under a base module identifier.

If you do not specify a value for the `paths` field, the package name is used to map the package’s root path, as if, you specified the package name for the path, as shown in the following example:

```json
{
  "name": "@my-org/viz-lib",
  "version": "1.0.0",
  "paths": {
    "@my-org/viz-lib": "/"
  }
}

```

You would normally specify scoped and hyphenated package name, yet the AMD module identifiers are also valid JavaScript identifiers. For this case, you would explicitly specify a root module, as shown in the following example:

```json
{
  "name": "@my-org/viz-lib",
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  }
}

```

## The dependencies field

You can use the `dependencies` field to map a package name to a version range in a simple object. The version range is a string that has one or more space-separated descriptors, as shown in the following example:

```json
{
  "name": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "dependencies": { 
    "bar": "~2.0" 
  }
}

```

See <https://github.com/npm/node-semver#ranges> for the definitions of available space-separated descriptors.

The `dependencies` field is used by Pentaho to determine the dependency tree, resolve runtime dependencies, and build the proper AMD/RequireJS mappings to allow each package to request external modules that satisfy the dependencies’ version restrictions.

For instance, in the above example, the code in the `@my-org/viz-lib` package can use modules from the `bar` dependency without the knowledge that it is available at a path such as `/bar@2.1.4/foo`.

### Unsupported identifiers

Only version ranges are supported. You cannot use the following identifiers:

* Local paths
* URLs
* Git URLs
* GitHub short URLs

## The config field

You set the `config` field to the module identifier listed your configuration object that is made available to AMD/RequireJS modules that match. Modules with a matching identifier can access the configuration object via `module.config`. You use this object to configure the `pentaho/modules` module, which is a basic inversion-of-control mechanism to inject the package resources into the system.

For example, to declare that the JavaScript module package in `config.js` exports a value that is an instance of the `pentaho/config/spec/IRuleSet` type, you would use the following sample lines of code:

```json
{ 
  "name": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "config": {
    "pentaho/modules": {
      "myOrg/visual/config": {"type": "pentaho/config/spec/IRuleSet"}
    }
  }
}

```

You can also use the `config` field to declare that a type (such as that exported by the JavaScript module in `Model.js`) is a subtype of the visualization base type, `pentaho/visual/Model`, as shown in the following example:

```json
{ 
  "name": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "config": {
    "pentaho/modules": {
      "myOrg/visual/Model": {"base": "pentaho/visual/Model"}
    }
  }
}

```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pentaho.com/pdia-admin/pentaho-developer-center-overview-cp/platform-javascript-apis/pentaho-web-package-visapi-cp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.