id.exergism.org

Persistent identifier infrastructure for Exergism Commons.

Public identifier authority: https://id.exergism.org/

This repository contains both the static bootstrap surface currently usable with GitHub Pages and a small native HTTP resolver for production deployment. Public identifiers are deliberately independent of this repository name, GitHub Pages, the VPS provider, and the TLS frontend.

Resolver architecture

The production resolver is a dependency-free Go service driven by resolver/registry.json.

It provides exact canonical paths, HTTP Accept content negotiation, accurate Content-Type, 406 Not Acceptable for unpublished representations, Vary: Accept, canonical/alternate Link headers, ETags/304 responses, GET/HEAD semantics, and explicit redirects only for registered aliases.

The resolver does not generate ontology semantics. It serves representations already produced and approved by the canonical owning repository. For Commons/Governance, CI additionally proves that the current and versioned Turtle bytes match the pinned Governance source commit exactly.

Run locally

go run ./cmd/idresolver -listen 127.0.0.1:8080 -root . -registry resolver/registry.json

Examples:

curl -i -H 'Accept: text/html' http://127.0.0.1:8080/commons
curl -i -H 'Accept: text/turtle' http://127.0.0.1:8080/commons
curl -i -H 'Accept: text/turtle' http://127.0.0.1:8080/ontology/governance/0.1-PRE2
curl -i -H 'Accept: application/json' http://127.0.0.1:8080/catalog/namespaces

Namespace registry and semantic discovery

Three separate machine-readable layers deliberately have different authority:

• resolver/registry.json defines HTTP dereferencing and representation routing;
• catalog/namespaces.json records namespace ownership/adoption and authoritative source locations;
• catalog/terms.json is a generated discovery projection and does not define term semantics.

Commons and Governance are adopted from Exergism-Commons/governance. Funding remains migrating until its owning normalization and resolver publication are adopted. Exergism and ECL remain migrating from their legacy identifier schemes.

The Commons/Governance term catalog is deterministically generated by tools/generate_term_catalog.py from provenance-bound owner-authored Turtle. CI fails if the committed projection drifts from those bytes.

Build and dependency policy

The resolver intentionally has no external Go module dependencies: it uses the Go standard library plus repository-local code only.

The module targets the current stable Go language line (go 1.27.0, with the reviewed toolchain declared in go.mod). GitHub Actions run tests and vetting and build statically linked Linux binaries for amd64 and arm64. Runtime releases publish the binaries together with an authoritative DEPLOYMENT_MANIFEST.json binding the exact source commit to architecture-specific runtime SHA-256 values. SHA256SUMS, SOURCE_COMMIT and build metadata remain compatibility/diagnostic artifacts. Production hosts therefore do not need a Go toolchain and do not compile source code.

Pushes to main publish the rolling runtime-main prerelease channel. Version tags matching v* publish versioned release assets suitable for immutable deployment. The DigitalOcean bootstrap verifies the selected binary and ensures the repository state containing the registry and representations matches the exact recorded source commit before starting the service.

GitHub Actions are pinned to reviewed release commits and Dependabot watches the workflow dependencies for stable updates. See THIRD_PARTY_NOTICES.md for the reviewed redistribution surface.

Minimal VPS deployment

A 512 MB VPS is sufficient for this service because build work happens in GitHub Actions rather than on the production host. The intended deployment is:

GitHub Actions -> verified runtime release
                         |
                         v
Internet -> TLS frontend -> idresolver (127.0.0.1:8080) -> release-matched representations

deploy/Caddyfile is deliberately tiny: Caddy terminates HTTPS and proxies bytes. All semantic routing and MIME negotiation belongs to idresolver.

A hardened systemd unit, deploy/setup-digitalocean.sh initial-host bootstrap and version-pinned deploy/install-deployment-attestation.sh handoff are included. The initial bootstrap captures the resolver release manifest, verifies the prebuilt resolver, checks out the matching source revision, installs Caddy/systemd and runs local smoke tests. The handoff script installs a reviewed deployment-attestation release through its digest-verified trusted-stage flow. After that handoff, the agent owns routine deployment, rollback/recovery and health checks; the initial bootstrap is not used as the normal updater. No database, Docker runtime, Java service, Go toolchain or application framework is required on the Droplet.

See deploy/README.md for the release and deployment contract.

Reserved identifier surfaces

Adopted organization vocabularies:

• Commons: https://id.exergism.org/commons#
• Governance: https://id.exergism.org/governance#

Migrating/reserved project vocabularies:

• Exergism: https://id.exergism.org/exergism#
• ECL: https://id.exergism.org/ecl#
• Funding: https://id.exergism.org/funding#

Current ontology IRIs include:

• https://id.exergism.org/ontology/commons
• https://id.exergism.org/ontology/governance
• https://id.exergism.org/ontology/exergism
• https://id.exergism.org/ontology/ecl
• https://id.exergism.org/ontology/funding

Owner-authored immutable Commons/Governance version IRIs currently published by this branch are:

• https://id.exergism.org/ontology/commons/0.1-PRE2
• https://id.exergism.org/ontology/governance/0.1-PRE2

The current Governance downstream authority profile is:

• https://id.exergism.org/governance/profile/0.1-DRAFT

Funding governance records use:

• https://id.exergism.org/funding/id/{stableId}

A cross-project entity family remains reserved for future specification:

• https://id.exergism.org/entity/...

See PERSISTENCE.md before minting new identifiers.

Migration boundary

id.exergism.org is the intended persistent identifier authority for EC's semantic projects, but namespace adoption remains project-controlled:

• Commons/Governance are owned and versioned by Exergism-Commons/governance; this resolver publishes their reviewed representations byte-for-byte.
• Exergism must migrate from http://www.exergia.org/ns/ through a canonical release.
• ECL must migrate from urn:ecl: through a canonical release.
• Funding remains migrating until the owning Funding normalization lands and a separate resolver publication is pinned to the actual adopted Funding commit.

Historical versioned artifacts are not silently rewritten. Compatibility mappings are published only where useful and semantically safe.

Publication and persistence boundary

Mutable “current” ontology IRIs and immutable owl:versionIRI resources are separate. Immutable routes are history-guarded: once published, their metadata/bytes cannot be silently changed in later Git transitions.

A cross-repository publication is not considered complete merely because a PR merged. The relevant resolver route must also be deployed and smoke-tested before a downstream repository relies on it operationally.

The service root additionally exposes a JSON-LD description of the identifier service itself.

Authority boundary

This repository resolves identifiers. It does not become the canonical source of ontology semantics, institutional authority, ECL legal artifacts or Funding decisions merely because those resources use identifiers under this host.

Project-specific authority remains with the repository and adopted process that owns the relevant layer. Organization-level governance controls the persistence contract and stewardship of the identifier authority.

Terms and redistribution

A short-form resolver EULA is available at EULA.md. It does not override third-party licences or project-specific terms. Third-party and redistribution notices are recorded in THIRD_PARTY_NOTICES.md, with required licence texts under LICENSES/.

The current Governance and Funding source repositories do not expose root licences granting general third-party redistribution rights for their semantic content. EC-controlled resolver publication is therefore documented separately from any broader redistribution grant; see THIRD_PARTY_NOTICES.md.