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.

Tip

For your very first publish, consider doing a trial run against the staging index at https://test.sysand.com before publishing to the production index at https://sysand.com. There is no way to re-publish or overwrite an existing version: if something is wrong with the released package, the only recovery path is to yank the broken version and publish again under a new version number, which leaves a visible gap in the project’s release history.

Accounts, organizations, and API tokens are not shared between the two indices, 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

  • the sysand client installed (Install instructions)

  • 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 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:

  • 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 --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:

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

  • 404 Not Found: the publisher namespace does not exist

  • 409 Conflict: that version has already been published

  • 400 Bad Request: the metadata or .kpar archive failed validation

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