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.

Migrate from the Beta Index

This guide is for package maintainers who already publish to the old beta index at beta.sysand.org and need to move their packages to the new Sysand Index at sysand.com. The beta index will be taken down shortly after sysand.com goes live, so each package needs to be re-published with a few updates to .project.json and the package layout.

The new index introduces user and organization namespaces, a publisher field, a self-serve sysand publish command, and per-package pages. For a conceptual overview of what changed and why, see Project name and publisher fields and Index organizations.

Before You Start

You need:

If the package should live under a team or company namespace instead of your personal one, request that namespace first. See Create an organization.

Step 1: Set the publisher Field

The new index uses namespaces, and every package must declare which one it belongs to via a new publisher field in .project.json. The value must normalize to your username or to an organization name you can publish under; otherwise the upload is rejected.

From the project directory:

sysand info publisher --set <publisher>

<publisher> is the readable form of your username or organization name (for example, Sensmetry, not the display name). For the normalization rules and which characters are accepted, see Project identifiers.

Step 2: Review the name Field

The beta index turned name into an identifier by running it through HTML escaping, which made spaces become %20 and pushed authors to drop spaces entirely. The new index normalizes properly: lowercase letters and hyphens for spaces, with periods preserved.

You can now set name to its readable form (for example, "My Package") and the index will derive the identifier (my-package) automatically. If you previously squashed your package name to work around the old behaviour, this is a good time to restore the readable form.

See Project name and publisher fields for the conceptual model and Project identifiers for the exact rules.

Step 3: Rewrite Standard-Library Usages

The new index no longer hosts the SysML v2 standard library — the official KPAR files at omg.org are now readable by sysand directly. Replace any urn:kpar:*-library usage entries with the dated OMG URLs.

Drop the versionConstraint for these entries. The SysML v2 standard library does not follow Semantic Versioning, so the old ^1.0.0 / ^2.0.0 constraints were misleading. Pinning a dated URL is more honest about what the package depends on.

Replace this:

"usage": [
  { "resource": "urn:kpar:semantic-library", "versionConstraint": "^1.0.0" },
  { "resource": "urn:kpar:data-type-library", "versionConstraint": "^1.0.0" },
  { "resource": "urn:kpar:function-library", "versionConstraint": "^1.0.0" },
  { "resource": "urn:kpar:systems-library", "versionConstraint": "^2.0.0" },
  { "resource": "urn:kpar:analysis-library", "versionConstraint": "^2.0.0" },
  { "resource": "urn:kpar:cause-and-effect-library", "versionConstraint": "^2.0.0" },
  { "resource": "urn:kpar:geometry-library", "versionConstraint": "^2.0.0" },
  { "resource": "urn:kpar:metadata-library", "versionConstraint": "^2.0.0" },
  { "resource": "urn:kpar:quantities-and-units-library", "versionConstraint": "^2.0.0" },
  { "resource": "urn:kpar:requirement-derivation-library", "versionConstraint": "^2.0.0" }
]

with this:

"usage": [
  { "resource": "https://www.omg.org/spec/KerML/20250201/Data-Type-Library.kpar" },
  { "resource": "https://www.omg.org/spec/KerML/20250201/Semantic-Library.kpar" },
  { "resource": "https://www.omg.org/spec/KerML/20250201/Function-Library.kpar" },
  { "resource": "https://www.omg.org/spec/SysML/20250201/Systems-Library.kpar" },
  { "resource": "https://www.omg.org/spec/SysML/20250201/Analysis-Domain-Library.kpar" },
  { "resource": "https://www.omg.org/spec/SysML/20250201/Cause-and-Effect-Domain-Library.kpar" },
  { "resource": "https://www.omg.org/spec/SysML/20250201/Geometry-Domain-Library.kpar" },
  { "resource": "https://www.omg.org/spec/SysML/20250201/Metadata-Domain-Library.kpar" },
  { "resource": "https://www.omg.org/spec/SysML/20250201/Quantities-and-Units-Domain-Library.kpar" },
  { "resource": "https://www.omg.org/spec/SysML/20250201/Requirement-Derivation-Domain-Library.kpar" }
]

When a new SysML v2 release ships, update the 20250201 segment in each URL to the new release identifier from the OMG standard library URLs.

Step 4: Rewrite Third-Party Usages

Any usage entries that point at packages on beta.sysand.org also need to be updated. The old urn:kpar:<name> form is replaced by the namespaced pkg:sysand/<publisher>/<name> form.

Each third-party package needs to have been re-published to sysand.com first, typically with a version bump — so the constraint usually changes too. For example, a dependency on Sensmetry’s DETECT library changes from:

{ "resource": "urn:kpar:detect", "versionConstraint": "^1.2.0" }

to:

{ "resource": "pkg:sysand/sensmetry/detect", "versionConstraint": "^1.3.0" }

If a dependency you rely on has not been re-published yet, coordinate with that package’s maintainer before migrating.

Step 5: Bundle README, Changelog, and Licenses

The new index renders bundled README.md, CHANGELOG.md, and LICENSES/ contents on the per-package page. None of these were used on the beta index, so they are likely missing from your project. A bundled README.md matters most — it is the first thing visitors to the project page see, and the beta index never required one, so most migrating packages will need a new README written from scratch. Add or refresh each of these now:

The LICENSES/ folder must contain one .txt file per license listed in the license field of .project.json. The README.md and CHANGELOG.md files are optional but appreciated.

Step 6: Publish to the New Index

Once .project.json and the project files are updated, follow Publishing your first project to create an API token, configure the credential environment variables, and run sysand publish against https://sysand.com. For the exact command-line flags , see the sysand publish reference.

After publishing succeeds, the package is available at:

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

After Migrating