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.

Field	Allowed characters	Length
`publisher`	ASCII letters, digits, spaces, and hyphens	3-50 characters
`name`	ASCII letters, digits, spaces, hyphens, and periods	3-50 characters

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:

Field	Valid examples	Invalid examples
`publisher`	`Sensmetry`, `ACME Systems`, `Team-42`	`acme.systems`, `-acme`, `acme--systems`
`name`	`Fancy Stuff.Teapots`, `sysml-utils`, `Core 2`	`.core`, `core..model`, `core_2`

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.

Identifier	Source field	Normalization
`normalized_publisher`	`.project.json` `publisher`	lowercase, then replace spaces with hyphens
`normalized_name`	`.project.json` `name`	lowercase, then replace spaces with hyphens; periods stay periods

Examples:

`.project.json` field	Normalized value
`publisher: "Sensmetry"`	`sensmetry`
`publisher: "ACME Systems"`	`acme-systems`
`name: "Fancy Stuff.Teapots"`	`fancy-stuff.teapots`

The normalized values must also match the index identifier rules:

Identifier	Allowed characters
`normalized_publisher`	lowercase letters, digits, and single hyphens
`normalized_name`	lowercase letters, digits, single hyphens, and single periods

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>