NobleID
Back to Docs

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/works/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/works/$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
HomeMintSearchHelpProfile