Project Identifiers

Sysand Index identifies published projects by a normalized publisher ID and a normalized project name ID. Source package metadata can use readable publisher and name fields, but the index stores, authorizes, and serves their normalized identifier forms.

This page is the technical reference for Sysand project identifier fields, normalization, and related URL and PURL forms. For the conceptual model behind these rules, see Project name and publisher fields.

Identifier Vocabulary¶

• Publisher field The .project.json publisher string, such as Sensmetry. It is a human-readable source field that must normalize to a publisher ID for Sysand Index uploads.

• Name field The .project.json name string, such as Fancy Stuff.Teapots. It is a human-readable source field that must normalize to a name ID for Sysand Index uploads.

• Publisher ID The normalized publisher field, such as sensmetry. It is a lowercase index namespace ID and must be an existing Sysand Index user or organization namespace for uploads.

• Name ID The normalized name field, such as fancy-stuff.teapots. It is the lowercase project name ID under a publisher namespace.

• Sysand project ID The <publisher-id>/<name-id> form, such as sensmetry/fancy-stuff.teapots. This is the canonical project identifier form used by Sysand Index.

• Sysand PURL The pkg:sysand/<sysand-project-id> form, such as pkg:sysand/sensmetry/fancy-stuff.teapots. This package URL form is used for Sysand package usages.

.project.json Fields¶

Uploaded packages include publisher and name fields in .project.json. Both fields are required for Sysand Index uploads and must be strings.

The name field is slightly more permissive than publisher: project names may contain periods, while publisher names may not.

For both fields:

• the first and last character must be a letter or digit

• separator characters must appear between letters or digits

• repeated separators such as --, .., -., or two spaces are not valid

Examples:

Regular expressions:

publisher field: ^[a-zA-Z0-9](?:[a-zA-Z0-9]|[- ](?=[a-zA-Z0-9])){1,48}[a-zA-Z0-9]$
name field:      ^[a-zA-Z0-9](?:[a-zA-Z0-9]|[-. ](?=[a-zA-Z0-9])){1,48}[a-zA-Z0-9]$

Normalized Identifiers¶

Sysand Index and the upload API use normalized identifier fields. These are also the publisher-id and name-id components of a Sysand project ID.

Examples:

The normalized values must also match the index identifier rules:

Regular expressions:

publisher ID: ^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){1,48}[a-z0-9]$
name ID:      ^[a-z0-9](?:[a-z0-9]|[.-](?=[a-z0-9])){1,48}[a-z0-9]$

During upload, Sysand Index rejects a package if:

• the upload metadata omits normalized_publisher or normalized_name

• either normalized value has an invalid format

• .project.json publisher does not normalize to normalized_publisher

• .project.json name does not normalize to normalized_name

Sysand Project IDs¶

A Sysand project ID combines the normalized publisher ID and name ID:

<publisher-id>/<name-id>

Example:

sensmetry/fancy-stuff.teapots

Use the Sysand project ID when referring to a Sysand Index package in index URLs, pkg:sysand usage resources, and upload metadata.

Publisher Namespace Requirements¶

The normalized publisher must map to an existing Sysand Index namespace. A namespace is either a username or an organization name.

For example, a package with this .project.json metadata:

{
  "publisher": "Sensmetry",
  "name": "Fancy Stuff.Teapots"
}

uploads under the normalized project identifier:

sensmetry/fancy-stuff.teapots

The upload is accepted only if sensmetry exists on Sysand Index as a user or organization namespace, and the upload token is authorized for that namespace and project.

Upload Metadata Fields¶

The upload API receives the normalized identifiers separately from the archive:

{
  "normalized_publisher": "sensmetry",
  "normalized_name": "fancy-stuff.teapots",
  "version": "1.2.3",
  "license": "MIT",
  "kpar_sha256_digest": "..."
}

The .kpar archive must contain a root .project.json file whose publisher and name fields normalize to the submitted normalized_publisher and normalized_name values.

Usage Identifiers¶

Usage entries in .project.json use IRI resources to identify how a dependency can be acquired. A Sysand package usage uses the Sysand PURL form:

pkg:sysand/<sysand-project-id>

Example:

pkg:sysand/sensmetry/fancy-stuff.teapots

For Sysand Index uploads, usage resources must reference either a current-index project with the Sysand PURL form or an OMG standard library .kpar URL such as https://www.omg.org/spec/SysML/20250201/Systems-Library.kpar. Other IRI schemes may be useful to general sysand tooling, but they are not accepted by the official index upload API.

Common Forms¶

The same publisher and project name appear in a few related forms: