Publisher Integration Guide

Give each item a short, verifiable, version-aware NOBLEID that keeps readers on the latest

Goal

Give each item (article/dataset/software) a short, verifiable, version-aware NOBLEID that you can display on your pages, while your readers stay on the latest.

Root (latest): ark:/nobleid/20092025/7X9K2Q → https://nobleid.org/20092025/7X9K2Q

Pinned: ark:/nobleid/20092025/7X9K2Q:v2 → https://nobleid.org/20092025/7X9K2Q:v2

A) One-time setup (30–60 min)

1. Request API key

For your journal/repository account.

2. Verify domain

DNS TXT to unlock higher quotas and "verified publisher" badge.

3. Add the Update-Checker widget

To your article template:

<!-- In the article template, near the title or metadata block -->
<script
  src="https://cdn.nobleid.org/widget.js"
  data-ark="ark:/nobleid/20092025/7X9K2Q"      <!-- replace per item -->
  data-style="badge"                            <!-- badge | inline -->
  defer
  integrity="<!-- SRI hash here -->"
  crossorigin="anonymous"></script>

The widget calls /check-update?ark=... and shows "Up to date" or "New version available".

4. Decide your metadata source

Your internal JSON → map to our fields, or provide a DOI to import.

B) Per-item flow

1. Create the record in your CMS

(title, authors, abstract, type, file URL)

2. Mint a NOBLEID (server-side):

POST /api/v1/nobleid/generate
{
  "title": "My Journal Article",
  "authors": ["A. Author","B. Author"],
  "type": "paper",
  "abstract": "Short abstract",
  "contentUrl": "https://yourjournal.org/articles/123.pdf",
  "externalUrls": ["https://yourjournal.org/articles/123"]
}

→ store root_id, root_ark, version_pid, resolve_url.

3. Render on article page

Display NOBLEID (short link + ARK)
Add Update-Checker script (data-ark set to the root ARK)
Include JSON-LD (ScholarlyArticle/Dataset) with identifier, sameAs, isBasedOn
Provide Citations (BibTeX/RIS/CSL-JSON links can point to resolver)

4. Go live

Optional: ping sitemap / OAI-PMH harvesters

When you update content (correction/new data)

POST /api/v1/nobleid/work/example_root_id/versions
{ "change_notes": "Corrigendum: data table updated" }

→ get ...:v2. Your page shows "New version available" via the widget within the cache window.

C) Checklist (ready to ship)

Metadata mapping

Title, authors (names + ORCID optional), abstract, type
Your canonical URL included in externalUrls
License, language, keywords (if available)

Page template

NOBLEID short link + ARK visible
JSON-LD includes identifier[], sameAs, isBasedOn
Update-Checker embedded with correct data-ark
"Cite" links (resolver endpoints for CSL-JSON, BibTeX, RIS)

Back-office

API key stored securely; retries/idempotency on mint
Store root_id & version_pid in your CMS
On edits, call create version (don't overwrite v1)

Quality

JSON-LD passes Google structured-data tests
Resolver page loads < 200 ms cached; widget SRI verified
A test item shows "Up to date" → on v2 publish shows "New version"

D) API quick refs

Mint: POST /api/v1/nobleid/generate → returns root_ark, version_pid, URLs

New version: POST /api/v1/nobleid/work/$example_root_id/versions

Resolve (HTML/redirect): GET https://nobleid.org/$example_date/$example_id or ...:vN

Metadata: GET /api/v1/nobleid/metadata/$example_arkOrVersion?format=json|xml|bibtex|ris|csl-json

Update status (widget): GET /api/v1/nobleid/check-update?ark=...

Proofs: GET /api/v1/nobleid/proofs/$example_root_ark/$example_version

Notes

Root always means latest; :vN pins a version
The full date in the ID is the UTC mint date
Keep your canonical SEO unchanged; add sameAs to the NOBLEID resolver to avoid duplication

<script src="https://cdn.nobleid.org/widget.js" data-ark="ark:/nobleid/20092025/7X9K2Q"  data-style="badge"  defer integrity="" crossorigin="anonymous"></script>

POST /api/v1/nobleid/generate { "title": "My Journal Article", "authors": ["A. Author","B. Author"], "type": "paper", "abstract": "Short abstract", "contentUrl": "https://yourjournal.org/articles/123.pdf", "externalUrls": ["https://yourjournal.org/articles/123"] }