Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

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, use the Sysand client documentation. This tutorial focuses on the Sysand Index concepts and checks that matter during a first publication.

Before You Start

You need:

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 readable publisher, a readable name, 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 can generate package metadata as part of its packaging workflow; use the client documentation for the exact command sequence.

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

Build the KPAR Archive

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

sysand build --update-meta

The --update-meta option refreshes .meta.json while building, including the SHA256 checksum values Sysand Index validates during upload. Without it, the archive can contain placeholder or stale checksum values and publishing may fail with a confusing error such as:

error: bad request: checksum['detect_criteria_list.sysml'].value must be a SHA256 hex digest in .meta.json

After the build finishes, publish the generated .kpar file in the next step.

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 with the .kpar archive you built in the previous step. For command flags and exact usage, see the sysand publish reference.

The client sends the .kpar archive and normalized metadata to Sysand Index, and authenticates with the token configured in your environment.

When 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.

Verify the Published Project

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

Live package index
Test package index
https://sysand.com/projects/<publisher-id>/<name-id>/

For the example project:

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

Check that:

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

If Publishing Fails

Use the error category to narrow the problem:

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