Resolver & SEO Guide

Optimize discoverability with JSON-LD, canonical links, and proper SEO mapping.

JSON-LD Structured Data

Embed rich metadata for search engines and knowledge graphs

{
  "@context": "https://schema.org",
  "@type": "ScholarlyArticle",
  "@id": "https://nobleid.org/ark:/nobleid/20092025/7X9K2Q",
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "ARK",
      "value": "ark:/nobleid/20092025/7X9K2Q"
    },
    {
      "@type": "PropertyValue", 
      "propertyID": "DOI",
      "value": "10.1000/182"
    }
  ],
  "name": "Example Research Paper",
  "author": {
    "@type": "Person",
    "name": "Dr. Jane Smith",
    "identifier": {
      "@type": "PropertyValue",
      "propertyID": "ORCID",
      "value": "0000-0002-1825-0097"
    }
  },
  "datePublished": "2025-01-15",
  "publisher": {
    "@type": "Organization",
    "name": "Example Journal"
  },
  "url": "https://example-journal.org/articles/2025/example-paper",
  "sameAs": [
    "https://nobleid.org/ark:/nobleid/20092025/7X9K2Q",
    "https://doi.org/10.1000/182"
  ],
  "isBasedOn": "https://nobleid.org/ark:/nobleid/20092025/7X9K2Q/v1"
}

Key Schema.org Properties

• @id - Canonical NOBLEID URL
• identifier - ARK, DOI, and other persistent IDs
• sameAs - Equivalent URLs (publisher, DOI resolver)
• isBasedOn - Previous versions for update tracking

Canonical URL Mapping

Set up proper canonical relationships between publisher and NOBLEID URLs

<!-- In your HTML head -->
<link rel="canonical" href="https://example-journal.org/articles/2025/example-paper">
<link rel="alternate" type="application/json+ld" href="https://api.nobleid.org/v1/resolve/ark:/nobleid/20092025/7X9K2Q">

<!-- OpenGraph -->
<meta property="og:url" content="https://example-journal.org/articles/2025/example-paper">
<meta property="og:type" content="article">
<meta property="og:title" content="Example Research Paper">

<!-- Schema.org JSON-LD -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "ScholarlyArticle",
  "@id": "https://nobleid.org/ark:/nobleid/20092025/7X9K2Q",
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "ARK",
      "value": "ark:/nobleid/20092025/7X9K2Q"
    },
    {
      "@type": "PropertyValue", 
      "propertyID": "DOI",
      "value": "10.1000/182"
    }
  ],
  "name": "Example Research Paper",
  "author": {
    "@type": "Person",
    "name": "Dr. Jane Smith",
    "identifier": {
      "@type": "PropertyValue",
      "propertyID": "ORCID",
      "value": "0000-0002-1825-0097"
    }
  },
  "datePublished": "2025-01-15",
  "publisher": {
    "@type": "Organization",
    "name": "Example Journal"
  },
  "url": "https://example-journal.org/articles/2025/example-paper",
  "sameAs": [
    "https://nobleid.org/ark:/nobleid/20092025/7X9K2Q",
    "https://doi.org/10.1000/182"
  ],
  "isBasedOn": "https://nobleid.org/ark:/nobleid/20092025/7X9K2Q/v1"
}
</script>

Best Practices

• Publisher URL should be canonical (primary)
• NOBLEID URL should reference publisher as canonical
• Include JSON-LD with sameAs relationships
• Use consistent URLs across all metadata

SameAs Relationships

Create bidirectional links between equivalent resources

# When minting via API, include publisher_url:
curl -X POST https://api.nobleid.org/v1/works \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Example Research Paper",
    "publisher_url": "https://example-journal.org/articles/2025/example-paper",
    "doi": "10.1000/182",
    ...
  }'

# This creates bidirectional sameAs relationships:
# NOBLEID → Publisher URL
# Publisher URL → NOBLEID ARK
# Both → DOI (if provided)

Relationship Types

• Publisher URL - Authoritative version on publisher site
• DOI - Persistent identifier from registration agency
• NOBLEID ARK - Version-aware persistent identifier
• Repository URLs - Institutional or subject repositories

Resolution Behavior

How ARK identifiers resolve to content and metadata

# ARK resolution follows this priority:
# 1. If publisher_url exists → 302 redirect to publisher
# 2. If content_url exists → 302 redirect to content  
# 3. Otherwise → 200 with NOBLEID metadata page

# API resolution always returns JSON:
curl -H "Accept: application/json" \
  https://api.nobleid.org/v1/resolve/ark:/nobleid/20092025/7X9K2Q

Content Negotiation

• text/html - Redirects to publisher or shows metadata page
• application/json - Returns structured metadata
• application/ld+json - Returns JSON-LD
• application/pdf - Redirects to content if available

SEO Optimization

Maximize discoverability and search engine understanding

Checklist

✓ Include JSON-LD structured data on all pages
✓ Set canonical links pointing to publisher URL
✓ Use consistent titles and descriptions
✓ Include OpenGraph and Twitter Card metadata
✓ Link to ORCID profiles for authors
✓ Reference DOIs and other persistent identifiers
✓ Include version history in sitemaps

Test Rich Results