JSONLD Exporter

A WordPress plugin that provides a REST API to export post data of different post types to valid JSON-LD post objects. Primarily designed to enable NLWeb Dataloader of WordPress content.

🔗 Links

• Source Code: GitHub Repository
• NLWeb: NLWeb Repository
• Articles:
  • NLWeb Enables AI-Powered Websites
  • Markdown to JSON-LD: Boosting VectorSearch RAGs

✨ Key Features

• Flexible REST API: Exposes endpoints to get a single post, posts by type, or all posts.

• Bulk Export: The endpoint can export all your content, with support for both JSON Array and JSON-Line () formats, perfect for large datasets. /all-posts``.jsonl

• Powerful Filtering: Filter bulk exports by modification date, control post limits with pagination, and define the sort order.

• Secure & Public Modes: Restrict API access with a unique, auto-generated API key (Private mode) or allow open access (Public mode).

• Admin Dashboard: An easy-to-use settings page to:

  • Select which post types are available in the API.
  • Switch between public and private modes.
  • Generate, reset, and copy your API key.
  • Toggle the automatic inclusion of JSON-LD in post headers for SEO.

• Developer Friendly: Comes with a comprehensive script to validate all API endpoints and parameters. test-api.sh

• Automated Deployments: Includes GitHub Actions workflows for deploying the plugin and its assets.

Description

WP-JSONLD Exporter creates REST API endpoints that allow you to retrieve WordPress posts as structured JSON-LD post objects. The plugin is primarily designed to enable NLWeb Dataloader of WordPress content and is powered by iunera.com.

This is particularly useful for:

• Implementing structured data for SEO
• Creating headless WordPress setups
• Building custom applications that need structured post data
• Integrating WordPress content with external systems
• Enabling NLWeb Dataloader to process WordPress content

The plugin maps WordPress post data to the schema.org Article format, with special attention to the post content itself.

Features

• REST API endpoints for retrieving single posts or multiple posts by post type
• Endpoint for retrieving all posts in JSON-line format for bulk importing
• Configurable post type selection for controlling which content is exported
• Flexible access control with public or private mode options
• API key authentication for secure access to endpoints when using private mode
• Comprehensive mapping of WordPress post data to JSON-LD article schema
• Support for featured images, authors, publishers, and more
• Integration with WordPress custom fields
• Automatic mapping of categories and tags to articleSection and keywords
• Admin settings page with API key management and documentation
• Automatic addition of JSON-LD links in the HTML head section for enabled post types

Header Links

When viewing a single post of an enabled post type, the plugin adds the following to the HTML head section:

1. The JSON-LD object of the post itself (if enabled in settings):

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Post Title",
  "description": "Post Excerpt",
  "articleBody": "Post Content",
  ...
}
</script>

2. A backlink to the project page for SEO purposes (always included):

<link rel="powered-by" href="https://www.iunera.com" title="Powered by iunera.com" />

You can enable or disable the JSON-LD object in the HTML head section through the "Header JSON-LD Settings" in the plugin settings page. The "Powered By" link is always included regardless of this setting.

This allows search engines and other tools to directly access the structured data of your content without making additional API requests.

API Endpoints

The plugin provides the following REST API endpoints. Authentication requirements depend on your access mode setting.

Authentication

The plugin supports two access modes:

• Private Mode (Default): All API requests require the api_key parameter with your API key.
• Public Mode: API requests can be made without an API key, making the data publicly accessible.

You can configure the access mode in the plugin settings page. Even in public mode, you can still use your API key for authenticated access if needed. You can find or generate your API key in the plugin settings page.

Single Post

GET /wp-json/jsonld-exporter/v1/post/{post_id}?api_key=YOUR_API_KEY

Retrieves a single post as a JSON-LD object.

Posts by Post Type

GET /wp-json/jsonld-exporter/v1/posts/{post_type}?api_key=YOUR_API_KEY

Retrieves multiple posts of a specific post type as JSON-LD objects.

Parameters:

• api_key: Your API key (required in private mode, optional in public mode)
• page: Page number for pagination (optional)

All Posts

GET /wp-json/jsonld-exporter/v1/all-posts?api_key=YOUR_API_KEY

Retrieves published posts from the selected post types. By default, only posts are included, but you can configure which post types to include in the plugin settings. This is useful for bulk importing or processing large amounts of content.

Parameters:

• api_key: Your API key (required in private mode, optional in public mode)
• format: Output format - 'jsonl' for JSON-line format (default) or 'json' for JSON Array format
• posts_per_page: Number of posts to return (default: 10, use -1 for all posts)
• date_modified_from: Filter posts modified after this date (YYYY-MM-DD or ISO 8601 format)
• date_modified_to: Filter posts modified before this date (YYYY-MM-DD or ISO 8601 format)
• order: Sort order - 'DESC' for newest first (default) or 'ASC' for oldest first
• download: Set to 1 to download the data as a file (optional)

JSON-LD Structure

The plugin maps WordPress post data to the JSON-LD Article schema. A sample output file is included in the plugin directory (sample-output.json) for reference.

