afv-library/skills/platform-metadata-api-context-get/examples/README.md

Salesforce Metadata API - Section-Specific Loading Examples

This directory contains working code examples demonstrating how to programmatically load only specific sections from metadata JSON files.

⚠️ Critical Warning

NEVER use built-in tools like Read, cat, or any other tool that loads entire JSON files into context!

These tools inject the complete file (including verbose WSDL segments and all sections) directly into your context, wasting 60-80% of tokens.

Available Examples

1. Python Example

File: python_section_loading.py

Demonstrates:

• Loading single section (fields only)
• Loading multiple sections (description + fields)
• Checking available sections first
• What NOT to do

Usage:

python3 examples/python_section_loading.py

Key Pattern:

import json
with open('data/metadata_api/CustomObject.json') as f:
    data = json.load(f)
    fields_only = data.get('fields', {})  # Only extract 'fields'

2. JavaScript/Node.js Example

File: javascript_section_loading.js

Demonstrates:

• Synchronous file loading with section extraction
• Multiple sections extraction
• Section checking
• Async/Promise version

Usage:

node examples/javascript_section_loading.js

Key Pattern:

const fs = require('fs');
const data = JSON.parse(fs.readFileSync('data/metadata_api/CustomObject.json', 'utf-8'));
const fieldsOnly = data.fields || {};  // Only extract 'fields'

3. Bash + jq Example

File: bash_section_loading.sh

Demonstrates:

• Using jq to extract specific sections
• Shell-based section filtering
• Field-level extraction
• Section availability checking

Prerequisites:

• jq must be installed
  • macOS: brew install jq
  • Linux: apt-get install jq or yum install jq
  • Windows: winget install jqlang.jq or choco install jq

Windows note: The Bash + jq example targets a POSIX shell (use WSL, Git Bash, or Cygwin on Windows). For a cross-platform, no-extra-dependency option, prefer the Python (python_section_loading.py) or JavaScript (javascript_section_loading.js) examples, which run natively on Windows.

Usage:

chmod +x examples/bash_section_loading.sh
./examples/bash_section_loading.sh

Key Pattern:

# Extract only the 'fields' section
jq '.fields' data/metadata_api/CustomObject.json

Token Savings

Approach	Tokens Used	Savings
❌ Read tool (entire file)	500-2,000	0% (baseline)
✅ Section-specific loading	50-200	60-80%

Common Patterns

Pattern 1: Single Section

Load only the section you need:

CustomObject.json → Extract only 'fields' → Use 200 tokens instead of 2,000

Pattern 2: Multiple Sections

Load 2-3 specific sections:

Flow.json → Extract 'description' + 'fields' → Use 400 tokens instead of 1,500

Pattern 3: Check First, Then Load

Always check what sections are available:

1. Read 'sections' array
2. Determine what's available
3. Load only what you need

What Sections to Load

Choose based on your need:

Your Need	Load These Sections	Skip These
Field definitions	fields	wsdl_segment, declarative_metadata_sample_definition
Understanding purpose	description	wsdl_segment, file_information
XML structure examples	declarative_metadata_sample_definition	wsdl_segment
Schema validation	wsdl_segment	(rarely needed)

Anti-Patterns (What NOT to Do)

❌ Wrong: Using Read Tool

# This loads the ENTIRE file into context (2,000 tokens)
Read data/metadata_api/CustomObject.json

❌ Wrong: Using cat/type

# This loads the ENTIRE file into context (2,000 tokens)
cat data/metadata_api/CustomObject.json
type data/metadata_api/CustomObject.json

✅ Correct: Programmatic Section Extraction

# This loads only the 'fields' section (200 tokens)
jq '.fields' data/metadata_api/CustomObject.json

Adapting to Other Languages

These patterns work in any language with JSON parsing:

• Python: json.load() or json.loads()
• JavaScript/Node.js: JSON.parse()
• Java: new Gson().fromJson() or new ObjectMapper().readValue()
• Go: json.Unmarshal()
• Ruby: JSON.parse()
• PHP: json_decode()
• C#: JsonConvert.DeserializeObject()
• Bash: jq

The key principle is the same: parse the JSON, extract only needed sections, ignore the rest.

Questions?

See the main SKILL.md for comprehensive documentation on token optimization strategies and conceptual approaches.