JET Pack Metadata

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01


Overview

As development teams become more familiar with JET and gain experience with implementing and packaging reusable bits of application functionality as custom JET Web Components, they encounter more complex use cases where multiple components have dependencies upon a set of shared development resources, including: related Components, JavaScript base and utility classes, CSS files, icons, translation bundles, etc.

The following JET component types can assist both JET Web Component producers and consumers with managing these complex use cases:

  • JET Component Packs, or JET Packs, define versioned sets of JET Web Components that can be managed, packaged, and delivered as a whole. JET Packs consist of metadata and additional artifacts that allow downstream consumers, such as Oracle Visual Builder or the JET Command Line interface, to automate the configuration and initialization of deployed applications that are built with these Components, including shared resources (e.g., CSS resources, utility JavaScript files, base JavaScript classes extended by multiple Web Components, etc.), and information about 3rd party packages.
  • JET Reference Components define a versioned external 3rd party library dependency – JET Packs, JET Resource Components, and individual JET Web Components can include a JET Reference Component as part of their dependencies metadata. JET Reference Components consist of metadata for automating the installation of the corresponding 3rd party library, as well as the necessary RequireJS configuration for calling into this 3rd party library from a deployed JET application.
  • JET Resource Components define and package resources shared by a set of JET Web Components – JET Packs, other JET Resource Components, and individual JET Web Components can include a JET Resource Component as part of their dependencies metadata. Shared resources can include shared CSS, JavaScript base classes & utility code, icons, translation bundles, etc.

Metadata Structure

Metatata for JET Packs, JET Reference Components, and JET Resource Components is specified in a component.json file that is expected at the root of the Component's packaging. Metadata properties like "name", "version", "jetVersion", "description", and "displayName" should be familiar from the metadata JSON that is defined for JET Web Components. The complete metadata structure for JET Packs, JET Reference Components, and JET Resource Components is as follows:

Key Required Type Description
name yes {string} The component name. The component name must meet the following requirements (based upon the W3C Custom Element spec):
  • The name can include only letters, digits, '-', and '_'.
  • The letters in the name should be all lowercase.
  • The name must start with a lowercase letter.
  • The name cannot be one of the following reserved names:
    • annotation-xml
    • color-profile
    • font-face
    • font-face-src
    • font-face-uri
    • font-face-format
    • font-face-name
    • missing-glyph
Note:
The full name of a component consists of its pack metadata value and its name metadata value, appended together with a hyphen separating them:  [pack_value]-[name_value]. For both JET Core Components and for JET Custom Components, this full name corresponds to the Component's custom element tag name. The names of standalone custom JET Web Components (i.e., custom components that are not members of a JET Pack, nor are JET Packs themselves) have the following additional requirements:
  • At least one hyphen is required.
  • The first segment (up to the first hyphen) is a namespace prefix. The namespace prefix 'oj' is reserved for components that are bundled with the JET release.
  • The first hyphen must be followed by at least one character.
version yes {string} The component version (following semantic version rules). Note that changes to the metadata even for minor updates like updating the jetVersion should result in at least a minor component version change, e.g. 1.0.0 -> 1.0.1.
jetVersion no {string} The semantic version of the supported JET version(s). JET Component authors should not specify a semantic version range that includes unreleased JET major versions as major releases may contain non backwards compatible changes. Authors should instead recertify components with each major release and update the metadata or release a new version that is compatible with the new release changes.

NOTE: Only valid for JET Packs and JET Resource Components.

bundles no {Object} Optional RequireJS-style bundles configuration metadata that applies to JET Packs and JET Reference Components:
  • JET Packs may contain bundles that consist of multiple AMD modules (for example, each component could be packaged as a separate module).
  • JET Reference Components may refer to 3rd party packages that include AMD-style bundles.
This configuration metadata allows RequireJS to map individual module names to the containing bundle.

The configuration object has the following properties:

Key Type Description
[bundle name] {Array<{string}>} An array of module names contained within the specified bundle.

Both the bundle names and the module names must correspond to paths that RequireJS is capable of loading. This typically means prefixing these names with a prefix that is known to be path-mapped, such as:
  • the pack name for JET Packs
  • some path that is specified by a JET Reference Component's paths metadata
Tools that consume JET Packs or JET Reference Components should merge the component.json bundles property into the application’s RequireJS config at build time, thus allowing the application to run against the bundled artifacts.

Example:
Assuming we have an “oj-foo” JET Pack that defines two bundles, the bundles property might be configured as follows:

 "bundles":
   {"oj-foo/some-bundle":
      ["oj-foo/component-one/loader", "oj-foo/component-two/loader"],
    "oj-foo/another-bundle":
      ["oj-foo/component-three/loader", "oj-foo/component-four/loader"],
   }
 