Here's an example of the JSON-LD structure:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Post Title",
  "description": "Post Excerpt",
  "articleBody": "Post Content",
  "datePublished": "2023-01-01T12:00:00+00:00",
  "dateModified": "2023-01-02T12:00:00+00:00",
  "url": "https://example.com/post-url",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://example.com/post-url"
  },
  "author": {
    "@type": "Person",
    "name": "Author Name",
    "url": "https://example.com/author-url"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Site Name",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  },
  "image": {
    "@type": "ImageObject",
    "url": "https://example.com/featured-image.jpg",
    "width": 1200,
    "height": 630
  },
  "articleSection": "Category1, Category2",
  "keywords": "Tag1, Tag2, Tag3",
  "wordCount": "1500"
}

Installation

1. Upload the wp-jsonld-exporter folder to the /wp-content/plugins/ directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Access the settings page at Settings > WP-JSONLD Exporter to view API documentation

Usage Examples

Retrieve a Single Post

GET /wp-json/jsonld-exporter/v1/post/123?api_key=YOUR_API_KEY

Retrieve Posts of a Specific Post Type

GET /wp-json/jsonld-exporter/v1/posts/post?api_key=YOUR_API_KEY

Retrieve Posts with Pagination

GET /wp-json/jsonld-exporter/v1/posts/post?page=2&api_key=YOUR_API_KEY

Retrieve Posts

GET /wp-json/jsonld-exporter/v1/all-posts?api_key=YOUR_API_KEY

This endpoint returns published posts from the selected post types. By default, it returns 10 posts in JSON-line format.

Retrieve Posts in JSON Array Format

GET /wp-json/jsonld-exporter/v1/all-posts?format=json&api_key=YOUR_API_KEY

This endpoint returns published posts in JSON Array format instead of JSON-line format.

Filter Posts by Date Modified

GET /wp-json/jsonld-exporter/v1/all-posts?date_modified_from=2023-01-01&date_modified_to=2023-12-31&api_key=YOUR_API_KEY

This endpoint returns posts that were modified between January 1, 2023 and December 31, 2023.

Retrieve More Posts Per Page

GET /wp-json/jsonld-exporter/v1/all-posts?posts_per_page=50&api_key=YOUR_API_KEY

This endpoint returns 50 posts instead of the default 10.

Sort Posts by Date (Oldest First)

GET /wp-json/jsonld-exporter/v1/all-posts?order=ASC&api_key=YOUR_API_KEY

This endpoint returns posts sorted by date in ascending order (oldest first).

Download Posts as File

GET /wp-json/jsonld-exporter/v1/all-posts?download=1&api_key=YOUR_API_KEY

This endpoint downloads published posts as a file named posts-export-YYYY-MM-DD.jsonl. The file contains posts in JSON-line format by default.

Download Posts as JSON Array File

GET /wp-json/jsonld-exporter/v1/all-posts?format=json&download=1&api_key=YOUR_API_KEY

This endpoint downloads published posts as a file named posts-export-YYYY-MM-DD.json. The file contains posts in JSON Array format.

API Access Mode

The plugin supports two access modes for the API endpoints:

1. Private Mode (Default): All API requests require an API key for authentication. This provides secure access to your content.
2. Public Mode: API requests can be made without an API key, making the data publicly accessible. This is useful for public-facing applications.

To configure the access mode:

1. Go to Settings > WP-JSONLD Exporter in your WordPress admin
2. Find the "API Access Mode" section
3. Select either "Private Access" or "Public Access"
4. Click "Save Access Mode Settings"

API Key Management

When using private access mode, the plugin requires an API key for all API requests to ensure secure access to your content. You can manage your API key in the plugin settings page:

1. Go to Settings > WP-JSONLD Exporter in your WordPress admin
2. Find the "API Key Management" section
3. View your current API key
4. Use the "Generate New Key" button to create a new key
5. Use the "Reset Key" button to reset the key to a new random value
6. Use the "Copy to Clipboard" button to copy the key for use in your applications

Important: When you generate a new key or reset the existing key, any applications using the old key will no longer work. Make sure to update all applications with the new key.

Custom Field Mapping

The plugin automatically maps the following custom fields to JSON-LD properties:

• keywords → keywords
• wordCount → wordCount
• articleSection → articleSection

You can extend this mapping by modifying the $field_mappings array in the wp_jsonld_convert_post_to_jsonld function.

Security

The plugin implements several security measures:

• API Key Authentication: All endpoints require an API key for access.
• Data Sanitization: All input data is properly sanitized using WordPress sanitization functions
• Data Validation: Input parameters are validated before processing
• Data Escaping: All output data is properly escaped to prevent XSS attacks
• Nonce Verification: Admin forms use nonces to prevent CSRF attacks

License

This plugin is licensed under the GPL v3 or later.

Building and Deployment

Local Build

To build the plugin for local testing or manual upload to WordPress.org:

# Build with current version
./build.sh

# Update version and build
./build.sh -v 1.0.0

The build script:

1. Checks version consistency across files
2. Updates version numbers when -v flag is used
3. Creates a clean build with only the necessary files
4. Packages everything into a zip file ready for WordPress.org

The built plugin will be available at build/wp-jsonld-exporter.zip.