Custom JSON Integration: Technical Documentation and Field Mapping

Overview

Custom JSON integration allows you to distribute technical documentation and product data through JSON-formatted feeds. This approach provides flexibility in how you structure and deliver your documentation source data to various distribution channels and platforms.

Unlike predefined feed templates, custom JSON sources let you define your own schema structure, field names, and data hierarchy. This guide covers how to configure JSON sources, map fields correctly, and ensure your technical documentation meets platform requirements.

Understanding Custom JSON Sources

A custom JSON source reads data from a JSON file or API endpoint and transforms it into a format compatible with your distribution channels. The JSON structure you provide becomes the foundation for all downstream field mappings.

When you set up a custom JSON integration, you specify:

• The location of your JSON data (file path or API endpoint)
• The root object or array containing your product or documentation records
• How nested properties should be accessed and flattened
• Which fields map to required channel attributes

The system then parses your JSON, extracts values from the paths you define, and passes them to your chosen distribution channels. If your JSON structure changes, your mappings remain intact as long as the field paths stay consistent.

JSON Schema Configuration

Structuring Your JSON Data

Your JSON file should contain an array of objects, with each object representing a single product, document, or resource entry. A basic structure looks like this:

{
  "products": [
    {
      "id": "doc-001",
      "title": "API Reference Guide",
      "description": "Complete API documentation",
      "category": "Technical Guides",
      "price": "0.00",
      "availability": "in stock"
    }
  ]
}

Nested properties are accessed using dot notation. For example, if your JSON contains "metadata": {"created_date": "2024-01-15"}, you reference it as metadata.created_date in your field mappings.

Arrays within objects can be flattened using bracket notation. If you have "authors": ["Alice", "Bob"], reference the first author as authors[0].

Root Path Configuration

Specify which part of your JSON contains the product array. If your JSON wraps products in a "data" object, set the root path to data. If products sit at the top level, leave the root path empty or set it to the array name.

This setting tells the system where to find individual records to process and distribute.

Field Mapping for Technical Documentation

Once your JSON source is configured, map each JSON field to the attributes required by your distribution channels. The mapping process connects your source data to channel-specific field names.

Direct Mapping

Direct mapping copies the value from your JSON field into the channel field without transformation. Use this when your JSON field name and value format already match what the channel expects.

For example, if your JSON contains "title": "User Authentication Guide" and the channel needs a title field, map it directly.

Conditional Mapping and Transformations

Some channels require specific value formats or conditional logic. If your JSON stores status as "published" but a channel expects "in stock", use a transformation rule to convert the value.

Common transformations include:

• Converting boolean values (true/false) to text (yes/no)
• Mapping status codes to channel-specific values
• Formatting dates to match channel requirements (DD/MM/YYYY)
• Extracting substrings from longer fields
• Combining multiple JSON fields into a single channel field

Handling Nested and Array Data

When your JSON contains nested objects or arrays, specify the exact path to extract the value you need.

If your documentation includes multiple authors stored as "contributors": [{"name": "Alice", "role": "author"}, {"name": "Bob", "role": "reviewer"}], you can map:

• contributors[0].name to capture the first author's name
• Create a concatenation rule to combine all author names with commas

For deeply nested data like "metadata": {"seo": {"keywords": ["api", "reference"]}}, use the full path: metadata.seo.keywords[0].

Practical Configuration Steps

Step 1: Prepare Your JSON File

Ensure your JSON is valid and properly formatted. Use a JSON validator to check for syntax errors. Confirm that all required fields for your distribution channels are present in your source data.

Test with a small sample (5-10 records) before uploading your full dataset.

Step 2: Upload or Connect Your JSON Source

Provide the file path or API endpoint where your JSON is hosted. If using an API endpoint, confirm that the system can access it and that it returns valid JSON.

For file-based sources, upload the JSON file to your feed management platform. For API sources, test the endpoint to ensure it responds correctly and consistently.

Step 3: Define the Root Path

Identify which part of your JSON structure contains the array of records. Test the root path to verify that the system correctly identifies and counts the number of records available.

Step 4: Map Fields to Channel Requirements

For each distribution channel you use, map your JSON fields to the required and optional channel attributes. Start with mandatory fields (id, title, description, link) and then add optional fields that improve listing quality.

Test a sample mapping with 1-2 records to confirm values are extracted and formatted correctly before processing your full feed.

Step 5: Validate and Preview

Run a validation check to identify any mapping errors, missing required fields, or data format issues. Review a preview of 5-10 records as they will appear on the distribution channel.

Correct any errors and retest before publishing the feed to live channels.

Technical Documentation Specific Considerations

Handling Version Information

If your documentation includes version numbers or release dates, ensure these are mapped to fields the channel recognises. Some channels support a product_type or custom field for version tracking.

Store version information consistently (for example, always as "v1.2.3" or "2024-01-15") so that channels can sort and filter documentation correctly.

Managing Documentation Status

Map your internal status values (draft, published, archived, deprecated) to the availability field or a custom status field. Channels use availability to determine whether a document appears in search results and listings.

Archived or deprecated documentation should typically be marked as unavailable or removed from the feed entirely.

Including Metadata and Keywords

If your JSON includes metadata like keywords, tags, or categories, map these to the description field or to channel-specific fields like google_product_category. This improves discoverability and helps channels categorise your documentation correctly.

Common Issues and Solutions

Missing or Null Values

If a JSON field is missing or contains null, the mapped channel field will be empty. Configure fallback values or default text for critical fields like title and description.

For optional fields, leaving them empty is acceptable and will not cause validation errors.

Encoding and Character Issues

Ensure your JSON file uses UTF-8 encoding. Special characters, accents, and symbols should be properly escaped or encoded.

If characters appear corrupted in the feed output, check that your JSON source file is saved with UTF-8 encoding and that special characters are not being double-encoded.

Array and Nested Object Complexity

If your JSON structure is deeply nested or contains complex arrays, use bracket notation and dot notation carefully. Test each path individually to confirm the system can extract the correct values.

For very complex structures, consider flattening your JSON before upload or using transformation rules to simplify the mapping.

API Endpoint Reliability

If your JSON source is an API endpoint, ensure it is reliable and responds quickly. Configure timeout settings appropriately and test the endpoint regularly.

If the endpoint fails, the feed will not update. Set up monitoring or fallback options to ensure continuous data delivery.

Summary

Custom JSON integration provides flexibility for distributing technical documentation and product data across multiple channels. By configuring your JSON structure correctly, mapping fields precisely, and testing thoroughly, you ensure that your documentation reaches the right audience in the right format.

Start with a small dataset, validate your mappings, and expand to your full feed once you confirm that data is extracted and formatted correctly. Regular monitoring and updates to your JSON source will keep your documentation current and available across all distribution channels.