dependencies no {Object} Dependency to semantic version mapping for JET Component dependencies.
Example:
dependencies:  {"oj-foo-composite1": "1.2.0", "oj-foo-composite2": "2.1.0"}
Note:
  • Always use the full name of the component when declaring a dependency upon it.
  • JET Packs use their dependencies metadata to specify the exact semantic versions of the JET Custom Components, JET Reference Components, and JET Resource Components that constitute the JET Pack – consequently, semantic version ranges are not permitted in JET Packs.
  • JET Packs do not support nesting – in other words a JET Pack may not declare a dependency upon another JET Pack.
  • JET Reference Components and JET Resource Components may use semantic version range syntax to specify the range of versions that are acceptable to fulfill their dependency requirements.
description no {string} A high-level description for the component.
displayName no {string} A user friendly, translatable name of the component.
extension no {Object} Placeholder for Extension metadata. Each section is identified by a key that specifies the downstream tool that will process this metadata.
For example:
Name Type Description
vbdt {string} Indentifies an object with Visual Builder design time metadata

Please consult the documentation for the downstream tool to determine what (if any) extension metadata is supported.
license no {string} A reference to the license under which use of the component is granted. The value can be:
  • the name of the license text file packaged with the component
  • a URL to a remote license file
If unspecified, downstream consumers can look for a default, case-insensitive license file at the root of the component package.
pack no {string} Identifies the component as belonging to the specified JET Pack.

A JET Pack is a versioned set of JET Components with additional metadata that enables applications to easily install and configure path mappings to the artifacts in that JET Pack.

  • If specified, then there should exist a JET Pack whose name is the pack value, and which lists this component's full name in its dependencies metadata.
  • If unspecified, then this is a standalone JET Component that is not a member of any JET Pack.
  • JET Packs do not supported nesting and are therefore, by definition, standalone JET Components.

package no {string} This metadata property is only valid for JET Reference Components, where it is a REQUIRED property.

Specifies the name of the AMD-compatible npm package that is referenced by this component. This is needed to allow the consuming application to identify the 3rd party library, for conflict resolution purposes as well as for security scanning and patching.

paths no {Object | Array<{Object}>} Specifies path metadata that is used to generate RequireJS path mappings.

Each object is defined as follows:

Key Type Description
npm {Object} Specifies paths to use when configuring a path mapping to an npm package. This is only valid for JET Reference Components. At least one of the following sub-properties must be specified:
Key Type Description
min {string} Path to the optimized form of the library, relative to the root of the npm package.
debug {string} Path to the debug form of the library, relative to the root of the npm package.
cdn {Object} Specifies url-based paths to use when configuring a path mapping to a CDN-hosted artifact. It is strongly recommended that urls be specified with https:, as this is required for HTTP/2 and the consuming app may be configured to disallow non-secure urls. At least one of the following sub-properties must be specified:
Key Type Description
min {string} The full url to the location of the optimized form of the artifact.
debug {string} The full url to the location of the debug form of the artifact.
name {string} Optional value to use on the left hand side of the RequireJS path mapping when installing a JET Reference Component into an application. If not specified, then the name defaults to the value of the package property, excluding any scope.
Notes:
  • If the paths value is an array, then each array item is of the type described above. When an array is specified, each element must resolve to a unique value for the name property. (In practical terms, that means that only one element in the array can leverage the package property value for its default name value.)
  • In addition to its use for JET Reference Components, paths is also valid for JET Packs and JET Resource Components with the following restrictions:
    1. Only a single path mapping is allowed (in other words, the value cannot be an array);
    2. The name sub-property is ignored – the left hand side of the RequireJS path mapping always defaults to the JET Pack or JET Resource Component name property value;
    3. The npm sub-property is ignored – JET Packs and JET Resource Components can leverage the cdn sub-property to configure loading those artifacts at runtime from a CDN;
    4. The information in the paths property is ignored for JET Resource Components that are part of a JET Pack – only the JET Pack itself will be path mapped.
type no {"composite" | "core" | "pack" | "reference" | "resource"}

Default:  "composite"

Identifies the type of this JET Component.

Supported values are:

Value Description
composite Identifies the component as a custom JET Web Component, also known as a "Composite Component". This is the default, if type is unspecified.
core Identifies the component as a JET Web Component that is bundled with a particular version of JET.
pack Identifies the component as a JET Component Pack, or JET Pack. A JET Pack is a versioned set of JET Web Components with additional metadata that enables applications to easily install and configure path mappings to the artifacts in that JET Pack.

The dependencies metadata property is used to specify the versioned components that make up the JET Pack.

reference Identifies the component as a JET Reference Component, which describes a versioned external 3rd party library.

A JET Reference Component can be referenced in the dependencies metadata of a JET Pack, a JET Resource Component, or an individual JET Web Component.

resource Identifes the component as a JET Resource Component, which describes a versioned set of shared resources (such as shared CSS, JavaScript base classes & utility code, icons, translation bundles, etc.)

A JET Resource Component can be referenced in the dependencies metadata of a JET Pack, another JET Resource Component, or an individual JET Web Component.

Metadata for JET Web Components are described in more detail in the JET Metadata topic.