Project name and publisher Fields

Sysand projects carry two readable identity fields in .project.json: publisher says who publishes the project, and name says what the project is called within that publisher namespace. Together they become the stable project identifier used by Sysand Index, package URLs, release pages, and dependency references.

This page explains why the fields exist and how to think about them. For exact formats, regexes, examples, and upload metadata fields, see Project identifiers.

Two Names for Two Audiences¶

The .project.json fields are intentionally readable. A package can say:

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

That is a good form for metadata, import-oriented contexts, and human review. It preserves capitalization and word boundaries without requiring users to think in URL-safe strings while authoring project metadata.

Sysand Index also needs an identifier that is stable in URLs, command-line arguments, files, and package references. For the same project, the normalized identifier is:

sensmetry/fancy-stuff.teapots

The readable fields are the source of truth, and the normalized identifier is the index-safe form derived from them.

The Publisher Is the Namespace¶

The publisher field decides which Sysand Index namespace owns the project. That namespace can be a user account or an organization.

For an upload to be accepted, the publisher field must normalize to an existing namespace, and the upload token must be authorized for that namespace and project. For example, publisher: "Sensmetry" normalizes to sensmetry, so it can publish under the sensmetry organization only when that organization exists and the uploader has the right project permissions.

Use a personal username as the publisher for individual projects. Use an organization as the publisher when the project should belong to a team, company, working group, or other shared identity. See Index organizations for the organization model.

The Project Name Is Scoped by Publisher¶

The name field identifies the project within one publisher namespace. Two different publishers can use the same project name because the full project identity includes both parts.

For example, these are different projects:

sensmetry/fancy-stuff.teapots
alice/fancy-stuff.teapots

This keeps project names short and meaningful while avoiding a single global pool of package names.

Normalization Is Deliberately Small¶

Sysand Index normalization does only two things: it lowercases letters and turns spaces into hyphens. Periods in project names stay as periods.

That narrow rule matters because it is predictable. A user can look at Fancy Stuff.Teapots and know it becomes fancy-stuff.teapots; there is no hidden transliteration, punctuation rewrite, or case-sensitive distinction.

The exact accepted characters are still constrained so the normalized form is usable in URLs, package URLs, command-line arguments, and filesystem paths. The technical constraints are listed in Project identifiers.

Why Case Does Not Distinguish Projects¶

Project identity is case-insensitive because case-sensitive package identity is easy to misread and hard to use consistently across tools. It also behaves poorly on filesystems where case distinctions are not reliable.

Lowercasing avoids treating Sensmetry/Fancy-Model and sensmetry/fancy-model as different projects. It also makes copied identifiers and dependency references more durable across shells, URLs, and generated files.

Why Spaces Become Hyphens¶

Spaces are useful in readable metadata but awkward in identifiers. They often need quoting in commands and percent-encoding in URLs.

Replacing spaces with hyphens keeps the authored metadata readable while making the derived project ID easier to copy, type, and embed:

Fancy Stuff.Teapots -> fancy-stuff.teapots

Hyphens also avoid switching between Fancy%20Stuff.Teapots, Fancy Stuff.Teapots, and shell-quoted variants of the same value.

Where Each Form Appears¶

Use the readable .project.json publisher and name fields when describing package metadata to humans:

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

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

sensmetry/fancy-stuff.teapots
pkg:sysand/sensmetry/fancy-stuff.teapots

The official Sysand Index requires uploads to provide publisher and name fields that yield this Sysand project ID. General sysand tooling may still encounter legacy project IDs for packages that cannot provide one; those are outside the normal publishing path for the official index.