README.md

Corporate Memory Package Template

A Copier template for creating eccenca Corporate Memory (Marketplace) packages.

Prerequisites

• Python 3.10+
• Copier >= 9.0.0: pip install copier or uv tool install copier

Usage

Create a new package directory from this template:

# create a new directory with the latest release of the template
copier copy gh:eccenca/cmem-package-template your-new-vocabulary-package

# create a new directory with the latest develop snapshot of the template
copier copy -r develop gh:eccenca/cmem-package-template your-new-vocabulary-package

Template Variables

Variable	Description	Default
package_type	Type: vocabulary, project	vocabulary
package_id	Package ID (lowercase, hyphens allowed)	-
package_name	Human-readable name	-
package_description	Short description	-
python_dependencies	Comma-separated Python package dependencies	-
vocab_dependencies	Comma-separated vocabulary/project dependencies	-
github_page	Link to GitHub page of the package	-

Generated Structure

your-new-vocabulary-package/
├── .copier-answers.env
├── .copier-answers.yml
├── .gitignore
├── .gitlab-ci.yml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── DOCUMENTATION.md   (shipped with the package, shown in the marketplace)
├── LICENSE
├── README.md          (for the package maintainer, not shipped)
├── Taskfile.yaml
└── {package_id}/
    ├── README.md      (link to ../DOCUMENTATION.md)
    ├── LICENSE        (link to ../LICENSE)
    ├── CHANGELOG.md   (link to ../CHANGELOG.md)
    ├── example.ttl
    └── cpa-manifest.json

The default license we add is Apache License 2.0 (Apache-2.0), see https://spdx.org/licenses/ if you need a different.

Development Tasks

After generating the package, use Task to run common operations:

task              # List available tasks
task build        # Build package archive
task check        # Run test suite
task import       # Import package to Corporate Memory
task export       # Export package from Corporate Memory
task publish      # Publish to marketplace

Package Manifest

Packages describe themselves in the cpa-manifest.json file. Some metadata has been asked during the copier process. Further metadata can be added to the cpa-manifest.json file:

Metadata

• comment: A maintainer or publisher comment - not processed or shown to users. A simple string:

  "comment": "This is a comment left by the package maintainer.",

Agents

• agents: List of person and organizations. An array of agent objects,

  • valid values for agent_type are
    • person and
    • organization,
  • valid values for agent_role are
    • publisher,
    • maintainer or
    • author.

  "agents": [
      {
          "agent_type": "organization",
          "agent_role": "publisher",
          "agent_name": "eccenca GmbH",
          "agent_email": "info@eccenca.com",
          "agent_url": "https://eccenca.com"
      },
      {
          "agent_type": "person",
          "agent_role": "maintainer",
          "agent_name": "John Doe",
          "agent_email": "john.doe@example.com",
          "agent_url": "https://example.com"
      }
  ]

URLs

• urls: List of package URLs. An array of URL objects,

  • valid values for url_role are:
    • homepage,
    • source,
    • documentation and
    • issues.

  "urls": [
      {
          "url_ref": "https://documentation.eccenca.com",
          "url_role": "documentation"
      },
      {
          "url_ref": "https://eccenca.com",
          "url_role": "homepage"
      },
      {
          "url_ref": "https://github.com/eccenca/cmem-package-template",
          "url_role": "source"
      },
      {
          "url_ref": "https://github.com/eccenca/cmem-package-template/issues",
          "url_role": "issues"
    }
  ]

Tags

• tags: List of package tags. An array of strings:

  "tags": [
      "example",
      "template",
      "eccenca"
  ]

Adding files

Add files (package contents) by copying or linking those into the package folder (or respective sub-folder) and referencing them in the files section.

Graphs

The following adds a graph. register_as_vocabulary and import_into are optional instructions. We suggest to organize graphs in a respective sub-folder (here graphs/), but this is up to you:

"files": [
    …
    {
        "file_type": "graph",
        "file_path": "graphs/file.ttl",
        "graph_iri": "http://www.example.org/file/",
        "register_as_vocabulary": true,
        "import_into": [
            "http://www.example.org/integration_graph/"
        ]
    },
    …
]

Note:

When using register_as_vocabulary, ensure that your graph contains an ontology declaration (owl:Ontology) and the corresponding VANN namespace metadata. In particular, the ontology resource should define both vann:preferredNamespacePrefix and vann:preferredNamespaceUri.

Example:

@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix vann: <http://purl.org/vocab/vann/> .

<http://www.example.org/file/> a owl:Ontology ;
    vann:preferredNamespacePrefix "ex" ;
    vann:preferredNamespaceUri "http://www.example.org/file/" .

The ontology resource carries the same IRI as the graph_iri of the file entry above. These annotations allow the vocabulary to be registered correctly and provide consumers with the preferred namespace URI and prefix associated with the ontology.

Projects

The following adds a project. We suggest to organize projects in a respective sub-folder (here projects/), but this is up to you:

"files": [
    …
    {
        "file_type": "project",
        "file_path": "projects/product-integration-demo.zip",
        "project_id": "product-integration-demo"
    },
    …
]

Icons and Images

The following adds an image and/or icon:

"files": [
    …
    {
        "file_path": "periodic-table.png",
        "file_type": "image",
        "file_role": "marketplace"
    },
    {
        "file_path": "icon.png",
        "file_type": "image",
        "file_role": "icon"
    },
    …
]