7. Properties & References

JsonDispatch goes beyond just returning status and data. It introduces two companion sections — _properties and _references — to make responses self-descriptive and context-aware without extra API calls.

7.1 _properties — Describe Your Data, Not Just Send It

The _properties object carries metadata about the ``data`` field. It helps clients understand the payload’s structure, count, pagination, and even its lifecycle (like deprecation or schema changes).

Field	Type	Purpose
type	string	Type of data (array, object, string, number, boolean).
name	string	Logical name for this data block.
template	string (URL)	Optional link to a JSON Schema or template definition.
deprecation	string (URL)	Optional link marking this resource as deprecated.
count	integer	Total number of items if the data is an array.
range	string	Range of records in paginated results (e.g., "21-40").
page	integer	Current page number, if paginated.

Example

"_properties": {
  "data": {
    "type": "array",
    "name": "articles",
    "count": 20,
    "page": 2,
    "range": "21-40",
    "deprecation": "https://api.example.com/docs/v2/articles"
  }
}

This tells the client:

• The data is an array named articles.

• It contains 20 items, displaying page 2 (items 21–40).

• The endpoint is deprecated in favor of the linked v2 spec.

Best practice: Always include at least type and name. This enables automated clients (CLI tools, SDKs, data grids) to interpret results correctly.

7.2 _references — Replace IDs with Meaning

The _references object defines lookup tables that map internal IDs or codes to human-readable labels. It eliminates the need for extra “dictionary” or “enum” endpoints.

Example

"_references": {
  "category": {
    "1": "News",
    "2": "Tutorial",
    "3": "Opinion"
  },
  "status": {
    "A": "Active",
    "I": "Inactive",
    "S": "Suspended"
  }
}

When a record includes "category": 2, the client can instantly render “Tutorial” using the mapping.

Best practice: Keep keys short and meaningful (e.g., category, status, role) that directly correspond to the field names inside data.

7.3 Choosing Between Them

Use Case	Use _properties	Use _references
Describe structure, pagination, or schema	✅
Translate IDs or codes to labels		✅
Mark field as deprecated or link to template	✅
Enumerate possible options or states		✅

7.4 Example — Combined in One Response

{
  "status": "success",
  "message": "Articles listed successfully",
  "data": [
    {
      "id": 1,
      "title": "Intro to JsonDispatch",
      "category": 1
    },
    {
      "id": 2,
      "title": "Error Handling Patterns",
      "category": 3
    }
  ],
  "_properties": {
    "data": {
      "type": "array",
      "name": "articles",
      "count": 2,
      "page": 1,
      "range": "1-2"
    }
  },
  "_references": {
    "category": {
      "1": "News",
      "2": "Tutorial",
      "3": "Opinion"
    }
  }
}

Clients can now:

• Display labels directly using _references.

• Understand that data is paginated and typed via _properties.

• Do all this without extra round-trips or hard-coded logic.

7.5 Nested _references Example

Complex datasets often include hierarchical or multi-level relationships — e.g., categories, subcategories, or status groups. JsonDispatch supports nested ``_references`` so you can express those relationships cleanly while keeping the payload compact.

This allows clients to resolve multi-level identifiers without multiple API calls.

Example — Category → Subcategory → Label Mapping

{
  "status": "success",
  "message": "Product list with hierarchical references",
  "data": [
    { "id": 1, "name": "iPhone 15", "category": 10, "subcategory": 101 },
    { "id": 2, "name": "Galaxy S24", "category": 10, "subcategory": 102 },
    { "id": 3, "name": "MacBook Air", "category": 20, "subcategory": 201 }
  ],
  "_references": {
    "category": {
      "10": {
        "label": "Mobile",
        "children": {
          "101": "Apple",
          "102": "Samsung"
        }
      },
      "20": {
        "label": "Laptop",
        "children": {
          "201": "Apple",
          "202": "Windows"
        }
      }
    }
  },
  "_properties": {
    "data": {
      "type": "array",
      "name": "products",
      "count": 3
    }
  }
}

Explanation

Field	Purpose
category	Maps high-level IDs (10, 20) to parent labels.
children	Maps subcategory IDs to their names under each parent.
label	A friendly label for the parent category.
_references	Keeps the hierarchy readable and cacheable on the client.

Why it matters

• Fewer round-trips — clients can render category and subcategory labels directly.

• Extensible — future nesting levels (e.g., regions → countries → cities) follow the same pattern.

• Localized references — _references can hold language-specific labels if needed.

Client behavior

When parsing, clients should:

1. Resolve subcategory first within its parent category.

2. Fallback to top-level label if no match is found.

3. Cache _references by version to avoid redundant lookups.

Best practice: Use nested _references only when relationships are stable and bounded. For dynamic trees, prefer dedicated endpoints (/categories, /locations).