pkl-forge

Tooling to generate a pkl template from the Forge manifest JSON schema. This allows to verify and configure a dynamic Atlassian Forge manifest.pkl file.

Use the following command to generate the ManifestSchema.pkl template

npm run generate

Note

The published Forge manifest JSON schema has some discrepancies with the actual manifest definition. These are the currently known issues:

• Connect modules are defined under definitions.ModuleSchema.properties and are prefixed with connect- instead of being defined under definitions.ConnectModuleSchema.properties
• some Connect module definitions are missing, in particular Jira Service Desk modules

This script attempts to fix some these issues by moving Connect module definitions under the correct definition scope and back-fill missing module Connect definitions.

Reference

Converting any JSON Schema to pkl template:

pkl eval package://pkg.pkl-lang.org/pkl-pantry/org.json_schema.contrib@1.0.1#/generate.pkl -m . -p source="https://json.schemastore.org/github-action.json"

Refer to the instructions here: apple/pkl#92 (comment)

Converting a manifest.yml to manifest.pkl

Create a file called manifest-converter.pkl in the same folder as your manifest.yml file with the following content:

import "pkl:yaml"

file = read("file:manifest.yml")
parsed = new yaml.Parser {}.parse(file)

output {
  value = parsed
}

After that run the following command to convert the YAML file to a pkl file:

pkl eval manifest-converter.pkl > manifest.pkl

Refer to this issue comment for details.

Important

We noticed that the conversion output may not always be compatible with the generated ManifestSchema.pkl (we believe because the pkl conversion is missing some type information).

For example, the pkl manifest template generated by this code generates display condition params of pkl type Mapping<String, Any>. However, the manifest-converter.pkl shown above creates params as properties, when the type Mapping<String, Any> requires them to be entries. As a result, you have to update the output generated by manifest-converter.pkl and convert params to entries by wrapping the key into square brackets and quotes (key1 becomes ["key1"]).

We may be able to solve this with ideas explained in this comment.