Publishing your first project#

This tutorial walks through publishing one SysML v2 or KerML project to Sysand Index for the first time. You will choose a publisher namespace, prepare the package metadata, create an API token, publish the release with the sysand client, and verify that the release is visible on the index.

For detailed sysand command-line usage, see the Sysand client documentation. This tutorial focuses on the Sysand Index concepts and checks that matter during a first publication.

Tip

For your very first publish, consider doing a trial run against the test index at https://test.sysand.com before publishing to the production index at https://sysand.com. There is no way to re-publish, overwrite, or remove a version once it is uploaded: if something is wrong with the released package, the only recovery path is to publish a fixed release under a new version number.

Accounts, organizations, and API tokens are not shared between the two indexes, so a trial run requires registering on test.sysand.com and creating a token there. The rest of this tutorial works the same way against either host — substitute test.sysand.com for sysand.com everywhere when you’re doing the trial run.

Before you start#

You need:

  • a Sysand Index account (sign up)

  • the sysand client installed and working (Installation, First steps)

  • a SysML v2 or KerML project that can be packaged as a .kpar archive

  • a license that you are allowed to publish with the project

You also need a publisher namespace. For a first personal project, use your Sysand Index username. For a team-owned project, use an organization namespace. If the organization does not exist yet, create it before publishing. See Create an organization.

Choose the project identity#

Every published project has a Sysand project ID:

<publisher-id>/<name-id>

For example:

alice/teapot-models

The publisher ID comes from your username or organization name. The name ID comes from the project name field after normalization.

For this tutorial, the examples use:

alice/teapot-models

Replace alice with your own username or organization name, and replace teapot-models with your project name.

Check .project.json#

Your project package must include a .project.json file at the archive root. At minimum for Sysand Index publishing, it needs a publisher and a name that follow the naming rules, a version, and a valid SPDX license expression.

Example:

{
  "publisher": "Alice",
  "name": "Teapot Models",
  "version": "0.1.0",
  "license": "MIT"
}

publisher: "Alice" normalizes to alice, and name: "Teapot Models" normalizes to teapot-models. During upload, Sysand Index checks that those normalized values match the upload metadata sent by the sysand client.

For the full naming rules, see Project identifiers. For the conceptual model, see Project name and publisher fields.

Include required package files#

The .kpar archive uploaded to Sysand Index must contain the files needed for index validation. A small project typically has this shape:

project-root/
  .project.json
  .meta.json
  README.md
  CHANGELOG.md
  LICENSES/
    MIT.txt
  model.sysml

README.md and CHANGELOG.md are technically optional, but in practice the README is what most visitors read first when deciding whether to depend on your project. Plan to bundle one that explains how to get started with the package, walks through how it is structured, and shares anything else users should know — see Bundle a README for what to include and a few writing tips.

License text files are required for the license identifiers used by .project.json.

The .meta.json file records the project metamodel and source file checksums. The sysand client generates and maintains it as part of its packaging workflow — Creating your first project covers the exact command sequence.

Before publishing, compare your archive with KPAR archive validation. Most first publish failures come from one of these issues:

  • the publisher or name does not normalize to the expected project ID

  • the publisher namespace does not exist on Sysand Index

  • the license expression and LICENSES/ files do not match

  • .meta.json is missing files, checksums, or a supported metamodel IRI

  • the archive contains extra files that Sysand Index does not accept

Build the KPAR archive#

Before publishing, build the .kpar archive from your project directory:

$ sysand build
    Building kpar `/home/alice/teapot-models/output/Teapot_Models-0.1.0.kpar`

The .kpar file is written to the output/ directory inside the project directory, named <name>-<version>.kpar using the name field from .project.json with characters such as spaces and hyphens replaced by underscores. Now it’s time to publish the generated archive.

Create an account API token#

For the first release of a new project, use an account API token. Account tokens can create a new project when your account is allowed to publish under the selected namespace.

Follow Create an API token and choose an account token, not a project token. Configure the sysand client environment variables with that account token, then return here when the token is configured.

Publish the release#

From your project directory, run

$ sysand publish --index https://sysand.com

Sysand will by default use the .kpar archive you just built. If you want to publish a different archive, give the path to it:

$ sysand publish --index https://sysand.com /path/to/project.kpar

The client authenticates with the token configured in your environment, and uploads the given .kpar archive to Sysand Index. On success, the command exits without an error message.

If the project does not exist yet, Sysand Index creates it during the first successful upload and makes you a project owner. Later releases of the same project require owner or maintainer access, and each version can be published only once.

For more information, see the sysand publish reference.

Verify the published project#

After publishing succeeds, open the project page on the index you published to:

https://sysand.com/projects/<publisher-id>/<name-id>/

For the example project:

https://sysand.com/projects/alice/teapot-models/

https://test.sysand.com/projects/<publisher-id>/<name-id>/

For the example project:

https://test.sysand.com/projects/alice/teapot-models/

Check that:

  • the project page loads

  • the version is the one you intended to publish

  • the README, changelog, license, and usage information render as expected

  • the publisher namespace is correct

The project also appears in the public index consumed by the sysand client.

If publishing fails#

Use the error category to narrow the problem:

  • 401 Unauthorized: the token is missing, expired, or copied incorrectly

  • 403 Forbidden: the token is valid but does not have permission for the namespace or project

  • 409 Conflict: that version has already been published

  • 400 Bad Request: the metadata or .kpar archive failed validation, or the publisher namespace does not exist on the index

For 400 Bad Request, start with KPAR archive validation and Project identifiers. For permission issues on organization projects, see Index organizations.